deepline 0.1.85 → 0.1.89

package/dist/index.js

@@ -246,10 +246,10 @@ var import_node_path2 = require("path");
 
 // src/release.ts
 var SDK_RELEASE = {
-  version: "0.1.85",
+  version: "0.1.89",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.85",
+    latest: "0.1.89",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -263,6 +263,7 @@ var SDK_API_CONTRACT = SDK_RELEASE.apiContract;
 var COORDINATOR_INTERNAL_TOKEN_HEADER = "x-deepline-internal-token";
 var COORDINATOR_URL_OVERRIDE_HEADER = "x-deepline-coordinator-url";
 var WORKER_CALLBACK_URL_OVERRIDE_HEADER = "x-deepline-worker-callback-url";
+var SYNTHETIC_RUN_HEADER = "x-deepline-synthetic-run";
 
 // src/http.ts
 var MAX_DIAGNOSTIC_HEADER_LENGTH = 120;
@@ -330,6 +331,10 @@ var HttpClient = class {
     if (workerCallbackUrl?.trim()) {
       headers[WORKER_CALLBACK_URL_OVERRIDE_HEADER] = workerCallbackUrl.trim();
     }
+    const syntheticRun = typeof process !== "undefined" ? process.env?.DEEPLINE_SYNTHETIC_RUN : void 0;
+    if (syntheticRun && syntheticRun.trim() && syntheticRun.trim() !== "0") {
+      headers[SYNTHETIC_RUN_HEADER] = "1";
+    }
     return headers;
   }
   /**
@@ -620,6 +625,21 @@ function isTransientCompileManifestError(error) {
 function isRecord(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
+function isPrebuiltPlayDescription(play) {
+  return play.origin === "prebuilt" || play.ownerType === "deepline";
+}
+function preferPrebuiltPlayDescriptions(plays) {
+  const prebuilt = [];
+  const owned = [];
+  for (const play of plays) {
+    if (isPrebuiltPlayDescription(play)) {
+      prebuilt.push(play);
+    } else {
+      owned.push(play);
+    }
+  }
+  return [...prebuilt, ...owned];
+}
 function isPlayRunPackage(value) {
   return Boolean(
     value && typeof value === "object" && !Array.isArray(value) && value.kind === "play_run" && value.run && typeof value.run?.id === "string"
@@ -743,8 +763,14 @@ function playRunStatusFromState(state) {
 var DeeplineClient = class {
   http;
   config;
+  /** Canonical run lifecycle namespace backed by `/api/v2/runs`. */
   runs;
   /**
+   * Create a low-level SDK client.
+   *
+   * Most callers can omit options and let the SDK resolve auth/config from
+   * environment variables and CLI-managed credentials.
+   *
    * @param options - Optional overrides for API key, base URL, timeout, and retries.
    * @throws {@link ConfigError} if no API key can be resolved from any source.
    */
@@ -846,12 +872,19 @@ var DeeplineClient = class {
   // ——————————————————————————————————————————————————————————
   // Secrets
   // ——————————————————————————————————————————————————————————
+  /** List secret metadata visible to the current workspace. */
   async listSecrets() {
     const response = await this.http.get(
       "/api/v2/secrets"
     );
     return Array.isArray(response.secrets) ? response.secrets : [];
   }
+  /**
+   * Check whether a named secret exists, is active, and has a stored value.
+   *
+   * @param name - Secret name. It is normalized to uppercase before lookup.
+   * @returns Matching active secret metadata, or `null`.
+   */
   async checkSecret(name) {
     const normalized = name.trim().toUpperCase();
     const secrets = await this.listSecrets();
@@ -964,9 +997,21 @@ var DeeplineClient = class {
       headers
     );
   }
+  /**
+   * Back-compatible alias for {@link executeTool}.
+   *
+   * Retained for callers that still use the older raw naming while the response
+   * envelope remains the same.
+   */
   async executeToolRaw(toolId, input, options) {
     return this.executeTool(toolId, input, options);
   }
+  /**
+   * Run a bounded SQL query against the customer data plane.
+   *
+   * Use this from trusted backend or agent contexts only. The API enforces
+   * workspace scoping and row limits.
+   */
   async queryCustomerDb(input) {
     return this.http.post("/api/v2/db/query", {
       sql: input.sql,
@@ -1038,6 +1083,17 @@ var DeeplineClient = class {
     );
     return normalizePlayRunStart(response);
   }
+  /**
+   * Start a play run and stream live runtime events from the same request.
+   *
+   * Use this when a caller wants low-level event handling instead of submitting
+   * first and then connecting to `streamPlayRunEvents(runId)`.
+   *
+   * @param request - Play run configuration.
+   * @param options - Optional streaming options.
+   * @param options.signal - Optional abort signal for the streaming request.
+   * @returns Async stream of play-scoped live events.
+   */
   async *startPlayRunStream(request, options) {
     const body = {
       ...request.name ? { name: request.name } : {},
@@ -1090,6 +1146,12 @@ var DeeplineClient = class {
       compilerManifest
     });
   }
+  /**
+   * Register multiple bundled play artifacts in one request.
+   *
+   * Used by packaging and prebuilt publication flows. Each artifact is compiled
+   * first when a compiler manifest is not already supplied.
+   */
   async registerPlayArtifacts(artifacts) {
     const compiledArtifacts = await Promise.all(
       artifacts.map(async (artifact) => ({
@@ -1106,6 +1168,13 @@ var DeeplineClient = class {
       artifacts: compiledArtifacts
     });
   }
+  /**
+   * Compile a bundled play artifact into the server-side compiler manifest.
+   *
+   * The manifest records imports, trigger bindings, static pipeline shape, and
+   * runtime metadata needed before a play artifact can be checked, registered,
+   * or run.
+   */
   async compilePlayManifest(input) {
     const retryDelays = COMPILE_MANIFEST_RETRY_DELAYS_MS.slice(
       0,
@@ -1134,9 +1203,21 @@ var DeeplineClient = class {
   async checkPlayArtifact(input) {
     return this.http.post("/api/v2/plays/check", input);
   }
+  /**
+   * Compile legacy enrich command arguments into a runtime plan.
+   *
+   * This is primarily used by CLI compatibility paths that translate older
+   * enrichment commands onto the play runtime.
+   */
   async compileEnrichPlan(input) {
     return this.http.post("/api/v2/enrich/compile", input);
   }
+  /**
+   * Register an already-bundled play artifact and start a run from it.
+   *
+   * This is the low-level file-backed run path used by SDK/CLI packaging
+   * wrappers after local bundling has produced the runtime artifact.
+   */
   async startPlayRunFromBundle(input) {
     const compilerManifest = input.compilerManifest ?? await this.compilePlayManifest({
       name: input.name,
@@ -1294,6 +1375,12 @@ var DeeplineClient = class {
     const response = await this.http.postFormData("/api/v2/plays/files/stage", buildFormData);
     return response.files;
   }
+  /**
+   * Resolve staged play files by content hash without uploading bytes.
+   *
+   * Missing files are returned so callers can upload only the files the server
+   * does not already have.
+   */
   async resolveStagedPlayFiles(files) {
     return this.http.post("/api/v2/plays/files/stage", { files });
   }
@@ -1510,6 +1597,12 @@ var DeeplineClient = class {
       entries
     };
   }
+  /**
+   * Export persisted runtime-sheet rows for a play dataset/table namespace.
+   *
+   * This is the SDK form of exporting `ctx.dataset(...).run()` output for a
+   * specific play and optional run id.
+   */
   async getPlaySheetRows(input) {
     const params = new URLSearchParams({
       tableNamespace: input.tableNamespace,
@@ -1538,6 +1631,12 @@ var DeeplineClient = class {
       options?.reason ? { reason: options.reason } : {}
     );
   }
+  /**
+   * List callable plays visible to the workspace.
+   *
+   * Pass `origin: "prebuilt"` for Deepline-managed prebuilts or
+   * `origin: "owned"` for org-owned plays.
+   */
   async listPlays(options) {
     const params = new URLSearchParams();
     if (options?.origin) params.set("origin", options.origin);
@@ -1552,15 +1651,32 @@ var DeeplineClient = class {
     );
     return response.plays ?? [];
   }
+  /**
+   * Search callable plays and return compact play descriptions.
+   *
+   * Prebuilt plays are preferred by default because they have maintained
+   * contracts and stable run behavior.
+   */
   async searchPlays(options) {
     const params = new URLSearchParams();
     params.set("search", options.query.trim());
+    const scope = options.scope ?? "prebuilt";
+    if (scope !== "all") {
+      params.set("origin", scope);
+    }
     const response = await this.http.get(
       `/api/v2/plays?${params.toString()}`
     );
-    return (response.plays ?? []).map(
+    const plays = (response.plays ?? []).map(
       (play) => this.summarizePlayListItem(play, options)
     );
+    if (scope === "prebuilt") {
+      return plays.filter(isPrebuiltPlayDescription);
+    }
+    if (scope === "owned") {
+      return plays.filter((play) => !isPrebuiltPlayDescription(play));
+    }
+    return preferPrebuiltPlayDescriptions(plays);
   }
   /**
    * Get the full definition and state of a named play.
@@ -1583,6 +1699,12 @@ var DeeplineClient = class {
     const encodedName = encodeURIComponent(name);
     return this.http.get(`/api/v2/plays/${encodedName}`);
   }
+  /**
+   * Get a normalized play description suitable for agents and CLIs.
+   *
+   * The description includes runnable examples, input/output summaries, clone
+   * guidance, revision state, and latest run metadata when available.
+   */
   async describePlay(name, options) {
     const detail = await this.getPlay(name);
     return this.summarizePlayDetail(detail, options);
@@ -2736,7 +2858,10 @@ var DeeplineStepProgram = class _DeeplineStepProgram {
         ...this.steps,
         {
           name,
-          resolver: stepResolver
+          resolver: stepResolver,
+          ...options?.staleAfterSeconds !== void 0 ? {
+            staleAfterSeconds: options.staleAfterSeconds
+          } : {}
         }
       ],
       this.returnResolver
@@ -2836,6 +2961,14 @@ function createNamedPlayHandle(clientFactory, name) {
 }
 var DeeplineContext = class {
   client;
+  /**
+   * Create a high-level SDK context.
+   *
+   * Most callers should use {@link Deepline.connect}; direct construction is
+   * equivalent when you already have explicit client options.
+   *
+   * @param options - Optional SDK client configuration.
+   */
   constructor(options) {
     this.client = new DeeplineClient(options);
   }
@@ -2865,12 +2998,25 @@ var DeeplineContext = class {
       }
     };
   }
+  /**
+   * Play discovery and named-play handles.
+   *
+   * Use `plays.list()` for discovery and `plays.get(name)` when you prefer a
+   * namespace spelling over `ctx.play(name)`.
+   */
   get plays() {
     return {
       list: () => this.client.listPlays(),
       get: (name) => this.play(name)
     };
   }
+  /**
+   * Convenience references for Deepline-managed prebuilt plays.
+   *
+   * Known prebuilts are exposed by camel-cased aliases. Any other property is
+   * converted into `prebuilt/<property>` so callers can pass the reference to
+   * `ctx.runPlay(...)`.
+   */
   get prebuilt() {
     const explicit = {
       companyToContact: {
@@ -2925,6 +3071,17 @@ var DeeplineContext = class {
   play(name) {
     return createNamedPlayHandle(() => this.client, name);
   }
+  /**
+   * Run a named or prebuilt play and wait for its output.
+   *
+   * This is the high-level SDK equivalent of `ctx.play(name).runSync(input)`.
+   * Inside a play runtime, prefer the in-play `ctx.runPlay(key, playRef, input,
+   * options)` form so the child run is checkpointed under a stable key.
+   *
+   * @param playOrRef - Play name or prebuilt/reference object.
+   * @param input - JSON input passed to the play.
+   * @returns Completed play output.
+   */
   async runPlay(playOrRef, input) {
     const name = typeof playOrRef === "string" ? playOrRef : playOrRef.playName ?? playOrRef.name ?? "";
     return await this.play(name).runSync(input);

package/dist/index.mjs

@@ -179,10 +179,10 @@ import { join as join2 } from "path";
 
 // src/release.ts
 var SDK_RELEASE = {
-  version: "0.1.85",
+  version: "0.1.89",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.85",
+    latest: "0.1.89",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -196,6 +196,7 @@ var SDK_API_CONTRACT = SDK_RELEASE.apiContract;
 var COORDINATOR_INTERNAL_TOKEN_HEADER = "x-deepline-internal-token";
 var COORDINATOR_URL_OVERRIDE_HEADER = "x-deepline-coordinator-url";
 var WORKER_CALLBACK_URL_OVERRIDE_HEADER = "x-deepline-worker-callback-url";
+var SYNTHETIC_RUN_HEADER = "x-deepline-synthetic-run";
 
 // src/http.ts
 var MAX_DIAGNOSTIC_HEADER_LENGTH = 120;
@@ -263,6 +264,10 @@ var HttpClient = class {
     if (workerCallbackUrl?.trim()) {
       headers[WORKER_CALLBACK_URL_OVERRIDE_HEADER] = workerCallbackUrl.trim();
     }
+    const syntheticRun = typeof process !== "undefined" ? process.env?.DEEPLINE_SYNTHETIC_RUN : void 0;
+    if (syntheticRun && syntheticRun.trim() && syntheticRun.trim() !== "0") {
+      headers[SYNTHETIC_RUN_HEADER] = "1";
+    }
     return headers;
   }
   /**
@@ -553,6 +558,21 @@ function isTransientCompileManifestError(error) {
 function isRecord(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
+function isPrebuiltPlayDescription(play) {
+  return play.origin === "prebuilt" || play.ownerType === "deepline";
+}
+function preferPrebuiltPlayDescriptions(plays) {
+  const prebuilt = [];
+  const owned = [];
+  for (const play of plays) {
+    if (isPrebuiltPlayDescription(play)) {
+      prebuilt.push(play);
+    } else {
+      owned.push(play);
+    }
+  }
+  return [...prebuilt, ...owned];
+}
 function isPlayRunPackage(value) {
   return Boolean(
     value && typeof value === "object" && !Array.isArray(value) && value.kind === "play_run" && value.run && typeof value.run?.id === "string"
@@ -676,8 +696,14 @@ function playRunStatusFromState(state) {
 var DeeplineClient = class {
   http;
   config;
+  /** Canonical run lifecycle namespace backed by `/api/v2/runs`. */
   runs;
   /**
+   * Create a low-level SDK client.
+   *
+   * Most callers can omit options and let the SDK resolve auth/config from
+   * environment variables and CLI-managed credentials.
+   *
    * @param options - Optional overrides for API key, base URL, timeout, and retries.
    * @throws {@link ConfigError} if no API key can be resolved from any source.
    */
@@ -779,12 +805,19 @@ var DeeplineClient = class {
   // ——————————————————————————————————————————————————————————
   // Secrets
   // ——————————————————————————————————————————————————————————
+  /** List secret metadata visible to the current workspace. */
   async listSecrets() {
     const response = await this.http.get(
       "/api/v2/secrets"
     );
     return Array.isArray(response.secrets) ? response.secrets : [];
   }
+  /**
+   * Check whether a named secret exists, is active, and has a stored value.
+   *
+   * @param name - Secret name. It is normalized to uppercase before lookup.
+   * @returns Matching active secret metadata, or `null`.
+   */
   async checkSecret(name) {
     const normalized = name.trim().toUpperCase();
     const secrets = await this.listSecrets();
@@ -897,9 +930,21 @@ var DeeplineClient = class {
       headers
     );
   }
+  /**
+   * Back-compatible alias for {@link executeTool}.
+   *
+   * Retained for callers that still use the older raw naming while the response
+   * envelope remains the same.
+   */
   async executeToolRaw(toolId, input, options) {
     return this.executeTool(toolId, input, options);
   }
+  /**
+   * Run a bounded SQL query against the customer data plane.
+   *
+   * Use this from trusted backend or agent contexts only. The API enforces
+   * workspace scoping and row limits.
+   */
   async queryCustomerDb(input) {
     return this.http.post("/api/v2/db/query", {
       sql: input.sql,
@@ -971,6 +1016,17 @@ var DeeplineClient = class {
     );
     return normalizePlayRunStart(response);
   }
+  /**
+   * Start a play run and stream live runtime events from the same request.
+   *
+   * Use this when a caller wants low-level event handling instead of submitting
+   * first and then connecting to `streamPlayRunEvents(runId)`.
+   *
+   * @param request - Play run configuration.
+   * @param options - Optional streaming options.
+   * @param options.signal - Optional abort signal for the streaming request.
+   * @returns Async stream of play-scoped live events.
+   */
   async *startPlayRunStream(request, options) {
     const body = {
       ...request.name ? { name: request.name } : {},
@@ -1023,6 +1079,12 @@ var DeeplineClient = class {
       compilerManifest
     });
   }
+  /**
+   * Register multiple bundled play artifacts in one request.
+   *
+   * Used by packaging and prebuilt publication flows. Each artifact is compiled
+   * first when a compiler manifest is not already supplied.
+   */
   async registerPlayArtifacts(artifacts) {
     const compiledArtifacts = await Promise.all(
       artifacts.map(async (artifact) => ({
@@ -1039,6 +1101,13 @@ var DeeplineClient = class {
       artifacts: compiledArtifacts
     });
   }
+  /**
+   * Compile a bundled play artifact into the server-side compiler manifest.
+   *
+   * The manifest records imports, trigger bindings, static pipeline shape, and
+   * runtime metadata needed before a play artifact can be checked, registered,
+   * or run.
+   */
   async compilePlayManifest(input) {
     const retryDelays = COMPILE_MANIFEST_RETRY_DELAYS_MS.slice(
       0,
@@ -1067,9 +1136,21 @@ var DeeplineClient = class {
   async checkPlayArtifact(input) {
     return this.http.post("/api/v2/plays/check", input);
   }
+  /**
+   * Compile legacy enrich command arguments into a runtime plan.
+   *
+   * This is primarily used by CLI compatibility paths that translate older
+   * enrichment commands onto the play runtime.
+   */
   async compileEnrichPlan(input) {
     return this.http.post("/api/v2/enrich/compile", input);
   }
+  /**
+   * Register an already-bundled play artifact and start a run from it.
+   *
+   * This is the low-level file-backed run path used by SDK/CLI packaging
+   * wrappers after local bundling has produced the runtime artifact.
+   */
   async startPlayRunFromBundle(input) {
     const compilerManifest = input.compilerManifest ?? await this.compilePlayManifest({
       name: input.name,
@@ -1227,6 +1308,12 @@ var DeeplineClient = class {
     const response = await this.http.postFormData("/api/v2/plays/files/stage", buildFormData);
     return response.files;
   }
+  /**
+   * Resolve staged play files by content hash without uploading bytes.
+   *
+   * Missing files are returned so callers can upload only the files the server
+   * does not already have.
+   */
   async resolveStagedPlayFiles(files) {
     return this.http.post("/api/v2/plays/files/stage", { files });
   }
@@ -1443,6 +1530,12 @@ var DeeplineClient = class {
       entries
     };
   }
+  /**
+   * Export persisted runtime-sheet rows for a play dataset/table namespace.
+   *
+   * This is the SDK form of exporting `ctx.dataset(...).run()` output for a
+   * specific play and optional run id.
+   */
   async getPlaySheetRows(input) {
     const params = new URLSearchParams({
       tableNamespace: input.tableNamespace,
@@ -1471,6 +1564,12 @@ var DeeplineClient = class {
       options?.reason ? { reason: options.reason } : {}
     );
   }
+  /**
+   * List callable plays visible to the workspace.
+   *
+   * Pass `origin: "prebuilt"` for Deepline-managed prebuilts or
+   * `origin: "owned"` for org-owned plays.
+   */
   async listPlays(options) {
     const params = new URLSearchParams();
     if (options?.origin) params.set("origin", options.origin);
@@ -1485,15 +1584,32 @@ var DeeplineClient = class {
     );
     return response.plays ?? [];
   }
+  /**
+   * Search callable plays and return compact play descriptions.
+   *
+   * Prebuilt plays are preferred by default because they have maintained
+   * contracts and stable run behavior.
+   */
   async searchPlays(options) {
     const params = new URLSearchParams();
     params.set("search", options.query.trim());
+    const scope = options.scope ?? "prebuilt";
+    if (scope !== "all") {
+      params.set("origin", scope);
+    }
     const response = await this.http.get(
       `/api/v2/plays?${params.toString()}`
     );
-    return (response.plays ?? []).map(
+    const plays = (response.plays ?? []).map(
       (play) => this.summarizePlayListItem(play, options)
     );
+    if (scope === "prebuilt") {
+      return plays.filter(isPrebuiltPlayDescription);
+    }
+    if (scope === "owned") {
+      return plays.filter((play) => !isPrebuiltPlayDescription(play));
+    }
+    return preferPrebuiltPlayDescriptions(plays);
   }
   /**
    * Get the full definition and state of a named play.
@@ -1516,6 +1632,12 @@ var DeeplineClient = class {
     const encodedName = encodeURIComponent(name);
     return this.http.get(`/api/v2/plays/${encodedName}`);
   }
+  /**
+   * Get a normalized play description suitable for agents and CLIs.
+   *
+   * The description includes runnable examples, input/output summaries, clone
+   * guidance, revision state, and latest run metadata when available.
+   */
   async describePlay(name, options) {
     const detail = await this.getPlay(name);
     return this.summarizePlayDetail(detail, options);
@@ -2669,7 +2791,10 @@ var DeeplineStepProgram = class _DeeplineStepProgram {
         ...this.steps,
         {
           name,
-          resolver: stepResolver
+          resolver: stepResolver,
+          ...options?.staleAfterSeconds !== void 0 ? {
+            staleAfterSeconds: options.staleAfterSeconds
+          } : {}
         }
       ],
       this.returnResolver
@@ -2769,6 +2894,14 @@ function createNamedPlayHandle(clientFactory, name) {
 }
 var DeeplineContext = class {
   client;
+  /**
+   * Create a high-level SDK context.
+   *
+   * Most callers should use {@link Deepline.connect}; direct construction is
+   * equivalent when you already have explicit client options.
+   *
+   * @param options - Optional SDK client configuration.
+   */
   constructor(options) {
     this.client = new DeeplineClient(options);
   }
@@ -2798,12 +2931,25 @@ var DeeplineContext = class {
       }
     };
   }
+  /**
+   * Play discovery and named-play handles.
+   *
+   * Use `plays.list()` for discovery and `plays.get(name)` when you prefer a
+   * namespace spelling over `ctx.play(name)`.
+   */
   get plays() {
     return {
       list: () => this.client.listPlays(),
       get: (name) => this.play(name)
     };
   }
+  /**
+   * Convenience references for Deepline-managed prebuilt plays.
+   *
+   * Known prebuilts are exposed by camel-cased aliases. Any other property is
+   * converted into `prebuilt/<property>` so callers can pass the reference to
+   * `ctx.runPlay(...)`.
+   */
   get prebuilt() {
     const explicit = {
       companyToContact: {
@@ -2858,6 +3004,17 @@ var DeeplineContext = class {
   play(name) {
     return createNamedPlayHandle(() => this.client, name);
   }
+  /**
+   * Run a named or prebuilt play and wait for its output.
+   *
+   * This is the high-level SDK equivalent of `ctx.play(name).runSync(input)`.
+   * Inside a play runtime, prefer the in-play `ctx.runPlay(key, playRef, input,
+   * options)` form so the child run is checkpointed under a stable key.
+   *
+   * @param playOrRef - Play name or prebuilt/reference object.
+   * @param input - JSON input passed to the play.
+   * @returns Completed play output.
+   */
   async runPlay(playOrRef, input) {
     const name = typeof playOrRef === "string" ? playOrRef : playOrRef.playName ?? playOrRef.name ?? "";
     return await this.play(name).runSync(input);

package/dist/repo/apps/play-runner-workers/src/dedup-do.ts

@@ -1302,6 +1302,7 @@ export class PlayDedup implements DurableObject {
             ? body.activeArtifactTableNamespace
             : null,
         updatedAt: typeof body.updatedAt === 'number' ? body.updatedAt : null,
+        liveNodeProgress: body.liveNodeProgress,
       };
     } else if (
       body.type === 'terminal' &&