deepline 0.3.258 → 0.3.259

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

@@ -3,6 +3,14 @@ import type {
   PlaySettingsPatch,
   PlaySettingsPathsPage,
 } from '../../shared_libs/plays/settings-contract';
+import type {
+  PlayTriggerConfigUpdate,
+  PlayTriggerConfigUpdateResult,
+  PlayTriggerConfigView,
+} from '../../shared_libs/plays/trigger-config-contract';
+// Value import from the dependency-free module: the client is bundled into
+// authored Plays, where `zod` (the contract's schemas) cannot resolve.
+import { playTriggerConfigPath } from '../../shared_libs/plays/trigger-config-route';
 import { iterateCursorPages } from './pagination.js';
 import { playInputExampleArgs } from './plays/input-example.js';
 /**
@@ -77,7 +85,6 @@ import type {
   PlayRunResult,
   PlayRunStart,
   PlayStatus,
-  PlayRunPackage,
   PlayLiveEvent,
   PlayListItem,
   ProductNotificationSettings,
@@ -112,6 +119,17 @@ import { isStopAllPlayRunsDryRunResult } from './types.js';
 import type { MonitorDefinition } from './monitors.js';
 import type { MonitorFleetDefinition } from './monitor-fleets.js';
 import type { PlayStagedFileRef } from './plays/local-file-discovery.js';
+import {
+  buildPlayRunStartBody,
+  isPlayRunPackage,
+  mintStagedPlayFileUploads,
+  normalizePlayRunStart,
+  PLAY_RUN_START_STREAM_PATH,
+  stagePlayFiles,
+  startPlayRun,
+  type MintStagedFileUpload,
+  type ResolvedStartPlayRunRequest,
+} from './plays/run-request';
 import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-manifest.js';
 import type { EnrichCompiledConfig } from './cli/enrich-play-compiler.js';
 import {
@@ -394,6 +412,30 @@ function resolvePlayRunRuntimeSelection(
   };
 }
 
+/**
+ * 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): {
+  request: ResolvedStartPlayRunRequest;
+  runtime: PlayRuntimeSelection | undefined;
+} {
+  const integrationMode = resolvePlayRunIntegrationMode(request);
+  const testPolicyOverrides =
+    request.testPolicyOverrides ?? parseEnvTestPolicyOverrides();
+  const runtime = resolvePlayRunRuntimeSelection(request);
+  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,
 ): Record<string, string> | undefined {
@@ -884,7 +926,7 @@ export type RunsNamespace = {
     runId?: string;
     limit?: number;
     offset?: number;
-    rowMode?: 'output' | 'all';
+    rowMode?: 'output' | 'all' | 'live';
     /** Cancel the page request, including its response body and retry waits. */
     signal?: AbortSignal;
   }) => Promise<PlaySheetRowsResult>;
@@ -2163,6 +2205,17 @@ export type BillingUsageOptions = {
   runId?: string;
 };
 
+/** One run's billed credits and settlement state from `getRunBilling`. */
+export type RunBillingResult = {
+  runs: Array<{
+    runId: string;
+    /** Customer-visible billed credits so far; absent when unknown. */
+    credits?: number;
+    /** The run owns a charge reservation that has not settled yet. */
+    settling: boolean;
+  }>;
+};
+
 export type BillingUsageResult = {
   org_id: string;
   balance?: number;
@@ -2308,17 +2361,6 @@ function preferPrebuiltPlayDescriptions<T extends PlayDescription>(
     .map(({ play }) => play);
 }
 
-function isPlayRunPackage(value: unknown): value is PlayRunPackage {
-  return Boolean(
-    value &&
-    typeof value === 'object' &&
-    !Array.isArray(value) &&
-    (value as Record<string, unknown>).kind === 'play_run' &&
-    (value as Record<string, unknown>).run &&
-    typeof (value as { run?: { id?: unknown } }).run?.id === 'string',
-  );
-}
-
 function normalizePlayStatus(raw: Record<string, unknown>): PlayStatus {
   const runPackage = isPlayRunPackage(raw)
     ? raw
@@ -2367,170 +2409,6 @@ function normalizePlayStatus(raw: Record<string, unknown>): PlayStatus {
   };
 }
 
-function normalizePlayRunStart(raw: Record<string, unknown>): PlayRunStart {
-  const runPackage = isPlayRunPackage(raw)
-    ? raw
-    : isPlayRunPackage(raw.package)
-      ? raw.package
-      : null;
-  if (!runPackage) {
-    const workflowId =
-      typeof raw.workflowId === 'string' && raw.workflowId
-        ? raw.workflowId
-        : typeof raw.runId === 'string'
-          ? raw.runId
-          : '';
-    return {
-      ...(raw as unknown as Omit<PlayRunStart, 'workflowId'>),
-      workflowId,
-    };
-  }
-  const status =
-    typeof runPackage.run.status === 'string'
-      ? runPackage.run.status
-      : 'running';
-  return {
-    workflowId: runPackage.run.id,
-    name: runPackage.run.playName,
-    status,
-    ...(runPackage.run.dashboardUrl
-      ? { dashboardUrl: runPackage.run.dashboardUrl }
-      : {}),
-    ...(isTerminalPlayRunLifecycleStatus(status)
-      ? { finalStatus: runPackage }
-      : {}),
-    package: runPackage,
-  };
-}
-
-function decodeBase64Bytes(value: string): Uint8Array {
-  const binary = atob(value);
-  const bytes = new Uint8Array(binary.length);
-  for (let index = 0; index < binary.length; index += 1) {
-    bytes[index] = binary.charCodeAt(index);
-  }
-  return bytes;
-}
-
-/**
- * A staged-file upload target minted by POST /api/v2/plays/files/stage/mint.
- * When `alreadyStaged` is true the server already holds the content-addressed
- * object and `uploadUrl` is null; otherwise the client PUTs the body to
- * `uploadUrl` with `uploadHeaders`.
- */
-type MintStagedFileUpload = {
-  logicalPath: string;
-  contentHash: string;
-  ref: PlayStagedFileRef;
-  alreadyStaged: boolean;
-  uploadUrl: string | null;
-  uploadHeaders: Record<string, string> | null;
-  uploadExpiresAt: string | null;
-};
-
-// Legacy multipart staging proxies the body through the serverless function,
-// which caps request bodies near 4.5MB. Stay conservatively below that so the
-// fail-loud guidance fires before the platform returns an opaque 413.
-const STAGE_LEGACY_MULTIPART_MAX_BYTES = 4_000_000;
-
-const STAGE_DIRECT_UPLOAD_MAX_ATTEMPTS = 3;
-
-function stagedUploadIdentity(
-  logicalPath: string,
-  contentHash: string,
-): string {
-  return `${contentHash}:${logicalPath}`;
-}
-
-function isStagedUploadMintUnsupported(error: unknown): boolean {
-  // A server without the mint route returns 404. Treat only that as
-  // "unsupported, fall back"; every other failure propagates.
-  return error instanceof DeeplineError && error.statusCode === 404;
-}
-
-function isStagedUploadDirectEgressDenied(error: unknown): boolean {
-  return (
-    error instanceof DeeplineError &&
-    error.code === 'STAGED_FILE_UPLOAD_EGRESS_DENIED'
-  );
-}
-
-function formatMegabytes(bytes: number): string {
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}
-
-async function uploadStagedFileToPresignedUrl(input: {
-  url: string;
-  headers: Record<string, string>;
-  body: Uint8Array;
-  logicalPath: string;
-}): Promise<void> {
-  // Wrap the bytes in a fresh Blob so the body is a BodyInit and the upload is
-  // re-runnable across retries (a consumed stream would not be).
-  const arrayBuffer = input.body.buffer.slice(
-    input.body.byteOffset,
-    input.body.byteOffset + input.body.byteLength,
-  ) as ArrayBuffer;
-  let lastError: unknown;
-  for (
-    let attempt = 1;
-    attempt <= STAGE_DIRECT_UPLOAD_MAX_ATTEMPTS;
-    attempt += 1
-  ) {
-    try {
-      const response = await fetch(input.url, {
-        method: 'PUT',
-        headers: input.headers,
-        body: new Blob([arrayBuffer]),
-      });
-      if (response.ok) {
-        return;
-      }
-      const text = await response.text().catch(() => '');
-      const egressDenied =
-        response.status === 403 &&
-        response.headers.get('x-deny-reason')?.trim().toLowerCase() ===
-          'host_not_allowed';
-      lastError = new DeeplineError(
-        `Direct storage upload of ${input.logicalPath} failed: ${response.status} ${text.slice(0, 200)}`,
-        response.status,
-        egressDenied
-          ? 'STAGED_FILE_UPLOAD_EGRESS_DENIED'
-          : 'STAGED_FILE_UPLOAD_FAILED',
-        { logicalPath: input.logicalPath },
-      );
-      // 4xx (other than throttling) will not recover on retry.
-      if (response.status < 500 && response.status !== 429) {
-        break;
-      }
-    } catch (error) {
-      // fetch rejects network-level failures instead of returning a Response.
-      // Sandboxed egress proxies commonly reject the TLS CONNECT this way, so
-      // preserve the existing multipart fallback after direct retries finish.
-      lastError =
-        error instanceof TypeError
-          ? new DeeplineError(
-              `Direct storage upload of ${input.logicalPath} could not reach the storage endpoint: ${error.message}`,
-              undefined,
-              'STAGED_FILE_UPLOAD_EGRESS_DENIED',
-              { logicalPath: input.logicalPath },
-            )
-          : error;
-    }
-    if (attempt < STAGE_DIRECT_UPLOAD_MAX_ATTEMPTS) {
-      await sleep(250 * attempt);
-    }
-  }
-  throw lastError instanceof Error
-    ? lastError
-    : new DeeplineError(
-        `Direct storage upload of ${input.logicalPath} failed.`,
-        undefined,
-        'STAGED_FILE_UPLOAD_FAILED',
-        { logicalPath: input.logicalPath },
-      );
-}
-
 function readStringArray(value: unknown): string[] {
   return Array.isArray(value)
     ? value.filter((line): line is string => typeof line === 'string')
@@ -3422,74 +3300,12 @@ export class DeeplineClient {
    * ```
    */
   async startPlayRun(request: StartPlayRunRequest): Promise<PlayRunStart> {
-    const integrationMode = resolvePlayRunIntegrationMode(request);
-    const testPolicyOverrides =
-      request.testPolicyOverrides ?? parseEnvTestPolicyOverrides();
-    const forceToolRefresh = request.forceToolRefresh === true;
-    const runtime = resolvePlayRunRuntimeSelection(request);
-    const response = await this.http.post<Record<string, unknown>>(
-      '/api/v2/plays/run',
-      {
-        ...(request.name ? { name: request.name } : {}),
-        ...(request.revisionId ? { revisionId: request.revisionId } : {}),
-        ...(request.artifactStorageKey
-          ? { artifactStorageKey: request.artifactStorageKey }
-          : {}),
-        ...(request.sourceCode ? { sourceCode: request.sourceCode } : {}),
-        ...(request.sourceFiles ? { sourceFiles: request.sourceFiles } : {}),
-        ...(request.description ? { description: request.description } : {}),
-        ...('staticPipeline' in request
-          ? { staticPipeline: request.staticPipeline }
-          : {}),
-        ...(request.artifactHash ? { artifactHash: request.artifactHash } : {}),
-        ...(request.graphHash ? { graphHash: request.graphHash } : {}),
-        ...(request.runtimeArtifact
-          ? { runtimeArtifact: request.runtimeArtifact }
-          : {}),
-        ...(request.compilerManifest
-          ? { compilerManifest: request.compilerManifest }
-          : {}),
-        ...(request.inputFileUpload
-          ? { inputFileUpload: request.inputFileUpload }
-          : {}),
-        ...(request.packagedFileUploads?.length
-          ? { packagedFileUploads: request.packagedFileUploads }
-          : {}),
-        ...(request.input ? { input: request.input } : {}),
-        ...(request.inputFile ? { inputFile: request.inputFile } : {}),
-        ...(request.packagedFiles?.length
-          ? { packagedFiles: request.packagedFiles }
-          : {}),
-        ...(request.force ? { force: true } : {}),
-        ...(forceToolRefresh ? { forceToolRefresh: true } : {}),
-        ...(typeof request.maxConcurrentExternalCalls === 'number'
-          ? {
-              maxConcurrentExternalCalls: request.maxConcurrentExternalCalls,
-            }
-          : {}),
-        ...(typeof request.maxConcurrentRows === 'number'
-          ? { maxConcurrentRows: request.maxConcurrentRows }
-          : {}),
-        ...(typeof request.waitForCompletionMs === 'number'
-          ? { waitForCompletionMs: request.waitForCompletionMs }
-          : {}),
-        // Profile selection is the API's job, not the CLI's. The server
-        // defaults to absurd; callers normally omit this field.
-        ...(request.profile ? { profile: request.profile } : {}),
-        ...(integrationMode ? { integrationMode } : {}),
-        ...(request.fixtureBehavior
-          ? { fixtureBehavior: request.fixtureBehavior }
-          : {}),
-        ...(runtime ? { runtime } : {}),
-        ...(testPolicyOverrides ? { testPolicyOverrides } : {}),
-      },
-      runtimeSelectionHeaders(runtime),
-      // A start can reach the server even when its response is lost or times
-      // out. Retrying this mutation without an idempotency key can create a
-      // second root run, so callers must resolve ambiguous failures explicitly.
-      { maxRetries: 0, exactUrlOnly: true },
+    const resolved = resolveStartPlayRunRequest(request);
+    return startPlayRun(
+      this.http,
+      resolved.request,
+      runtimeSelectionHeaders(resolved.runtime),
     );
-    return normalizePlayRunStart(response);
   }
 
   /**
@@ -3509,67 +3325,14 @@ export class DeeplineClient {
     request: StartPlayRunRequest,
     options?: { signal?: AbortSignal },
   ): AsyncGenerator<PlayLiveEvent> {
-    const integrationMode = resolvePlayRunIntegrationMode(request);
-    const testPolicyOverrides =
-      request.testPolicyOverrides ?? parseEnvTestPolicyOverrides();
-    const forceToolRefresh = request.forceToolRefresh === true;
-    const runtime = resolvePlayRunRuntimeSelection(request);
-    const body = {
-      ...(request.name ? { name: request.name } : {}),
-      ...(request.revisionId ? { revisionId: request.revisionId } : {}),
-      ...(request.artifactStorageKey
-        ? { artifactStorageKey: request.artifactStorageKey }
-        : {}),
-      ...(request.sourceCode ? { sourceCode: request.sourceCode } : {}),
-      ...(request.sourceFiles ? { sourceFiles: request.sourceFiles } : {}),
-      ...(request.description ? { description: request.description } : {}),
-      ...('staticPipeline' in request
-        ? { staticPipeline: request.staticPipeline }
-        : {}),
-      ...(request.artifactHash ? { artifactHash: request.artifactHash } : {}),
-      ...(request.graphHash ? { graphHash: request.graphHash } : {}),
-      ...(request.runtimeArtifact
-        ? { runtimeArtifact: request.runtimeArtifact }
-        : {}),
-      ...(request.compilerManifest
-        ? { compilerManifest: request.compilerManifest }
-        : {}),
-      ...(request.inputFileUpload
-        ? { inputFileUpload: request.inputFileUpload }
-        : {}),
-      ...(request.packagedFileUploads?.length
-        ? { packagedFileUploads: request.packagedFileUploads }
-        : {}),
-      ...(request.input ? { input: request.input } : {}),
-      ...(request.inputFile ? { inputFile: request.inputFile } : {}),
-      ...(request.packagedFiles?.length
-        ? { packagedFiles: request.packagedFiles }
-        : {}),
-      ...(request.force ? { force: true } : {}),
-      ...(forceToolRefresh ? { forceToolRefresh: true } : {}),
-      ...(typeof request.maxConcurrentExternalCalls === 'number'
-        ? { maxConcurrentExternalCalls: request.maxConcurrentExternalCalls }
-        : {}),
-      ...(typeof request.maxConcurrentRows === 'number'
-        ? { maxConcurrentRows: request.maxConcurrentRows }
-        : {}),
-      ...(typeof request.waitForCompletionMs === 'number'
-        ? { waitForCompletionMs: request.waitForCompletionMs }
-        : {}),
-      ...(request.profile ? { profile: request.profile } : {}),
-      ...(integrationMode ? { integrationMode } : {}),
-      ...(request.fixtureBehavior
-        ? { fixtureBehavior: request.fixtureBehavior }
-        : {}),
-      ...(runtime ? { runtime } : {}),
-      ...(testPolicyOverrides ? { testPolicyOverrides } : {}),
-    };
+    const resolved = resolveStartPlayRunRequest(request);
+    const body = buildPlayRunStartBody(resolved.request);
     for await (const event of this.http.streamSse<PlayLiveEvent>(
-      '/api/v2/plays/run?stream=true',
+      PLAY_RUN_START_STREAM_PATH,
       {
         method: 'POST',
         body,
-        headers: runtimeSelectionHeaders(runtime),
+        headers: runtimeSelectionHeaders(resolved.runtime),
         signal: options?.signal,
       },
     )) {
@@ -3998,94 +3761,7 @@ export class DeeplineClient {
       bytes: number;
     }>,
   ): Promise<PlayStagedFileRef[]> {
-    // Primary path: mint presigned R2 PUT targets and upload each file body
-    // straight to storage. This bypasses the ~4.5MB serverless request-body
-    // limit that the legacy multipart proxy hits (413
-    // FUNCTION_PAYLOAD_TOO_LARGE), so large enriched CSVs stage and resume.
-    let uploads: MintStagedFileUpload[];
-    try {
-      uploads = await this.mintStagedPlayFileUploads(
-        files.map((file) => ({
-          logicalPath: file.logicalPath,
-          contentHash: file.contentHash,
-          contentType: file.contentType,
-          bytes: file.bytes,
-        })),
-      );
-    } catch (error) {
-      if (isStagedUploadMintUnsupported(error)) {
-        // The connected server predates direct-to-storage staging. Fall back to
-        // the legacy multipart proxy, but only for files small enough to clear
-        // the serverless body limit; larger files fail loud with guidance.
-        return this.stagePlayFilesViaMultipart(files);
-      }
-      throw error;
-    }
-
-    const uploadByIdentity = new Map<string, MintStagedFileUpload>();
-    for (const upload of uploads) {
-      uploadByIdentity.set(
-        stagedUploadIdentity(upload.logicalPath, upload.contentHash),
-        upload,
-      );
-    }
-
-    type DirectStageResult =
-      | { ref: PlayStagedFileRef }
-      | { fallbackFile: (typeof files)[number] };
-    const directResults: DirectStageResult[] = await Promise.all(
-      files.map(async (file) => {
-        const upload = uploadByIdentity.get(
-          stagedUploadIdentity(file.logicalPath, file.contentHash),
-        );
-        if (!upload) {
-          throw new DeeplineError(
-            `The staging server did not return an upload target for ${file.logicalPath}.`,
-            undefined,
-            'STAGED_FILE_MINT_INCOMPLETE',
-          );
-        }
-        if (upload.alreadyStaged || !upload.uploadUrl) {
-          return { ref: upload.ref };
-        }
-        try {
-          await uploadStagedFileToPresignedUrl({
-            url: upload.uploadUrl,
-            headers: upload.uploadHeaders ?? {
-              'content-type': file.contentType,
-            },
-            body: decodeBase64Bytes(file.contentBase64),
-            logicalPath: file.logicalPath,
-          });
-          return { ref: upload.ref };
-        } catch (error) {
-          if (isStagedUploadDirectEgressDenied(error)) {
-            return { fallbackFile: file };
-          }
-          throw error;
-        }
-      }),
-    );
-
-    return await Promise.all(
-      directResults.map(async (result) => {
-        if ('fallbackFile' in result) {
-          const [ref] = await this.stagePlayFilesViaMultipart(
-            [result.fallbackFile],
-            'direct-egress-denied',
-          );
-          if (!ref) {
-            throw new DeeplineError(
-              `The staging server did not return an upload target for ${result.fallbackFile.logicalPath}.`,
-              undefined,
-              'STAGED_FILE_MINT_INCOMPLETE',
-            );
-          }
-          return ref;
-        }
-        return result.ref;
-      }),
-    );
+    return stagePlayFiles(this.http, files);
   }
 
   /**
@@ -4103,72 +3779,7 @@ export class DeeplineClient {
       bytes: number;
     }>,
   ): Promise<MintStagedFileUpload[]> {
-    const response = await this.http.post<{
-      uploads: MintStagedFileUpload[];
-    }>('/api/v2/plays/files/stage/mint', { files });
-    return response.uploads ?? [];
-  }
-
-  private async stagePlayFilesViaMultipart(
-    files: Array<{
-      logicalPath: string;
-      contentBase64: string;
-      contentHash: string;
-      contentType: string;
-      bytes: number;
-    }>,
-    reason: 'mint-unsupported' | 'direct-egress-denied' = 'mint-unsupported',
-  ): Promise<PlayStagedFileRef[]> {
-    for (const file of files) {
-      if (file.bytes > STAGE_LEGACY_MULTIPART_MAX_BYTES) {
-        const reasonMessage =
-          reason === 'direct-egress-denied'
-            ? "direct storage is blocked by this environment's network egress policy"
-            : 'the connected Deepline server does not support direct-to-storage uploads';
-        throw new DeeplineError(
-          `Cannot stage ${file.logicalPath} (${formatMegabytes(file.bytes)}): ${reasonMessage}, and this file exceeds the ~4.5MB request-body limit the legacy upload path is subject to.`,
-          413,
-          'STAGED_FILE_TOO_LARGE_FOR_LEGACY_UPLOAD',
-          {
-            logicalPath: file.logicalPath,
-            bytes: file.bytes,
-            maxBytes: STAGE_LEGACY_MULTIPART_MAX_BYTES,
-          },
-        );
-      }
-    }
-    const buildFormData = () => {
-      const formData = new FormData();
-      formData.set(
-        'metadata',
-        JSON.stringify({
-          files: files.map((file, index) => ({
-            index,
-            logicalPath: file.logicalPath,
-            contentHash: file.contentHash,
-            contentType: file.contentType,
-            bytes: file.bytes,
-          })),
-        }),
-      );
-      for (const [index, file] of files.entries()) {
-        const bytes = decodeBase64Bytes(file.contentBase64);
-        const body = bytes.buffer.slice(
-          bytes.byteOffset,
-          bytes.byteOffset + bytes.byteLength,
-        ) as ArrayBuffer;
-        formData.set(
-          `file:${index}`,
-          new Blob([body], { type: file.contentType }),
-          file.logicalPath,
-        );
-      }
-      return formData;
-    };
-    const response = await this.http.postFormData<{
-      files: PlayStagedFileRef[];
-    }>('/api/v2/plays/files/stage', buildFormData);
-    return response.files;
+    return mintStagedPlayFileUploads(this.http, files);
   }
 
   /**
@@ -4750,7 +4361,7 @@ export class DeeplineClient {
     }
     return this.http.post<RerunPlayRunResult>(
       `/api/v2/runs/${encodeURIComponent(runId)}/rerun`,
-      {},
+      options?.inputOverrides ? { inputOverrides: options.inputOverrides } : {},
       { 'Idempotency-Key': idempotencyKey || globalThis.crypto.randomUUID() },
     );
   }
@@ -4906,7 +4517,7 @@ export class DeeplineClient {
     runId?: string;
     limit?: number;
     offset?: number;
-    rowMode?: 'output' | 'all';
+    rowMode?: 'output' | 'all' | 'live';
     /** Cancel the page request, including its response body and retry waits. */
     signal?: AbortSignal;
   }): Promise<PlaySheetRowsResult> {
@@ -4918,8 +4529,8 @@ export class DeeplineClient {
     if (input.runId?.trim()) {
       params.set('runId', input.runId.trim());
     }
-    if (input.rowMode === 'all') {
-      params.set('rowMode', 'all');
+    if (input.rowMode === 'all' || input.rowMode === 'live') {
+      params.set('rowMode', input.rowMode);
     }
     const result = await this.http.get<PlaySheetRowsResult>(
       `/api/v2/plays/${encodeURIComponent(input.playName)}/sheet?${params.toString()}`,
@@ -5146,6 +4757,23 @@ export class DeeplineClient {
     );
   }
 
+  /** Read a Play's cron and webhook triggers and their scheduler state. */
+  async getPlayTriggerConfig(playName: string): Promise<PlayTriggerConfigView> {
+    return this.http.get(playTriggerConfigPath(playName));
+  }
+
+  /**
+   * Declare a Play's cron and/or webhook trigger (null removes it) and publish
+   * the rewritten source as a new live revision. Retry-safe: a request the
+   * live revision already satisfies returns `changed: false`.
+   */
+  async updatePlayTriggerConfig(
+    playName: string,
+    update: PlayTriggerConfigUpdate,
+  ): Promise<PlayTriggerConfigUpdateResult> {
+    return this.http.put(playTriggerConfigPath(playName), update);
+  }
+
   /** List one bounded page of existing Play locations; continue with cursor. */
   async listPlaySettingsPaths(
     options: { root?: 'person' | 'team'; limit?: number; cursor?: string } = {},
@@ -6028,6 +5656,17 @@ export class DeeplineClient {
     return event;
   }
 
+  /**
+   * What Deepline has billed each run so far (customer-visible credits, never
+   * provider spend) and whether any of its charges is still settling — the
+   * same read the dashboard's runs grid shows. `GET /api/v2/runs/billing`.
+   */
+  async getRunBilling(runIds: readonly string[]): Promise<RunBillingResult> {
+    const params = new URLSearchParams();
+    for (const runId of runIds) params.append('runId', runId);
+    return this.http.get<RunBillingResult>(`/api/v2/runs/billing?${params}`);
+  }
+
   /**
    * Read workspace usage and recent customer-facing Deepline charges. Pass
    * the `job_id` from `executeTool` as `requestId` to retrieve one exact call,