deepline 0.3.392 → 0.3.393

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

@@ -148,14 +148,15 @@ import { isStopAllPlayRunsDryRunResult } from './types';
 import type { MonitorDefinition } from './monitors';
 import type { MonitorFleetDefinition } from './monitor-fleets';
 import type { PlayStagedFileRef } from './plays/local-file-discovery';
+import type { RuntimeSheetRunRowMembershipPage } from '../../shared_libs/play-data-plane/runtime-sheet-storage-contract';
 import {
-  buildPlayRunStartBody,
   isPlayRunPackage,
   mintStagedPlayFileUploads,
   normalizePlayRunStart,
   PLAY_RUN_START_STREAM_PATH,
   stagePlayFiles,
   startPlayRun,
+  preparePlayRunAdmission,
   type MintStagedFileUpload,
   type ResolvedStartPlayRunRequest,
 } from './plays/run-request';
@@ -366,8 +367,7 @@ function resolvePlayRunRuntimeSelection(
   // 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 configuredToken = env.DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN?.trim();
   const configuredPlacementPolicy =
     env.DEEPLINE_RUNTIME_SANDBOX_PLACEMENT_POLICY?.trim();
   if (!configured) {
@@ -412,8 +412,7 @@ function resolvePlayRunRuntimeSelection(
       'INVALID_RUNTIME_NAMESPACE',
     );
   }
-  const configuredBackendValue =
-    env.DEEPLINE_PLAY_RUNNER_BACKEND?.trim();
+  const configuredBackendValue = env.DEEPLINE_PLAY_RUNNER_BACKEND?.trim();
   const configuredBackend =
     configuredBackendValue === 'daytona' || configuredBackendValue === 'modal'
       ? configuredBackendValue
@@ -487,8 +486,7 @@ function runtimeSelectionHeaders(
       'RUNTIME_ENVIRONMENT_TOKEN_REQUIRED',
     );
   }
-  const receivers =
-    env.DEEPLINE_RUNTIME_RETAINED_PIPELINE_RECEIVERS?.trim();
+  const receivers = env.DEEPLINE_RUNTIME_RETAINED_PIPELINE_RECEIVERS?.trim();
   return {
     [RUNTIME_ENVIRONMENT_TOKEN_HEADER]: token,
     ...(receivers ? { [RETAINED_PIPELINE_RECEIVERS_HEADER]: receivers } : {}),
@@ -1101,6 +1099,14 @@ export type PlaySheetRowsResult = {
   deltaCursor?: number;
 };
 
+export type PlayRunRowHistoryOptions = {
+  playName: string;
+  runId: string;
+  tableNamespace: string;
+  limit?: number;
+  cursor?: string;
+};
+
 export type PlaySecretMetadata = {
   _id: string;
   orgId: string;
@@ -1185,6 +1191,10 @@ export type RunsNamespace = {
     /** Cancel the page request, including its response body and retry waits. */
     signal?: AbortSignal;
   }) => Promise<PlaySheetRowsResult>;
+  /** One immutable history page; incomplete legacy coverage stays explicit. */
+  rowHistory: (
+    input: PlayRunRowHistoryOptions,
+  ) => Promise<RuntimeSheetRunRowMembershipPage>;
   /** Stop a running/waiting run. */
   stop: (
     runId: string,
@@ -2504,6 +2514,8 @@ export type BillingUsageResult = {
  * @sdkReference client 030 client.billing
  */
 export type BillingNamespace = {
+  /** Read a bounded sandbox-session estimate; excludes tools and Customer DB. */
+  quote: (input: BillingQuoteRequest) => Promise<BillingQuoteResult>;
   /** Current workspace provider benefits; discovery does not authorize a call. */
   entitlements: () => Promise<BillingEntitlements>;
   /** Charge the saved payment method and add Deepline credits to the active workspace. */
@@ -2572,6 +2584,30 @@ export type BillingNamespace = {
   }) => Promise<{ url: string }>;
 };
 
+export type BillingQuoteRequest = {
+  quantity: number;
+  sandbox_runtime: { timeout?: string; size?: 'standard' };
+};
+
+export type BillingQuoteResult = {
+  scope: 'sandbox_session';
+  quantity: number;
+  resources: {
+    timeoutSeconds: number;
+    memoryGiB: number;
+    cpu: number;
+    diskGiB: number;
+  };
+  maximum_credits: number;
+  maximum_billing_seconds: number;
+  total_play_credits: null;
+  total_budget_supported: false;
+  unbounded_components: string[];
+  explanation: string;
+  plan_version_id: string;
+  rate_card_id: string;
+};
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
@@ -2918,6 +2954,7 @@ export class DeeplineClient {
       input: (runId) => this.getRunInput(runId),
       rerun: (runId, options) => this.rerun(runId, options),
       exportDatasetRows: (input) => this.getPlaySheetRows(input),
+      rowHistory: (input) => this.getPlayRunRowHistory(input),
       stop: (runId, options) => this.stopRun(runId, options),
       stopAll: ((options?: StopAllRunsOptions) =>
         this.stopAllRuns(options)) as RunsNamespace['stopAll'],
@@ -2927,6 +2964,8 @@ export class DeeplineClient {
       planQuery: (input) => planCustomerDbQuery(input),
     };
     this.billing = {
+      quote: (input) =>
+        this.http.post<BillingQuoteResult>('/api/v2/billing/quote', input),
       entitlements: () => this.http.get('/api/v2/billing/entitlements'),
       topUp: (options) => this.topUpBillingBalance(options),
       topUpWithReceipt: (options) =>
@@ -3564,15 +3603,85 @@ export class DeeplineClient {
    * });
    * ```
    */
-  async startPlayRun(request: StartPlayRunRequest): Promise<PlayRunStart> {
+  async startPlayRun(
+    request: StartPlayRunRequest,
+    options?: {
+      onSubmission?: (intent: {
+        workflowId: string;
+        orgId: string;
+        request: Record<string, unknown>;
+      }) => void | Promise<void>;
+    },
+  ): Promise<PlayRunStart> {
     const resolved = resolveStartPlayRunRequest(request, this.environment);
     return startPlayRun(
       this.http,
       resolved.request,
       runtimeSelectionHeaders(resolved.runtime, this.environment),
+      options?.onSubmission,
     );
   }
 
+  /**
+   * Prepare a tenant-scoped start intent without executing it. Its stream
+   * sender retains the exact body and transport selected during preparation.
+   */
+  async preparePlayRunAdmission(
+    request: StartPlayRunRequest,
+    options?: {
+      onSubmission?: (intent: {
+        workflowId: string;
+        orgId: string;
+        request: Record<string, unknown>;
+      }) => void | Promise<void>;
+    },
+  ) {
+    const resolved = resolveStartPlayRunRequest(request, this.environment);
+    const prepared = await preparePlayRunAdmission(
+      this.http,
+      resolved.request,
+      options?.onSubmission,
+    );
+    const bodyJson = JSON.stringify(prepared.body);
+    const headers = runtimeSelectionHeaders(resolved.runtime, this.environment);
+    const http = this.http;
+    let submitted = false;
+    return {
+      ...prepared,
+      async *startStream(streamOptions?: { signal?: AbortSignal }) {
+        if (submitted && !prepared.supportsCallerIntent) {
+          throw new DeeplineError(
+            'This server has not enabled caller-owned admission recovery. Do not retry an ambiguous start.',
+            409,
+            'PLAY_RUN_ADMISSION_RECOVERY_UNSUPPORTED',
+          );
+        }
+        if (submitted) {
+          // A later transport attempt may reach a rolled-back server or a
+          // different workspace. Re-prove support for the pinned intent,
+          // without rebuilding it or persisting another submission journal.
+          await preparePlayRunAdmission(
+            http,
+            JSON.parse(bodyJson) as ResolvedStartPlayRunRequest,
+          );
+        }
+        submitted = true;
+        for await (const event of http.streamSse<PlayLiveEvent>(
+          PLAY_RUN_START_STREAM_PATH,
+          {
+            method: 'POST',
+            body: JSON.parse(bodyJson),
+            headers,
+            signal: streamOptions?.signal,
+            exactUrlOnly: true,
+          },
+        )) {
+          if (event.scope === 'play') yield event;
+        }
+      },
+    };
+  }
+
   /**
    * Submit a play run through the legacy event response.
    *
@@ -3588,23 +3697,17 @@ export class DeeplineClient {
    */
   async *startPlayRunStream(
     request: StartPlayRunRequest,
-    options?: { signal?: AbortSignal },
+    options?: {
+      signal?: AbortSignal;
+      onSubmission?: (intent: {
+        workflowId: string;
+        orgId: string;
+        request: Record<string, unknown>;
+      }) => void | Promise<void>;
+    },
   ): AsyncGenerator<PlayLiveEvent> {
-    const resolved = resolveStartPlayRunRequest(request, this.environment);
-    const body = buildPlayRunStartBody(resolved.request);
-    for await (const event of this.http.streamSse<PlayLiveEvent>(
-      PLAY_RUN_START_STREAM_PATH,
-      {
-        method: 'POST',
-        body,
-        headers: runtimeSelectionHeaders(resolved.runtime, this.environment),
-        signal: options?.signal,
-      },
-    )) {
-      if (event.scope === 'play') {
-        yield event;
-      }
-    }
+    const prepared = await this.preparePlayRunAdmission(request, options);
+    yield* prepared.startStream({ signal: options?.signal });
   }
 
   /**
@@ -5034,6 +5137,24 @@ export class DeeplineClient {
     );
   }
 
+  /**
+   * Read one page of immutable admitted and terminal rows for a Play Run dataset.
+   * Follow nextCursor; coverage explicitly identifies unavailable or incomplete history.
+   */
+  async getPlayRunRowHistory(
+    input: PlayRunRowHistoryOptions,
+  ): Promise<RuntimeSheetRunRowMembershipPage> {
+    const params = new URLSearchParams({
+      runId: input.runId,
+      tableNamespace: input.tableNamespace,
+    });
+    if (input.limit !== undefined) params.set('limit', String(input.limit));
+    if (input.cursor !== undefined) params.set('cursor', input.cursor);
+    return this.http.get(
+      `/api/v2/plays/${encodeURIComponent(input.playName)}/sheet/history?${params}`,
+    );
+  }
+
   /**
    * Export persisted runtime-sheet rows for a play dataset/table namespace.
    *
@@ -5328,6 +5449,17 @@ export class DeeplineClient {
     return this.http.get('/api/v2/settings/notifications');
   }
 
+  /** Save provider-owned credential fields without starting an OAuth browser flow. */
+  async setIntegrationCredentials(
+    provider: string,
+    credentials: Record<string, string>,
+  ): Promise<{ ok: boolean; credential_saved?: boolean }> {
+    return this.http.post('/api/v2/integrations/connect', {
+      provider,
+      credentials,
+    });
+  }
+
   /** Start the Slack OAuth flow required by product notifications. */
   async connectNotificationSlack(options?: {
     successUrl?: string;

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

@@ -1,4 +1,5 @@
 import { SDK_API_CONTRACT, SDK_API_MAJOR, SDK_VERSION } from './version.js';
+import { SDK_RELEASE } from './release.js';
 import { randomUUID } from 'node:crypto';
 import {
   existsSync,
@@ -62,6 +63,10 @@ export type SdkCompatibilityResponse = {
 
 export type SdkCompatibilitySkillsUpdate = {
   needs_update: boolean;
+  /** Preserve installed skills until this CLI can execute the new guidance. */
+  requires_cli_update?: boolean;
+  minimum_cli_version?: string;
+  required_cli_capability?: number;
   local: {
     version: string | null;
   };
@@ -366,6 +371,10 @@ export async function checkSdkCompatibility(
     }
     if (options.skillsVersion !== undefined) {
       url.searchParams.set('skills_version', options.skillsVersion ?? '');
+      url.searchParams.set(
+        'skills_cli_capability',
+        String(SDK_RELEASE.packageCapabilities.skillsGuidance),
+      );
     }
     if (options.catalog) {
       url.searchParams.set('catalog_tool_id', options.catalog.toolId);

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

@@ -104,6 +104,7 @@ interface StreamOptions {
   body?: unknown;
   headers?: Record<string, string>;
   signal?: AbortSignal;
+  exactUrlOnly?: boolean;
 }
 
 type RequestAbortTaggedError = Error & {
@@ -813,7 +814,10 @@ export class HttpClient {
     }
     let lastError: Error | null = null;
 
-    for (const candidateUrl of buildCandidateUrls(url)) {
+    const candidateUrls = options?.exactUrlOnly
+      ? [url]
+      : buildCandidateUrls(url);
+    for (const candidateUrl of candidateUrls) {
       try {
         const response = await fetch(candidateUrl, {
           method,

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

@@ -116,6 +116,9 @@ export type {
   BillingInvoiceEntry,
   BillingInvoicesResult,
   BillingNamespace,
+  BillingQuoteRequest,
+  BillingQuoteResult,
+  PlayRunRowHistoryOptions,
   BillingRecentUsageEntry,
   DbNamespace,
   BillingPaymentMethodSummary,
@@ -313,6 +316,8 @@ export type {
   ResolvedConfig,
   ToolDefinition,
   ToolMetadata,
+  ToolRequestCondition,
+  ToolRequestWarningRule,
   LiveEventEnvelope,
   PlayLiveEvent,
   PlayRunResult,

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

@@ -17,6 +17,10 @@
  */
 import { DeeplineError } from '../../../shared_libs/plays/tool-execution-error';
 import { isTerminalPlayRunLifecycleStatus } from '../../../shared_libs/play-runtime/run-lifecycle-policy.js';
+import {
+  buildCallerPlayWorkflowId,
+  callerPlayWorkflowIdMatchesRequest,
+} from '../../../shared_libs/play-runtime/run-identity';
 import { apiErrorCodeFromResponse, apiErrorMessage } from '../api-error';
 import type {
   PlayRunPackage,
@@ -40,6 +44,7 @@ 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>;
   post<T = unknown>(
     path: string,
     body: unknown,
@@ -66,6 +71,13 @@ export function buildPlayRunStartBody(
   request: ResolvedStartPlayRunRequest,
 ): Record<string, unknown> {
   return {
+    ...(request.admissionOrgId
+      ? { admissionOrgId: request.admissionOrgId }
+      : {}),
+    ...(request.workflowId ? { workflowId: request.workflowId } : {}),
+    ...(request.maxTotalCredits !== undefined
+      ? { maxTotalCredits: request.maxTotalCredits }
+      : {}),
     ...(request.name ? { name: request.name } : {}),
     ...(request.revisionId ? { revisionId: request.revisionId } : {}),
     ...(request.artifactStorageKey
@@ -134,17 +146,180 @@ export function buildPlayRunStartBody(
  * or times out, and retrying without an idempotency key can create a second
  * root run, so callers resolve ambiguous failures explicitly.
  */
+export async function preparePlayRunAdmission(
+  http: PlayRunHttp,
+  request: ResolvedStartPlayRunRequest,
+  onSubmission?: (intent: {
+    workflowId: string;
+    orgId: string;
+    request: Record<string, unknown>;
+  }) => void | Promise<void>,
+): Promise<{
+  body: Record<string, unknown>;
+  workflowId?: string;
+  supportsCallerIntent: boolean;
+}> {
+  // The reader ships before the writer. An older route ignores workflowId;
+  // that response cannot prove an identity can be reused safely after a timeout.
+  let capability: {
+    admissionContract?: string;
+    strictTotalBudget?: string;
+    orgId?: string;
+  } | null = null;
+  if (http.get) {
+    try {
+      capability = await http.get(PLAY_RUN_START_PATH);
+    } catch (error) {
+      if (
+        !(error instanceof DeeplineError) ||
+        ![404, 405].includes(error.statusCode ?? 0)
+      )
+        throw error;
+      // Only an authoritative absent route proves an older server. A timeout,
+      // 503, or authentication denial must never switch to an unkeyed writer.
+    }
+    if (
+      capability &&
+      !['caller-intent-v1', 'unsupported'].includes(
+        capability.admissionContract ?? '',
+      )
+    ) {
+      throw new DeeplineError(
+        'The server admission capability response is unknown; execution was not submitted.',
+        503,
+        'PLAY_RUN_ADMISSION_CAPABILITY_UNKNOWN',
+      );
+    }
+  }
+  const supportsCallerIntent =
+    capability?.admissionContract === 'caller-intent-v1';
+  if (
+    supportsCallerIntent &&
+    (!capability?.orgId ||
+      (request.admissionOrgId && request.admissionOrgId !== capability.orgId))
+  ) {
+    throw new DeeplineError(
+      'The admission workspace could not be pinned to this request; execution was not submitted.',
+      409,
+      'PLAY_RUN_ADMISSION_TENANT_CONFLICT',
+    );
+  }
+  if (request.workflowId && !supportsCallerIntent) {
+    throw new DeeplineError(
+      'This server has not enabled caller-owned admission recovery. Do not retry an ambiguous start.',
+      409,
+      'PLAY_RUN_ADMISSION_RECOVERY_UNSUPPORTED',
+    );
+  }
+  if (
+    request.maxTotalCredits !== undefined &&
+    capability?.strictTotalBudget !== 'fail-closed-v1'
+  ) {
+    throw new DeeplineError(
+      'This server cannot honor a strict total Play budget. Execution was not submitted.',
+      409,
+      'PLAY_TOTAL_BUDGET_UNSUPPORTED',
+    );
+  }
+  // Snapshot the exact JSON representation once. Date/toJSON/undefined and
+  // nonfinite values must hash to precisely the bytes the server will parse.
+  const wireBody = JSON.parse(
+    JSON.stringify(
+      buildPlayRunStartBody({
+        ...request,
+        ...(supportsCallerIntent ? { admissionOrgId: capability!.orgId } : {}),
+      }),
+    ),
+  ) as Record<string, unknown>;
+  const workflowId = supportsCallerIntent
+    ? (request.workflowId ??
+      buildCallerPlayWorkflowId(request.name ?? 'play', wireBody))
+    : undefined;
+  const submittedBody = workflowId ? { workflowId, ...wireBody } : wireBody;
+  if (
+    workflowId &&
+    !callerPlayWorkflowIdMatchesRequest(workflowId, submittedBody)
+  ) {
+    throw new DeeplineError(
+      'workflowId must be the caller run ID of this same immutable request.',
+      400,
+      'PLAY_RUN_START_INTENT_CONFLICT',
+    );
+  }
+  if (onSubmission) {
+    if (!workflowId || !capability?.orgId) {
+      throw new DeeplineError(
+        'This server cannot persist a recoverable submission intent. Execution was not submitted.',
+        409,
+        'PLAY_RUN_ADMISSION_RECOVERY_UNSUPPORTED',
+      );
+    }
+    await onSubmission({
+      workflowId,
+      orgId: capability.orgId,
+      request: submittedBody,
+    });
+  }
+  return { body: submittedBody, workflowId, supportsCallerIntent };
+}
+
 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>,
 ): Promise<PlayRunStart> {
-  const response = await http.post<Record<string, unknown>>(
-    PLAY_RUN_START_PATH,
-    buildPlayRunStartBody(request),
-    headers,
-    { maxRetries: 0, exactUrlOnly: true },
-  );
+  const {
+    body: submittedBody,
+    workflowId,
+    supportsCallerIntent,
+  } = await preparePlayRunAdmission(http, request, onSubmission);
+  let response: Record<string, unknown>;
+  try {
+    response = await http.post<Record<string, unknown>>(
+      PLAY_RUN_START_PATH,
+      submittedBody,
+      headers,
+      { maxRetries: 0, exactUrlOnly: true },
+    );
+  } catch (error) {
+    if (
+      (error instanceof DeeplineError &&
+        ['NETWORK_TIMEOUT', 'NETWORK_ERROR', 'FETCH_FAILED'].includes(
+          error.code ?? '',
+        )) ||
+      error instanceof TypeError ||
+      (error instanceof Error &&
+        ['AbortError', 'TimeoutError'].includes(error.name))
+    ) {
+      const originalMessage =
+        error instanceof Error ? error.message : 'Transport failed';
+      const failure = new DeeplineError(
+        workflowId
+          ? `${originalMessage} Admission outcome is unknown for ${workflowId}. Inspect this run before retrying; reuse this workflowId for the same immutable request.`
+          : `${originalMessage} Admission outcome is unknown. This server did not prove caller-owned recovery support; inspect existing runs before starting again.`,
+        error instanceof DeeplineError ? error.statusCode : undefined,
+        error instanceof DeeplineError ? error.code : 'NETWORK_ERROR',
+        {
+          ...(workflowId ? { runId: workflowId, workflowId } : {}),
+          admissionState: 'unknown',
+          recoverySupported: supportsCallerIntent,
+          next: {
+            inspect: workflowId
+              ? `deepline runs get ${workflowId} --json`
+              : 'deepline runs list --json',
+          },
+        },
+      );
+      Object.assign(failure, { cause: error });
+      throw failure;
+    }
+    throw error;
+  }
   return normalizePlayRunStart(response);
 }
 
@@ -843,6 +1018,7 @@ export function createSessionPlayRunHttp(
     return parsed as T;
   };
   return {
+    get: (path) => send(path, { method: 'GET' }),
     post: (path, body, headers) =>
       send(path, {
         method: 'POST',

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

@@ -147,6 +147,8 @@ export type SdkRelease = {
   /** Capabilities stamped into the published package's `deepline` metadata. */
   packageCapabilities: {
     updatePreferences: 1;
+    /** Skill guidance/command surface understood by this built package. */
+    skillsGuidance: 1;
   };
   /** Named compatibility policies. This is the only authored contract policy. */
   contracts: DeeplineContractPolicy;
@@ -200,11 +202,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.392',
+  version: '0.3.393',
   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: {
     updatePreferences: 1,
+    skillsGuidance: 1,
   },
   contracts: {
     api: {

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

@@ -1,4 +1,9 @@
 import type { PlaySettings } from '../../shared_libs/plays/settings-contract';
+import type { ToolRequestWarningRule } from '../../shared_libs/integration-contracts/request-warnings';
+export type {
+  ToolRequestCondition,
+  ToolRequestWarningRule,
+} from '../../shared_libs/integration-contracts/request-warnings';
 import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-manifest';
 import type { RunGetStatus, RunLifecycleStatus } from './client';
 import type { PlayGrepMatch } from '../../shared_libs/plays/play-grep-search';
@@ -376,6 +381,8 @@ export interface ToolDefinition extends ToolExecutionMetadataFields {
     message: string;
     execution?: 'terminal' | 'forward';
   };
+  /** Ordered server-authored request warnings. The CLI prints the first match before dispatch. */
+  requestWarnings?: readonly ToolRequestWarningRule[];
   /**
    * Connection status for discovery: `managed` (Deepline-run credentials),
    * `connected` (your own credential is connected), or `requires_connection`
@@ -2090,6 +2097,12 @@ export interface PlayCheckToolGetterHint {
  * ```
  */
 export interface StartPlayRunRequest {
+  /** Tenant pin supplied by admission capability discovery; recovery must preserve it. */
+  admissionOrgId?: string;
+  /** Caller-owned canonical run ID. Reuse it to reconcile or replay an ambiguous start. */
+  workflowId?: string;
+  /** Strict total Deepline spend ceiling, including compute. Unbounded workloads are refused before admission. */
+  maxTotalCredits?: number;
   /** Play name for registered revisions. */
   name?: string;
   /** Explicit revision ID when the caller wants a specific saved version. */