deepline 0.1.119 → 0.1.121

package/dist/index.d.ts

@@ -1,228 +1,4 @@
-/**
- * The runtime shape of a built play artifact. Different runner backends need
- * different bundle outputs:
- *   - cjs_node20: Daytona + local-process (full Node.js sandbox).
- *   - esm_workers: Cloudflare Workers (V8 isolate, no `fs`/`child_process`).
- *
- * The CLI selects which kind to build based on the target backend; the worker
- * validates the kind matches the backend it's about to dispatch to.
- */
-declare const PLAY_ARTIFACT_KINDS: {
-    readonly cjsNode20: "cjs_node20";
-    readonly esmWorkers: "esm_workers";
-};
-type PlayArtifactKind = (typeof PLAY_ARTIFACT_KINDS)[keyof typeof PLAY_ARTIFACT_KINDS];
-
-/**
- * A top-level key the play's function literally `return`s. Derived from the
- * `return { ... }` object literal — NOT from dataset `.withColumn(...)` names —
- * so the "Returns" graph node mirrors the function's real output shape.
- * `isDataset` is true when the key's value is a `PlayDataset` handle (a table).
- */
-interface PlayStaticReturnField {
-    name: string;
-    isDataset: boolean;
-}
-interface PlayStaticPipeline {
-    tableNamespace?: string;
-    inputFields?: string[];
-    rowKeyFields?: string[];
-    csvArg?: string;
-    hasInlineData?: boolean;
-    csvDescription?: string;
-    datasetDescription?: string;
-    fields: string[];
-    /**
-     * Top-level keys of the play's `return { ... }` object literal, in source
-     * order. Undefined when the terminal return isn't a statically-known object
-     * literal (bare value, dataset handle, conditional returns, etc.).
-     */
-    returnFields?: PlayStaticReturnField[];
-    stages?: PlayStaticSubstep[];
-    substeps: PlayStaticSubstep[];
-    sheetContract?: PlaySheetContract | null;
-    sheetContractErrors?: string[];
-}
-type PlaySheetColumnSource = 'input' | 'datasetColumn' | 'waterfallStep' | 'childPlayColumn';
-interface PlaySheetColumnContract {
-    id: string;
-    sqlName: string;
-    source: PlaySheetColumnSource;
-    field?: string;
-    parentField?: string;
-    playId?: string;
-    waterfallId?: string;
-    outputField?: string;
-    outputSqlName?: string;
-    stepId?: string;
-    toolId?: string;
-    isRowKey?: boolean;
-}
-interface PlaySheetContract {
-    tableNamespace: string;
-    columns: PlaySheetColumnContract[];
-}
-type PlayStaticColumnProducerKind = 'tool' | 'waterfall' | 'stepProgram' | 'playCall' | 'controlFlow' | 'transform';
-interface PlayStaticColumnProducer {
-    id: string;
-    kind: PlayStaticColumnProducerKind;
-    field: string;
-    toolId?: string;
-    playId?: string;
-    dependsOnFields?: string[];
-    recompute?: boolean;
-    recomputeOnError?: boolean;
-    staleAfterSeconds?: number;
-    conditional?: boolean;
-    sourceRange?: PlayStaticSourceRange;
-    steps?: PlayStaticColumnProducer[];
-    substep: PlayStaticSubstep;
-}
-interface PlayStaticDatasetColumn {
-    id: string;
-    source: PlaySheetColumnSource;
-    sqlName?: string;
-    recompute?: boolean;
-    recomputeOnError?: boolean;
-    staleAfterSeconds?: number;
-    producers: PlayStaticColumnProducer[];
-}
-interface PlayStaticSourceRange {
-    sourcePath?: string;
-    startLine: number;
-    endLine: number;
-    startColumn: number;
-    endColumn: number;
-}
-type PlayStaticSubstepMetadata = {
-    conditional?: boolean;
-    dependsOnFields?: string[];
-    recompute?: boolean;
-    recomputeOnError?: boolean;
-    staleAfterSeconds?: number;
-};
-type PlayStaticSubstep = PlayStaticSubstepMetadata & ({
-    type: 'csv';
-    field: string;
-    path?: string;
-    description?: string;
-    sourceRange?: PlayStaticSourceRange;
-    callDepth?: number;
-    callPath?: string[];
-} | {
-    type: 'dataset';
-    field: string;
-    name?: string;
-    tableNamespace?: string;
-    inputFields?: string[];
-    rowKeyFields?: string[];
-    outputFields?: string[];
-    columns?: PlayStaticDatasetColumn[];
-    waterfallIds?: string[];
-    steps?: PlayStaticSubstep[];
-    sheetContract?: PlaySheetContract | null;
-    description?: string;
-    sourceRange?: PlayStaticSourceRange;
-    callDepth?: number;
-    callPath?: string[];
-} | {
-    type: 'tool';
-    toolId: string;
-    field: string;
-    paramsSource?: string;
-    sourceText?: string;
-    description?: string;
-    inLoop?: boolean;
-    isEventWait?: boolean;
-    sourceRange?: PlayStaticSourceRange;
-    callDepth?: number;
-    callPath?: string[];
-} | {
-    type: 'waterfall';
-    tool?: string;
-    field: string;
-    inLoop?: boolean;
-    id?: string;
-    output?: string;
-    minResults?: number;
-    sourceText?: string;
-    steps?: Array<{
-        id: string;
-        kind?: 'tool' | 'code';
-        toolId?: string;
-        paramsSource?: string;
-    }>;
-    description?: string;
-    sourceRange?: PlayStaticSourceRange;
-    callDepth?: number;
-    callPath?: string[];
-} | {
-    type: 'step_suite';
-    field: string;
-    steps: PlayStaticSubstep[];
-    returnSource?: string;
-    description?: string;
-    sourceRange?: PlayStaticSourceRange;
-    callDepth?: number;
-    callPath?: string[];
-} | {
-    type: 'play_call';
-    playId: string;
-    field: string;
-    inLoop?: boolean;
-    pipeline?: PlayStaticPipeline | null;
-    cycleDetected?: boolean;
-    resolutionError?: string;
-    description?: string;
-    sourceRange?: PlayStaticSourceRange;
-    callDepth?: number;
-    callPath?: string[];
-} | {
-    type: 'control_flow';
-    kind: 'conditional' | 'loop';
-    field: string;
-    steps: PlayStaticSubstep[];
-    description?: string;
-    sourceRange?: PlayStaticSourceRange;
-    callDepth?: number;
-    callPath?: string[];
-} | {
-    type: 'run_javascript';
-    alias: string;
-    sourceText?: string;
-    description?: string;
-    sourceRange?: PlayStaticSourceRange;
-    callDepth?: number;
-    callPath?: string[];
-} | {
-    type: 'code';
-    field: string;
-    sourceText?: string;
-    description?: string;
-    sourceRange?: PlayStaticSourceRange;
-    callDepth?: number;
-    callPath?: string[];
-});
-
-type PlayCompilerDependencyManifest = {
-    playName: string;
-    /** Original source path for direct imported definePlay dependencies. */
-    filePath?: string;
-    sourceHash: string;
-    graphHash: string;
-    artifactHash: string;
-    staticPipeline: PlayStaticPipeline;
-};
-type PlayCompilerManifest = {
-    compilerVersion: number;
-    playName: string;
-    sourceHash: string;
-    graphHash: string;
-    artifactHash: string;
-    artifactKind?: PlayArtifactKind;
-    staticPipeline: PlayStaticPipeline;
-    importedPlayDependencies: PlayCompilerDependencyManifest[];
-};
+import { a as PlayCompilerManifest } from './compiler-manifest-BjoRENv9.js';
 
 declare const DEEPLINE_TOOL_CATEGORIES: readonly ["company_search", "people_search", "people_enrich", "email_finder", "email_verify", "phone_finder", "phone_verify", "identity_resolution", "reverse_lookup", "enrichment", "batch", "premium", "free"];
 type DeeplineToolCategory = (typeof DEEPLINE_TOOL_CATEGORIES)[number] | (string & {});
@@ -2047,17 +1823,18 @@ declare class DeeplineClient {
      */
     listRuns(options: RunsListOptions): Promise<PlayRunListItem[]>;
     /**
-     * Observe one run's live events through the Convex Run Snapshot
-     * subscription transport (ADR-0008). Yields the same `play.*` event
-     * envelopes as {@link streamPlayRunEvents} and ends after the terminal
-     * snapshot. Throws {@link RunObserveTransportUnavailableError} when this
-     * server cannot serve the transport (older server, unconfigured grants, or
-     * unreachable Convex) — callers fall back to the SSE stream with a notice.
+     * Observe one run's live events. Uses the Convex Run Snapshot subscription
+     * transport first (ADR-0008), then falls back to the canonical SSE stream
+     * when the subscription transport or its optional client modules are not
+     * available. Pass `fallback: 'none'` to receive
+     * {@link RunObserveTransportUnavailableError} instead.
      */
     observeRunEvents(runId: string, options?: {
         signal?: AbortSignal;
         onNotice?: (message: string) => void;
+        fallback?: 'sse' | 'none';
     }): AsyncGenerator<PlayLiveEvent>;
+    private streamPlayRunEventsUntilTerminal;
     /**
      * Tail one run through the subscription transport until terminal, then
      * return one durable REST status read (the final Run Response Package).

package/dist/index.js

@@ -274,10 +274,10 @@ var SDK_RELEASE = {
   // skill on the sdk sync surface, and the people-search-to-email prebuilt.
   // 0.1.108 ships explicit dataset column/tool recompute policy and removes
   // the SDK enrich generator's one-second stale policy.
-  version: "0.1.119",
+  version: "0.1.121",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.119",
+    latest: "0.1.121",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -2771,20 +2771,105 @@ var DeeplineClient = class {
     return response.runs ?? [];
   }
   /**
-   * Observe one run's live events through the Convex Run Snapshot
-   * subscription transport (ADR-0008). Yields the same `play.*` event
-   * envelopes as {@link streamPlayRunEvents} and ends after the terminal
-   * snapshot. Throws {@link RunObserveTransportUnavailableError} when this
-   * server cannot serve the transport (older server, unconfigured grants, or
-   * unreachable Convex) — callers fall back to the SSE stream with a notice.
+   * Observe one run's live events. Uses the Convex Run Snapshot subscription
+   * transport first (ADR-0008), then falls back to the canonical SSE stream
+   * when the subscription transport or its optional client modules are not
+   * available. Pass `fallback: 'none'` to receive
+   * {@link RunObserveTransportUnavailableError} instead.
    */
-  observeRunEvents(runId, options) {
-    return observeRunEvents({
-      http: this.http,
+  async *observeRunEvents(runId, options) {
+    let yieldedObserveEvent = false;
+    try {
+      for await (const event of observeRunEvents({
+        http: this.http,
+        runId,
+        signal: options?.signal,
+        onNotice: options?.onNotice
+      })) {
+        yieldedObserveEvent = true;
+        yield event;
+      }
+    } catch (error) {
+      if (!(error instanceof RunObserveTransportUnavailableError) || yieldedObserveEvent || options?.fallback === "none") {
+        throw error;
+      }
+      options?.onNotice?.(
+        `[observe] live subscription unavailable (${error.reason}); falling back to SSE tail (support window, ADR-0008)`
+      );
+      yield* this.streamPlayRunEventsUntilTerminal(runId, options);
+    }
+  }
+  async *streamPlayRunEventsUntilTerminal(runId, options) {
+    const state = {
       runId,
-      signal: options?.signal,
-      onNotice: options?.onNotice
-    });
+      status: "running",
+      logs: [],
+      lastLogSeq: 0,
+      latest: null
+    };
+    let lastEventId;
+    let reconnectAttempt = 0;
+    for (; ; ) {
+      if (options?.signal?.aborted) {
+        return;
+      }
+      const connectedAt = Date.now();
+      let sawEvent = false;
+      let endedReason = "stream window ended before a terminal event";
+      try {
+        for await (const event of this.streamPlayRunEvents(runId, {
+          mode: "cli",
+          signal: options?.signal,
+          ...lastEventId ? { lastEventId } : {}
+        })) {
+          sawEvent = true;
+          if (event.cursor?.trim()) {
+            lastEventId = event.cursor;
+          }
+          yield event;
+          const status = updatePlayLiveStatusState(state, event);
+          if (status && TERMINAL_PLAY_STATUSES.has(status.status)) {
+            return;
+          }
+        }
+      } catch (error) {
+        if (options?.signal?.aborted) {
+          return;
+        }
+        if (!isTransientPlayStreamError(error)) {
+          throw error;
+        }
+        endedReason = error instanceof Error ? error.message : String(error);
+      }
+      let refreshed = null;
+      try {
+        refreshed = await this.getRunStatus(runId);
+      } catch (error) {
+        if (!isTransientPlayStreamError(error)) {
+          throw error;
+        }
+      }
+      if (refreshed && TERMINAL_PLAY_STATUSES.has(refreshed.status)) {
+        yield {
+          cursor: String(Date.now()),
+          streamId: `sse-fallback:${runId}`,
+          scope: "play",
+          type: "play.run.status",
+          at: (/* @__PURE__ */ new Date()).toISOString(),
+          payload: refreshed
+        };
+        return;
+      }
+      if (sawEvent || Date.now() - connectedAt >= STREAM_HEALTHY_CONNECTION_MS) {
+        reconnectAttempt = 0;
+      }
+      const delayMs = streamReconnectDelayMs(reconnectAttempt);
+      reconnectAttempt += 1;
+      options?.onNotice?.(
+        `[observe] SSE tail window ended before terminal status (${endedReason}); reconnecting to run ${runId}`
+      );
+      await sleep2(delayMs);
+    }
   }
   /**
    * Tail one run through the subscription transport until terminal, then
@@ -2800,7 +2885,8 @@ var DeeplineClient = class {
     };
     for await (const event of this.observeRunEvents(runId, {
       signal: options?.signal,
-      onNotice: options?.onNotice
+      onNotice: options?.onNotice,
+      fallback: "none"
     })) {
       const status = updatePlayLiveStatusState(state, event);
       if (!status || !TERMINAL_PLAY_STATUSES.has(status.status)) {

package/dist/index.mjs

@@ -196,10 +196,10 @@ var SDK_RELEASE = {
   // skill on the sdk sync surface, and the people-search-to-email prebuilt.
   // 0.1.108 ships explicit dataset column/tool recompute policy and removes
   // the SDK enrich generator's one-second stale policy.
-  version: "0.1.119",
+  version: "0.1.121",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.119",
+    latest: "0.1.121",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -2693,20 +2693,105 @@ var DeeplineClient = class {
     return response.runs ?? [];
   }
   /**
-   * Observe one run's live events through the Convex Run Snapshot
-   * subscription transport (ADR-0008). Yields the same `play.*` event
-   * envelopes as {@link streamPlayRunEvents} and ends after the terminal
-   * snapshot. Throws {@link RunObserveTransportUnavailableError} when this
-   * server cannot serve the transport (older server, unconfigured grants, or
-   * unreachable Convex) — callers fall back to the SSE stream with a notice.
+   * Observe one run's live events. Uses the Convex Run Snapshot subscription
+   * transport first (ADR-0008), then falls back to the canonical SSE stream
+   * when the subscription transport or its optional client modules are not
+   * available. Pass `fallback: 'none'` to receive
+   * {@link RunObserveTransportUnavailableError} instead.
    */
-  observeRunEvents(runId, options) {
-    return observeRunEvents({
-      http: this.http,
+  async *observeRunEvents(runId, options) {
+    let yieldedObserveEvent = false;
+    try {
+      for await (const event of observeRunEvents({
+        http: this.http,
+        runId,
+        signal: options?.signal,
+        onNotice: options?.onNotice
+      })) {
+        yieldedObserveEvent = true;
+        yield event;
+      }
+    } catch (error) {
+      if (!(error instanceof RunObserveTransportUnavailableError) || yieldedObserveEvent || options?.fallback === "none") {
+        throw error;
+      }
+      options?.onNotice?.(
+        `[observe] live subscription unavailable (${error.reason}); falling back to SSE tail (support window, ADR-0008)`
+      );
+      yield* this.streamPlayRunEventsUntilTerminal(runId, options);
+    }
+  }
+  async *streamPlayRunEventsUntilTerminal(runId, options) {
+    const state = {
       runId,
-      signal: options?.signal,
-      onNotice: options?.onNotice
-    });
+      status: "running",
+      logs: [],
+      lastLogSeq: 0,
+      latest: null
+    };
+    let lastEventId;
+    let reconnectAttempt = 0;
+    for (; ; ) {
+      if (options?.signal?.aborted) {
+        return;
+      }
+      const connectedAt = Date.now();
+      let sawEvent = false;
+      let endedReason = "stream window ended before a terminal event";
+      try {
+        for await (const event of this.streamPlayRunEvents(runId, {
+          mode: "cli",
+          signal: options?.signal,
+          ...lastEventId ? { lastEventId } : {}
+        })) {
+          sawEvent = true;
+          if (event.cursor?.trim()) {
+            lastEventId = event.cursor;
+          }
+          yield event;
+          const status = updatePlayLiveStatusState(state, event);
+          if (status && TERMINAL_PLAY_STATUSES.has(status.status)) {
+            return;
+          }
+        }
+      } catch (error) {
+        if (options?.signal?.aborted) {
+          return;
+        }
+        if (!isTransientPlayStreamError(error)) {
+          throw error;
+        }
+        endedReason = error instanceof Error ? error.message : String(error);
+      }
+      let refreshed = null;
+      try {
+        refreshed = await this.getRunStatus(runId);
+      } catch (error) {
+        if (!isTransientPlayStreamError(error)) {
+          throw error;
+        }
+      }
+      if (refreshed && TERMINAL_PLAY_STATUSES.has(refreshed.status)) {
+        yield {
+          cursor: String(Date.now()),
+          streamId: `sse-fallback:${runId}`,
+          scope: "play",
+          type: "play.run.status",
+          at: (/* @__PURE__ */ new Date()).toISOString(),
+          payload: refreshed
+        };
+        return;
+      }
+      if (sawEvent || Date.now() - connectedAt >= STREAM_HEALTHY_CONNECTION_MS) {
+        reconnectAttempt = 0;
+      }
+      const delayMs = streamReconnectDelayMs(reconnectAttempt);
+      reconnectAttempt += 1;
+      options?.onNotice?.(
+        `[observe] SSE tail window ended before terminal status (${endedReason}); reconnecting to run ${runId}`
+      );
+      await sleep2(delayMs);
+    }
   }
   /**
    * Tail one run through the subscription transport until terminal, then
@@ -2722,7 +2807,8 @@ var DeeplineClient = class {
     };
     for await (const event of this.observeRunEvents(runId, {
       signal: options?.signal,
-      onNotice: options?.onNotice
+      onNotice: options?.onNotice,
+      fallback: "none"
     })) {
       const status = updatePlayLiveStatusState(state, event);
       if (!status || !TERMINAL_PLAY_STATUSES.has(status.status)) {

package/dist/plays/bundle-play-file.d.mts

@@ -0,0 +1,120 @@
+import { P as PlayArtifactKind$1, a as PlayCompilerManifest } from '../compiler-manifest-BjoRENv9.mjs';
+export { b as PLAY_ARTIFACT_KINDS } from '../compiler-manifest-BjoRENv9.mjs';
+
+type PlayPackageImport = {
+    name: string;
+    version: string | null;
+};
+type PlayImportPolicy = {
+    localFiles: string[];
+    nodeBuiltins: string[];
+    packages: PlayPackageImport[];
+};
+type PlayRuntimeFeature = 'artifact_storage' | 'checkpoint_resume' | 'durable_sleep' | 'packaged_files';
+type PlayArtifactCompatibility = {
+    apiVersion: number;
+    artifactVersion: number;
+    minRunnerVersion: number;
+    runtimeFeatures: PlayRuntimeFeature[];
+    runtimeBackend?: string | null;
+};
+/**
+ * Identifies which runtime can consume this artifact:
+ *   - cjs_node20: Daytona / local-process (Node.js)
+ *   - esm_workers: Cloudflare Workers (V8 isolate)
+ */
+type PlayArtifactKind = 'cjs_node20' | 'esm_workers';
+type PlayBundleArtifact = {
+    codeFormat: 'cjs_module' | 'esm_module';
+    /** Defaults to cjs_node20 when not present (legacy artifacts). */
+    artifactKind?: PlayArtifactKind;
+    entryFile: string;
+    virtualFilename: string;
+    sourceHash: string;
+    graphHash: string;
+    artifactHash: string;
+    sourceMapHash: string;
+    bundledCode: string;
+    sourceMap: string;
+    importPolicy: PlayImportPolicy;
+    compatibility: PlayArtifactCompatibility;
+    generatedAt: number;
+    cacheHit: boolean;
+};
+
+type ImportedPlayDependency = {
+    filePath: string;
+    playName: string;
+};
+type PlayLocalFileReference = {
+    sourceFragment: string;
+    logicalPath: string;
+    absolutePath: string;
+    bytes: number;
+    contentHash: string;
+    contentType: string;
+};
+type PlayLocalFileDiscoveryError = {
+    sourceFragment: string;
+    message: string;
+};
+type PlayLocalFileDiscoveryResult = {
+    files: PlayLocalFileReference[];
+    unresolved: PlayLocalFileDiscoveryError[];
+};
+type PlayBundlingAdapter = {
+    projectRoot: string;
+    nodeModulesDir: string;
+    cacheDir?: string;
+    sdkSourceRoot: string;
+    sdkPackageJson: string;
+    sdkEntryFile: string;
+    sdkTypesEntryFile?: string;
+    sdkWorkersEntryFile: string;
+    workersHarnessEntryFile: string;
+    workersHarnessFilesDir: string;
+    workersRuntimeFingerprintDirs?: string[];
+    discoverPackagedLocalFiles(filePath: string): Promise<PlayLocalFileDiscoveryResult>;
+    typecheckPlaySource?(input: {
+        sourceCode: string;
+        sourcePath: string;
+        importedFilePaths: string[];
+    }): Promise<string[]> | string[];
+    warnAboutNonDevelopmentBundling?(filePath: string): void;
+};
+type BundledPlayFileSuccess = {
+    success: true;
+    artifact: PlayBundleArtifact;
+    sourceCode: string;
+    sourceFiles: Record<string, string>;
+    filePath: string;
+    playName: string | null;
+    compilerManifest?: PlayCompilerManifest;
+    packagedFiles: PlayLocalFileReference[];
+    unresolvedFileReferences: PlayLocalFileDiscoveryError[];
+    importedPlayDependencies: ImportedPlayDependency[];
+};
+type BundledPlayFileFailure = {
+    success: false;
+    errors: string[];
+    filePath: string;
+};
+type BundledPlayFileResult = BundledPlayFileSuccess | BundledPlayFileFailure;
+declare function extractDefinedPlayName(sourceCode: string): string | null;
+type BundlePlayFileOptions = {
+    /**
+     * Which artifact to produce. Defaults to `cjs_node20` (Daytona / local-process
+     * runner). Pass `esm_workers` to produce a Cloudflare Worker bundle that
+     * combines the play with the Workers harness.
+     *
+     * The CLI selects this from the execution profile or an explicit flag. Each
+     * kind is cached independently on disk.
+     */
+    target?: PlayArtifactKind$1;
+    exportName?: string;
+};
+
+declare function createSdkPlayBundlingAdapter(): PlayBundlingAdapter;
+declare function bundlePlayFile(filePath: string, options?: BundlePlayFileOptions): Promise<BundledPlayFileResult>;
+
+export { type BundlePlayFileOptions, type BundledPlayFileResult, type BundledPlayFileSuccess, type ImportedPlayDependency, type PlayArtifactCompatibility, type PlayBundleArtifact, type PlayImportPolicy, type PlayLocalFileDiscoveryError, type PlayLocalFileReference, type PlayPackageImport, type PlayRuntimeFeature, bundlePlayFile, createSdkPlayBundlingAdapter, extractDefinedPlayName };