deepline 0.1.210 → 0.1.212

package/dist/bundling-sources/apps/play-runner-workers/src/runtime/tool-dispatch.ts

@@ -229,7 +229,7 @@ type WorkerToolCompletionResult =
 const WORKER_TOOL_BATCH_GRACE_MS = 250;
 const COMPLETE_RECEIPT_RETRY_BACKOFFS_MS = [1_000, 3_000, 9_000] as const;
 const COMPLETE_RECEIPT_RETRY_MIN_HEADROOM_MS = 10_000;
-export const WORKER_TOOL_COMPLETE_RECEIPTS_MAX_BATCH_BYTES = 8 * 1024 * 1024;
+export const WORKER_TOOL_COMPLETE_RECEIPTS_MAX_BATCH_BYTES = 32 * 1024 * 1024;
 export const WORKER_TOOL_COMPLETE_RECEIPTS_MAX_BATCH_MEMBERS = 500;
 export const WORKER_TOOL_RECEIPT_RECOVERY_MAX_CONCURRENT_READS = 25;
 
@@ -2000,8 +2000,14 @@ export class WorkerToolBatchScheduler {
     toolId: string,
     requests: WorkerToolBatchRequest[],
   ): Promise<void> {
+    const receiptPrepareStartedAt = this.options.nowMs();
     const { claimedRequests, deferredClaimedRequests } =
       await this.prepareDurableToolRequests(requests);
+    this.options.recordPerfTrace?.({
+      phase: 'runner.tool.receipt_prepare',
+      ms: this.options.nowMs() - receiptPrepareStartedAt,
+      extra: { toolId, requests: requests.length },
+    });
     await this.executeClaimedToolRequests(
       toolId,
       requests.length,
@@ -2071,6 +2077,7 @@ export class WorkerToolBatchScheduler {
         // charges tool budget, holds a global tool-concurrency slot, and
         // applies per-(org,provider) pacing before the call runs.
         let slot: { release: () => void };
+        const admissionStartedAt = this.options.nowMs();
         try {
           slot = await this.options.governor.acquireToolSlot(toolId, {
             signal: this.options.abortSignal,
@@ -2082,6 +2089,11 @@ export class WorkerToolBatchScheduler {
           );
           return;
         }
+        this.options.recordPerfTrace?.({
+          phase: 'runner.tool.admission',
+          ms: this.options.nowMs() - admissionStartedAt,
+          extra: { toolId, requests: 1 },
+        });
         try {
           let result: unknown;
           try {
@@ -2100,59 +2112,68 @@ export class WorkerToolBatchScheduler {
                   claimed,
                 })
               : null;
-            result = await executeWithWorkerReceiptHeartbeats({
-              playName: this.options.req.playName,
-              runId: this.options.req.runId,
-              runAttempt: this.options.req.runAttempt ?? 0,
-              ...(this.options.receiptStore
-                ? { receiptStore: this.options.receiptStore }
-                : {}),
-              budgetMeter: this.options.budgetMeter,
-              heartbeatIntervalMs:
-                this.options.runtimeReceiptHeartbeatIntervalMs,
-              targets: claimed.receiptKey
-                ? [
-                    {
-                      key: claimed.receiptKey,
-                      leaseId: claimed.receiptLeaseId,
-                    },
-                  ]
-                : [],
-              execute: () =>
-                this.options.executeTool({
-                  id: request.id,
-                  toolId,
-                  input: request.input,
-                  workflowStep: request.workflowStep,
-                  callbacks: this.options.callbacks,
-                  onProviderBackpressure: (retryAfterMs) =>
-                    this.reportBackpressure(toolId, retryAfterMs),
-                  onRetryAttempt: () =>
-                    this.options.governor.chargeBudget('retry'),
-                  transientHttpRetrySafe:
-                    toolContract?.retrySafeTransientHttp === true,
-                  ...(durableReceiptKey
-                    ? {
-                        durableCallReceiptKey: durableReceiptKey,
-                        executionAuthScopeDigest:
-                          request.executionAuthScopeDigest,
-                        providerIdempotencyKey:
-                          providerIdempotencyKeyForClaimed({
-                            req: this.options.req,
-                            claimed,
-                          }),
-                      }
-                    : {}),
-                  runtimeTimeoutMs: resolveWorkerToolRuntimeTimeoutMs(
-                    [claimed],
-                    {
-                      resolveOwnerTimeoutMs: (request) =>
-                        request.runtimeTimeoutMs,
-                    },
-                  ),
-                  directOptions: request.directOptions,
-                }),
-            });
+            const providerStartedAt = this.options.nowMs();
+            try {
+              result = await executeWithWorkerReceiptHeartbeats({
+                playName: this.options.req.playName,
+                runId: this.options.req.runId,
+                runAttempt: this.options.req.runAttempt ?? 0,
+                ...(this.options.receiptStore
+                  ? { receiptStore: this.options.receiptStore }
+                  : {}),
+                budgetMeter: this.options.budgetMeter,
+                heartbeatIntervalMs:
+                  this.options.runtimeReceiptHeartbeatIntervalMs,
+                targets: claimed.receiptKey
+                  ? [
+                      {
+                        key: claimed.receiptKey,
+                        leaseId: claimed.receiptLeaseId,
+                      },
+                    ]
+                  : [],
+                execute: () =>
+                  this.options.executeTool({
+                    id: request.id,
+                    toolId,
+                    input: request.input,
+                    workflowStep: request.workflowStep,
+                    callbacks: this.options.callbacks,
+                    onProviderBackpressure: (retryAfterMs) =>
+                      this.reportBackpressure(toolId, retryAfterMs),
+                    onRetryAttempt: () =>
+                      this.options.governor.chargeBudget('retry'),
+                    transientHttpRetrySafe:
+                      toolContract?.retrySafeTransientHttp === true,
+                    ...(durableReceiptKey
+                      ? {
+                          durableCallReceiptKey: durableReceiptKey,
+                          executionAuthScopeDigest:
+                            request.executionAuthScopeDigest,
+                          providerIdempotencyKey:
+                            providerIdempotencyKeyForClaimed({
+                              req: this.options.req,
+                              claimed,
+                            }),
+                        }
+                      : {}),
+                    runtimeTimeoutMs: resolveWorkerToolRuntimeTimeoutMs(
+                      [claimed],
+                      {
+                        resolveOwnerTimeoutMs: (request) =>
+                          request.runtimeTimeoutMs,
+                      },
+                    ),
+                    directOptions: request.directOptions,
+                  }),
+              });
+            } finally {
+              this.options.recordPerfTrace?.({
+                phase: 'runner.tool.provider',
+                ms: this.options.nowMs() - providerStartedAt,
+                extra: { toolId, requests: 1 },
+              });
+            }
           } catch (error) {
             if (error instanceof RuntimeLeaseLostError) {
               this.rejectRequests(claimed, error);
@@ -2173,10 +2194,16 @@ export class WorkerToolBatchScheduler {
             return;
           }
           try {
+            const receiptCompleteStartedAt = this.options.nowMs();
             this.settleRequests(
               claimed,
               await this.completeDurableToolRequest(claimed, result),
             );
+            this.options.recordPerfTrace?.({
+              phase: 'runner.tool.receipt_complete',
+              ms: this.options.nowMs() - receiptCompleteStartedAt,
+              extra: { toolId, requests: 1 },
+            });
           } catch (receiptError) {
             this.rejectRequests(claimed, receiptError);
           }
@@ -2261,12 +2288,22 @@ export class WorkerToolBatchScheduler {
         }
         // One provider call per batch -> one tool slot (budget + global
         // concurrency + per-(org,provider) pacing) around the whole batch.
+        const admissionStartedAt = this.options.nowMs();
         const slot = await this.options.governor.acquireToolSlot(
           batch.batchOperation,
           {
             signal: this.options.abortSignal,
           },
         );
+        this.options.recordPerfTrace?.({
+          phase: 'runner.tool.admission',
+          ms: this.options.nowMs() - admissionStartedAt,
+          extra: {
+            toolId: batch.batchOperation,
+            requests: batch.memberRequests.length,
+            batched: true,
+          },
+        });
         try {
           await this.markAdmittedToolRequestsRunning(batch.memberRequests);
           this.options.budgetMeter?.count('provider');
@@ -2281,54 +2318,69 @@ export class WorkerToolBatchScheduler {
             batchOperation: batch.batchOperation,
             receiptKeys,
           });
-          return await executeWithWorkerReceiptHeartbeats({
-            playName: this.options.req.playName,
-            runId: this.options.req.runId,
-            runAttempt: this.options.req.runAttempt ?? 0,
-            ...(this.options.receiptStore
-              ? { receiptStore: this.options.receiptStore }
-              : {}),
-            budgetMeter: this.options.budgetMeter,
-            heartbeatIntervalMs: this.options.runtimeReceiptHeartbeatIntervalMs,
-            targets: batch.memberRequests.map((member) => ({
-              key: member.receiptKey,
-              leaseId: member.receiptLeaseId,
-            })),
-            execute: () =>
-              this.options.executeTool({
-                id: `batch:${batch.memberRequests.map((request) => request.request.id).join('|')}`,
-                toolId: batch.batchOperation,
-                input: batch.batchPayload,
-                callbacks: this.options.callbacks,
-                onProviderBackpressure: (retryAfterMs) =>
-                  this.reportBackpressure(input.sourceToolId, retryAfterMs),
-                onRetryAttempt: () =>
-                  this.options.governor.chargeBudget('retry'),
-                transientHttpRetrySafe:
-                  toolContract?.retrySafeTransientHttp === true,
-                durableCallReceiptKey: aggregateReceiptKey,
-                executionAuthScopeDigest:
-                  batch.memberRequests[0]?.request.executionAuthScopeDigest ??
-                  null,
-                providerIdempotencyKey: buildBatchProviderIdempotencyKey({
-                  aggregateReceiptKey,
-                  receiptKeys,
-                  providerIdempotencyKeys: batch.memberRequests.map((member) =>
-                    providerIdempotencyKeyForClaimed({
-                      req: this.options.req,
-                      claimed: member,
-                    }),
+          const providerStartedAt = this.options.nowMs();
+          try {
+            return await executeWithWorkerReceiptHeartbeats({
+              playName: this.options.req.playName,
+              runId: this.options.req.runId,
+              runAttempt: this.options.req.runAttempt ?? 0,
+              ...(this.options.receiptStore
+                ? { receiptStore: this.options.receiptStore }
+                : {}),
+              budgetMeter: this.options.budgetMeter,
+              heartbeatIntervalMs:
+                this.options.runtimeReceiptHeartbeatIntervalMs,
+              targets: batch.memberRequests.map((member) => ({
+                key: member.receiptKey,
+                leaseId: member.receiptLeaseId,
+              })),
+              execute: () =>
+                this.options.executeTool({
+                  id: `batch:${batch.memberRequests.map((request) => request.request.id).join('|')}`,
+                  toolId: batch.batchOperation,
+                  input: batch.batchPayload,
+                  callbacks: this.options.callbacks,
+                  onProviderBackpressure: (retryAfterMs) =>
+                    this.reportBackpressure(input.sourceToolId, retryAfterMs),
+                  onRetryAttempt: () =>
+                    this.options.governor.chargeBudget('retry'),
+                  transientHttpRetrySafe:
+                    toolContract?.retrySafeTransientHttp === true,
+                  durableCallReceiptKey: aggregateReceiptKey,
+                  executionAuthScopeDigest:
+                    batch.memberRequests[0]?.request.executionAuthScopeDigest ??
+                    null,
+                  providerIdempotencyKey: buildBatchProviderIdempotencyKey({
+                    aggregateReceiptKey,
+                    receiptKeys,
+                    providerIdempotencyKeys: batch.memberRequests.map(
+                      (member) =>
+                        providerIdempotencyKeyForClaimed({
+                          req: this.options.req,
+                          claimed: member,
+                        }),
+                    ),
+                  }),
+                  runtimeTimeoutMs: resolveWorkerToolRuntimeTimeoutMs(
+                    batch.memberRequests,
+                    {
+                      resolveOwnerTimeoutMs: (request) =>
+                        request.runtimeTimeoutMs,
+                    },
                   ),
                 }),
-                runtimeTimeoutMs: resolveWorkerToolRuntimeTimeoutMs(
-                  batch.memberRequests,
-                  {
-                    resolveOwnerTimeoutMs: (request) =>
-                      request.runtimeTimeoutMs,
-                  },
-                ),
-              }),
-          });
+            });
+          } finally {
+            this.options.recordPerfTrace?.({
+              phase: 'runner.tool.provider',
+              ms: this.options.nowMs() - providerStartedAt,
+              extra: {
+                toolId: batch.batchOperation,
+                requests: batch.memberRequests.length,
+                batched: true,
+              },
+            });
+          }
         } finally {
           slot.release();
         }
@@ -2389,6 +2441,7 @@ export class WorkerToolBatchScheduler {
               : entry.request.memberRequests.map(() => null);
           let completedResults: WorkerToolCompletionResult[];
           try {
+            const receiptCompleteStartedAt = this.options.nowMs();
             completedResults = await this.completeDurableToolRequests(
               entry.request.memberRequests.map((claimed, index) => ({
                 claimed,
@@ -2399,6 +2452,15 @@ export class WorkerToolBatchScheduler {
                 ),
               })),
             );
+            this.options.recordPerfTrace?.({
+              phase: 'runner.tool.receipt_complete',
+              ms: this.options.nowMs() - receiptCompleteStartedAt,
+              extra: {
+                toolId: entry.request.batchOperation,
+                requests: entry.request.memberRequests.length,
+                batched: true,
+              },
+            });
           } catch (receiptError) {
             for (const claimed of entry.request.memberRequests) {
               this.rejectRequests(claimed, receiptError);

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

@@ -282,9 +282,23 @@ export type RunsListOptions = {
   limit?: number;
 };
 
+/** Options for `client.runs.get(...)`. */
+export type RunsGetOptions = {
+  /** Return the raw status payload instead of the compact package. */
+  full?: 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). */
+  failedLogLimit?: number;
+};
+
+const RUNS_FAILED_LOG_LIMIT = 20;
+
 /** Streaming options for `client.runs.tail(...)`. */
 export type RunsTailOptions = {
   signal?: AbortSignal;
+  /** Observe each canonical live event while `tail` waits for terminal state. */
+  onEvent?: (event: PlayLiveEvent) => void;
   /**
    * Called before each stream reconnect. Server stream windows are finite, so
    * long runs reconnect with backoff until a terminal status is observed.
@@ -308,6 +322,8 @@ export type RunsLogsOptions = {
   limit?: number;
   /** Fetch every stored log line, paginating to the full totalCount. */
   all?: boolean;
+  /** Select the bounded failure view; truncated runs degrade explicitly. */
+  failed?: boolean;
 };
 
 /** Persisted log response for one play run. */
@@ -320,6 +336,14 @@ export type RunsLogsResult = {
   truncated: boolean;
   hasMore: boolean;
   entries: string[];
+  /** Selected public log view. */
+  view?: 'tail' | 'failed' | 'all';
+  /** Whether entries are terminal context or the last pre-truncation lines. */
+  association?: 'terminal_failure_window' | 'retained_before_truncation';
+  /** Loud explanation when the terminal failure window was not retained. */
+  warning?: string;
+  /** Exact follow-up command when the selected view is degraded. */
+  next?: { logs: string };
   /**
    * True when the run crossed the Run Log Stream retention cap: `totalCount`
    * keeps counting, but stored line bodies end at a loud truncation marker.
@@ -342,6 +366,10 @@ type RunLogsPageResponse = {
   lastSeq: number | null;
   hasMore: boolean;
   nextAfterSeq: number | null;
+  view?: 'failed';
+  association?: 'terminal_failure_window' | 'retained_before_truncation';
+  warning?: string;
+  next?: { logs: string };
 };
 
 /** One persisted runtime-sheet row returned by `client.runs.exportDatasetRows(...)`. */
@@ -395,7 +423,7 @@ export type PlaySecretMetadata = {
  */
 export type RunsNamespace = {
   /** Get current run status by public run id. */
-  get: (runId: string, options?: { full?: boolean }) => Promise<PlayStatus>;
+  get: (runId: string, options?: RunsGetOptions) => Promise<PlayStatus>;
   /** List runs for one play, optionally filtered by status. */
   list: (options: RunsListOptions) => Promise<PlayRunListItem[]>;
   /** Stream run events and return the latest/terminal run status. */
@@ -2469,7 +2497,7 @@ export class DeeplineClient {
    */
   async getRunStatus(
     runId: string,
-    options?: { full?: boolean },
+    options?: RunsGetOptions,
   ): Promise<PlayStatus> {
     const params = new URLSearchParams();
     if (options?.full === true) {
@@ -2479,7 +2507,55 @@ export class DeeplineClient {
     const response = await this.http.get<Record<string, unknown>>(
       `/api/v2/runs/${encodeURIComponent(runId)}${query}`,
     );
-    return normalizePlayStatus(response);
+    const status = normalizePlayStatus(response);
+    if (options?.failedLogs !== true || status.status !== 'failed') {
+      return status;
+    }
+    const requestedFailedLogLimit =
+      typeof options.failedLogLimit === 'number' &&
+      Number.isFinite(options.failedLogLimit)
+        ? Math.max(1, Math.floor(options.failedLogLimit))
+        : RUNS_FAILED_LOG_LIMIT;
+    let failedLogs: RunsLogsResult;
+    let failedLogsLoaded = true;
+    try {
+      failedLogs = await this.getRunLogs(runId, {
+        failed: true,
+        limit: Math.min(RUNS_FAILED_LOG_LIMIT, requestedFailedLogLimit),
+      });
+    } catch (error) {
+      failedLogsLoaded = false;
+      const retryCommand = `deepline runs get ${runId} --log-failed --json`;
+      const reason =
+        error instanceof Error && error.message.trim()
+          ? ` (${error.message.trim().slice(0, 500)})`
+          : '';
+      failedLogs = {
+        runId,
+        totalCount: 0,
+        returnedCount: 0,
+        firstSequence: null,
+        lastSequence: null,
+        truncated: false,
+        hasMore: false,
+        entries: [],
+        view: 'failed',
+        warning: `Failed logs could not be loaded${reason}. The run status and persisted datasets are still available.`,
+        next: { logs: retryCommand },
+      };
+    }
+    return {
+      ...status,
+      failedLogs: {
+        ...failedLogs,
+        view: 'failed' as const,
+        ...(failedLogsLoaded
+          ? {
+              association: failedLogs.association ?? 'terminal_failure_window',
+            }
+          : {}),
+      },
+    };
   }
 
   /**
@@ -2657,6 +2733,7 @@ export class DeeplineClient {
       onNotice: options?.onNotice,
       fallback: 'none',
     })) {
+      options?.onEvent?.(event);
       const status = updatePlayLiveStatusState(state, event);
       if (!status || !TERMINAL_PLAY_STATUSES.has(status.status)) {
         continue;
@@ -2725,6 +2802,7 @@ export class DeeplineClient {
           mode: 'cli',
           signal: options?.signal,
         })) {
+          options?.onEvent?.(event);
           sawEvent = true;
           const status = updatePlayLiveStatusState(state, event);
           if (!status || !TERMINAL_PLAY_STATUSES.has(status.status)) {
@@ -2786,6 +2864,42 @@ export class DeeplineClient {
     runId: string,
     options?: RunsLogsOptions,
   ): Promise<RunsLogsResult> {
+    if (options?.all === true && options.failed === true) {
+      throw new DeeplineError(
+        'runs.logs cannot combine all and failed views.',
+        undefined,
+        'INVALID_RUN_LOG_VIEW',
+      );
+    }
+    if (options?.failed === true) {
+      const requestedLimit =
+        typeof options.limit === 'number' &&
+        Number.isFinite(options.limit) &&
+        options.limit > 0
+          ? Math.trunc(options.limit)
+          : RUNS_FAILED_LOG_LIMIT;
+      const failedLimit = Math.min(RUNS_FAILED_LOG_LIMIT, requestedLimit);
+      const page = await this.http.get<RunLogsPageResponse>(
+        `/api/v2/runs/${encodeURIComponent(runId)}/logs?view=failed&limit=${failedLimit}`,
+      );
+      return {
+        runId: page.runId,
+        totalCount: page.totalLogCount,
+        returnedCount: page.entries.length,
+        firstSequence: page.firstSeq,
+        lastSequence: page.lastSeq,
+        // The failed view is a complete designed window, not a pageable slice.
+        // `truncated` means retention loss here; association/warning explain it.
+        truncated: page.logsTruncated === true,
+        hasMore: false,
+        entries: page.entries.map((entry) => entry.line),
+        view: page.view ?? 'failed',
+        association: page.association ?? 'terminal_failure_window',
+        ...(page.warning ? { warning: page.warning } : {}),
+        ...(page.next ? { next: page.next } : {}),
+        ...(page.logsTruncated ? { logsTruncated: true } : {}),
+      };
+    }
     const limit = options?.all
       ? Number.MAX_SAFE_INTEGER
       : typeof options?.limit === 'number' &&
@@ -2830,6 +2944,7 @@ export class DeeplineClient {
       truncated: entries.length < probe.totalLogCount,
       hasMore: lastSequence !== null && lastSequence < lastStoredSeq,
       entries: entries.map((entry) => entry.line),
+      view: options?.all ? 'all' : 'tail',
       ...(probe.logsTruncated ? { logsTruncated: true } : {}),
     };
   }

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

@@ -173,6 +173,8 @@ export type PlayBindings = {
    * older clients can continue to register revisions during the migration.
    */
   description?: string;
+  /** Allow compilers to bundle this named handler directly without a child run. */
+  inline?: boolean;
   /** Optional per-run billing controls enforced by the runtime. */
   billing?: {
     /** Stop the run before a billed action would push total run credits above this cap. */

package/dist/bundling-sources/sdk/src/plays/bundle-play-file.ts

@@ -39,7 +39,7 @@ export type {
 
 export { extractDefinedPlayName } from '../../../shared_libs/plays/bundling/index.js';
 
-const PLAY_BUNDLE_CACHE_VERSION = 30;
+const PLAY_BUNDLE_CACHE_VERSION = 31;
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const SDK_PACKAGE_ROOT = resolve(MODULE_DIR, '..', '..');
 const SOURCE_REPO_ROOT = resolve(SDK_PACKAGE_ROOT, '..');

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

@@ -106,10 +106,10 @@ export const SDK_RELEASE = {
   // 0.1.154 removes the short-lived generated enrich StepOptions recompute
   // fields shipped in 0.1.153.
   // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting.
-  version: '0.1.210',
+  version: '0.1.212',
   apiContract: '2026-06-dataset-handle-results-hard-cutover',
   supportPolicy: {
-    latest: '0.1.210',
+    latest: '0.1.212',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
     commandMinimumSupported: [

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

@@ -463,6 +463,14 @@ export type PlayRunActionPackage =
       runId: string;
       datasetPath: string;
       format: 'csv';
+    }
+  | {
+      kind: 'deepline_run_logs';
+      runId: string;
+      view: 'failed' | 'tail';
+      limit: number;
+      command: string;
+      api: { method: 'GET'; path: string };
     };
 
 /**
@@ -493,11 +501,30 @@ export interface PlayRunPackage {
   steps: Array<Record<string, unknown>>;
   /** Named output summaries, including dataset handles and scalar outputs. */
   outputs: Record<string, Record<string, unknown>>;
+  /** Every durable Dataset Handle explicitly registered by this run. */
+  datasets?: Array<{
+    kind: 'dataset';
+    datasetId?: string;
+    path: string;
+    tableNamespace?: string;
+    rowCount?: number;
+    recovered?: true;
+    preview?: Record<string, unknown>;
+    actions?: Record<string, PlayRunActionPackage>;
+  }>;
+  /** Small retained tail of customer and runtime logs; fetch the full stream through `runs.logs`. */
+  logs?: {
+    tail: string[];
+    totalCount: number;
+    returnedCount: number;
+    truncated?: boolean;
+  };
   /** Follow-up actions a caller can perform against the run. */
   next?: {
     inspect?: PlayRunActionPackage;
     export?: PlayRunActionPackage;
     query?: PlayRunActionPackage;
+    logs?: PlayRunActionPackage;
   };
 }
 
@@ -524,6 +551,8 @@ export interface PlayStatus {
   apiVersion?: number;
   /** Saved play name for this run, when available. */
   name?: string;
+  /** Exact saved revision launched for this run, when applicable. */
+  revisionId?: string;
   /** Alias for `name` used by run/result APIs. */
   playName?: string;
   /** Dashboard URL for inspecting the play and its run output in the app. */
@@ -564,6 +593,24 @@ export interface PlayStatus {
   } | null;
   /** Structured follow-up actions for inspect/query/export. */
   next?: PlayRunPackage['next'] | Record<string, unknown>;
+  /** Bounded terminal-failure log window requested by `runs.get`. */
+  failedLogs?: {
+    runId: string;
+    totalCount: number;
+    returnedCount: number;
+    firstSequence: number | null;
+    lastSequence: number | null;
+    truncated: boolean;
+    hasMore: boolean;
+    entries: string[];
+    view?: 'failed';
+    association?: 'terminal_failure_window' | 'retained_before_truncation';
+    warning?: string;
+    next?: { logs: string };
+    logsTruncated?: boolean;
+  };
+  /** Exact ordinary `plays run` command that can rerun a failed execution. */
+  rerunCommand?: string;
 }
 
 export type LiveEventScope = 'play' | 'agent';