deepline 0.1.211 → 0.1.212

package/dist/bundling-sources/apps/play-runner-workers/src/entry.ts

@@ -68,6 +68,7 @@ import {
 } from './child-play-await';
 import { submitChildPlayThroughCoordinator } from './child-play-submit';
 import { isRetryableWorkerRuntimeApiError } from './runtime-api-retry';
+import { formatCustomerConsoleValue } from './runtime/customer-console';
 import {
   attachToolResultListDataset,
   createToolExecuteResult,
@@ -116,6 +117,7 @@ import {
   isQueryResultDatasetTool,
 } from '../../../shared_libs/play-runtime/query-result-dataset';
 import { DEDUPE_DUPLICATE_KEY_SAMPLE_CAP } from '../../../shared_libs/play-runtime/map-row-identity';
+import { createRuntimeDatasetId } from '../../../shared_libs/play-runtime/dataset-id';
 import {
   getTopLevelPipelineSubsteps,
   getCompiledPipelineSubsteps,
@@ -300,7 +302,7 @@ import type {
   LiveNodeProgressMap,
   LiveNodeProgressSnapshot,
 } from './runtime/live-progress';
-import { extractErrorBilling } from './runtime/tool-http-errors';
+import { extractErrorBilling, ToolHttpError } from './runtime/tool-http-errors';
 import {
   WorkflowAbortError,
   isAbortLikeError,
@@ -324,6 +326,55 @@ import type { PlayRunInputPayload } from '../../../shared_libs/play-runtime/sche
 // @ts-ignore - virtual module substituted by esbuild plugin at bundle time.
 import playFn from 'deepline-play-entry';
 
+const customerConsoleStorage = new AsyncLocalStorage<
+  (message: string) => void
+>();
+
+type CustomerConsoleGlobal = typeof globalThis & {
+  __deeplineCaptureCustomerConsole?: (
+    method: string,
+    args: unknown[],
+  ) => unknown;
+};
+
+(globalThis as CustomerConsoleGlobal).__deeplineCaptureCustomerConsole = (
+  method,
+  args,
+) => {
+  const log = customerConsoleStorage.getStore();
+  if (log) {
+    assertNoSecretTaint(args, `console.${method}`);
+    const message = args.map(formatCustomerConsoleValue).join(' ');
+    log(`[console.${method}] ${message}`.slice(0, 2_000));
+  }
+};
+
+function runCustomerPlay(
+  ctx: unknown,
+  input: PlayRunInputPayload,
+): Promise<unknown> {
+  return customerConsoleStorage.run(
+    (ctx as { log(message: string): void }).log,
+    () => (playFn as typeof runCustomerPlay)(ctx, input),
+  );
+}
+
+function runtimeDatasetIdentity(playName: string, tableNamespace: string) {
+  return {
+    datasetId: createRuntimeDatasetId(playName, tableNamespace),
+    path: `datasets.${tableNamespace}`,
+    tableNamespace,
+  };
+}
+
+function datasetAvailableLog(
+  runId: string,
+  dataset: ReturnType<typeof runtimeDatasetIdentity>,
+  count: number,
+): string {
+  return `Dataset ${dataset.path} available: ${count} persisted rows; export: deepline runs export ${runId} --dataset ${dataset.path} --out ${dataset.tableNamespace}.csv`;
+}
+
 type RunRequest = {
   runId: string;
   callbackUrl: string;
@@ -999,6 +1050,17 @@ type WorkerCtxCallbacks = {
   }) => void | Promise<void>;
   onMapStarted?: (nodeId: string, at?: number) => void;
   onMapCompleted?: (nodeId: string, at?: number) => void;
+  onDatasetLifecycle?: (event: {
+    datasetId: string;
+    path: string;
+    tableNamespace: string;
+    phase: 'registered' | 'available' | 'failed';
+    persistedRows?: number;
+    succeededRows?: number;
+    failedRows?: number;
+    complete?: boolean;
+    at: number;
+  }) => void | Promise<void>;
   onToolCalled?: (toolId: string, at?: number) => void;
   onToolFailed?: (toolId: string, at?: number) => void;
 };
@@ -2073,6 +2135,7 @@ async function callToolDirect(
   while (true) {
     requestAttempt += 1;
     let res: Response;
+    const providerCallStartedAt = nowMs();
     try {
       const runtimeApiTimeout = resolveToolRuntimeApiTimeout({
         requestInput: input,
@@ -2161,8 +2224,11 @@ async function callToolDirect(
     } catch (error) {
       transportAttempt += 1;
       const message = error instanceof Error ? error.message : String(error);
-      lastError = new Error(
+      lastError = new ToolHttpError(
         `Tool ${toolId} transport failed calling ${path} for run ${req.runId} on attempt ${transportAttempt}/${TOOL_EXECUTE_TRANSPORT_MAX_ATTEMPTS}: ${message}`,
+        null,
+        0,
+        'repairable',
       );
       if (
         transportAttempt >= TOOL_EXECUTE_TRANSPORT_MAX_ATTEMPTS ||
@@ -2212,6 +2278,7 @@ async function callToolDirect(
       bodyText: text,
       retryAfterHeader: res.headers.get('retry-after'),
       transientHttpRetrySafe,
+      providerLatencyMs: nowMs() - providerCallStartedAt,
     });
     lastError = failure.error;
     if (failure.backpressureDelayMs !== null) {
@@ -4865,6 +4932,7 @@ function createMinimalWorkerCtx(
     };
 
     let totalRowsWritten = 0;
+    let datasetLifecycleRegistered = false;
 
     const volatileWorkflowChunkRows = new Map<
       number,
@@ -4915,6 +4983,22 @@ function createMinimalWorkerCtx(
         budgetMeter: workBudgetMeter,
         force: !!req.force,
       });
+      if (!datasetLifecycleRegistered) {
+        datasetLifecycleRegistered = true;
+        const dataset = runtimeDatasetIdentity(req.playName, name);
+        await callbacks?.onDatasetLifecycle?.({
+          ...dataset,
+          phase: 'registered',
+          complete: false,
+          at: nowMs(),
+        });
+        emitEvent({
+          type: 'log',
+          level: 'info',
+          message: `Dataset ${dataset.path} registered`,
+          ts: nowMs(),
+        });
+      }
       const activeRowAttempt = {
         attemptId: prepared.attemptId ?? rowAttempt.attemptId,
         attemptOwnerRunId:
@@ -6261,6 +6345,23 @@ function createMinimalWorkerCtx(
                 finalizedRowsWritten,
               ),
       });
+      const dataset = runtimeDatasetIdentity(req.playName, name);
+      const persistedRows = finalizedRowsWritten + totalRowsFailed;
+      await callbacks?.onDatasetLifecycle?.({
+        ...dataset,
+        phase: 'available',
+        persistedRows,
+        succeededRows: finalizedRowsWritten,
+        failedRows: totalRowsFailed,
+        complete: true,
+        at: completedAt,
+      });
+      emitEvent({
+        type: 'log',
+        level: totalRowsFailed > 0 ? 'warn' : 'info',
+        message: datasetAvailableLog(req.runId, dataset, persistedRows),
+        ts: completedAt,
+      });
       callbacks?.onMapCompleted?.(mapNodeId, completedAt);
       emitEvent({
         type: 'log',
@@ -6534,7 +6635,8 @@ function createMinimalWorkerCtx(
           if (chunkResult.fatalError) {
             throw new Error(
               `ctx.dataset("${name}") stopped after a runtime persistence failure ` +
-                `outside the retryable chunk step. Provider calls already executed for ` +
+                `outside the retryable chunk step. Circuit breaker prevented queued row ` +
+                `dispatch. Provider calls already executed for ` +
                 `${chunkResult.rowsExecuted} row(s), so the chunk was not retried. ` +
                 `Fix the runtime persistence cause and re-run to resume. ` +
                 `First error: ${chunkResult.fatalError}`,
@@ -7607,9 +7709,7 @@ async function handleRun(request: Request, env: WorkerEnv): Promise<Response> {
       captureHarnessBinding(env);
       await probeHarnessOnce(env, runPrefix);
       const ctx = createMinimalWorkerCtx(req, emit, env);
-      const result = await (
-        playFn as (ctx: unknown, input: PlayRunInputPayload) => Promise<unknown>
-      )(ctx, req.runtimeInput);
+      const result = await runCustomerPlay(ctx, req.runtimeInput);
       emit({
         type: 'result',
         result,
@@ -8023,6 +8123,17 @@ async function executeRunRequest(
     },
     onMapStarted: (nodeId, at) => stepLifecycle?.onMapStarted(nodeId, at),
     onMapCompleted: (nodeId, at) => stepLifecycle?.onMapCompleted(nodeId, at),
+    onDatasetLifecycle: async (event) => {
+      const { at, ...dataset } = event;
+      pendingLedgerEvents.push({
+        ...dataset,
+        type: 'dataset.lifecycle',
+        runId: req.runId,
+        source: 'worker',
+        occurredAt: at,
+      });
+      await flushLedgerEvents(event.complete === true);
+    },
     onToolCalled: (toolId, at) => stepLifecycle?.onToolCalled(toolId, at),
     onToolFailed: (toolId, at) => stepLifecycle?.onToolFailed(toolId, at),
   };
@@ -8089,9 +8200,7 @@ async function executeRunRequest(
       : null;
   try {
     const playStartedAt = nowMs();
-    const result = await (
-      playFn as (ctx: unknown, input: PlayRunInputPayload) => Promise<unknown>
-    )(ctx, req.runtimeInput);
+    const result = await runCustomerPlay(ctx, req.runtimeInput);
     recordRunnerPerfTrace({
       req,
       phase: 'runner.play_function',
@@ -8135,7 +8244,33 @@ async function executeRunRequest(
         ms: nowMs() - ledgerFlushWaitStartedAt,
       });
       const resultDatasetStartedAt = nowMs();
-      await persistResultDatasets(req, promoted.handles, serializedResult);
+      const persistedResultCounts = await persistResultDatasets(
+        req,
+        promoted.handles,
+        serializedResult,
+      );
+      for (const dataset of promoted.handles) {
+        if (dataset.datasetKind === 'map') continue;
+        const identity = runtimeDatasetIdentity(
+          req.playName,
+          dataset.tableNamespace,
+        );
+        const count = persistedResultCounts.get(dataset.tableNamespace) ?? 0;
+        pendingLedgerEvents.push({
+          ...identity,
+          type: 'dataset.lifecycle',
+          runId: req.runId,
+          source: 'worker',
+          occurredAt: nowMs(),
+          phase: 'available',
+          persistedRows: count,
+          succeededRows: count,
+          failedRows: 0,
+          complete: true,
+        });
+        appendRunLogLine(datasetAvailableLog(req.runId, identity, count));
+      }
+      await flushLedgerEvents(true);
       resultDatasetsPersisted = true;
       recordRunnerPerfTrace({
         req,
@@ -8599,8 +8734,9 @@ async function persistResultDatasets(
   req: RunRequest,
   resultDatasets: ProjectedResultDatasetHandle[],
   serializedResult: unknown,
-): Promise<void> {
+): Promise<Map<string, number>> {
   const persistedNamespaces = new Set<string>();
+  const persistedCounts = new Map<string, number>();
   for (const dataset of resultDatasets) {
     if (dataset.datasetKind === 'map') continue;
     const handle = dataset.handle as WorkerDatasetHandle<
@@ -8639,6 +8775,7 @@ async function persistResultDatasets(
       inputOffset += chunk.length;
     }
     persistedNamespaces.add(dataset.tableNamespace);
+    persistedCounts.set(dataset.tableNamespace, inputOffset);
   }
 
   const datasets = collectDatasetEnvelopes(serializedResult);
@@ -8672,7 +8809,9 @@ async function persistResultDatasets(
       attemptLeaseTtlMs: runtimeSheetAttemptLeaseTtlMs(req),
       userEmail: req.userEmail,
     });
+    persistedCounts.set(dataset.tableNamespace, dataset.rows.length);
   }
+  return persistedCounts;
 }
 
 const RESULT_DATASET_PERSIST_CHUNK_ROWS = 5_000;

package/dist/bundling-sources/apps/play-runner-workers/src/runtime/customer-console.ts

@@ -0,0 +1,23 @@
+export function formatCustomerConsoleValue(value: unknown): string {
+  if (typeof value === 'string') return value;
+  try {
+    if (value instanceof Error) return value.stack ?? value.message;
+    if (value && typeof value === 'object') {
+      const seen = new WeakSet<object>();
+      const serialized = JSON.stringify(value, (_key, nested) => {
+        if (typeof nested === 'symbol' || typeof nested === 'bigint') {
+          return nested.toString();
+        }
+        if (nested && typeof nested === 'object') {
+          if (seen.has(nested)) return '[Circular]';
+          seen.add(nested);
+        }
+        return nested;
+      });
+      if (serialized !== undefined) return serialized;
+    }
+    return String(value);
+  } catch {
+    return '[Unprintable]';
+  }
+}

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;
 

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/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.211',
+  version: '0.1.212',
   apiContract: '2026-06-dataset-handle-results-hard-cutover',
   supportPolicy: {
-    latest: '0.1.211',
+    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';