deepline 0.3.461 → 0.3.463

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

@@ -52,7 +52,7 @@ export type {
  * });
  * ```
  *
- * Then run with the CLI: `deepline plays run --file my-play.play.ts`
+ * Then run with the CLI: `deepline run my-play.play.ts`
  * Installed npm CLIs can also run saved or prebuilt plays by name.
  *
  * ## Architecture
@@ -125,6 +125,9 @@ export type {
   BillingTopUpResult,
   BillingTopUpReceipt,
   BillingUsageEvent,
+  BillingUsageEventListEntry,
+  BillingUsageEventsOptions,
+  BillingUsageEventsResult,
   BillingUsageOptions,
   BillingUsageResult,
   WorkspaceCreateResult,

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

@@ -37,7 +37,7 @@
  * }
  * ```
  *
- * Run it with `deepline plays run lookup.play.ts --input '{"domain":"stripe.com"}'`.
+ * Run it with `deepline run lookup.play.ts --input '{"domain":"stripe.com"}'`.
  *
  * ### Programmatic usage
  *
@@ -468,8 +468,8 @@ export type DeeplinePlayRuntimeContext = PlayAuthoringRuntimeContext<'array'>;
  * ```
  *
  * ```bash
- * deepline plays run lookup.play.ts --input '{"domain":"stripe.com"}'
- * deepline plays run -e 'deepline.log("hello"); return { ok: true };'
+ * deepline run lookup.play.ts --input '{"domain":"stripe.com"}'
+ * deepline run -e 'deepline.log("hello"); return { ok: true };'
  * ```
  *
  * Compose with `import child from './child.play'` and
@@ -575,7 +575,7 @@ export const deepline: ScriptPlayContext = new Proxy({} as ScriptPlayContext, {
     if (!run) {
       if (!latestScriptRun) {
         throw new Error(
-          `deepline.${property} is only available while a play runs. Run the file with: deepline plays run <file>.play.ts`,
+          `deepline.${property} is only available while a play runs. Run the file with: deepline run <file>.play.ts`,
         );
       }
       if (Object.hasOwn(scriptCalls, property)) {
@@ -609,7 +609,7 @@ function contextMember(
 
 /**
  * Handle to a Play execution: inspect status, stream logs, await output, or cancel.
- * Like `deepline plays run` and `POST /api/v2/plays/run`, it returns a run id first.
+ * Like `deepline run` and `POST /api/v2/plays/run`, it returns a run id first.
  * Read completed output through `PlayJob.get()` or the status endpoint's `result` field;
  * runtime logs in `status().progress.logs` are separate from that output.
  *

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

@@ -0,0 +1,437 @@
+/**
+ * Remote Play operations shared by the full SDK client and imported Play handles.
+ * Handles resolve configuration lazily; a submitted job keeps its original client.
+ */
+import { DeeplineError } from '../errors';
+import type { HttpClient } from '../http-core';
+import { SDK_API_MAJOR } from '../version';
+import type {
+  ClearPlayHistoryRequest,
+  ClearPlayHistoryResult,
+  PlayDetail,
+  PlayRevisionSummary,
+  PlayRunListItem,
+  PlayRunStart,
+  PlayStatus,
+  PublishPlayVersionRequest,
+  PublishPlayVersionResult,
+  StartPlayRunRequest,
+  StopPlayRunResult,
+} from '../types';
+import {
+  isPlayRunPackage,
+  startPlayRun,
+  type ResolvedStartPlayRunRequest,
+  type PlayRunStartOptions,
+} from './run-request';
+import {
+  RUNTIME_ENVIRONMENT_TOKEN_HEADER,
+  RETAINED_PIPELINE_RECEIVERS_HEADER,
+} from '../../../shared_libs/play-runtime/coordinator-headers.js';
+import {
+  normalizePlayRuntimeEnvironment,
+  normalizePlayRuntimeNamespace,
+  normalizePlayRuntimeSandboxPlacementPolicy,
+  normalizePlayRunRuntimeSelection,
+  type PlayRunRuntimeSelection,
+} from '../../../shared_libs/play-runtime/runtime-environment.js';
+import { decodePlayRunPublicStatus } from '../../../shared_libs/play-runtime/run-lifecycle-policy.js';
+
+export function normalizePlayRunIntegrationMode(
+  value: unknown,
+): 'live' | 'eval_stub' | 'fixture' | undefined {
+  if (value === 'live' || value === 'eval_stub' || value === 'fixture') {
+    return value;
+  }
+  return undefined;
+}
+
+export type ClientEnvironment = Readonly<Record<string, string | undefined>>;
+
+function resolvePlayRunIntegrationMode(
+  request: StartPlayRunRequest,
+  env: ClientEnvironment,
+): 'live' | 'eval_stub' | 'fixture' | undefined {
+  return normalizePlayRunIntegrationMode(
+    request.integrationMode ?? env.DEEPLINE_EVAL_INTEGRATION_MODE,
+  );
+}
+
+function resolvePlayRunRuntimeSelection(
+  request: StartPlayRunRequest,
+  env: ClientEnvironment,
+): PlayRunRuntimeSelection | undefined {
+  if (request.runtime !== undefined) {
+    const runtime = normalizePlayRunRuntimeSelection(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}$, or { environment: "native", sandboxPlacementPolicy: "policy_name@1" }.',
+        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;
+  }
+  if (configured === 'native') {
+    // The app's own runtime on a named placement policy. The server decides
+    // from the API key's account whether this caller may ask for it.
+    const sandboxPlacementPolicy = normalizePlayRuntimeSandboxPlacementPolicy(
+      configuredPlacementPolicy,
+    );
+    if (configuredNamespace || !sandboxPlacementPolicy) {
+      throw new DeeplineError(
+        'DEEPLINE_RUNTIME_ENVIRONMENT=native requires DEEPLINE_RUNTIME_SANDBOX_PLACEMENT_POLICY (such as modal_only@1) and no DEEPLINE_RUNTIME_NAMESPACE.',
+        undefined,
+        'INVALID_RUNTIME_ENVIRONMENT',
+      );
+    }
+    return { environment: 'native', sandboxPlacementPolicy };
+  }
+  const environment = normalizePlayRuntimeEnvironment(configured);
+  if (!environment) {
+    throw new DeeplineError(
+      `DEEPLINE_RUNTIME_ENVIRONMENT must be preview or native. Received "${configured}". Omit it to use the app-native runtime.`,
+      undefined,
+      'INVALID_RUNTIME_ENVIRONMENT',
+    );
+  }
+  const namespace = normalizePlayRuntimeNamespace(configuredNamespace);
+  if (!namespace) {
+    throw new DeeplineError(
+      'DEEPLINE_RUNTIME_NAMESPACE is required for preview and must match ^[a-z][a-z0-9-]{0,30}$.',
+      undefined,
+      'INVALID_RUNTIME_NAMESPACE',
+    );
+  }
+  const configuredBackendValue = env.DEEPLINE_PLAY_RUNNER_BACKEND?.trim();
+  const configuredBackend =
+    configuredBackendValue === 'daytona' || configuredBackendValue === 'modal'
+      ? configuredBackendValue
+      : undefined;
+  if (configuredBackendValue && !configuredBackend) {
+    throw new DeeplineError(
+      `DEEPLINE_PLAY_RUNNER_BACKEND must be daytona or modal for preview runtime selection. Received "${configuredBackendValue}".`,
+      undefined,
+      'INVALID_RUNTIME_BACKEND',
+    );
+  }
+  if (
+    configuredPlacementPolicy &&
+    !normalizePlayRuntimeSandboxPlacementPolicy(configuredPlacementPolicy)
+  ) {
+    throw new DeeplineError(
+      `DEEPLINE_RUNTIME_SANDBOX_PLACEMENT_POLICY must be a versioned placement policy id such as daytona_only@1. Received "${configuredPlacementPolicy}".`,
+      undefined,
+      'INVALID_RUNTIME_SANDBOX_PLACEMENT_POLICY',
+    );
+  }
+  return {
+    environment,
+    namespace,
+    ...(configuredBackend ? { backend: configuredBackend } : {}),
+    ...(configuredPlacementPolicy
+      ? { sandboxPlacementPolicy: configuredPlacementPolicy }
+      : {}),
+  };
+}
+
+/**
+ * Resolve the environment-derived run-start fields (eval integration mode,
+ * test policy overrides, preview runtime) into explicit request fields, in the
+ * order the SDK has always validated them. The shared body builder in
+ * `plays/run-request` never reads the environment.
+ */
+export function resolveStartPlayRunRequest(
+  request: StartPlayRunRequest,
+  env: ClientEnvironment,
+): {
+  request: ResolvedStartPlayRunRequest;
+  runtime: PlayRunRuntimeSelection | undefined;
+} {
+  const integrationMode = resolvePlayRunIntegrationMode(request, env);
+  const testPolicyOverrides =
+    request.testPolicyOverrides ?? parseEnvTestPolicyOverrides(env);
+  const runtime = resolvePlayRunRuntimeSelection(request, env);
+  const resolved: ResolvedStartPlayRunRequest = { ...request };
+  delete resolved.integrationMode;
+  delete resolved.runtime;
+  delete resolved.testPolicyOverrides;
+  if (integrationMode) resolved.integrationMode = integrationMode;
+  if (runtime) resolved.runtime = runtime;
+  if (testPolicyOverrides) resolved.testPolicyOverrides = testPolicyOverrides;
+  return { request: resolved, runtime };
+}
+
+export function runtimeSelectionHeaders(
+  runtime: PlayRunRuntimeSelection | undefined,
+  env: ClientEnvironment,
+): Record<string, string> | undefined {
+  // A native selection carries no credential: the server checks the account.
+  if (!runtime || runtime.environment === 'native') return undefined;
+  // Keep the credential out of the typed runtime payload. The app consumes it
+  // at the HTTP boundary and never forwards it to Fly, Absurd, or Daytona.
+  const token = env.DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN?.trim();
+  if (!token) {
+    throw new DeeplineError(
+      'DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN is required for explicit preview runtime selection.',
+      undefined,
+      'RUNTIME_ENVIRONMENT_TOKEN_REQUIRED',
+    );
+  }
+  const receivers = env.DEEPLINE_RUNTIME_RETAINED_PIPELINE_RECEIVERS?.trim();
+  return {
+    [RUNTIME_ENVIRONMENT_TOKEN_HEADER]: token,
+    ...(receivers ? { [RETAINED_PIPELINE_RECEIVERS_HEADER]: receivers } : {}),
+  };
+}
+
+function normalizeTestPolicyOverrides(
+  value: unknown,
+  source: string,
+): Record<string, unknown> {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  throw new DeeplineError(
+    `${source} must be a JSON object.`,
+    undefined,
+    'INVALID_TEST_POLICY_OVERRIDES',
+  );
+}
+
+function parseEnvTestPolicyOverrides(
+  env: ClientEnvironment,
+): Record<string, unknown> | undefined {
+  const raw = env.DEEPLINE_TEST_POLICY_OVERRIDES;
+  const trimmed = raw?.trim();
+  if (!trimmed) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch (error) {
+    const detail = error instanceof Error ? ` ${error.message}` : '';
+    throw new DeeplineError(
+      `DEEPLINE_TEST_POLICY_OVERRIDES must be valid JSON.${detail}`,
+      undefined,
+      'INVALID_TEST_POLICY_OVERRIDES',
+    );
+  }
+  return normalizeTestPolicyOverrides(parsed, 'DEEPLINE_TEST_POLICY_OVERRIDES');
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+export function normalizePlayStatus(raw: Record<string, unknown>): PlayStatus {
+  const runPackage = isPlayRunPackage(raw)
+    ? raw
+    : isPlayRunPackage(raw.package)
+      ? raw.package
+      : null;
+  const packageRun = runPackage?.run;
+  const rawStatus =
+    typeof raw.status === 'string'
+      ? raw.status
+      : typeof packageRun?.status === 'string'
+        ? packageRun.status
+        : null;
+  const status = decodePlayRunPublicStatus(rawStatus);
+  if (!status) {
+    throw new Error(
+      `Invalid play run lifecycle status in API response: ${JSON.stringify(rawStatus)}.`,
+    );
+  }
+  const runId =
+    typeof raw.runId === 'string'
+      ? raw.runId
+      : typeof raw.workflowId === 'string'
+        ? raw.workflowId
+        : (packageRun?.id ?? '');
+  const legacyOverview = runPackage?.overview ?? raw.overview;
+  const runStatus = runPackage?.runStatus ?? raw.runStatus;
+  return {
+    ...(raw as unknown as Omit<PlayStatus, 'runId' | 'status'>),
+    runId,
+    ...(isRecord(legacyOverview)
+      ? {
+          overview: legacyOverview as unknown as PlayStatus['overview'],
+        }
+      : {}),
+    ...(isRecord(runStatus)
+      ? { runStatus: runStatus as unknown as PlayStatus['runStatus'] }
+      : {}),
+    ...(runPackage
+      ? {
+          package: runPackage,
+          outputs: runPackage.outputs,
+        }
+      : {}),
+    status,
+  };
+}
+
+export class PlayClient {
+  constructor(
+    private readonly http: HttpClient,
+    private readonly environment: ClientEnvironment = process.env,
+  ) {}
+
+  async startPlayRun(
+    request: StartPlayRunRequest,
+    options?: PlayRunStartOptions,
+  ): Promise<PlayRunStart> {
+    const resolved = resolveStartPlayRunRequest(request, this.environment);
+    const headers = runtimeSelectionHeaders(resolved.runtime, this.environment);
+    return startPlayRun(
+      this.http,
+      resolved.request,
+      options?.cliAdmission
+        ? { ...headers, 'X-Deepline-API-Major': String(SDK_API_MAJOR) }
+        : headers,
+      options,
+    );
+  }
+
+  async getPlayStatus(
+    workflowId: string,
+    options?: { billing?: boolean; full?: boolean },
+  ): Promise<PlayStatus> {
+    const params = new URLSearchParams();
+    if (options?.billing === false) {
+      params.set('billing', 'false');
+    }
+    if (options?.full === true) {
+      params.set('full', 'true');
+    }
+    const query = params.size > 0 ? `?${params.toString()}` : '';
+    const response = await this.http.get<Record<string, unknown>>(
+      `/api/v2/runs/${encodeURIComponent(workflowId)}${query}`,
+    );
+    return normalizePlayStatus(response);
+  }
+
+  async cancelPlay(workflowId: string): Promise<void> {
+    await this.http.request(
+      `/api/v2/runs/${encodeURIComponent(workflowId)}/stop`,
+      { method: 'POST' },
+    );
+  }
+
+  async stopPlay(
+    workflowId: string,
+    options?: { reason?: string },
+  ): Promise<StopPlayRunResult> {
+    return this.http.post<StopPlayRunResult>(
+      `/api/v2/runs/${encodeURIComponent(workflowId)}/stop`,
+      options?.reason ? { reason: options.reason } : {},
+    );
+  }
+
+  async listPlayRuns(playName: string): Promise<PlayRunListItem[]> {
+    const encodedName = encodeURIComponent(playName);
+    const response = await this.http.get<{ runs: PlayRunListItem[] }>(
+      `/api/v2/plays/${encodedName}/runs`,
+    );
+    return response.runs ?? [];
+  }
+
+  async getPlay(
+    name: string,
+    options?: {
+      source?: 'working' | 'live' | `version:${number}`;
+      guidance?: boolean;
+    },
+  ): Promise<PlayDetail> {
+    const encodedName = encodeURIComponent(name);
+    const query = options?.source
+      ? `?include=source&revision=${encodeURIComponent(options.source)}`
+      : options?.guidance
+        ? '?include=guidance'
+        : '';
+    return this.http.get<PlayDetail>(`/api/v2/plays/${encodedName}${query}`);
+  }
+
+  async clearPlayHistory(
+    name: string,
+    request: ClearPlayHistoryRequest = {},
+  ): Promise<ClearPlayHistoryResult> {
+    const encodedName = encodeURIComponent(name);
+    return this.http.post<ClearPlayHistoryResult>(
+      `/api/v2/plays/${encodedName}/history/clear`,
+      request,
+    );
+  }
+
+  async listPlayVersions(
+    name: string,
+    options?: { full?: boolean },
+  ): Promise<PlayRevisionSummary[]> {
+    const encodedName = encodeURIComponent(name);
+    const suffix = options?.full ? '?full=true' : '';
+    const response = await this.http.get<{ versions: PlayRevisionSummary[] }>(
+      `/api/v2/plays/${encodedName}/versions${suffix}`,
+    );
+    return response.versions ?? [];
+  }
+
+  async publishPlayVersion(
+    name: string,
+    request: PublishPlayVersionRequest = {},
+  ): Promise<PublishPlayVersionResult> {
+    const encodedName = encodeURIComponent(name);
+    return this.http.post<PublishPlayVersionResult>(
+      `/api/v2/plays/${encodedName}/live`,
+      request,
+    );
+  }
+}
+
+export type PlayClientOperations = Pick<
+  PlayClient,
+  | 'getPlay'
+  | 'listPlayRuns'
+  | 'listPlayVersions'
+  | 'publishPlayVersion'
+  | 'clearPlayHistory'
+  | 'startPlayRun'
+  | 'getPlayStatus'
+  | 'cancelPlay'
+  | 'stopPlay'
+>;