deepline 0.3.409 → 0.3.411

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

@@ -79,6 +79,14 @@ export type {
   ToolExecution,
 } from './tool-calls';
 import { HttpClient } from './http';
+import {
+  PlayClient,
+  type ClientEnvironment,
+  normalizePlayRunIntegrationMode,
+  normalizePlayStatus,
+  resolveStartPlayRunRequest,
+  runtimeSelectionHeaders,
+} from './plays/client';
 import { PRODUCT_NOTIFICATION_SLACK_OAUTH_SCOPES } from '../../shared_libs/product-notifications/contract.js';
 import {
   DEFAULT_PRODUCT_NOTIFICATION_DELIVERY_TIMING,
@@ -90,7 +98,10 @@ import {
   type EffectiveProductNotificationGroup,
   type ProductNotificationGroupDraft,
 } from '../../shared_libs/product-notifications/configuration.js';
-import { watchRunEvents as pollRunSnapshotEvents } from './runs/watch-polling';
+import {
+  watchRunEvents as pollRunSnapshotEvents,
+  type WatchPollObservation,
+} from './runs/watch-polling';
 import { encodeRunLogsCursor, parseRunLogsCursor } from './runs/log-cursor';
 import {
   normalizeRunEventOperationRequest,
@@ -139,6 +150,8 @@ import type {
   PublishSharePageRequest,
   UpdateSharePageRequest,
   ToolDefinition,
+  ToolCategorySummary,
+  ToolCategoryListing,
   ProviderDefinition,
   ToolSearchOptions,
   ToolSearchResult,
@@ -159,24 +172,19 @@ import {
   isPlayRunPackage,
   mintStagedPlayFileUploads,
   normalizePlayRunStart,
+  CLI_PLAY_RUN_START_STREAM_PATH,
+  CliPlayAdmissionUnsupportedError,
   PLAY_RUN_START_STREAM_PATH,
   stagePlayFiles,
-  startPlayRun,
   preparePlayRunAdmission,
   type MintStagedFileUpload,
+  type PlayRunStartOptions,
   type ResolvedStartPlayRunRequest,
 } from './plays/run-request';
 import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-manifest.js';
 import type { EnrichCompiledConfig } from './cli/enrich-play-compiler';
+import { COORDINATOR_INTERNAL_TOKEN_HEADER } from '../../shared_libs/play-runtime/coordinator-headers.js';
 import {
-  COORDINATOR_INTERNAL_TOKEN_HEADER,
-  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';
@@ -189,6 +197,57 @@ export type SlackNotificationTarget =
   | { channel: string; memberId?: never }
   | { channel?: never; memberId: string };
 
+type ToolDiscoveryResponse = {
+  view?: string;
+  categories?: unknown;
+  tools?: ToolDefinition[];
+};
+
+function invalidToolDiscoveryResponse(): DeeplineError {
+  return new DeeplineError(
+    'The server returned an invalid tool discovery response.',
+    502,
+    'INVALID_TOOL_DISCOVERY_RESPONSE',
+  );
+}
+
+function readToolCategorySummaries(value: unknown): ToolCategorySummary[] {
+  if (!Array.isArray(value)) throw invalidToolDiscoveryResponse();
+  const seen = new Set<string>();
+  return value.map((item: unknown) => {
+    if (
+      !item ||
+      typeof item !== 'object' ||
+      !('name' in item) ||
+      typeof item.name !== 'string' ||
+      !item.name.trim() ||
+      seen.has(item.name) ||
+      !('count' in item) ||
+      typeof item.count !== 'number' ||
+      !Number.isSafeInteger(item.count) ||
+      item.count < 0
+    ) {
+      throw invalidToolDiscoveryResponse();
+    }
+    seen.add(item.name);
+    return { name: item.name, count: item.count };
+  });
+}
+
+function summarizeToolCategories(
+  tools: ToolDefinition[],
+): ToolCategorySummary[] {
+  const counts = new Map<string, number>();
+  for (const tool of tools) {
+    for (const category of tool.categories ?? []) {
+      counts.set(category, (counts.get(category) ?? 0) + 1);
+    }
+  }
+  return [...counts]
+    .map(([name, count]) => ({ name, count }))
+    .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+}
+
 export type CreateNotificationInput = {
   name: string;
   provider: 'slack';
@@ -331,174 +390,6 @@ export type IngestionStorageRepairResult = {
   };
 };
 
-function normalizePlayRunIntegrationMode(
-  value: unknown,
-): 'live' | 'eval_stub' | 'fixture' | undefined {
-  if (value === 'live' || value === 'eval_stub' || value === 'fixture') {
-    return value;
-  }
-  return undefined;
-}
-
-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.
- */
-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 };
-}
-
-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 } : {}),
-  };
-}
-
 /** The isolated PR estate needs its existing internal credential to read its pinned scheduler scope. */
 function isolatedCiRuntimeEventReadHeaders(
   env: ClientEnvironment,
@@ -522,40 +413,6 @@ function isolatedCiRuntimeEventReadHeaders(
   return { [COORDINATOR_INTERNAL_TOKEN_HEADER]: token };
 }
 
-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 sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1288,7 +1145,7 @@ export type StopAllRunsOptions = {
 
 /** Current mutable customer database namespace exposed as `client.db`. */
 export type DbNamespace = {
-  /** Run a bounded SQL query; every request is attempted once. */
+  /** Run bounded SQL; unkeyed requests run once, while keyed requests retain one recovery identity across safe retries. */
   query: (input: CustomerDbQueryOptions) => Promise<CustomerDbQueryResult>;
   /** Describe the request, effects and recovery policy without executing SQL. */
   planQuery: (input: CustomerDbQueryOptions) => CustomerDbQueryPlan;
@@ -2433,6 +2290,10 @@ export type BillingUsageEvent = {
   pricing_model: string | null;
   policy_id: string | null;
   created_at: string;
+  /** Present when the original request is resolved through its canonical charge. */
+  charge_state?: BillingRecentUsageEntry['charge_state'];
+  /** Pending/unknown amounts are null; a final amount can be zero. */
+  charge_finality?: BillingRecentUsageEntry['charge_finality'];
 };
 
 /** One customer-facing recent billing operation from `/api/v2/billing/usage`. */
@@ -2650,54 +2511,6 @@ function preferPrebuiltPlayDescriptions<T extends PlayDescription>(
     .map(({ play }) => play);
 }
 
-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 RunLifecycleStatus,
-        }
-      : {}),
-    ...(isRecord(runStatus)
-      ? { runStatus: runStatus as unknown as RunGetStatus }
-      : {}),
-    ...(runPackage
-      ? {
-          package: runPackage,
-          outputs: runPackage.outputs,
-        }
-      : {}),
-    status,
-  };
-}
-
 function readStringArray(value: unknown): string[] {
   return Array.isArray(value)
     ? value.filter((line): line is string => typeof line === 'string')
@@ -2905,6 +2718,7 @@ function playRunResultFromStatus(
 export class DeeplineClient {
   private readonly http: HttpClient;
   private readonly toolCalls: ToolCalls;
+  private readonly playClient: PlayClient;
   private readonly config: ResolvedConfig;
   private readonly environment: ClientEnvironment;
   /** Canonical run lifecycle namespace backed by `/api/v2/runs`. */
@@ -2931,6 +2745,7 @@ export class DeeplineClient {
     this.config = resolveConfig(options);
     this.environment = this.config.environment ?? process.env;
     this.http = new HttpClient(this.config);
+    this.playClient = new PlayClient(this.http, this.environment);
     this.toolCalls = new ToolCalls(
       this.http,
       this.config.timeout,
@@ -2978,7 +2793,7 @@ export class DeeplineClient {
     };
     this.db = {
       query: (input) => this.queryDb(input),
-      planQuery: (input) => planCustomerDbQuery(input),
+      planQuery: (input) => planCustomerDbQuery(input, this.config.maxRetries),
     };
     this.billing = {
       quote: (input) =>
@@ -3220,6 +3035,57 @@ export class DeeplineClient {
     return res.tools;
   }
 
+  /** List category counts without downloading tool definitions. */
+  async listToolCategories(): Promise<ToolCategorySummary[]> {
+    const response = await this.http.get<ToolDiscoveryResponse>(
+      '/api/v2/tools?view=categories&compact=true',
+    );
+    if (response.view === 'categories') {
+      return readToolCategorySummaries(response.categories);
+    }
+    // Older servers ignore the additive view and return their existing list.
+    if (response.view === undefined && Array.isArray(response.tools)) {
+      return summarizeToolCategories(response.tools);
+    }
+    throw invalidToolDiscoveryResponse();
+  }
+
+  /** Read one complete category and its live category counts in one request. */
+  async listToolsInCategory(
+    category: string,
+    options?: { compact?: boolean },
+  ): Promise<ToolCategoryListing> {
+    const normalizedCategory = category.trim();
+    if (!normalizedCategory || category.includes(',')) {
+      throw new DeeplineError(
+        'Provide one non-empty tool category.',
+        400,
+        'INVALID_TOOL_CATEGORY',
+      );
+    }
+    const params = new URLSearchParams({
+      view: 'category',
+      categories: normalizedCategory,
+      compact: options?.compact === true ? 'true' : 'false',
+    });
+    const response = await this.http.get<ToolDiscoveryResponse>(
+      `/api/v2/tools?${params}`,
+    );
+    if (
+      !Array.isArray(response.tools) ||
+      (response.view !== 'category' && response.view !== undefined)
+    ) {
+      throw invalidToolDiscoveryResponse();
+    }
+    return {
+      tools: response.tools,
+      categories:
+        response.view === 'category'
+          ? readToolCategorySummaries(response.categories)
+          : await this.listToolCategories(),
+    };
+  }
+
   /** List discoverable providers without requiring a local plugin catalog. */
   async listProviders(options?: {
     changed?: boolean;
@@ -3394,7 +3260,7 @@ export class DeeplineClient {
   private async queryDb(
     input: CustomerDbQueryOptions,
   ): Promise<CustomerDbQueryResult> {
-    return queryCustomerDatabase(this.http, input);
+    return queryCustomerDatabase(this.http, input, this.config.maxRetries);
   }
 
   /**
@@ -3469,21 +3335,9 @@ export class DeeplineClient {
    */
   async startPlayRun(
     request: StartPlayRunRequest,
-    options?: {
-      onSubmission?: (intent: {
-        workflowId: string;
-        orgId: string;
-        request: Record<string, unknown>;
-      }) => void | Promise<void>;
-    },
+    options?: PlayRunStartOptions,
   ): Promise<PlayRunStart> {
-    const resolved = resolveStartPlayRunRequest(request, this.environment);
-    return startPlayRun(
-      this.http,
-      resolved.request,
-      runtimeSelectionHeaders(resolved.runtime, this.environment),
-      options?.onSubmission,
-    );
+    return this.playClient.startPlayRun(request, options);
   }
 
   /**
@@ -3493,6 +3347,7 @@ export class DeeplineClient {
   async preparePlayRunAdmission(
     request: StartPlayRunRequest,
     options?: {
+      cliAdmission?: boolean;
       onSubmission?: (intent: {
         workflowId: string;
         orgId: string;
@@ -3530,17 +3385,28 @@ export class DeeplineClient {
           );
         }
         submitted = true;
-        for await (const event of http.streamSse<PlayLiveEvent>(
-          PLAY_RUN_START_STREAM_PATH,
-          {
+        const streamPath = options?.cliAdmission
+          ? CLI_PLAY_RUN_START_STREAM_PATH
+          : PLAY_RUN_START_STREAM_PATH;
+        try {
+          for await (const event of http.streamSse<PlayLiveEvent>(streamPath, {
             method: 'POST',
             body: JSON.parse(bodyJson),
             headers,
             signal: streamOptions?.signal,
             exactUrlOnly: true,
-          },
-        )) {
-          if (event.scope === 'play') yield event;
+          })) {
+            if (event.scope === 'play') yield event;
+          }
+        } catch (error) {
+          if (
+            options?.cliAdmission &&
+            error instanceof DeeplineError &&
+            (error.statusCode === 404 || error.statusCode === 405)
+          ) {
+            throw new CliPlayAdmissionUnsupportedError(error.statusCode);
+          }
+          throw error;
         }
       },
     };
@@ -4061,27 +3927,31 @@ export class DeeplineClient {
     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);
+    return this.playClient.getPlayStatus(workflowId, options);
   }
 
-  /** Poll authenticated run snapshots every two seconds and emit changed events. */
+  /**
+   * Poll authenticated snapshots and emit changes; `deferLogs` delays terminal logs; `omitTerminalLogs` skips them.
+   */
   async *watchRunEvents(
     workflowId: string,
     options?: {
       signal?: AbortSignal;
       onNotice?: (message: string) => void;
       onRetry?: RunsWatchOptions['onRetry'];
+      /** Defer log-store reads until the run is terminal; the final log tail is unchanged. */
+      deferLogs?: boolean;
+      /** Skip log-store reads entirely for consumers that never render run logs. */
+      omitTerminalLogs?: boolean;
+      /** @internal Exposes bounded request timing for CLI diagnostics. */
+      onPoll?: (observation: WatchPollObservation) => void;
+      /** @internal Receive the requested durable status before terminal events. */
+      terminalStatus?: {
+        full?: boolean;
+        billing?: boolean;
+        runStatus?: boolean;
+        onStatus: (status: PlayStatus) => void | Promise<void>;
+      };
     },
   ): AsyncGenerator<PlayLiveEvent> {
     for await (const event of pollRunSnapshotEvents({
@@ -4090,6 +3960,31 @@ export class DeeplineClient {
       signal: options?.signal,
       onNotice: options?.onNotice,
       onRetry: options?.onRetry,
+      deferLogs: options?.deferLogs,
+      omitTerminalLogs: options?.omitTerminalLogs,
+      onPoll: options?.onPoll,
+      ...(options?.terminalStatus
+        ? {
+            terminalStatus: {
+              ...options.terminalStatus,
+              onStatus: async (
+                raw: Record<string, unknown>,
+                expectedStatus: string,
+              ) => {
+                const status = normalizePlayStatus(raw);
+                if (
+                  status.runId !== workflowId ||
+                  status.status !== expectedStatus
+                ) {
+                  throw new Error(
+                    `Run watch returned a mismatched terminal status for ${workflowId}.`,
+                  );
+                }
+                await options.terminalStatus?.onStatus(status);
+              },
+            },
+          }
+        : {}),
     })) {
       yield event as PlayLiveEvent;
     }
@@ -4155,10 +4050,17 @@ export class DeeplineClient {
     // Forward events without retaining their log history. Only lifecycle
     // evidence is needed here; the final package comes from the durable read.
     let terminalObserved = false;
+    let terminalStatus: PlayStatus | null = null;
     for await (const event of this.watchRunEvents(runId, {
       signal: options?.signal,
       onNotice: options?.onNotice,
       onRetry: options?.onRetry ?? options?.onReconnect,
+      terminalStatus: {
+        runStatus: true,
+        onStatus: (status) => {
+          terminalStatus = status;
+        },
+      },
     })) {
       options?.onEvent?.(event);
       if (isTerminalPlayRunLifecycleStatus(playLiveRunStatus(event))) {
@@ -4168,7 +4070,7 @@ export class DeeplineClient {
     if (options?.signal?.aborted) {
       throw new DeeplineError('Run watch aborted.', undefined, 'ABORTED');
     }
-    const refreshed = await this.getRunStatus(runId);
+    const refreshed = terminalStatus ?? (await this.getRunStatus(runId));
     if (
       terminalObserved ||
       isTerminalPlayRunLifecycleStatus(refreshed.status)
@@ -4210,10 +4112,7 @@ export class DeeplineClient {
    * ```
    */
   async cancelPlay(workflowId: string): Promise<void> {
-    await this.http.request(
-      `/api/v2/runs/${encodeURIComponent(workflowId)}/stop`,
-      { method: 'POST' },
-    );
+    return this.playClient.cancelPlay(workflowId);
   }
 
   /**
@@ -4226,10 +4125,7 @@ export class DeeplineClient {
     workflowId: string,
     options?: { reason?: string },
   ): Promise<StopPlayRunResult> {
-    return this.http.post<StopPlayRunResult>(
-      `/api/v2/runs/${encodeURIComponent(workflowId)}/stop`,
-      options?.reason ? { reason: options.reason } : {},
-    );
+    return this.playClient.stopPlay(workflowId, options);
   }
 
   /**
@@ -4250,11 +4146,7 @@ export class DeeplineClient {
    * ```
    */
   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 ?? [];
+    return this.playClient.listPlayRuns(playName);
   }
 
   // ---------------------------------------------------------------------------
@@ -5762,13 +5654,7 @@ export class DeeplineClient {
       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}`);
+    return this.playClient.getPlay(name, options);
   }
 
   /** Read one trigger inventory page without loading run histories. */
@@ -5857,11 +5743,7 @@ export class DeeplineClient {
     name: string,
     request: ClearPlayHistoryRequest = {},
   ): Promise<ClearPlayHistoryResult> {
-    const encodedName = encodeURIComponent(name);
-    return this.http.post<ClearPlayHistoryResult>(
-      `/api/v2/plays/${encodedName}/history/clear`,
-      request,
-    );
+    return this.playClient.clearPlayHistory(name, request);
   }
 
   /**
@@ -5877,12 +5759,7 @@ export class DeeplineClient {
     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 ?? [];
+    return this.playClient.listPlayVersions(name, options);
   }
 
   /**
@@ -5907,11 +5784,7 @@ export class DeeplineClient {
     name: string,
     request: PublishPlayVersionRequest = {},
   ): Promise<PublishPlayVersionResult> {
-    const encodedName = encodeURIComponent(name);
-    return this.http.post<PublishPlayVersionResult>(
-      `/api/v2/plays/${encodedName}/live`,
-      request,
-    );
+    return this.playClient.publishPlayVersion(name, request);
   }
 
   /**