deepline 0.3.274 → 0.3.276

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

@@ -74,6 +74,7 @@ import {
   type ProductNotificationGroupDraft,
 } from '../../shared_libs/product-notifications/configuration.js';
 import { watchRunEvents as pollRunSnapshotEvents } from './runs/watch-polling.js';
+import { encodeRunLogsCursor, parseRunLogsCursor } from './runs/log-cursor.js';
 import type {
   DeeplineClientOptions,
   ResolvedConfig,
@@ -626,6 +627,49 @@ export type RunsListPage = {
   hasMore?: boolean;
 };
 
+/** Cursor-paged workspace run history, including runs of removed Plays. */
+export type RunsHistoryOptions = {
+  /** Case-insensitive Play/workflow name, run ID, or status substring. */
+  search?: string;
+  /** Search classification from recorded trigger metadata; requires search. */
+  type?: 'all' | 'plays' | 'monitors';
+  cursor?: string;
+  limit?: number;
+  /** Must match the workspace authorized by the credential. */
+  orgId?: string;
+  signal?: AbortSignal;
+};
+
+export type RunsHistoryItem = {
+  runId: string;
+  workflowId: string;
+  workflowName: string;
+  playScope: 'org' | 'system' | null;
+  status: string;
+  createdAt: number;
+  updatedAt: number;
+  callerName: string | null;
+  callerEmail: string | null;
+  authorName: string | null;
+  authorEmail: string | null;
+  callerAgent: string | null;
+  executionMode: string | null;
+  bindingId: string | null;
+  parentWorkflowName: string | null;
+  outputRowCount: number | null;
+  hasOutput: boolean;
+  billingTotalCredits?: number;
+  triggerSource?: string;
+};
+
+/** An empty search page is incomplete while hasMore is true. */
+export type RunsHistoryPage = {
+  runs: RunsHistoryItem[];
+  nextCursor: string | null;
+  hasMore: boolean;
+  avatarsByName?: Record<string, string>;
+};
+
 export type PlaysListOptions = {
   origin?: 'prebuilt' | 'owned';
   grep?: string;
@@ -657,6 +701,8 @@ export type PlaysListPage = {
 export type RunsGetOptions = {
   /** Return the raw status payload instead of the compact package. */
   full?: boolean;
+  /** Explicitly read this run's recorded graph and source, without full results. */
+  configuration?: boolean;
   /** Attach a bounded end-of-stream window for a failed run. */
   failedLogs?: boolean;
   /** Requested failed-log lines to attach (default 20, hard-capped at 20). */
@@ -748,6 +794,12 @@ export type RunsLogsOptions = {
   all?: boolean;
   /** Read a terminal-failed run's last 20 retained lines, or fewer with `limit`. Retention loss returns an explicit association and warning. */
   failed?: boolean;
+  /**
+   * Continue with the next OLDER page: pass a prior result's `nextCursor`.
+   * The page holds the last `limit` stored lines before that cursor (with
+   * `all`, every stored line before it).
+   */
+  cursor?: string;
 };
 
 /** Retained text for one run. Counts and retention flags describe the stored stream, not every original console call. */
@@ -764,8 +816,14 @@ export type RunsLogsResult = {
   lastSequence: number | null;
   /** Tail/all: returned count is below total count. Failed: the stream lost bodies to retention. Check `logsTruncated` to distinguish retention loss from a selected tail. */
   truncated: boolean;
-  /** More retained lines exist after `lastSequence`; always false for the designed failure window. */
+  /** Older stored lines exist before this page; `nextCursor` reads them. */
   hasMore: boolean;
+  /**
+   * Opaque cursor for the next older page (`runs.logs(id, { cursor })`),
+   * null when this page reaches the oldest stored line. Absent for the failed
+   * view, which is a complete designed window rather than a pageable slice.
+   */
+  nextCursor?: string | null;
   /** Formatted text lines in stored sequence order; structured context is available through event search. */
   entries: string[];
   /** Selected public log view. */
@@ -783,7 +841,7 @@ export type RunsLogsResult = {
   logsTruncated?: boolean;
 };
 
-/** Read existing events in the authenticated organization/runtime scope, newest first by occurrence time and event ID. See the complete catalog and field contract in `deepline runs logs --help`. */
+/** Search existing events in your organization, newest first. Discover kinds and filters with `deepline runs logs --help`. */
 export type RunsEventSearchOptions = {
   /** Inclusive UTC timestamp; defaults to one hour before the request. */
   since?: string;
@@ -795,9 +853,9 @@ export type RunsEventSearchOptions = {
   playName?: string;
   /** Exact dotted event kind, such as `step.failed`. The catalog is discoverable with `runs logs --help`; future stored kinds are accepted too. */
   kind?: string;
-  /** Equality joined with `&&`, at most eight predicates and 512 bytes. Fields: orgId, runId, playName, runtimeScope, producerAttempt, kind, status, source, stepId, stepKind, datasetId, phase, provider, operation and scalar `context.<key>`. Missing fields do not match; status is not inferred from kind. No body, message, level, nested payload, range or OR search. HTTP `jsonpath`, CLI `--where`. */
+  /** JSONPath equality joined with `&&`, at most eight predicates and 512 bytes. See `runs logs --help` for fields and examples. Missing fields do not match; status is not inferred from kind. HTTP `jsonpath`, CLI `--where`. */
   jsonpath?: string;
-  /** Add stored canonical `eventPayload` and, for receipt matches, retained `payload`. At most ten events and 16 MiB; unavailable receipts return null. HTTP `payloads=true`, CLI `--payloads`. Does not execute tools. */
+  /** Include available `eventPayload` details and receipt `payload` results; maximum ten events and 16 MiB. HTTP `payloads=true`, CLI `--payloads`. */
   includePayloads?: boolean;
   /** Page size: default 100, maximum 200; with payloads, default and maximum ten. */
   limit?: number;
@@ -807,7 +865,7 @@ export type RunsEventSearchOptions = {
   runtime?: PlayRuntimeSelection;
 };
 
-/** One indexed observation; optional indexed fields and payloads depend on what its producer recorded. */
+/** One matching event. Optional fields and details are present only when recorded. */
 export type RunsEventSearchEntry = {
   /** Stable event identity; also breaks ties in newest-first pagination. */
   eventId: string;
@@ -819,15 +877,15 @@ export type RunsEventSearchEntry = {
   runId: string;
   /** Recorded Play name. */
   playName: string;
-  /** Exact indexed kind; canonical payloads use `type` for this dotted name. */
+  /** Exact dotted event kind, such as `step.failed`. */
   kind: string;
   /** Recorded log severity, or null; not a JSONPath filter field. */
   level: string | null;
   /** Log message preview of at most 2,048 characters, or null. Use text logs/export for the full retained line. */
   message: string | null;
-  /** Indexed identity and recorded scalar fields. SDK/API keep this nested; CLI search flattens it onto each event. Provider/operation describe typed activity observations, not every provider call. */
+  /** Recorded filter fields. SDK/API keep this nested; the CLI places these fields directly on each event. */
   searchDoc: Record<string, unknown>;
-  /** Stored canonical event details, only when payloads are requested and available. Lifecycle/activity/dataset payloads are observations, not complete tool responses or dataset rows. */
+  /** Available event details when requested with `includePayloads`; dataset events contain metadata, not dataset rows. */
   eventPayload?: Record<string, unknown>;
   /** Retained work result for a receipt match when payloads are requested; null if unavailable. Other events need not carry this field. */
   payload?: RunsEventPayload | null;
@@ -845,7 +903,7 @@ export type RunsEventSearchResult = {
   until: string;
 };
 
-/** Retained work outcome hydrated for a receipt event; not a new execution, billing receipt or guarantee of a raw HTTP response. */
+/** Saved work result returned for a receipt event. Reading it does not execute the work again. */
 export type RunsEventPayload = {
   /** Recorded terminal work outcome. */
   status: 'completed' | 'failed' | 'skipped';
@@ -965,6 +1023,8 @@ export type RunsNamespace = {
   list: (options: RunsListOptions) => Promise<PlayRunListItem[]>;
   /** Read one run page with total, offset, limit and completeness metadata. */
   listPage: (options: RunsListOptions) => Promise<RunsListPage>;
+  /** Search/page workspace run history newest first; follow empty continuing pages. */
+  history: (options?: RunsHistoryOptions) => Promise<RunsHistoryPage>;
   /** Poll run snapshots every two seconds until terminal status. */
   watch: (runId: string, options?: RunsWatchOptions) => Promise<PlayStatus>;
   /** @deprecated Use `watch`; retained as a source-compatible alias. */
@@ -2709,6 +2769,7 @@ export class DeeplineClient {
       status: (runId) => this.getRunLifecycleStatus(runId),
       list: (options) => this.listRuns(options),
       listPage: (options) => this.listRunsPage(options),
+      history: (options) => this.getRunsHistory(options),
       watch: (runId, options) => this.watchRunToTerminal(runId, options),
       tail: (runId, options) => this.tailRun(runId, options),
       logs: (runId, options) => this.getRunLogs(runId, options),
@@ -4222,11 +4283,24 @@ export class DeeplineClient {
     if (options?.full === true) {
       params.set('full', 'true');
     }
+    if (options?.configuration === true) {
+      params.set('include', 'configuration');
+    }
     const query = params.size > 0 ? `?${params.toString()}` : '';
     const response = await this.http.get<Record<string, unknown>>(
       `/api/v2/runs/${encodeURIComponent(runId)}${query}`,
       { headers: { 'x-deepline-run-status': '1' } },
     );
+    if (
+      options?.configuration === true &&
+      !Object.hasOwn(response, 'contract')
+    ) {
+      throw new DeeplineError(
+        'This server does not support recorded configuration reads.',
+        undefined,
+        'RUN_CONFIGURATION_UNAVAILABLE',
+      );
+    }
     const status = normalizePlayStatus(response);
     if (options?.failedLogs !== true || status.status !== 'failed') {
       return status;
@@ -4335,6 +4409,36 @@ export class DeeplineClient {
     return (await this.listRunsPage(options)).runs;
   }
 
+  /** The same tenant-scoped run history searched by the dashboard and CLI. */
+  async getRunsHistory(
+    options: RunsHistoryOptions = {},
+  ): Promise<RunsHistoryPage> {
+    const params = new URLSearchParams();
+    const search = options.search?.trim();
+    if (search && search.length > 200) {
+      throw new Error('Run search must be at most 200 characters.');
+    }
+    if (options.type && options.type !== 'all' && !search) {
+      throw new Error('runs.history options.type requires options.search.');
+    }
+    if (search) params.set('search', search);
+    if (search && options.type) params.set('type', options.type);
+    if (options.cursor) params.set('cursor', options.cursor);
+    if (options.orgId) params.set('orgId', options.orgId);
+    if (options.limit !== undefined) {
+      if (!Number.isSafeInteger(options.limit) || options.limit < 1) {
+        throw new Error(
+          'runs.history options.limit must be a positive integer.',
+        );
+      }
+      params.set('limit', String(options.limit));
+    }
+    return this.http.get<RunsHistoryPage>(
+      `/api/v2/dashboard/runs-history?${params.toString()}`,
+      { signal: options.signal },
+    );
+  }
+
   /** Read one run page without discarding server pagination metadata. */
   async listRunsPage(options: RunsListOptions): Promise<RunsListPage> {
     const playName = options.play?.trim();
@@ -4477,6 +4581,13 @@ export class DeeplineClient {
         'INVALID_RUN_LOG_VIEW',
       );
     }
+    if (options?.cursor !== undefined && options.failed === true) {
+      throw new DeeplineError(
+        'runs.logs cannot combine failed with cursor.',
+        undefined,
+        'INVALID_RUN_LOG_VIEW',
+      );
+    }
     if (options?.failed === true) {
       const requestedLimit =
         typeof options.limit === 'number' &&
@@ -4507,6 +4618,8 @@ export class DeeplineClient {
         ...(page.logsTruncated ? { logsTruncated: true } : {}),
       };
     }
+    const beforeSequence =
+      options?.cursor !== undefined ? parseRunLogsCursor(options.cursor) : null;
     const limit = options?.all
       ? Number.MAX_SAFE_INTEGER
       : typeof options?.limit === 'number' &&
@@ -4520,29 +4633,44 @@ export class DeeplineClient {
         { retryApiErrors: true },
       );
     // Probe for the run's stored extent, then read the LAST `limit` stored
-    // lines (matching the historical tail-slice semantics), paginating in
-    // server-capped pages until the window is exhausted.
+    // lines (matching the historical tail-slice semantics) ending before the
+    // cursor, paginating in server-capped pages until the window is exhausted.
     const probe = await fetchPage(0, 1);
     const lastStoredSeq = probe.lastStoredSeq;
-    let afterSeq = options?.all ? 0 : Math.max(0, lastStoredSeq - limit);
+    const oldestStoredSeq = probe.entries[0]?.seq ?? null;
+    const upperSeq =
+      beforeSequence === null
+        ? Number.POSITIVE_INFINITY
+        : Math.min(beforeSequence - 1, lastStoredSeq);
+    const windowEndSeq = Math.min(upperSeq, lastStoredSeq);
+    let afterSeq = options?.all ? 0 : Math.max(0, windowEndSeq - limit);
     const entries: Array<{ seq: number; line: string }> = [];
-    while (entries.length < limit) {
+    while (entries.length < limit && afterSeq < upperSeq) {
       const page = await fetchPage(
         afterSeq,
-        Math.min(RUN_LOGS_PAGE_LIMIT, limit - entries.length),
+        Math.min(
+          RUN_LOGS_PAGE_LIMIT,
+          limit - entries.length,
+          upperSeq - afterSeq,
+        ),
       );
-      if (page.entries.length === 0) {
+      const inWindow = page.entries.filter((entry) => entry.seq <= upperSeq);
+      if (inWindow.length === 0) {
         break;
       }
-      entries.push(...page.entries);
-      afterSeq = page.entries[page.entries.length - 1]!.seq;
-      if (!page.hasMore) {
+      entries.push(...inWindow);
+      afterSeq = inWindow[inWindow.length - 1]!.seq;
+      if (!page.hasMore || inWindow.length < page.entries.length) {
         break;
       }
     }
     const firstSequence = entries.length > 0 ? entries[0]!.seq : null;
     const lastSequence =
       entries.length > 0 ? entries[entries.length - 1]!.seq : null;
+    const olderLinesExist =
+      firstSequence !== null &&
+      oldestStoredSeq !== null &&
+      firstSequence > oldestStoredSeq;
     return {
       runId: probe.runId,
       totalCount: probe.totalLogCount,
@@ -4550,7 +4678,8 @@ export class DeeplineClient {
       firstSequence,
       lastSequence,
       truncated: entries.length < probe.totalLogCount,
-      hasMore: lastSequence !== null && lastSequence < lastStoredSeq,
+      hasMore: olderLinesExist,
+      nextCursor: olderLinesExist ? encodeRunLogsCursor(firstSequence) : null,
       entries: entries.map((entry) => entry.line),
       view: options?.all ? 'all' : 'tail',
       ...(probe.logsTruncated ? { logsTruncated: true } : {}),

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

@@ -139,6 +139,9 @@ export type {
   PlaySheetRowsResult,
   RunsListOptions,
   RunsListPage,
+  RunsHistoryOptions,
+  RunsHistoryItem,
+  RunsHistoryPage,
   RunLifecycleStatus,
   PlaysListOptions,
   PlaysListPage,

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

@@ -481,16 +481,10 @@ export type CsvOptions = PlayAuthoringCsvOptions;
 export type DeeplinePlayRuntimeContext = PlayAuthoringRuntimeContext;
 
 /**
- * Handle to a running play execution.
- *
- * Provides methods to check status, stream logs, wait for completion,
- * or cancel the execution.
- *
- * This handle is the SDK-context equivalent of `deepline plays run` and
- * `POST /api/v2/plays/run`: every surface returns a run id first, then exposes
- * the completed user output through `PlayJob.get()` or the status endpoint's
- * `result` field. Runtime logs are available from `status().progress.logs` and
- * are intentionally separate from the returned output object.
+ * Handle to a Play execution: inspect status, stream logs, await output, or cancel.
+ * Like `deepline plays run` and `POST /api/v2/plays/run`, it returns a run id first.
+ * Read completed output through `PlayJob.get()` or the status endpoint's `result` field;
+ * runtime logs in `status().progress.logs` are separate from that output.
  *
  * @typeParam TOutput - The play's return type
  *

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.274',
+  version: '0.3.276',
   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/runs/log-cursor.ts

@@ -0,0 +1,35 @@
+/**
+ * Continuation cursor for the bounded run-log tail.
+ *
+ * `runs logs` returns the LAST `limit` stored lines, so the lines a caller has
+ * not seen yet are the OLDER ones. The cursor names the exclusive upper
+ * sequence bound of the next (older) page. Treat it as opaque; the `before:`
+ * prefix keeps it distinct from runtime event-search cursors, which share the
+ * `--cursor` flag on `deepline runs logs`.
+ */
+const RUN_LOGS_CURSOR_PREFIX = 'before:';
+
+export function encodeRunLogsCursor(beforeSequence: number): string {
+  return `${RUN_LOGS_CURSOR_PREFIX}${beforeSequence}`;
+}
+
+export function isRunLogsCursor(value: string): boolean {
+  return value.startsWith(RUN_LOGS_CURSOR_PREFIX);
+}
+
+/** Returns the exclusive upper sequence bound, or throws on a foreign token. */
+export function parseRunLogsCursor(value: string): number {
+  const raw = isRunLogsCursor(value)
+    ? value.slice(RUN_LOGS_CURSOR_PREFIX.length)
+    : '';
+  const parsed = /^[1-9]\d*$/.test(raw) ? Number(raw) : NaN;
+  if (!Number.isSafeInteger(parsed)) {
+    throw Object.assign(
+      new Error(
+        `Invalid run log cursor ${JSON.stringify(value)}. Pass the nextCursor value from a previous deepline runs logs result.`,
+      ),
+      { exitCode: 2 },
+    );
+  }
+  return parsed;
+}

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

@@ -1075,6 +1075,12 @@ export type PlayLiveEvent = LiveEventEnvelope<unknown> & {
 export interface StopPlayRunResult {
   /** Public play-run identifier the stop request targeted. */
   runId: string;
+  /**
+   * Typed stop outcome: `stopped` (terminal), `cancelling` (cancellation
+   * durably queued; cleanup and the final run update are pending, not an
+   * error), or `failed` (the stop was not confirmed). Absent on older servers.
+   */
+  state?: 'stopped' | 'cancelling' | 'failed';
   /** Whether the server confirmed the run was stopped. */
   stopped: boolean;
   /** True when the durable cancellation lane accepted the request and is draining. */
@@ -1084,11 +1090,12 @@ export interface StopPlayRunResult {
   /** True if HITL state or its same-message Slack card still needs retrying. */
   hitlCancellationPending?: boolean;
   /**
-   * True when the scheduler state for the run was stale and the stop could
-   * not be confirmed. Absent on older servers (treated as confirmed).
+   * True only when the scheduler and the canonical run ledger disagree (for
+   * example a terminal scheduler run whose ledger projection is pending), so
+   * the stop could not be confirmed. Never set for a queued cancellation.
    */
   staleSchedulerState?: boolean;
-  /** Server-side error detail when the stop was not confirmed. */
+  /** Server-side error detail when the stop failed (`state: 'failed'`). */
   error?: string;
 }
 

package/dist/bundling-sources/shared_libs/observability/scheduled-jobs.json

@@ -125,24 +125,6 @@
     "failureAlert": "github_workflow_run",
     "domainReportRequired": true
   },
-  {
-    "id": "github.convex-preview-usage-limit-reset",
-    "name": "Reset Convex Preview usage limits",
-    "scheduler": "github_actions",
-    "cadence": "0 0 1 * *",
-    "timezone": "UTC",
-    "source": ".github/workflows/apply-preview-convex-usage-limits.yml",
-    "locator": "schedule:",
-    "owner": "platform",
-    "criticality": "operational",
-    "purpose": "Restore the strict per-deployment usage thresholds for current-project Convex Previews after their monthly UTC usage windows reset.",
-    "successDefinition": "Every current-project Preview has all eight daily and monthly limits active at the strict baseline; only explicitly retired inventory entries are skipped.",
-    "failureDefinition": "Preview inventory is unavailable, a deployment cannot be addressed, or any usage threshold cannot be set and verified.",
-    "startGraceMs": 900000,
-    "runTimeoutMs": 2700000,
-    "failureAlert": "github_workflow_run",
-    "domainReportRequired": true
-  },
   {
     "id": "github.daily-slack-report",
     "name": "Daily Slack report",
@@ -325,15 +307,18 @@
   },
   {
     "id": "github.runtime-lifecycle",
-    "name": "Scheduled Runtime Lifecycle Load Monitor",
+    "name": "On-Demand Runtime Lifecycle Load Check",
+    "legacyNames": [
+      "Scheduled Runtime Lifecycle Load Monitor"
+    ],
     "scheduler": "github_actions",
-    "cadence": "10 1-23/2 * * *",
+    "cadence": "runAfter explicit workflow dispatch or PR label",
     "timezone": "UTC",
     "source": ".github/workflows/runtime-daytona-lifecycle-scheduled.yml",
-    "locator": "schedule:",
+    "locator": "workflow_dispatch:",
     "owner": "runtime",
     "criticality": "operational",
-    "purpose": "Exercise the canonical Daytona/Play runtime lifecycle against the exact healthy Preview target and retain load evidence.",
+    "purpose": "Exercise the canonical Daytona/Play runtime lifecycle against the exact healthy Preview target when explicitly requested and retain load evidence.",
     "successDefinition": "Target preparation, lifecycle bursts, correctness/latency checks, cleanup, and reporting complete.",
     "failureDefinition": "Target resolution, lifecycle execution, evaluation, cleanup, or reporting fails.",
     "startGraceMs": 600000,
@@ -361,19 +346,20 @@
   },
   {
     "id": "github.runtime-shape",
-    "name": "Twice-Daily Play Runtime Dataset Matrix",
+    "name": "On-Demand Play Runtime Dataset Matrix",
     "legacyNames": [
+      "Twice-Daily Play Runtime Dataset Matrix",
       "Every-Six-Hours Play Runtime Dataset Matrix",
       "Every-Two-Hours Play Runtime Dataset Matrix"
     ],
     "scheduler": "github_actions",
-    "cadence": "0 */12 * * *",
+    "cadence": "runAfter explicit workflow dispatch",
     "timezone": "UTC",
     "source": ".github/workflows/runtime-shape-hourly.yml",
-    "locator": "schedule:",
+    "locator": "workflow_dispatch:",
     "owner": "runtime",
     "criticality": "operational",
-    "purpose": "Run the exact-SHA Play runtime dataset-shape matrix across isolated Preview lanes.",
+    "purpose": "Run the exact-SHA Play runtime dataset-shape matrix across isolated Preview lanes when explicitly requested.",
     "successDefinition": "All required lanes pass and every lane is cleaned up with detailed results retained.",
     "failureDefinition": "A lane cannot prepare, violates a shape invariant, or cleanup/evidence is incomplete.",
     "startGraceMs": 600000,

package/dist/bundling-sources/shared_libs/observability/scheduled-work-manual.ts

@@ -44,10 +44,14 @@ export function isManuallyRunnableConvexCronJob(
   return manuallyRunnableConvexCronJobIds.has(jobId);
 }
 
-/** Preview cron roots run only when requested during a check. */
-export function isPreviewOnDemandScheduledWork(
+/** Non-production cron roots run only when explicitly requested. */
+export function isNonProductionOnDemandScheduledWork(
   jobId: string,
   environment: string,
 ): boolean {
-  return environment === 'preview' && isManuallyRunnableConvexCronJob(jobId);
+  const normalizedEnvironment = environment.trim().toLowerCase();
+  return (
+    ['dev', 'development', 'preview'].includes(normalizedEnvironment) &&
+    isManuallyRunnableConvexCronJob(jobId)
+  );
 }

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backend.ts

@@ -261,8 +261,11 @@ export type PlaySchedulerRunHandle = {
   observe(options?: {
     signal?: AbortSignal;
   }): AsyncIterable<PlaySchedulerProgressEvent>;
-  /** Cooperatively cancel the run. */
-  cancel(reason?: string): Promise<void>;
+  /**
+   * Cooperatively cancel the run. Resolves with the scheduler's typed
+   * outcome; a queued cancellation is an expected state, never an error.
+   */
+  cancel(reason?: string): Promise<PlaySchedulerCancelOutcome>;
   /** Inject an external event (HITL, webhook). */
   signal(payload: PlaySchedulerSignalPayload): Promise<void>;
   /** Block until terminal state and return final envelope. */
@@ -270,12 +273,17 @@ export type PlaySchedulerRunHandle = {
 };
 
 /**
- * The durable engine cancellation lane accepted the stop request, but the
- * scheduler run has not reached its authoritative terminal state yet.
- * Callers must surface this as an in-progress cancellation, never as success.
+ * Outcome of a scheduler cancel request.
+ *
+ * - `stopped`: the scheduler run is terminal (cancelled now, or it already
+ *   reached a terminal state before the request).
+ * - `cancelling`: the durable engine cancellation lane accepted the request,
+ *   but sandbox cleanup and the final run update are still pending. Callers
+ *   surface this as an in-progress cancellation, never as success or failure.
  */
-export const RUNTIME_SCHEDULER_CANCELLATION_PENDING_CODE =
-  'RUNTIME_SCHEDULER_CANCELLATION_PENDING';
+export type PlaySchedulerCancelOutcome =
+  | { state: 'stopped' }
+  | { state: 'cancelling' };
 
 export type PlaySchedulerSignalPayload = {
   kind: 'integration_event' | 'cancel' | 'custom';

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/absurd.ts

@@ -25,6 +25,7 @@ import { PLAY_ADMISSION_MAX_ACTIVE_LIFECYCLES } from '../admission-transport-pol
 import {
   PLAY_SCHEDULER_BACKENDS,
   type PlaySchedulerBackend,
+  type PlaySchedulerCancelOutcome,
   type PlaySchedulerRunHandle,
   type PlaySchedulerSubmitInput,
 } from '../scheduler-backend';
@@ -46,7 +47,6 @@ import {
   withRuntimeSchedulerClient,
   withRuntimeSchedulerTransaction,
 } from './postgres-pool';
-import { RUNTIME_SCHEDULER_CANCELLATION_PENDING_CODE } from '../scheduler-backend';
 import { resolveRuntimeSchedulerSchemaEnv } from './runtime-scheduler-schema';
 import { withRuntimeSchedulerSubmitAdmission } from './submit-admission';
 import {
@@ -75,7 +75,10 @@ export type AbsurdSchedulerBackendOptions = AbsurdSchedulerOptions & {
   queueSuffix?: string | null;
 };
 
-const cancellationFlights = new Map<string, Promise<void>>();
+const cancellationFlights = new Map<
+  string,
+  Promise<PlaySchedulerCancelOutcome>
+>();
 const ABSURD_CANCEL_TASK_SAVEPOINT = 'deepline_cancel_absurd_task';
 
 function quotePostgresIdentifier(identifier: string): string {
@@ -127,8 +130,8 @@ async function cancelAbsurdTaskIfPresent(
 
 function runCancellationSingleFlight(
   key: string,
-  operation: () => Promise<void>,
-): Promise<void> {
+  operation: () => Promise<PlaySchedulerCancelOutcome>,
+): Promise<PlaySchedulerCancelOutcome> {
   const existing = cancellationFlights.get(key);
   if (existing) return existing;
   const flight = operation().finally(() => {
@@ -285,20 +288,17 @@ function absurdRunHandle(input: {
       { maxAttempts: 1 },
     );
 
-  const requestCancellation = async (reason?: string) => {
-    await runCancellationSingleFlight(cancellationKey, async () => {
-      const queued = await queueCancellation(reason);
-      if (queued) {
-        const error = new Error(
-          `Cancellation queued for ${input.runId}; sandbox cleanup and final run update are pending.`,
-        );
-        Object.assign(error, {
-          code: RUNTIME_SCHEDULER_CANCELLATION_PENDING_CODE,
-        });
-        throw error;
-      }
-    });
-  };
+  // A queued cancellation is the normal Absurd outcome: the worker owns
+  // sandbox cleanup and the final run update. Report it as a typed state, not
+  // an error; `stopped` means the scheduler result was already terminal.
+  const requestCancellation = (
+    reason?: string,
+  ): Promise<PlaySchedulerCancelOutcome> =>
+    runCancellationSingleFlight(cancellationKey, async () =>
+      (await queueCancellation(reason))
+        ? { state: 'cancelling' }
+        : { state: 'stopped' },
+    );
 
   return {
     ...delegate,

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/postgres.ts

@@ -20098,6 +20098,7 @@ export function postgresSchedulerRunHandle(
           priority: 'critical',
         },
       );
+      return { state: 'stopped' };
     },
     signal: async (payload) => {
       if (payload.kind === 'cancel') {