deepline 0.3.257 → 0.3.259

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

@@ -0,0 +1,855 @@
+/**
+ * The one client-side construction of a Play run start.
+ *
+ * `deepline plays run <name>` (CLI), `DeeplineClient.startPlayRun` (SDK), and
+ * the dashboard's "Run in UI" form all start a run through this module: the
+ * same file-input bindings, the same staged-file upload
+ * (`/api/v2/plays/files/stage/mint`, direct PUT, multipart fallback), the same
+ * `POST /api/v2/plays/run` body, and the same start-response normalization.
+ * The strict CSV check on the `csv` data input lives in `./csv-data-input`. Only the transport differs: the SDK's
+ * `HttpClient` carries an API key, the dashboard's same-origin transport
+ * carries the browser session cookie, and one route handler accepts both.
+ *
+ * Browser-safe by construction: no `node:` imports, no `process`, no global
+ * `Buffer`. Environment-derived options (eval integration mode, preview
+ * runtime selection, test policy overrides) are resolved by the caller and
+ * passed in as explicit request fields.
+ */
+import { DeeplineError } from '../../../shared_libs/plays/tool-execution-error';
+import { isTerminalPlayRunLifecycleStatus } from '../../../shared_libs/play-runtime/run-lifecycle-policy.js';
+import { apiErrorCodeFromResponse, apiErrorMessage } from '../api-error';
+import type {
+  PlayRunPackage,
+  PlayRunStart,
+  StartPlayRunRequest,
+} from '../types.js';
+import type { PlayStagedFileRef } from './local-file-discovery.js';
+
+export { DeeplineError };
+
+/** The single run-start route. CLI, SDK, API, and dashboard all POST here. */
+export const PLAY_RUN_START_PATH = '/api/v2/plays/run';
+export const PLAY_RUN_START_STREAM_PATH = `${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`;
+
+/**
+ * The HTTP surface a run start needs. `HttpClient` satisfies it structurally;
+ * the dashboard implements it over same-origin `fetch` with session cookies.
+ * Implementations throw `DeeplineError` (with `statusCode`) for non-2xx
+ * responses so the staging fallbacks below classify failures identically.
+ */
+export interface PlayRunHttp {
+  post<T = unknown>(
+    path: string,
+    body: unknown,
+    headers?: Record<string, string>,
+    options?: { maxRetries?: number; exactUrlOnly?: boolean },
+  ): Promise<T>;
+  postFormData<T = unknown>(
+    path: string,
+    formData: FormData | (() => FormData),
+  ): Promise<T>;
+}
+
+// ── Run-start body and response ─────────────────────────────────────────────
+
+/**
+ * A run-start request whose environment-derived fields are already resolved.
+ * `buildPlayRunStartBody` never reads the environment; the SDK client resolves
+ * `integrationMode`, `runtime`, and `testPolicyOverrides` before calling it.
+ */
+export type ResolvedStartPlayRunRequest = StartPlayRunRequest;
+
+/** The exact JSON body `POST /api/v2/plays/run` receives. Key order is part of the contract. */
+export function buildPlayRunStartBody(
+  request: ResolvedStartPlayRunRequest,
+): Record<string, unknown> {
+  return {
+    ...(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 } : {}),
+    ...(request.forceToolRefresh === true ? { 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 caller's. The server
+    // defaults to absurd; callers normally omit this field.
+    ...(request.profile ? { profile: request.profile } : {}),
+    ...(request.integrationMode
+      ? { integrationMode: request.integrationMode }
+      : {}),
+    ...(request.fixtureBehavior
+      ? { fixtureBehavior: request.fixtureBehavior }
+      : {}),
+    ...(request.runtime ? { runtime: request.runtime } : {}),
+    ...(request.testPolicyOverrides
+      ? { testPolicyOverrides: request.testPolicyOverrides }
+      : {}),
+  };
+}
+
+/**
+ * Start a run: one POST of {@link buildPlayRunStartBody} to
+ * {@link PLAY_RUN_START_PATH}, normalized to a {@link PlayRunStart}.
+ *
+ * Never retried: a start can reach the server even when its response is lost
+ * or times out, and retrying without an idempotency key can create a second
+ * root run, so callers resolve ambiguous failures explicitly.
+ */
+export async function startPlayRun(
+  http: PlayRunHttp,
+  request: ResolvedStartPlayRunRequest,
+  headers?: Record<string, string>,
+): Promise<PlayRunStart> {
+  const response = await http.post<Record<string, unknown>>(
+    PLAY_RUN_START_PATH,
+    buildPlayRunStartBody(request),
+    headers,
+    { maxRetries: 0, exactUrlOnly: true },
+  );
+  return normalizePlayRunStart(response);
+}
+
+export 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',
+  );
+}
+
+/** Normalize any run-start response shape to `{ workflowId, … }`. */
+export 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,
+  };
+}
+
+/**
+ * The run request for a Play started by name. `extra` carries caller options
+ * (CLI flags such as `--force`); the dashboard passes none.
+ */
+export function buildNamedPlayRunRequest(input: {
+  name: string;
+  revisionId?: string | null;
+  runtimeInput: Record<string, unknown>;
+  stagedFileInputs: StagedFileInputs;
+  extra?: Omit<
+    StartPlayRunRequest,
+    'name' | 'revisionId' | 'input' | 'inputFile' | 'packagedFiles'
+  >;
+}): StartPlayRunRequest {
+  return {
+    name: input.name,
+    ...(input.revisionId ? { revisionId: input.revisionId } : {}),
+    ...(Object.keys(input.runtimeInput).length > 0
+      ? { input: input.runtimeInput }
+      : {}),
+    ...(input.stagedFileInputs.inputFile
+      ? { inputFile: input.stagedFileInputs.inputFile }
+      : {}),
+    ...(input.stagedFileInputs.packagedFiles.length
+      ? { packagedFiles: input.stagedFileInputs.packagedFiles }
+      : {}),
+    ...input.extra,
+  };
+}
+
+// ── File-input bindings ─────────────────────────────────────────────────────
+
+/** A declared input whose value is a file the run stages before starting. */
+export type FileInputBinding = { inputPath: string };
+
+/**
+ * The declared property name that carries the play's CSV row data (the row
+ * source). Only this key triggers strict CSV parsing; every other file input
+ * is staged without parsing its contents.
+ */
+export const CSV_DATA_INPUT_KEY = 'csv';
+
+function schemaMetadata(
+  schema: Record<string, unknown> | null | undefined,
+  key: string,
+): Record<string, unknown> | null {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema))
+    return null;
+  const value = schema[key];
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function stringMetadata(
+  metadata: Record<string, unknown> | null | undefined,
+  key: string,
+): string | null {
+  const value = metadata?.[key];
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function inputFieldFromCsvArg(csvArg: unknown): string | null {
+  if (typeof csvArg !== 'string') return null;
+  // The static pipeline preserves the authored expression, not just the
+  // resolved source. A very common, valid form is
+  // `ctx.csv(input.csv ?? 'default.csv')`: when the caller supplies --csv, the
+  // input field still owns the staged file and must be rewritten to its logical
+  // path before the runner starts.
+  const match =
+    /^\(?\s*input\.([A-Za-z_$][\w$]*)\s*\)?(?:\s*\?\?[\s\S]+)?$/.exec(
+      csvArg.trim(),
+    );
+  return match?.[1] ?? null;
+}
+
+/** The `csvInput` binding a `CsvInput<Row>` field compiles to. */
+export function fileInputBindingsFromPlaySchema(
+  inputSchema: Record<string, unknown> | null | undefined,
+): FileInputBinding[] {
+  const csvInput = schemaMetadata(inputSchema, 'csvInput');
+  if (!csvInput) return [];
+  return [
+    {
+      inputPath: stringMetadata(csvInput, 'inputField') ?? CSV_DATA_INPUT_KEY,
+    },
+  ];
+}
+
+/** The input field a `ctx.csv(input.x)` call reads. */
+export function fileInputBindingsFromStaticPipeline(
+  staticPipeline: unknown,
+): FileInputBinding[] {
+  if (
+    !staticPipeline ||
+    typeof staticPipeline !== 'object' ||
+    Array.isArray(staticPipeline)
+  ) {
+    return [];
+  }
+  const inputField = inputFieldFromCsvArg(
+    (staticPipeline as Record<string, unknown>).csvArg,
+  );
+  return inputField ? [{ inputPath: inputField }] : [];
+}
+
+/** Every file-input binding of a Play definition, in staging order. */
+export function playRunFileInputBindings(play: {
+  inputSchema?: Record<string, unknown> | null;
+  staticPipeline?: unknown;
+}): FileInputBinding[] {
+  return [
+    ...fileInputBindingsFromPlaySchema(play.inputSchema),
+    ...fileInputBindingsFromStaticPipeline(play.staticPipeline),
+  ];
+}
+
+export function getDottedInputValue(
+  input: Record<string, unknown>,
+  path: string,
+): unknown {
+  const parts = path
+    .split('.')
+    .map((part) => part.trim())
+    .filter(Boolean);
+  let cursor: unknown = input;
+  for (const part of parts) {
+    if (!cursor || typeof cursor !== 'object' || Array.isArray(cursor)) {
+      return undefined;
+    }
+    cursor = (cursor as Record<string, unknown>)[part];
+  }
+  return cursor;
+}
+
+export function setDottedInputValue(
+  input: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): void {
+  const parts = path
+    .split('.')
+    .map((part) => part.trim())
+    .filter(Boolean);
+  if (parts.length === 0) {
+    throw new Error(`Invalid play input flag path: ${path}`);
+  }
+  let cursor: Record<string, unknown> = input;
+  for (const part of parts.slice(0, -1)) {
+    const existing = cursor[part];
+    if (
+      existing !== undefined &&
+      (!existing || typeof existing !== 'object' || Array.isArray(existing))
+    ) {
+      throw new Error(
+        `Cannot set --${path}; input.${part} is already a non-object value.`,
+      );
+    }
+    if (!existing) {
+      cursor[part] = {};
+    }
+    cursor = cursor[part] as Record<string, unknown>;
+  }
+  cursor[parts[parts.length - 1]!] = value;
+}
+
+// ── Staged file uploads ─────────────────────────────────────────────────────
+
+/** One file's bytes, encoded the way the staging routes receive them. */
+export type StagedFileUpload = {
+  logicalPath: string;
+  contentBase64: string;
+  contentHash: string;
+  contentType: string;
+  bytes: number;
+};
+
+/**
+ * Byte encoders. The default uses Web Crypto and `btoa` (browser and Node
+ * 18+); the CLI passes Node's `createHash`/`Buffer`, which produce identical
+ * output faster for large files.
+ */
+export type StagedFileCodec = {
+  sha256Hex(bytes: Uint8Array): Promise<string> | string;
+  base64(bytes: Uint8Array): string;
+};
+
+export const webStagedFileCodec: StagedFileCodec = {
+  async sha256Hex(bytes) {
+    const digest = await globalThis.crypto.subtle.digest(
+      'SHA-256',
+      bytes as Uint8Array<ArrayBuffer>,
+    );
+    return Array.from(new Uint8Array(digest), (byte) =>
+      byte.toString(16).padStart(2, '0'),
+    ).join('');
+  },
+  base64(bytes) {
+    let binary = '';
+    for (let offset = 0; offset < bytes.length; offset += 0x8000) {
+      binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+    }
+    return btoa(binary);
+  },
+};
+
+export function stagedFileContentType(logicalPath: string): string {
+  const lower = logicalPath.toLowerCase();
+  return lower.endsWith('.csv')
+    ? 'text/csv'
+    : lower.endsWith('.json')
+      ? 'application/json'
+      : 'application/octet-stream';
+}
+
+export async function createStagedFileUpload(
+  logicalPath: string,
+  bytes: Uint8Array,
+  codec: StagedFileCodec = webStagedFileCodec,
+): Promise<StagedFileUpload> {
+  return {
+    logicalPath,
+    contentBase64: codec.base64(bytes),
+    contentHash: await codec.sha256Hex(bytes),
+    contentType: stagedFileContentType(logicalPath),
+    bytes: bytes.byteLength,
+  };
+}
+
+/**
+ * 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`.
+ */
+export 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.
+export const STAGE_LEGACY_MULTIPART_MAX_BYTES = 4_000_000;
+
+const STAGE_DIRECT_UPLOAD_MAX_ATTEMPTS = 3;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+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`;
+}
+
+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;
+}
+
+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, and
+      // a browser rejects a cross-origin PUT the storage bucket's CORS policy
+      // does not allow the same way, so both take the 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 },
+      );
+}
+
+/**
+ * Mint short-lived presigned upload targets for staged play files. The server
+ * returns an already-staged ref (no upload needed) for content-addressed files
+ * it already holds, or a presigned PUT URL the caller uploads the body to.
+ */
+export async function mintStagedPlayFileUploads(
+  http: PlayRunHttp,
+  files: Array<{
+    logicalPath: string;
+    contentHash: string;
+    contentType: string;
+    bytes: number;
+  }>,
+): Promise<MintStagedFileUpload[]> {
+  const response = await http.post<{
+    uploads: MintStagedFileUpload[];
+  }>(PLAY_FILES_STAGE_MINT_PATH, { files });
+  return response.uploads ?? [];
+}
+
+async function stagePlayFilesViaMultipart(
+  http: PlayRunHttp,
+  files: StagedFileUpload[],
+  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 http.postFormData<{
+    files: PlayStagedFileRef[];
+  }>(PLAY_FILES_STAGE_PATH, buildFormData);
+  return response.files;
+}
+
+/**
+ * Stage play files. Primary path: mint presigned R2 PUT targets and upload each
+ * body straight to storage, bypassing the ~4.5MB serverless request-body limit.
+ * Falls back to the multipart route when the server predates minting, or per
+ * file when direct storage is unreachable from this environment.
+ */
+export async function stagePlayFiles(
+  http: PlayRunHttp,
+  files: StagedFileUpload[],
+): Promise<PlayStagedFileRef[]> {
+  let uploads: MintStagedFileUpload[];
+  try {
+    uploads = await mintStagedPlayFileUploads(
+      http,
+      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 stagePlayFilesViaMultipart(http, 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: StagedFileUpload };
+  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 stagePlayFilesViaMultipart(
+          http,
+          [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;
+    }),
+  );
+}
+
+export type StagedFileInputs = {
+  inputFile: PlayStagedFileRef | null;
+  packagedFiles: PlayStagedFileRef[];
+};
+
+/** A bound input value that resolves to local bytes (a CLI path or a dropped file). */
+export type LocalFileInput = {
+  logicalPath: string;
+  read(): Promise<Uint8Array>;
+};
+
+/**
+ * Stage every bound file input whose value resolves to local bytes, rewrite
+ * that input to the staged logical path, and return the staged refs: the first
+ * is the run's `inputFile`, the rest are `packagedFiles`.
+ */
+export async function stageFileInputs(input: {
+  /** `stagePlayFiles` bound to the caller's transport (the SDK client's `stagePlayFiles`, or {@link stagePlayFiles} over the session transport). */
+  stage: (files: StagedFileUpload[]) => Promise<PlayStagedFileRef[]>;
+  runtimeInput: Record<string, unknown>;
+  bindings: readonly FileInputBinding[];
+  resolveLocalFile: (
+    value: unknown,
+    binding: FileInputBinding,
+  ) => LocalFileInput | null;
+  codec?: StagedFileCodec;
+  onStaging?: (fileCount: number) => void;
+}): Promise<StagedFileInputs> {
+  const uniqueBindings = [
+    ...new Map(
+      input.bindings.map((binding) => [binding.inputPath, binding]),
+    ).values(),
+  ];
+  const localFiles = uniqueBindings.flatMap((binding) => {
+    const file = input.resolveLocalFile(
+      getDottedInputValue(input.runtimeInput, binding.inputPath),
+      binding,
+    );
+    return file ? [{ binding, file }] : [];
+  });
+
+  if (localFiles.length === 0) {
+    return { inputFile: null, packagedFiles: [] };
+  }
+
+  input.onStaging?.(localFiles.length);
+  const uploads = await Promise.all(
+    localFiles.map(async ({ file }) =>
+      createStagedFileUpload(file.logicalPath, await file.read(), input.codec),
+    ),
+  );
+  const staged = await input.stage(uploads);
+  for (const [index, { binding, file }] of localFiles.entries()) {
+    setDottedInputValue(
+      input.runtimeInput,
+      binding.inputPath,
+      file.logicalPath,
+    );
+    const stagedFile = staged[index];
+    if (stagedFile && stagedFile.logicalPath !== file.logicalPath) {
+      setDottedInputValue(
+        input.runtimeInput,
+        binding.inputPath,
+        stagedFile.logicalPath,
+      );
+    }
+  }
+
+  return {
+    inputFile: staged[0] ?? null,
+    packagedFiles: staged.slice(1),
+  };
+}
+
+// ── Same-origin session transport ───────────────────────────────────────────
+
+/**
+ * {@link PlayRunHttp} for a signed-in dashboard: relative same-origin paths,
+ * authenticated by the browser session cookie instead of an API key. It never
+ * retries; a start is never retried by the SDK client either.
+ */
+export function createSessionPlayRunHttp(
+  fetchImpl: typeof fetch = (...args) => fetch(...args),
+): PlayRunHttp {
+  const send = async <T>(path: string, init: RequestInit): Promise<T> => {
+    const response = await fetchImpl(path, {
+      ...init,
+      credentials: 'include',
+    });
+    const text = await response.text();
+    let parsed: unknown = text;
+    try {
+      parsed = text ? JSON.parse(text) : null;
+    } catch {
+      // Keep the raw text; a non-JSON error body still surfaces below.
+    }
+    if (!response.ok) {
+      throw new DeeplineError(
+        apiErrorMessage(parsed, response.status),
+        response.status,
+        apiErrorCodeFromResponse(parsed),
+        { response: parsed },
+      );
+    }
+    return parsed as T;
+  };
+  return {
+    post: (path, body, headers) =>
+      send(path, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...headers },
+        body: JSON.stringify(body),
+      }),
+    postFormData: (path, formData) =>
+      send(path, {
+        method: 'POST',
+        body: typeof formData === 'function' ? formData() : formData,
+      }),
+  };
+}