deepline 0.3.409 → 0.3.410

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

@@ -0,0 +1,431 @@
+/**
+ * Remote Play operations shared by the full SDK client and imported Play handles.
+ * Handles resolve configuration lazily; a submitted job keeps its original client.
+ */
+import { resolveConfig } from '../config';
+import { DeeplineError } from '../errors';
+import { HttpClient } from '../http';
+import { SDK_API_MAJOR } from '../version';
+import type {
+  DeeplineClientOptions,
+  ClearPlayHistoryRequest,
+  ClearPlayHistoryResult,
+  PlayDetail,
+  PlayRevisionSummary,
+  PlayRunListItem,
+  PlayRunStart,
+  PlayStatus,
+  PublishPlayVersionRequest,
+  PublishPlayVersionResult,
+  StartPlayRunRequest,
+  StopPlayRunResult,
+} from '../types';
+import {
+  isPlayRunPackage,
+  startPlayRun,
+  type ResolvedStartPlayRunRequest,
+  type PlayRunStartOptions,
+} from './run-request';
+import {
+  RUNTIME_ENVIRONMENT_TOKEN_HEADER,
+  RETAINED_PIPELINE_RECEIVERS_HEADER,
+} from '../../../shared_libs/play-runtime/coordinator-headers.js';
+import {
+  normalizePlayRuntimeEnvironment,
+  normalizePlayRuntimeNamespace,
+  normalizePlayRuntimeSandboxPlacementPolicy,
+  normalizePlayRuntimeSelection,
+  type PlayRuntimeSelection,
+} from '../../../shared_libs/play-runtime/runtime-environment.js';
+import { decodePlayRunPublicStatus } from '../../../shared_libs/play-runtime/run-lifecycle-policy.js';
+
+export function normalizePlayRunIntegrationMode(
+  value: unknown,
+): 'live' | 'eval_stub' | 'fixture' | undefined {
+  if (value === 'live' || value === 'eval_stub' || value === 'fixture') {
+    return value;
+  }
+  return undefined;
+}
+
+export type ClientEnvironment = Readonly<Record<string, string | undefined>>;
+
+function resolvePlayRunIntegrationMode(
+  request: StartPlayRunRequest,
+  env: ClientEnvironment,
+): 'live' | 'eval_stub' | 'fixture' | undefined {
+  return normalizePlayRunIntegrationMode(
+    request.integrationMode ?? env.DEEPLINE_EVAL_INTEGRATION_MODE,
+  );
+}
+
+function resolvePlayRunRuntimeSelection(
+  request: StartPlayRunRequest,
+  env: ClientEnvironment,
+): PlayRuntimeSelection | undefined {
+  if (request.runtime !== undefined) {
+    const runtime = normalizePlayRuntimeSelection(request.runtime);
+    if (!runtime) {
+      throw new DeeplineError(
+        'runtime must be { environment: "preview", namespace, backend?: "daytona" | "modal", sandboxPlacementPolicy?: "policy_name@1" } with namespace matching ^[a-z][a-z0-9-]{0,30}$.',
+        undefined,
+        'INVALID_RUNTIME_SELECTION',
+      );
+    }
+    return runtime;
+  }
+  // These variables select where the app executes a run, not which app the
+  // SDK calls. DEEPLINE_API_BASE_URL still chooses the app host. Environment
+  // opts into remote preview routing, namespace names the isolated lane, and
+  // the token only authorizes that selection. Omitting all three leaves the
+  // app free to use its native runtime (local for a local app, prod for prod).
+  const configured = env.DEEPLINE_RUNTIME_ENVIRONMENT?.trim();
+  const configuredNamespace = env.DEEPLINE_RUNTIME_NAMESPACE?.trim();
+  const configuredToken = env.DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN?.trim();
+  const configuredPlacementPolicy =
+    env.DEEPLINE_RUNTIME_SANDBOX_PLACEMENT_POLICY?.trim();
+  if (!configured) {
+    if (configuredNamespace || configuredToken || configuredPlacementPolicy) {
+      // Name the variables that are actually set. This branch is almost always
+      // hit by a stale value auto-loaded from a .env/.env.local rather than by
+      // a deliberate export, so the message has to say where to look and how
+      // to run the command anyway.
+      const present: string[] = [];
+      if (configuredNamespace) present.push('DEEPLINE_RUNTIME_NAMESPACE');
+      if (configuredToken) present.push('DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN');
+      if (configuredPlacementPolicy) {
+        present.push('DEEPLINE_RUNTIME_SANDBOX_PLACEMENT_POLICY');
+      }
+      const isPlural = present.length > 1;
+      throw new DeeplineError(
+        [
+          `Incomplete play runtime selection: ${present.join(' and ')} ${isPlural ? 'are' : 'is'} set but DEEPLINE_RUNTIME_ENVIRONMENT is not.`,
+          'Preview routing requires DEEPLINE_RUNTIME_ENVIRONMENT=preview together with DEEPLINE_RUNTIME_NAMESPACE; the token alone authorizes nothing.',
+          `If you did not export ${isPlural ? 'these' : 'this'} yourself, ${isPlural ? 'they were' : 'it was'} most likely auto-loaded from a .env or .env.local in the current directory (bun loads those automatically, and in a git worktree .env.local is usually a symlink to the main checkout).`,
+          `To run against the app-native runtime, clear ${isPlural ? 'them' : 'it'} for this command: ${present.map((name) => `${name}=`).join(' ')} <your deepline command>`,
+        ].join('\n'),
+        undefined,
+        'INVALID_RUNTIME_ENVIRONMENT',
+      );
+    }
+    return undefined;
+  }
+  const environment = normalizePlayRuntimeEnvironment(configured);
+  if (!environment) {
+    throw new DeeplineError(
+      `DEEPLINE_RUNTIME_ENVIRONMENT supports only explicit preview selection. Received "${configured}". Omit it to use the app-native runtime.`,
+      undefined,
+      'INVALID_RUNTIME_ENVIRONMENT',
+    );
+  }
+  const namespace = normalizePlayRuntimeNamespace(configuredNamespace);
+  if (!namespace) {
+    throw new DeeplineError(
+      'DEEPLINE_RUNTIME_NAMESPACE is required for preview and must match ^[a-z][a-z0-9-]{0,30}$.',
+      undefined,
+      'INVALID_RUNTIME_NAMESPACE',
+    );
+  }
+  const configuredBackendValue = env.DEEPLINE_PLAY_RUNNER_BACKEND?.trim();
+  const configuredBackend =
+    configuredBackendValue === 'daytona' || configuredBackendValue === 'modal'
+      ? configuredBackendValue
+      : undefined;
+  if (configuredBackendValue && !configuredBackend) {
+    throw new DeeplineError(
+      `DEEPLINE_PLAY_RUNNER_BACKEND must be daytona or modal for preview runtime selection. Received "${configuredBackendValue}".`,
+      undefined,
+      'INVALID_RUNTIME_BACKEND',
+    );
+  }
+  if (
+    configuredPlacementPolicy &&
+    !normalizePlayRuntimeSandboxPlacementPolicy(configuredPlacementPolicy)
+  ) {
+    throw new DeeplineError(
+      `DEEPLINE_RUNTIME_SANDBOX_PLACEMENT_POLICY must be a versioned placement policy id such as daytona_only@1. Received "${configuredPlacementPolicy}".`,
+      undefined,
+      'INVALID_RUNTIME_SANDBOX_PLACEMENT_POLICY',
+    );
+  }
+  return {
+    environment,
+    namespace,
+    ...(configuredBackend ? { backend: configuredBackend } : {}),
+    ...(configuredPlacementPolicy
+      ? { sandboxPlacementPolicy: configuredPlacementPolicy }
+      : {}),
+  };
+}
+
+/**
+ * Resolve the environment-derived run-start fields (eval integration mode,
+ * test policy overrides, preview runtime) into explicit request fields, in the
+ * order the SDK has always validated them. The shared body builder in
+ * `plays/run-request` never reads the environment.
+ */
+export function resolveStartPlayRunRequest(
+  request: StartPlayRunRequest,
+  env: ClientEnvironment,
+): {
+  request: ResolvedStartPlayRunRequest;
+  runtime: PlayRuntimeSelection | undefined;
+} {
+  const integrationMode = resolvePlayRunIntegrationMode(request, env);
+  const testPolicyOverrides =
+    request.testPolicyOverrides ?? parseEnvTestPolicyOverrides(env);
+  const runtime = resolvePlayRunRuntimeSelection(request, env);
+  const resolved: ResolvedStartPlayRunRequest = { ...request };
+  delete resolved.integrationMode;
+  delete resolved.runtime;
+  delete resolved.testPolicyOverrides;
+  if (integrationMode) resolved.integrationMode = integrationMode;
+  if (runtime) resolved.runtime = runtime;
+  if (testPolicyOverrides) resolved.testPolicyOverrides = testPolicyOverrides;
+  return { request: resolved, runtime };
+}
+
+export function runtimeSelectionHeaders(
+  runtime: PlayRuntimeSelection | undefined,
+  env: ClientEnvironment,
+): Record<string, string> | undefined {
+  if (!runtime) return undefined;
+  // Keep the credential out of the typed runtime payload. The app consumes it
+  // at the HTTP boundary and never forwards it to Fly, Absurd, or Daytona.
+  const token = env.DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN?.trim();
+  if (!token) {
+    throw new DeeplineError(
+      'DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN is required for explicit preview runtime selection.',
+      undefined,
+      'RUNTIME_ENVIRONMENT_TOKEN_REQUIRED',
+    );
+  }
+  const receivers = env.DEEPLINE_RUNTIME_RETAINED_PIPELINE_RECEIVERS?.trim();
+  return {
+    [RUNTIME_ENVIRONMENT_TOKEN_HEADER]: token,
+    ...(receivers ? { [RETAINED_PIPELINE_RECEIVERS_HEADER]: receivers } : {}),
+  };
+}
+
+function normalizeTestPolicyOverrides(
+  value: unknown,
+  source: string,
+): Record<string, unknown> {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  throw new DeeplineError(
+    `${source} must be a JSON object.`,
+    undefined,
+    'INVALID_TEST_POLICY_OVERRIDES',
+  );
+}
+
+function parseEnvTestPolicyOverrides(
+  env: ClientEnvironment,
+): Record<string, unknown> | undefined {
+  const raw = env.DEEPLINE_TEST_POLICY_OVERRIDES;
+  const trimmed = raw?.trim();
+  if (!trimmed) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch (error) {
+    const detail = error instanceof Error ? ` ${error.message}` : '';
+    throw new DeeplineError(
+      `DEEPLINE_TEST_POLICY_OVERRIDES must be valid JSON.${detail}`,
+      undefined,
+      'INVALID_TEST_POLICY_OVERRIDES',
+    );
+  }
+  return normalizeTestPolicyOverrides(parsed, 'DEEPLINE_TEST_POLICY_OVERRIDES');
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+export function normalizePlayStatus(raw: Record<string, unknown>): PlayStatus {
+  const runPackage = isPlayRunPackage(raw)
+    ? raw
+    : isPlayRunPackage(raw.package)
+      ? raw.package
+      : null;
+  const packageRun = runPackage?.run;
+  const rawStatus =
+    typeof raw.status === 'string'
+      ? raw.status
+      : typeof packageRun?.status === 'string'
+        ? packageRun.status
+        : null;
+  const status = decodePlayRunPublicStatus(rawStatus);
+  if (!status) {
+    throw new Error(
+      `Invalid play run lifecycle status in API response: ${JSON.stringify(rawStatus)}.`,
+    );
+  }
+  const runId =
+    typeof raw.runId === 'string'
+      ? raw.runId
+      : typeof raw.workflowId === 'string'
+        ? raw.workflowId
+        : (packageRun?.id ?? '');
+  const legacyOverview = runPackage?.overview ?? raw.overview;
+  const runStatus = runPackage?.runStatus ?? raw.runStatus;
+  return {
+    ...(raw as unknown as Omit<PlayStatus, 'runId' | 'status'>),
+    runId,
+    ...(isRecord(legacyOverview)
+      ? {
+          overview: legacyOverview as unknown as PlayStatus['overview'],
+        }
+      : {}),
+    ...(isRecord(runStatus)
+      ? { runStatus: runStatus as unknown as PlayStatus['runStatus'] }
+      : {}),
+    ...(runPackage
+      ? {
+          package: runPackage,
+          outputs: runPackage.outputs,
+        }
+      : {}),
+    status,
+  };
+}
+
+export class PlayClient {
+  constructor(
+    private readonly http: HttpClient,
+    private readonly environment: ClientEnvironment = process.env,
+  ) {}
+
+  async startPlayRun(
+    request: StartPlayRunRequest,
+    options?: PlayRunStartOptions,
+  ): Promise<PlayRunStart> {
+    const resolved = resolveStartPlayRunRequest(request, this.environment);
+    const headers = runtimeSelectionHeaders(resolved.runtime, this.environment);
+    return startPlayRun(
+      this.http,
+      resolved.request,
+      options?.cliAdmission
+        ? { ...headers, 'X-Deepline-API-Major': String(SDK_API_MAJOR) }
+        : headers,
+      options,
+    );
+  }
+
+  async getPlayStatus(
+    workflowId: string,
+    options?: { billing?: boolean; full?: boolean },
+  ): Promise<PlayStatus> {
+    const params = new URLSearchParams();
+    if (options?.billing === false) {
+      params.set('billing', 'false');
+    }
+    if (options?.full === true) {
+      params.set('full', 'true');
+    }
+    const query = params.size > 0 ? `?${params.toString()}` : '';
+    const response = await this.http.get<Record<string, unknown>>(
+      `/api/v2/runs/${encodeURIComponent(workflowId)}${query}`,
+    );
+    return normalizePlayStatus(response);
+  }
+
+  async cancelPlay(workflowId: string): Promise<void> {
+    await this.http.request(
+      `/api/v2/runs/${encodeURIComponent(workflowId)}/stop`,
+      { method: 'POST' },
+    );
+  }
+
+  async stopPlay(
+    workflowId: string,
+    options?: { reason?: string },
+  ): Promise<StopPlayRunResult> {
+    return this.http.post<StopPlayRunResult>(
+      `/api/v2/runs/${encodeURIComponent(workflowId)}/stop`,
+      options?.reason ? { reason: options.reason } : {},
+    );
+  }
+
+  async listPlayRuns(playName: string): Promise<PlayRunListItem[]> {
+    const encodedName = encodeURIComponent(playName);
+    const response = await this.http.get<{ runs: PlayRunListItem[] }>(
+      `/api/v2/plays/${encodedName}/runs`,
+    );
+    return response.runs ?? [];
+  }
+
+  async getPlay(
+    name: string,
+    options?: {
+      source?: 'working' | 'live' | `version:${number}`;
+      guidance?: boolean;
+    },
+  ): Promise<PlayDetail> {
+    const encodedName = encodeURIComponent(name);
+    const query = options?.source
+      ? `?include=source&revision=${encodeURIComponent(options.source)}`
+      : options?.guidance
+        ? '?include=guidance'
+        : '';
+    return this.http.get<PlayDetail>(`/api/v2/plays/${encodedName}${query}`);
+  }
+
+  async clearPlayHistory(
+    name: string,
+    request: ClearPlayHistoryRequest = {},
+  ): Promise<ClearPlayHistoryResult> {
+    const encodedName = encodeURIComponent(name);
+    return this.http.post<ClearPlayHistoryResult>(
+      `/api/v2/plays/${encodedName}/history/clear`,
+      request,
+    );
+  }
+
+  async listPlayVersions(
+    name: string,
+    options?: { full?: boolean },
+  ): Promise<PlayRevisionSummary[]> {
+    const encodedName = encodeURIComponent(name);
+    const suffix = options?.full ? '?full=true' : '';
+    const response = await this.http.get<{ versions: PlayRevisionSummary[] }>(
+      `/api/v2/plays/${encodedName}/versions${suffix}`,
+    );
+    return response.versions ?? [];
+  }
+
+  async publishPlayVersion(
+    name: string,
+    request: PublishPlayVersionRequest = {},
+  ): Promise<PublishPlayVersionResult> {
+    const encodedName = encodeURIComponent(name);
+    return this.http.post<PublishPlayVersionResult>(
+      `/api/v2/plays/${encodedName}/live`,
+      request,
+    );
+  }
+}
+
+export type PlayClientOperations = Pick<
+  PlayClient,
+  | 'getPlay'
+  | 'listPlayRuns'
+  | 'listPlayVersions'
+  | 'publishPlayVersion'
+  | 'clearPlayHistory'
+  | 'startPlayRun'
+  | 'getPlayStatus'
+  | 'cancelPlay'
+  | 'stopPlay'
+>;
+
+export function createPlayClient(options?: DeeplineClientOptions): PlayClient {
+  const config = resolveConfig(options);
+  return new PlayClient(
+    new HttpClient(config),
+    config.environment ?? process.env,
+  );
+}

package/dist/bundling-sources/sdk/src/plays/local-play-execution.ts

@@ -1,5 +1,5 @@
-import type { DeeplineClient } from '../client';
-import type { BundledPlayFileSuccess } from './bundle-play-file';
+import type { DeeplineClient } from '../client.js';
+import type { BundledPlayFileSuccess } from './bundle-play-file.js';
 
 export type LocalPlayGraph = {
   root: BundledPlayFileSuccess;

package/dist/bundling-sources/sdk/src/plays/run-request.ts

@@ -31,9 +31,12 @@ import type { PlayStagedFileRef } from './local-file-discovery';
 
 export { DeeplineError };
 
-/** The single run-start route. CLI, SDK, API, and dashboard all POST here. */
+/** Canonical admission; the CLI adapter adds compatibility before this handler. */
 export const PLAY_RUN_START_PATH = '/api/v2/plays/run';
+export const CLI_PLAY_RUN_START_PATH = `${PLAY_RUN_START_PATH}/cli`;
+export const CLI_PLAY_RUN_SUPPORTED_HEADER = 'x-deepline-cli-play-admission';
 export const PLAY_RUN_START_STREAM_PATH = `${PLAY_RUN_START_PATH}?stream=true`;
+export const CLI_PLAY_RUN_START_STREAM_PATH = `${CLI_PLAY_RUN_START_PATH}?stream=true`;
 export const PLAY_FILES_STAGE_PATH = '/api/v2/plays/files/stage';
 export const PLAY_FILES_STAGE_MINT_PATH = `${PLAY_FILES_STAGE_PATH}/mint`;
 
@@ -44,12 +47,20 @@ export const PLAY_FILES_STAGE_MINT_PATH = `${PLAY_FILES_STAGE_PATH}/mint`;
  * responses so the staging fallbacks below classify failures identically.
  */
 export interface PlayRunHttp {
-  get?<T = unknown>(path: string): Promise<T>;
+  get?<T = unknown>(
+    path: string,
+    options?: { signal?: AbortSignal },
+  ): Promise<T>;
   post<T = unknown>(
     path: string,
     body: unknown,
     headers?: Record<string, string>,
-    options?: { maxRetries?: number; exactUrlOnly?: boolean },
+    options?: {
+      maxRetries?: number;
+      exactUrlOnly?: boolean;
+      signal?: AbortSignal;
+      onResponse?: (response: Response) => void;
+    },
   ): Promise<T>;
   postFormData<T = unknown>(
     path: string,
@@ -66,6 +77,28 @@ export interface PlayRunHttp {
  */
 export type ResolvedStartPlayRunRequest = StartPlayRunRequest;
 
+export type PlayRunStartOptions = {
+  signal?: AbortSignal;
+  onSubmission?: (intent: {
+    workflowId: string;
+    orgId: string;
+    request: Record<string, unknown>;
+  }) => void | Promise<void>;
+  /** @internal CLI JSON admission checks compatibility in the same request. */
+  cliAdmission?: boolean;
+};
+
+/** Only the transport can prove that the named action never dispatched. */
+export class CliPlayAdmissionUnsupportedError extends DeeplineError {
+  constructor(status: number) {
+    super(
+      'This server does not support CLI Play admission.',
+      status,
+      'CLI_PLAY_ADMISSION_UNSUPPORTED',
+    );
+  }
+}
+
 /** The exact JSON body `POST /api/v2/plays/run` receives. Key order is part of the contract. */
 export function buildPlayRunStartBody(
   request: ResolvedStartPlayRunRequest,
@@ -122,6 +155,7 @@ export function buildPlayRunStartBody(
     ...(typeof request.waitForCompletionMs === 'number'
       ? { waitForCompletionMs: request.waitForCompletionMs }
       : {}),
+    ...(request.terminalStatus === 'full' ? { terminalStatus: 'full' } : {}),
     // Profile selection is the API's job, not the caller's. The server
     // defaults to absurd; callers normally omit this field.
     ...(request.profile ? { profile: request.profile } : {}),
@@ -154,6 +188,7 @@ export async function preparePlayRunAdmission(
     orgId: string;
     request: Record<string, unknown>;
   }) => void | Promise<void>,
+  options?: { signal?: AbortSignal },
 ): Promise<{
   body: Record<string, unknown>;
   workflowId?: string;
@@ -168,7 +203,7 @@ export async function preparePlayRunAdmission(
   } | null = null;
   if (http.get) {
     try {
-      capability = await http.get(PLAY_RUN_START_PATH);
+      capability = await http.get(PLAY_RUN_START_PATH, options);
     } catch (error) {
       if (
         !(error instanceof DeeplineError) ||
@@ -193,6 +228,7 @@ export async function preparePlayRunAdmission(
   }
   const supportsCallerIntent =
     capability?.admissionContract === 'caller-intent-v1';
+  options?.signal?.throwIfAborted();
   if (
     supportsCallerIntent &&
     (!capability?.orgId ||
@@ -211,6 +247,23 @@ export async function preparePlayRunAdmission(
       'PLAY_RUN_ADMISSION_RECOVERY_UNSUPPORTED',
     );
   }
+  if (
+    request.maxTotalCredits !== undefined &&
+    capability?.strictTotalBudget === 'unbounded-v1'
+  ) {
+    if (request.maxTotalCredits === 0) {
+      throw new DeeplineError(
+        'A zero-credit total budget cannot admit a Play: sandbox compute is billed even when provider tools are free.',
+        422,
+        'PLAY_TOTAL_BUDGET_COMPUTE_REQUIRED',
+      );
+    }
+    throw new DeeplineError(
+      'A strict total Play budget cannot currently be admitted: provider operations, Customer DB compute, and additional sandbox sessions do not have a finite admitted upper bound.',
+      422,
+      'PLAY_TOTAL_BUDGET_UNBOUNDED',
+    );
+  }
   if (
     request.maxTotalCredits !== undefined &&
     capability?.strictTotalBudget !== 'fail-closed-v1'
@@ -267,26 +320,49 @@ export async function startPlayRun(
   http: PlayRunHttp,
   request: ResolvedStartPlayRunRequest,
   headers?: Record<string, string>,
-  onSubmission?: (intent: {
-    workflowId: string;
-    orgId: string;
-    request: Record<string, unknown>;
-  }) => void | Promise<void>,
+  options?: PlayRunStartOptions,
 ): Promise<PlayRunStart> {
   const {
     body: submittedBody,
     workflowId,
     supportsCallerIntent,
-  } = await preparePlayRunAdmission(http, request, onSubmission);
+  } = await preparePlayRunAdmission(
+    http,
+    request,
+    options?.onSubmission,
+    options,
+  );
+  let cliAdmissionSupported = false;
   let response: Record<string, unknown>;
   try {
     response = await http.post<Record<string, unknown>>(
-      PLAY_RUN_START_PATH,
+      options?.cliAdmission ? CLI_PLAY_RUN_START_PATH : PLAY_RUN_START_PATH,
       submittedBody,
       headers,
-      { maxRetries: 0, exactUrlOnly: true },
+      {
+        maxRetries: 0,
+        exactUrlOnly: true,
+        ...(options?.signal ? { signal: options.signal } : {}),
+        ...(options?.cliAdmission
+          ? {
+              onResponse: (response: Response) => {
+                cliAdmissionSupported =
+                  response.headers.get(CLI_PLAY_RUN_SUPPORTED_HEADER) ===
+                  'true';
+              },
+            }
+          : {}),
+      },
     );
   } catch (error) {
+    if (
+      options?.cliAdmission &&
+      !cliAdmissionSupported &&
+      error instanceof DeeplineError &&
+      (error.statusCode === 404 || error.statusCode === 405)
+    ) {
+      throw new CliPlayAdmissionUnsupportedError(error.statusCode);
+    }
     if (
       (error instanceof DeeplineError &&
         ['NETWORK_TIMEOUT', 'NETWORK_ERROR', 'FETCH_FAILED'].includes(
@@ -320,7 +396,18 @@ export async function startPlayRun(
     }
     throw error;
   }
-  return normalizePlayRunStart(response);
+  const started = normalizePlayRunStart(response);
+  if (
+    options?.cliAdmission &&
+    (!started.workflowId || started.workflowId === 'pending')
+  ) {
+    throw new DeeplineError(
+      'Play admission returned no run id. Check recent runs before submitting again.',
+      undefined,
+      'PLAY_START_MISSING_RUN_ID',
+    );
+  }
+  return started;
 }
 
 export function isPlayRunPackage(value: unknown): value is PlayRunPackage {
@@ -367,7 +454,9 @@ export function normalizePlayRunStart(
       ? { dashboardUrl: runPackage.run.dashboardUrl }
       : {}),
     ...(isTerminalPlayRunLifecycleStatus(status)
-      ? { finalStatus: runPackage }
+      ? raw.finalStatusView === 'full' && raw.runId === runPackage.run.id
+        ? { finalStatus: raw, finalStatusView: 'full' as const }
+        : { finalStatus: runPackage }
       : {}),
     package: runPackage,
   };
@@ -1018,12 +1107,13 @@ export function createSessionPlayRunHttp(
     return parsed as T;
   };
   return {
-    get: (path) => send(path, { method: 'GET' }),
-    post: (path, body, headers) =>
+    get: (path, options) => send(path, { method: 'GET', ...options }),
+    post: (path, body, headers, options) =>
       send(path, {
         method: 'POST',
         headers: { 'content-type': 'application/json', ...headers },
         body: JSON.stringify(body),
+        ...(options?.signal ? { signal: options.signal } : {}),
       }),
     postFormData: (path, formData) =>
       send(path, {

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

@@ -139,11 +139,14 @@ export type SdkRelease = {
    */
   version: string;
   /**
-   * One concise, agent-readable explanation shown while this release is an
-   * available update. Keep it actionable; the compatibility route includes it
-   * in its existing update message so older installed CLIs can print it too.
+   * One concise, agent-readable explanation of what a named release changed.
+   * The compatibility route shows it only to clients older than
+   * `introducedIn`, labelled with that version. `version` above is bumped on
+   * every publish while this text is written by hand, so labelling it with the
+   * latest version would repeat the same line for releases it does not
+   * describe. Keep it actionable; older installed CLIs print it too.
    */
-  updateSummary?: string;
+  updateSummary?: { introducedIn: string; summary: string };
   /** Capabilities stamped into the published package's `deepline` metadata. */
   packageCapabilities: {
     updatePreferences: 1;
@@ -202,9 +205,12 @@ 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.409',
-  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.',
+  version: '0.3.410',
+  updateSummary: {
+    introducedIn: '0.3.90',
+    summary:
+      'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
+  },
   packageCapabilities: {
     updatePreferences: 1,
     skillsGuidance: 1,