deepline 0.3.88 → 0.3.89

package/dist/index.mjs

@@ -691,7 +691,10 @@ function resolveConfig(options) {
     apiKey,
     baseUrl,
     timeout: options?.timeout ?? DEFAULT_TIMEOUT,
-    maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES
+    maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES,
+    // Pass through untouched: the transport owns case-insensitive merging so
+    // there is exactly one place that decides which header wins.
+    ...options?.headers ? { headers: { ...options.headers } } : {}
   };
 }
 
@@ -744,7 +747,7 @@ var SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: "0.3.88",
+  version: "0.3.89",
   updateSummary: "Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.",
   packageCapabilities: {
     updatePreferences: 1
@@ -1289,11 +1292,33 @@ function normalizeRequestAbortError(error, input) {
   }
   return normalized;
 }
+function applyExplicitHeaders(headers, explicit) {
+  if (!explicit) return headers;
+  for (const [rawName, value] of Object.entries(explicit)) {
+    const name = rawName.trim().toLowerCase();
+    if (!name) continue;
+    for (const existing of Object.keys(headers)) {
+      if (existing.toLowerCase() === name) delete headers[existing];
+    }
+    headers[name] = value;
+  }
+  return headers;
+}
 function isAbortLikeError(error) {
   const name = error.name.toLowerCase();
   const message = error.message.toLowerCase();
   return name === "aborterror" || message.includes("operation was aborted") || message === "aborted";
 }
+function withErrorCause(error, cause) {
+  if (cause !== null && cause !== void 0) {
+    Object.defineProperty(error, "cause", {
+      value: cause,
+      configurable: true,
+      writable: true
+    });
+  }
+  return error;
+}
 function mapNetworkError(baseUrl, error, targetLabel2) {
   const tagged = error;
   const timeoutMs = tagged?.[REQUEST_TIMEOUT_MARKER];
@@ -1410,7 +1435,7 @@ var HttpClient = class {
     if (coordinatorInternalToken?.trim() && (coordinatorUrl?.trim() || workerCallbackUrl?.trim() || runtimeTestFault?.trim() || absurdReleaseOverride?.trim() || preferredReceiptGatewayMachineId?.trim())) {
       headers[COORDINATOR_INTERNAL_TOKEN_HEADER] = coordinatorInternalToken.trim();
     }
-    return headers;
+    return applyExplicitHeaders(headers, this.config.headers);
   }
   /**
    * Send an HTTP request with automatic retries and error handling.
@@ -1564,32 +1589,38 @@ var HttpClient = class {
     );
     if (options?.toolId) {
       const code = mappedNetworkError.code;
-      throw new ToolExecutionError(
-        withCoworkNetworkHint(mappedNetworkError.message),
-        {
-          toolId: options.toolId,
-          provider: providerLabelFromToolId(options.toolId),
-          operation: options.toolId,
-          code,
-          origin: "deepline",
-          category: "network",
-          // A direct client timeout has ambiguous delivery. Fail closed unless
-          // the server returns the authoritative action delivery contract.
-          retryable: false,
-          statusCode: null,
-          requestId: null,
-          retryAfterMs: null,
-          networkKind: code === "NETWORK_TIMEOUT" ? "timeout" : code === "NETWORK_ABORTED" ? "unknown" : "unavailable",
-          networkScope: "client_to_deepline",
-          details: mappedNetworkError.details
-        }
+      throw withErrorCause(
+        new ToolExecutionError(
+          withCoworkNetworkHint(mappedNetworkError.message),
+          {
+            toolId: options.toolId,
+            provider: providerLabelFromToolId(options.toolId),
+            operation: options.toolId,
+            code,
+            origin: "deepline",
+            category: "network",
+            // A direct client timeout has ambiguous delivery. Fail closed unless
+            // the server returns the authoritative action delivery contract.
+            retryable: false,
+            statusCode: null,
+            requestId: null,
+            retryAfterMs: null,
+            networkKind: code === "NETWORK_TIMEOUT" ? "timeout" : code === "NETWORK_ABORTED" ? "unknown" : "unavailable",
+            networkScope: "client_to_deepline",
+            details: mappedNetworkError.details
+          }
+        ),
+        lastError
       );
     }
-    throw new DeeplineError(
-      withCoworkNetworkHint(mappedNetworkError.message),
-      void 0,
-      mappedNetworkError.code,
-      mappedNetworkError.details
+    throw withErrorCause(
+      new DeeplineError(
+        withCoworkNetworkHint(mappedNetworkError.message),
+        void 0,
+        mappedNetworkError.code,
+        mappedNetworkError.details
+      ),
+      lastError
     );
   }
   /**
@@ -1938,6 +1969,13 @@ var PRODUCT_NOTIFICATION_DELIVERY_LEASE_MS = 2 * 6e4;
 var PRODUCT_NOTIFICATION_SUCCESS_TTL_MS = 15 * 6e4;
 var PRODUCT_NOTIFICATION_FAILURE_TTL_MS = 24 * 60 * 6e4;
 
+// ../product-notifications/configuration.ts
+var PRODUCT_NOTIFICATION_EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function normalizeProductNotificationEmail(value) {
+  const email = typeof value === "string" ? value.trim().toLowerCase() : "";
+  return email && email.length <= 320 && PRODUCT_NOTIFICATION_EMAIL_PATTERN.test(email) ? email : null;
+}
+
 // src/stream-reconnect.ts
 var STREAM_RECONNECT_BASE_DELAY_MS = 500;
 var STREAM_RECONNECT_MAX_DELAY_MS = 15e3;
@@ -2466,7 +2504,7 @@ function isRecord4(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function isPlayActivityObservation(value) {
-  if (!isRecord4(value) || value.schemaVersion !== 1 || typeof value.activityId !== "string" || !value.activityId.trim() || typeof value.observedAt !== "number" || !Number.isFinite(value.observedAt) || !isRecord4(value.target) || !isRecord4(value.state)) {
+  if (!isRecord4(value) || value.schemaVersion !== void 0 && value.schemaVersion !== 1 || typeof value.activityId !== "string" || !value.activityId.trim() || typeof value.observedAt !== "number" || !Number.isFinite(value.observedAt) || !isRecord4(value.target) || !isRecord4(value.state)) {
     return false;
   }
   const targetKinds = /* @__PURE__ */ new Set([
@@ -2573,7 +2611,6 @@ function projectPlayRunActivity(input) {
   if (input.waitKind === "detached_runner") {
     return projection(
       {
-        schemaVersion: 1,
         activityId: "runner:managed",
         target: {
           kind: "runner",
@@ -2589,7 +2626,6 @@ function projectPlayRunActivity(input) {
   if (input.waitKind === "sleep") {
     return projection(
       {
-        schemaVersion: 1,
         activityId: "run:sleep",
         target: {
           kind: "step",
@@ -2609,7 +2645,6 @@ function projectPlayRunActivity(input) {
   if (input.waitKind === "integration_event" || input.waitKind === "integration_event_batch") {
     return projection(
       {
-        schemaVersion: 1,
         activityId: `event:${input.activeNodeId ?? "run"}`,
         stepId: input.activeNodeId ?? void 0,
         target: {
@@ -2633,7 +2668,6 @@ function projectPlayRunActivity(input) {
   if (normalizedStatus === "waiting") {
     return projection(
       {
-        schemaVersion: 1,
         activityId: "run:legacy-wait",
         target: {
           kind: "step",
@@ -2660,7 +2694,6 @@ function projectPlayRunActivity(input) {
     const datasetProgress = datasetStep?.progress ?? null;
     return projection(
       {
-        schemaVersion: 1,
         activityId: `dataset:${pendingDataset.datasetId ?? pendingDataset.tableNamespace}`,
         target: {
           kind: "dataset",
@@ -2688,7 +2721,6 @@ function projectPlayRunActivity(input) {
     const provider = toolId?.split(/[._]/)[0]?.trim() || null;
     return projection(
       {
-        schemaVersion: 1,
         activityId: `step:${activeStep.nodeId}`,
         stepId: activeStep.nodeId,
         target: toolId && provider ? {
@@ -2713,7 +2745,6 @@ function projectPlayRunActivity(input) {
   if (normalizedStatus === "queued") {
     return projection(
       {
-        schemaVersion: 1,
         activityId: "capacity:worker",
         target: { kind: "capacity", pool: "worker" },
         state: { kind: "queued", reason: "capacity" },
@@ -2723,7 +2754,6 @@ function projectPlayRunActivity(input) {
     );
   }
   const fallback = {
-    schemaVersion: 1,
     activityId: "run:legacy",
     target: {
       kind: "step",
@@ -3738,7 +3768,7 @@ async function* observeRunEvents(options) {
   }
 }
 
-// ../../shared_libs/integrations/theirstack-execution-policy.ts
+// ../integration-contracts/theirstack/execution-policy.ts
 var THEIRSTACK_SLOW_JOB_SEARCH_PROVIDER_TIMEOUT_MS = 135e3;
 var THEIRSTACK_SLOW_JOB_SEARCH_CLIENT_TIMEOUT_MS = 6e4 + THEIRSTACK_SLOW_JOB_SEARCH_PROVIDER_TIMEOUT_MS + 15e3;
 var THEIRSTACK_COMPANY_SEARCH_CLIENT_TIMEOUT_MS = 21e4;
@@ -3792,7 +3822,7 @@ function resolveTheirstackClientTimeoutMs(endpointId, payload) {
   return usesExtendedTheirstackJobSearchBudget(endpointId, payload) ? THEIRSTACK_SLOW_JOB_SEARCH_CLIENT_TIMEOUT_MS : null;
 }
 
-// ../../shared_libs/integrations/bettercontact-execution-policy.ts
+// ../integration-contracts/bettercontact/execution-policy.ts
 var BETTERCONTACT_LAUNCHER_CLIENT_TIMEOUT_MS = 12e4;
 var BETTERCONTACT_LAUNCHER_TOOL_IDS = /* @__PURE__ */ new Set([
   "bettercontact_enrich",
@@ -3883,6 +3913,42 @@ function providerMetaFromToolResponseRawV2(rawV2, view) {
 }
 
 // src/client.ts
+var MAX_NOTIFICATION_GROUP_CREATE_TARGETS = 50;
+function parseNotificationGroupTarget(value) {
+  const normalized = value.trim();
+  if (normalized.toLowerCase().startsWith("email:")) {
+    const email = normalizeProductNotificationEmail(normalized.slice(6));
+    if (!email) {
+      throw new Error(
+        `Invalid email notification target "${value}". Use --to email:name@example.com.`
+      );
+    }
+    return { kind: "email", email };
+  }
+  const slack = /^slack:(.+)$/i.exec(normalized)?.[1]?.trim();
+  if (!slack) {
+    const provider = normalized.split(":", 1)[0] || normalized;
+    throw new Error(
+      `Unsupported notification destination "${provider}". Use email: or slack:.`
+    );
+  }
+  const member = /^member:([UW][A-Z0-9]{8,})$/i.exec(slack);
+  if (member?.[1]) {
+    return { kind: "slack", memberId: member[1].toUpperCase() };
+  }
+  if (slack.toLowerCase().startsWith("member:")) {
+    throw new Error(
+      "Slack member IDs must look like slack:member:U0123456789."
+    );
+  }
+  if (!slack.replace(/^#/, "").trim()) {
+    throw new Error("Use --to slack:#channel.");
+  }
+  return { kind: "slack", channel: slack };
+}
+function notificationObjectKey(kind) {
+  return `${kind}.${globalThis.crypto.randomUUID()}`;
+}
 var TERMINAL_PLAY_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
 var INCLUDE_TOOL_METADATA_HEADER = "x-deepline-include-tool-metadata";
 var EXECUTE_RESPONSE_CONTRACT_HEADER = "x-deepline-execute-response-contract";
@@ -4452,6 +4518,10 @@ var DeeplineClient = class {
       audit: (options2) => this.auditMonitors(options2),
       repair: (options2) => this.repairMonitors(options2),
       health: (options2) => this.readMonitorsHealth(options2),
+      batch: {
+        submit: (options2) => this.submitMonitorBatch(options2),
+        get: (operationId, options2) => this.getMonitorBatch(operationId, options2)
+      },
       fleets: {
         sync: (definitionOrId, options2) => this.syncMonitorFleet(definitionOrId, options2),
         get: (fleetId, options2) => fleetId === void 0 ? this.listMonitorFleets() : this.getMonitorFleet(fleetId, options2),
@@ -4584,6 +4654,16 @@ var DeeplineClient = class {
       (secret) => secret.name === normalized && secret.status === "active" && secret.hasValue
     ) ?? null;
   }
+  /** Check effective scope and active-version health without reading the value.
+   * Without playName, checks the organization-scoped secret only. With a Play
+   * name, an active Play secret takes precedence; a deleted/disabled Play
+   * secret falls back to the organization-scoped secret.
+   */
+  async inspectSecret(name, options = {}) {
+    const params = new URLSearchParams({ name: name.trim().toUpperCase() });
+    if (options.playName !== void 0) params.set("play", options.playName);
+    return this.http.get(`/api/v2/secrets?${params.toString()}`);
+  }
   // ——————————————————————————————————————————————————————————
   // Tools
   // ——————————————————————————————————————————————————————————
@@ -4675,6 +4755,10 @@ var DeeplineClient = class {
       `/api/v2/integrations/${encodeURIComponent(toolId)}/get`,
       {
         method: "GET",
+        // Tool metadata is a read-only catalog lookup. Keep the metadata
+        // header while opting into the same transient edge-response retries as
+        // other GET catalog methods such as searchTools().
+        retryApiErrors: true,
         headers: {
           "x-deepline-tool-meta-only": "1"
         }
@@ -6130,6 +6214,197 @@ var DeeplineClient = class {
   async getNotifications() {
     return this.http.get("/api/v2/notifications");
   }
+  /** Read the group-based product-notification configuration and rule catalog. */
+  async getNotificationConfiguration() {
+    return this.http.get("/api/v2/notifications/configuration");
+  }
+  /** Atomically apply one retry-safe desired configuration change. */
+  async changeNotificationConfiguration(expectedWorkspaceVersion, change) {
+    return this.http.put("/api/v2/notifications/configuration", {
+      expectedWorkspaceVersion,
+      change
+    });
+  }
+  /** Create one notification group and its destinations as a retry-safe unit. */
+  async createNotificationGroup(input) {
+    const name = input.name.trim().replace(/\s+/g, " ");
+    if (!name) throw new Error("Notification group name is required.");
+    if (input.targets.length < 1 || input.targets.length > MAX_NOTIFICATION_GROUP_CREATE_TARGETS) {
+      throw new Error(
+        `Choose between 1 and ${MAX_NOTIFICATION_GROUP_CREATE_TARGETS} notification targets.`
+      );
+    }
+    const targets = input.targets.map(parseNotificationGroupTarget);
+    const legacyEvents = input.legacyEvents ?? [];
+    const legacyTarget = targets.length === 1 && targets[0]?.kind === "slack" && legacyEvents.length > 0 ? targets[0] : null;
+    if (legacyEvents.length > 0 && !legacyTarget) {
+      throw new Error(
+        "--for is supported only by the legacy one-Slack-target form. Create the group first, then add rules in notification configuration."
+      );
+    }
+    if (!legacyTarget && name.toLowerCase() === "default") {
+      throw new Error(
+        "Default is reserved for the workspace default notification group."
+      );
+    }
+    const normalizedTargets = targets.map(
+      (target) => target.kind === "email" ? `email:${target.email}` : "memberId" in target ? `slack:member:${target.memberId}` : `slack:${target.channel}`
+    );
+    if (input.dryRun) {
+      return {
+        mode: "dry_run",
+        compatibilityMode: legacyTarget !== null,
+        name: legacyTarget ? input.name : name,
+        targets: normalizedTargets,
+        legacyEvents
+      };
+    }
+    if (legacyTarget) {
+      const notification = await this.createNotification({
+        name: input.name,
+        provider: "slack",
+        ..."channel" in legacyTarget ? { channel: legacyTarget.channel } : { memberId: legacyTarget.memberId },
+        eventTypes: legacyEvents
+      });
+      return { mode: "legacy", notification };
+    }
+    const current = await this.getNotificationConfiguration();
+    const existingGroup = current.configuration.groups.find(
+      (candidate) => candidate.name.toLowerCase() === name.toLowerCase()
+    );
+    const groupKey = existingGroup?.groupKey ?? notificationObjectKey("group");
+    const group = existingGroup ?? {
+      groupKey,
+      name,
+      enabled: true,
+      deliveryTiming: { mode: "immediate" },
+      source: "workspace",
+      configMode: "custom",
+      version: 0
+    };
+    const destinations = current.configuration.destinations.filter(
+      (destination) => destination.groupKey === groupKey
+    );
+    const emails = [
+      ...new Set(
+        targets.flatMap(
+          (target) => target.kind === "email" ? [target.email] : []
+        )
+      )
+    ].sort();
+    const existingEmails = new Set(
+      destinations.flatMap(
+        (destination) => destination.settings.kind === "email_addresses" ? destination.settings.to : []
+      )
+    );
+    const newEmails = emails.filter((email) => !existingEmails.has(email));
+    if (newEmails.length > 0) {
+      destinations.push({
+        destinationKey: notificationObjectKey("destination"),
+        groupKey,
+        name: "Email recipients",
+        enabled: true,
+        source: "workspace",
+        configMode: "custom",
+        version: 0,
+        status: "active",
+        settings: { kind: "email_addresses", to: newEmails }
+      });
+    }
+    const slackTargets = /* @__PURE__ */ new Map();
+    for (const target of targets) {
+      if (target.kind !== "slack") continue;
+      const targetKey = "memberId" in target ? `member:${target.memberId}` : `channel:${target.channel.replace(/^#/, "").toLowerCase()}`;
+      slackTargets.set(targetKey, target);
+    }
+    const connectionId = current.slackConnection.connectionId;
+    if (slackTargets.size > 0 && !connectionId) {
+      throw new Error(
+        "Slack is not connected to this workspace. Connect it in Dashboard \u2192 Integrations, then retry."
+      );
+    }
+    const resolvedSlackTargets = await Promise.all(
+      [...slackTargets.values()].map(async (target) => {
+        if ("memberId" in target) {
+          return {
+            targetKind: "member",
+            targetId: target.memberId,
+            targetName: target.memberId
+          };
+        }
+        const channel = target.channel;
+        const requested = channel.replace(/^#/, "");
+        const response = await this.listNotificationChannels(channel);
+        const matches = response.channels.filter(
+          (candidate) => candidate.id === requested || candidate.name.toLowerCase() === requested.toLowerCase()
+        );
+        if (matches.length !== 1) {
+          throw new Error(
+            matches.length === 0 ? `Slack channel ${channel} was not found or is not visible to the Deepline app.` : `Slack channel ${channel} is ambiguous. Use its channel ID.`
+          );
+        }
+        return {
+          targetKind: "channel",
+          targetId: matches[0].id,
+          targetName: matches[0].name
+        };
+      })
+    );
+    const uniqueSlackTargets = new Map(
+      resolvedSlackTargets.map((target) => [
+        `${target.targetKind}:${target.targetId}`,
+        target
+      ])
+    );
+    for (const target of uniqueSlackTargets.values()) {
+      if (destinations.some(
+        (destination) => destination.settings.kind === "slack" && destination.settings.targetKind === target.targetKind && destination.settings.targetId === target.targetId
+      )) {
+        continue;
+      }
+      destinations.push({
+        destinationKey: notificationObjectKey("destination"),
+        groupKey,
+        name: `${target.targetKind === "channel" ? "#" : "@"}${target.targetName}`,
+        enabled: true,
+        source: "workspace",
+        configMode: "custom",
+        version: 0,
+        status: "pending_verification",
+        settings: {
+          kind: "slack",
+          ...target,
+          oauthConnectionId: connectionId
+        }
+      });
+    }
+    const draft = {
+      group,
+      destinations,
+      rules: current.configuration.rules.filter(
+        (rule) => rule.groupKey === groupKey
+      )
+    };
+    const result = await this.changeNotificationConfiguration(
+      current.configuration.workspaceVersion,
+      { kind: "save_group", draft }
+    );
+    const storedGroup = result.configuration.groups.find(
+      (candidate) => candidate.groupKey === groupKey
+    );
+    if (!storedGroup) {
+      throw new Error("Notification group creation returned no saved group.");
+    }
+    return {
+      mode: "native",
+      groupKey,
+      targets: normalizedTargets,
+      group: storedGroup,
+      destinations: result.configuration.destinations.filter(
+        (destination) => destination.groupKey === groupKey
+      )
+    };
+  }
   /** List Slack channels available to an already-connected Slack integration. */
   async listNotificationChannels(query) {
     const suffix = query ? `?search=${encodeURIComponent(query)}` : "";
@@ -6674,6 +6949,78 @@ var DeeplineClient = class {
       { method: "GET" }
     );
   }
+  /** Submit durable monitor work; transport retries use the same idempotency key. */
+  async submitMonitorBatch(options) {
+    const idempotencyKey = options.idempotencyKey.trim();
+    if (!idempotencyKey) {
+      throw new DeeplineError(
+        "Monitor batch idempotencyKey is required.",
+        void 0,
+        "INVALID_MONITOR_BATCH_IDEMPOTENCY_KEY"
+      );
+    }
+    if (options.kind === "deploy") {
+      if (!options.manifestNdjson.trim()) {
+        throw new DeeplineError(
+          "Monitor batch deploy requires a non-empty NDJSON manifest.",
+          void 0,
+          "INVALID_MONITOR_BATCH_MANIFEST"
+        );
+      }
+      return this.http.request(
+        "/api/v2/monitors/batch",
+        {
+          method: "POST",
+          body: {
+            kind: "deploy",
+            manifest_ndjson: options.manifestNdjson,
+            dry_run: options.dryRun === true,
+            idempotency_key: idempotencyKey
+          },
+          headers: { "Idempotency-Key": idempotencyKey },
+          maxRetries: 0,
+          exactUrlOnly: true
+        }
+      );
+    }
+    const scope = options.scope.kind === "keys" ? { kind: "keys", monitor_keys: options.scope.monitorKeys } : options.scope.kind === "fleet" ? { kind: "fleet", fleet_id: options.scope.fleetId } : { kind: "target", target: options.scope.target };
+    return this.http.request(
+      "/api/v2/monitors/batch",
+      {
+        method: "POST",
+        body: {
+          kind: options.kind,
+          scope,
+          dry_run: options.dryRun === true,
+          idempotency_key: idempotencyKey,
+          ...options.deactivationReason === void 0 ? {} : { deactivation_reason: options.deactivationReason }
+        },
+        headers: { "Idempotency-Key": idempotencyKey },
+        // Durable submission is itself idempotent, but an ambiguous local retry
+        // must retain the exact key and never turn a CLI attempt into two runs.
+        maxRetries: 0,
+        exactUrlOnly: true
+      }
+    );
+  }
+  /** Get durable batch progress and a bounded retained evidence page. */
+  async getMonitorBatch(operationId, options) {
+    const runId = operationId.trim();
+    if (!runId) {
+      throw new DeeplineError(
+        "Monitor batch operation id is required.",
+        void 0,
+        "INVALID_MONITOR_BATCH_OPERATION_ID"
+      );
+    }
+    const params = new URLSearchParams();
+    if (options?.cursor) params.set("cursor", options.cursor);
+    const suffix = params.size > 0 ? `?${params}` : "";
+    return this.http.request(
+      `/api/v2/monitors/batch/${encodeURIComponent(runId)}${suffix}`,
+      { method: "GET" }
+    );
+  }
   /**
    * The deployable monitor tools catalog. Pass a tool id (positional or
    * `{ tool }`) to describe one tool's full payload/stream contract, or no tool
@@ -9554,6 +9901,82 @@ var PLAY_AUTHORING_FIELD_REGISTRY = {
     description: "Unsupported legacy child-workflow timeout.",
     errorMessage: "ctx.runPlay timeoutMs is unsupported because child Plays execute inline."
   },
+  "ctx.runPlayAsync.key": {
+    schema: Type.String({ minLength: 1 }),
+    fixtures: {
+      valid: "request-approval",
+      invalid: "",
+      absent: void 0,
+      unresolved: { expression: "callKey" },
+      edition1: "request-approval"
+    },
+    referenceType: "string",
+    required: true,
+    resolution: "runtime-dynamic",
+    issueCode: "play_authoring_run_play_option_invalid",
+    description: "Stable identity for one independent child Play Run.",
+    errorMessage: "ctx.runPlayAsync key must be a non-empty string."
+  },
+  "ctx.runPlayAsync.playRef": {
+    schema: Type.Union([
+      Type.String({ minLength: 1 }),
+      Type.Union([
+        Type.Object(
+          { playName: Type.String({ minLength: 1 }) },
+          { additionalProperties: true }
+        ),
+        Type.Object(
+          { name: Type.String({ minLength: 1 }) },
+          { additionalProperties: true }
+        )
+      ])
+    ]),
+    fixtures: {
+      valid: "request-approval",
+      invalid: {},
+      absent: void 0,
+      unresolved: { expression: "playRef" },
+      edition1: "request-approval"
+    },
+    referenceType: "string | PlayReferenceLike",
+    required: true,
+    resolution: "runtime-dynamic",
+    issueCode: "play_authoring_run_play_option_invalid",
+    description: "Independently published scalar child Play name or strongly typed definition handle.",
+    errorMessage: "ctx.runPlayAsync playRef must be a non-empty Play name or definition handle."
+  },
+  "ctx.runPlayAsync.input": {
+    schema: Type.Record(Type.String(), Type.Unknown()),
+    fixtures: {
+      valid: { draftId: "draft-1" },
+      invalid: "draft-1",
+      absent: void 0,
+      unresolved: "childInput",
+      edition1: {}
+    },
+    referenceType: "Record<string, unknown>",
+    required: true,
+    resolution: "runtime-dynamic",
+    issueCode: "play_authoring_run_play_option_invalid",
+    description: "Scalar input object submitted to the independent child Run.",
+    errorMessage: "ctx.runPlayAsync input must be an object."
+  },
+  "ctx.runPlayAsync.options.description": {
+    schema: Type.String({ minLength: 1 }),
+    fixtures: {
+      valid: "Request approval.",
+      invalid: "",
+      absent: void 0,
+      unresolved: { expression: "description" },
+      edition1: "Request approval."
+    },
+    referenceType: "string",
+    required: true,
+    resolution: "runtime-dynamic",
+    issueCode: "play_authoring_run_play_option_invalid",
+    description: "Non-empty purpose for one independent child Play Run.",
+    errorMessage: "ctx.runPlayAsync options.description must be non-empty."
+  },
   "runtime.timeout": {
     schema: Type.String({ pattern: "^\\d+\\s*[mh]$" }),
     fixtures: {
@@ -9841,6 +10264,10 @@ var PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   `export type CsvOptions = { description?: ${cloudReferenceType("ctx.csv.options.description")}; columns?: ${cloudReferenceType("ctx.csv.options.columns")}; rename?: ${cloudReferenceType("ctx.csv.options.rename")}; required?: ${cloudReferenceType("ctx.csv.options.required")} };`,
   "export type PlayCallExecution = 'inline';",
   `export type PlayCallOptions = { description: ${cloudReferenceType("ctx.runPlay.options.description")}; execution?: ${cloudReferenceType("ctx.runPlay.options.execution")}; timeoutMs?: ${cloudReferenceType("ctx.runPlay.options.timeoutMs")} };`,
+  `export type PlayAsyncCallOptions = { description: ${cloudReferenceType("ctx.runPlayAsync.options.description")} };`,
+  "declare const PLAY_RUN_ID_BRAND: unique symbol;",
+  "export type PlayRunId = string & { readonly [PLAY_RUN_ID_BRAND]: 'PlayRunId' };",
+  "export type AsyncPlayRunRef = Readonly<{ runId: PlayRunId }>;",
   `export type RuntimeStepOptions = { semanticKey?: ${cloudReferenceType("ctx.step.semanticKey")}; staleAfterSeconds?: ${cloudReferenceType("ctx.step.staleAfterSeconds")} };`,
   `export type FetchOptions = { staleAfterSeconds?: ${cloudReferenceType("ctx.fetch.staleAfterSeconds")}; transient?: boolean };`,
   "export type PlayFetchResponse = { ok: boolean; status: number; statusText: string; url: string; headers: Record<string, string>; bodyText: string; json: unknown | null };",
@@ -9866,11 +10293,11 @@ var PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   "  withColumn<Name extends string, Value>(name: Name, definition: DatasetColumnDefinition<OutputRow, Value> & { readonly runIf: (row: OutputRow, index: number) => boolean | Promise<boolean> }): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;",
   "  withColumn<Name extends string, Value>(name: Name, definition: DatasetColumnDefinition<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;",
   "  withColumn<Name extends string, Value>(name: Name, resolver: StepResolver<OutputRow, Value> | RunnableColumnStepProgram<Value>, options: StepOptions<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;",
-  "  withColumns<Program extends StepProgram<OutputRow, object, unknown>>(program: Program): DatasetBuilder<InputRow, StepProgramOutput<Program>>;",
+  "  withColumns<ProgramOutput extends OutputRow, Return>(program: StepProgram<OutputRow, ProgramOutput, Return>): DatasetBuilder<InputRow, ProgramOutput>;",
   "  step<Name extends string, Value>(name: Name, resolver: ColumnResolver<OutputRow, Value>): never;",
   "  run(options?: DatasetRunOptions<InputRow>): Promise<PlayDataset<OutputRow>>;",
   "};",
-  "export type PlayReferenceLike = { readonly playName: string; readonly name?: string } | { readonly name: string; readonly playName?: string };",
+  "export type PlayReferenceLike<TInput extends Record<string, unknown> = Record<string, unknown>> = ({ readonly playName: string; readonly name?: string } | { readonly name: string; readonly playName?: string }) & { readonly __inputType?: TInput };",
   "export interface DeeplinePlayRuntimeContext {",
   "  csv<T = Record<string, unknown>>(path: string | CsvInput<T & object>, options?: CsvOptions): Promise<PlayDataset<T>>;",
   "  dataset<TSource extends PlayDatasetInput<object>>(key: string, items: TSource): DatasetBuilder<PlayDatasetRow<TSource> & object, PlayDatasetRow<TSource> & object>;",
@@ -9884,6 +10311,8 @@ var PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   "  fetch(key: string, url: string | URL, init?: RequestInit & { headers?: HeadersInit & { 'Idempotency-Key'?: string; 'X-Idempotency-Key'?: string }; auth?: SecretAuthInput }, options?: FetchOptions): Promise<PlayFetchResponse>;",
   "  secrets: { get(name: string): SecretPromise; bearer(secret: string | SecretPromise | SecretHandle): SecretAuth; header(header: string, secret: string | SecretPromise | SecretHandle): SecretAuth };",
   `  runPlay<TOutput = unknown>(key: string, playRef: ${cloudReferenceType("ctx.runPlay.playRef")}, input: ${cloudReferenceType("ctx.runPlay.input")}, options: PlayCallOptions): Promise<TOutput>;`,
+  "  runPlayAsync<TInput extends Record<string, unknown>>(key: string, playRef: PlayReferenceLike<TInput>, input: NoInfer<TInput>, options: PlayAsyncCallOptions): Promise<AsyncPlayRunRef>;",
+  "  runPlayAsync(key: string, playRef: string, input: Record<string, unknown>, options: PlayAsyncCallOptions): Promise<AsyncPlayRunRef>;",
   "  log(message: string, options?: { level?: 'debug' | 'info' | 'warn' | 'error' }): void;",
   `  sleep(ms: ${cloudReferenceType("ctx.sleep.ms")}): Promise<void>;`,
   "}",