deepline 0.1.51 → 0.1.53

package/dist/repo/sdk/src/client.ts

@@ -46,6 +46,7 @@ import type {
   PlayRunResult,
   PlayRunStart,
   PlayStatus,
+  PlayRunPackage,
   PlayLiveEvent,
   PlayListItem,
   PlayDescription,
@@ -158,7 +159,7 @@ export type PlaySheetRowsResult = {
 };
 
 export type RunsNamespace = {
-  get: (runId: string) => Promise<PlayStatus>;
+  get: (runId: string, options?: { full?: boolean }) => Promise<PlayStatus>;
   list: (options: RunsListOptions) => Promise<PlayRunListItem[]>;
   tail: (runId: string, options?: RunsTailOptions) => Promise<PlayStatus>;
   logs: (runId: string, options?: RunsLogsOptions) => Promise<RunsLogsResult>;
@@ -179,22 +180,69 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
 
+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
+    : isPlayRunPackage(raw.package)
+      ? raw.package
+      : null;
+  const packageRun = runPackage?.run;
   const status =
-    typeof raw.status === 'string' ? raw.status : 'running';
+    typeof raw.status === 'string'
+      ? raw.status
+      : typeof packageRun?.status === 'string'
+        ? packageRun.status
+        : 'running';
   const runId =
     typeof raw.runId === 'string'
       ? raw.runId
       : typeof raw.workflowId === 'string'
         ? raw.workflowId
-        : '';
+        : packageRun?.id ?? '';
   return {
     ...(raw as unknown as Omit<PlayStatus, 'runId' | 'status'>),
     runId,
+    ...(runPackage ? { package: runPackage, outputs: runPackage.outputs } : {}),
     status: status as PlayStatus['status'],
   };
 }
 
+function normalizePlayRunStart(raw: Record<string, unknown>): PlayRunStart {
+  const runPackage = isPlayRunPackage(raw)
+    ? raw
+    : isPlayRunPackage(raw.package)
+      ? raw.package
+      : null;
+  if (!runPackage) {
+    return raw as unknown as PlayRunStart;
+  }
+  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 }
+      : {}),
+    ...(TERMINAL_PLAY_STATUSES.has(status)
+      ? { finalStatus: runPackage }
+      : {}),
+    package: runPackage,
+  };
+}
+
 function decodeBase64Bytes(value: string): Uint8Array {
   const binary = atob(value);
   const bytes = new Uint8Array(binary.length);
@@ -259,18 +307,32 @@ function updatePlayLiveStatusState(
   const runId =
     typeof payload.runId === 'string' && payload.runId
       ? payload.runId
+      : isPlayRunPackage(payload)
+        ? payload.run.id
       : state.runId;
-  const status = normalizeLiveStatus(payload.status) ?? state.status;
-  const logs = readStringArray(payload.logs);
+  const status =
+    normalizeLiveStatus(payload.status) ??
+    (isPlayRunPackage(payload)
+      ? normalizeLiveStatus(payload.run.status)
+      : null) ??
+    state.status;
+  const progressPayload = isRecord(payload.progress)
+    ? payload.progress
+    : {};
+  const payloadLogs = readStringArray(payload.logs);
+  const progressLogs = readStringArray(progressPayload.logs);
+  const logs = payloadLogs.length > 0 ? payloadLogs : progressLogs;
   if (
     logs.length > 0 ||
     event.type === 'play.run.snapshot' ||
-    event.type === 'play.run.final_status'
+    (event.type === 'play.run.final_status' && !isPlayRunPackage(payload))
   ) {
     state.logs = logs;
   }
   if ('result' in payload) {
     state.result = payload.result;
+  } else if (isPlayRunPackage(payload)) {
+    state.result = payload;
   }
   if (typeof payload.error === 'string' && payload.error.trim()) {
     state.error = payload.error;
@@ -278,16 +340,14 @@ function updatePlayLiveStatusState(
   state.runId = runId;
   state.status = status;
 
-  const progressRecord =
-    payload.progress &&
-    typeof payload.progress === 'object' &&
-    !Array.isArray(payload.progress)
-      ? (payload.progress as Record<string, unknown>)
-      : {};
+  const progressRecord = progressPayload;
   const next: PlayStatus = {
     ...(payload as unknown as Omit<PlayStatus, 'runId' | 'status' | 'progress'>),
     runId,
     status,
+    ...(isPlayRunPackage(payload)
+      ? { package: payload, outputs: payload.outputs }
+      : {}),
     progress: {
       ...progressRecord,
       status:
@@ -311,7 +371,8 @@ function playRunResultFromStatus(
   return {
     success: status.status === 'completed',
     runId: status.runId || fallbackRunId,
-    result: status.result,
+    result: status.package ?? status.result,
+    ...(status.package ? { package: status.package } : {}),
     logs: status.progress?.logs ?? [],
     durationMs: Date.now() - startedAt,
     error:
@@ -366,7 +427,7 @@ export class DeeplineClient {
     this.config = resolveConfig(options);
     this.http = new HttpClient(this.config);
     this.runs = {
-      get: (runId) => this.getRunStatus(runId),
+      get: (runId, options) => this.getRunStatus(runId, options),
       list: (options) => this.listRuns(options),
       tail: (runId, options) => this.tailRun(runId, options),
       logs: (runId, options) => this.getRunLogs(runId, options),
@@ -647,9 +708,9 @@ export class DeeplineClient {
    *   artifactStorageKey: 'plays/v1/orgs/acme/plays/my-play/artifacts/playgraph_abc123.json',
    * });
    * ```
-   */
+  */
   async startPlayRun(request: StartPlayRunRequest): Promise<PlayRunStart> {
-    return this.http.post<PlayRunStart>('/api/v2/plays/run', {
+    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
@@ -688,6 +749,7 @@ export class DeeplineClient {
       // different profile pass `request.profile` explicitly.
       ...(request.profile ? { profile: request.profile } : {}),
     });
+    return normalizePlayRunStart(response);
   }
 
   async *startPlayRunStream(
@@ -1124,12 +1186,15 @@ export class DeeplineClient {
    */
   async getPlayStatus(
     workflowId: string,
-    options?: { billing?: boolean },
+    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/plays/run/${encodeURIComponent(workflowId)}${query}`,
@@ -1236,9 +1301,17 @@ export class DeeplineClient {
    * deepline runs get <run-id> --json
    * ```
    */
-  async getRunStatus(runId: string): Promise<PlayStatus> {
+  async getRunStatus(
+    runId: string,
+    options?: { full?: boolean },
+  ): Promise<PlayStatus> {
+    const params = new URLSearchParams();
+    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(runId)}`,
+      `/api/v2/runs/${encodeURIComponent(runId)}${query}`,
     );
     return normalizePlayStatus(response);
   }

package/dist/repo/sdk/src/play.ts

@@ -838,6 +838,9 @@ class DeeplinePlayJobImpl<TOutput = unknown> implements PlayJob<TOutput> {
               `Play run ${this.id} ended with ${status.status}.`,
           );
         }
+        if (status.package) {
+          return status.package as TOutput;
+        }
         const payload = status.result as { output?: unknown } | undefined;
         return ((payload && 'output' in payload
           ? payload.output

package/dist/repo/sdk/src/release.ts

@@ -0,0 +1,60 @@
+/**
+ * Single source of truth for SDK release metadata.
+ *
+ * Edit THIS file to bump the SDK version, advance the support window, or rev
+ * the SDK/API contract identifier. Everything else derives from these values:
+ *
+ *   - `sdk/src/version.ts` re-exports `SDK_VERSION` and `SDK_API_CONTRACT`.
+ *   - `src/lib/sdk/release-policy.ts` re-exports `SDK_RELEASE_POLICY`.
+ *   - `sdk/package.json` `version` is stamped from `SDK_RELEASE.version` by
+ *     `scripts/sync-sdk-package-version.ts`, which runs as part of
+ *     `bun run sdk:build`.
+ *   - `contracts/sdk-api.manifest.json` is regenerated at build time from
+ *     `src/lib/sdk/api-routes.ts` and the apiContract here; the hash in
+ *     `contracts/sdk-api.manifest.hash` is the invariant that lands in git.
+ *
+ * Human editors should ONLY touch this file when releasing or changing
+ * compatibility policy. Every other location is derived and any drift is a
+ * `check:sdk-release-readiness` failure with a one-shot fix command.
+ */
+
+export type SdkReleaseChannel = 'latest' | 'next' | 'beta';
+
+export type SdkSupportPolicy = {
+  /** Newest published deepline SDK/CLI on npm. */
+  latest: string;
+  /**
+   * Anything strictly below this returns `status: "unsupported"` from
+   * `/api/v2/sdk/compat` and the CLI must hard-fail with the update command.
+   * Only advance after the support window closes.
+   */
+  minimumSupported: string;
+  /**
+   * Anything strictly below this returns `status: "deprecated"` (still works,
+   * warns). Advance when a release becomes the new floor.
+   */
+  deprecatedBelow: string;
+};
+
+export type SdkRelease = {
+  /** Version published to npm; the only place humans should bump it. */
+  version: string;
+  /**
+   * SDK/API contract identifier. Bump on incompatible protocol or schema
+   * changes between the installed SDK/CLI and the Deepline backend.
+   * See `docs/sdk-runtime-compatibility.md`.
+   */
+  apiContract: string;
+  /** Public support policy reported by `/api/v2/sdk/compat`. */
+  supportPolicy: SdkSupportPolicy;
+};
+
+export const SDK_RELEASE = {
+  version: '0.1.53',
+  apiContract: '2026-05-run-response-package',
+  supportPolicy: {
+    latest: '0.1.53',
+    minimumSupported: '0.1.53',
+    deprecatedBelow: '0.1.53',
+  },
+} as const satisfies SdkRelease;

package/dist/repo/sdk/src/types.ts

@@ -264,7 +264,7 @@ export interface ToolMetadata extends ToolDefinition {
  * ```typescript
  * const result = await client.runPlay(code, null, 'my-play');
  * if (result.success) {
- *   console.log('Output:', result.result);
+ *   console.log('Run package:', result.result);
  *   console.log(`Completed in ${result.durationMs}ms`);
  * } else {
  *   console.error('Failed:', result.error);
@@ -277,8 +277,10 @@ export interface PlayRunResult {
   success: boolean;
   /** Public play-run identifier. */
   runId: string;
-  /** The play's return value. Only present on success. */
+  /** Canonical run package for current play runs; legacy clients may receive a raw result. */
   result?: unknown;
+  /** Canonical compact run package when returned by the server. */
+  package?: PlayRunPackage;
   /** All log lines emitted via `ctx.log()` during execution. */
   logs: string[];
   /** Wall-clock duration from submission to completion, in milliseconds. */
@@ -301,6 +303,53 @@ export interface PlayProgressStatus {
   error?: string;
 }
 
+export type PlayRunActionPackage =
+  | {
+      kind: 'deepline_run_inspect';
+      runId: string;
+      api: { method: 'GET'; path: string };
+    }
+  | {
+      kind: 'deepline_db_query';
+      datasetPath: string;
+      tableNamespace?: string;
+      sql: string;
+      maxRows: number;
+      api: {
+        method: 'POST';
+        path: '/api/v2/db/query';
+      };
+    }
+  | {
+      kind: 'deepline_run_export';
+      runId: string;
+      datasetPath: string;
+      format: 'csv';
+    };
+
+export interface PlayRunPackage {
+  schemaVersion: 1;
+  kind: 'play_run';
+  run: {
+    id: string;
+    playName: string;
+    status: string;
+    dashboardUrl?: string;
+    updatedAt?: number | null;
+    startedAt?: number | null;
+    finishedAt?: number | null;
+    durationMs?: number | null;
+    error?: string;
+  };
+  steps: Array<Record<string, unknown>>;
+  outputs: Record<string, Record<string, unknown>>;
+  next?: {
+    inspect?: PlayRunActionPackage;
+    export?: PlayRunActionPackage;
+    query?: PlayRunActionPackage;
+  };
+}
+
 /**
  * Current status of a play execution, returned by {@link DeeplineClient.getPlayStatus}.
  *
@@ -340,8 +389,13 @@ export interface PlayStatus {
   progress?: PlayProgressStatus;
   /** Partial or final result. Available once the play returns. */
   result?: unknown;
+  /** Compact typed run package returned by current run status endpoints. */
+  package?: PlayRunPackage;
+  /** Compact typed output summaries, mirrored from the run package when present. */
+  outputs?: PlayRunPackage['outputs'];
   /** Scheduler-backed run metadata when returned by the status endpoint. */
   run?: {
+    id?: string;
     startTime?: string | null;
     closeTime?: string | null;
     [key: string]: unknown;
@@ -357,6 +411,8 @@ export interface PlayStatus {
     eventKey?: string;
     until?: number;
   } | null;
+  /** Structured follow-up actions for inspect/query/export. */
+  next?: PlayRunPackage['next'] | Record<string, unknown>;
 }
 
 export type LiveEventScope = 'play' | 'agent';
@@ -654,6 +710,8 @@ export interface PlayRunStart {
   dashboardUrl?: string;
   /** Terminal status returned when the start request used a short completion wait. */
   finalStatus?: unknown;
+  /** Canonical compact run package returned by current SDK/API responses. */
+  package?: PlayRunPackage;
 }
 
 /**

package/dist/repo/sdk/src/version.ts

@@ -1,2 +1,6 @@
-export const SDK_VERSION = "0.1.51";
-export const SDK_API_CONTRACT = "2026-05-stripe-promo-checkout";
+// Derived from sdk/src/release.ts. Do not edit by hand.
+// Bump the version in sdk/src/release.ts; this file follows.
+import { SDK_RELEASE } from './release.js';
+
+export const SDK_VERSION: string = SDK_RELEASE.version;
+export const SDK_API_CONTRACT: string = SDK_RELEASE.apiContract;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {
@@ -38,11 +38,12 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "sync-version": "bun ../scripts/sync-sdk-package-version.ts",
+    "build": "bun ../scripts/sync-sdk-package-version.ts && tsup",
+    "dev": "bun ../scripts/sync-sdk-package-version.ts && tsup --watch",
     "typecheck": "tsc --noEmit --declaration false --declarationMap false",
-    "prepack": "tsup",
-    "prepublishOnly": "tsup"
+    "prepack": "bun ../scripts/sync-sdk-package-version.ts && tsup",
+    "prepublishOnly": "bun ../scripts/sync-sdk-package-version.ts && tsup"
   },
   "dependencies": {
     "@types/node": "^20.0.0",