@adcp/sdk 16.5.0 → 16.6.0

package/dist/lib/media-buy/action-assessment.js

@@ -30,6 +30,7 @@ var import_action_contracts = require('./action-contracts.js');
 var import_action_constraints = require('./action-constraints.js');
 var import_mutations = require('./mutations.js');
 var import_available_actions = require('./available-actions.js');
+var import_version = require('../version.js');
 function assessProductAction(product, action) {
   if (product?.allowed_actions === void 0)
     return { status: "unknown", binding: false, message: "Product action information is absent." };
@@ -54,6 +55,13 @@ function assessActionAvailability(buy, action, options = {}) {
       "Invalid mutation field shape; validate against the selected wire schema.",
       "unknown"
     );
+  const startupControl = action === "update_creative_start_policy";
+  if (startupControl && options.request?.packages?.some(
+    (pkg) => pkg.start_requires_all_creatives_approved !== void 0 && typeof pkg.start_requires_all_creatives_approved !== "boolean"
+  ))
+    return deny("condition_unresolved", "The package start policy must be a boolean.", "unknown");
+  if (startupControl && !(0, import_action_contracts.supportsCreativeStartPolicyAction)(options.adcpVersion ?? import_version.ADCP_VERSION))
+    return deny("condition_unresolved", "Creative start policy controls require AdCP 3.3 or newer.", "unknown");
   if (!buy) return deny("condition_unresolved", "Current MediaBuy state is missing.", "unknown");
   if (options.request?.packages?.length) {
     const requested = options.request.packages.map((p) => p.package_id);
@@ -83,7 +91,7 @@ function assessActionAvailability(buy, action, options = {}) {
       "At least one requested field has no supported action mapping; executable-now assessment requires a fully mapped request.",
       "unknown"
     );
-  const metadataOnly = action === "update_name";
+  const metadataOnly = (0, import_action_contracts.isOperationalMediaBuyAction)(action);
   const proposal = buy.accepted_proposal;
   const terms = proposal?.commercial_terms?.change_terms;
   if (terms === void 0 && !metadataOnly)
@@ -105,7 +113,7 @@ function assessActionAvailability(buy, action, options = {}) {
   if (!metadataOnly && promise.status === "unknown") return deny("condition_unresolved", promise.message, "unknown");
   if (!metadataOnly && promise.status === "not_negotiated")
     return deny("not_supported_on_buy", "This action was not negotiated in the accepted proposal.");
-  const term = promise.status === "promised" ? promise.term : void 0;
+  const term = !metadataOnly && promise.status === "promised" ? promise.term : void 0;
   const packageLifecycle = ["pause", "resume"].includes(action) && options.request?.packages?.filter((p) => p.paused !== void 0 && (p.paused ? "pause" : "resume") === action);
   const scopedLifecycle = packageLifecycle && packageLifecycle.length > 0 && options.request?.paused === void 0;
   const packageControlStatuses = scopedLifecycle ? [...(0, import_action_contracts.actionAllowedStatuses)({ action: "pause" }), ...(0, import_action_contracts.actionAllowedStatuses)({ action: "resume" })] : [];
@@ -144,6 +152,24 @@ function assessActionAvailability(buy, action, options = {}) {
   if ((0, import_action_contracts.liveActionIssues)(entries).length)
     return deny("condition_unresolved", "The live action projection is invalid or ambiguous.", "unknown");
   const entry = entries.find((e) => e.action === action);
+  if (startupControl && entry) {
+    const ids = entry.applicable_package_ids;
+    if (!ids?.length || !buy.packages || new Set(buy.packages.map((pkg) => pkg.package_id)).size !== buy.packages.length || ids.some((id) => !buy.packages.some((pkg) => pkg.package_id === id)))
+      return deny(
+        "condition_unresolved",
+        "An exact current seller package scope is required for startup controls.",
+        "unknown"
+      );
+    for (const id of ids) {
+      const status = (0, import_action_contracts.packageActionStatus)(buy.packages.find((pkg) => pkg.package_id === id));
+      if (status === void 0)
+        return deny("condition_unresolved", "Current package lifecycle state is missing.", "unknown");
+      if (!import_action_contracts.NON_TERMINAL_ACTION_STATUSES.includes(status))
+        return deny("wrong_status", "The startup control is not available for a terminal package.");
+    }
+    if (entry.task !== "control_media_buy")
+      return deny("mode_mismatch", "Startup policy changes require the declared control_media_buy task.");
+  }
   if (options.adcpVersion && entry && !(0, import_action_contracts.liveActionFitsVersion)(entry, options.adcpVersion))
     return deny(
       "condition_unresolved",
@@ -163,7 +189,7 @@ function assessActionAvailability(buy, action, options = {}) {
   if (options.termsRefIsAlias && entry.change_term_id !== void 0 && entry.terms_ref !== void 0 && entry.terms_ref !== entry.change_term_id)
     return deny("condition_unresolved", "The deliberately emitted term aliases disagree.", "unknown");
   if (metadataOnly && entry.change_term_id !== void 0)
-    return deny("condition_unresolved", "Metadata-only actions cannot identify a commercial change term.", "unknown");
+    return deny("condition_unresolved", "Operational actions cannot identify a commercial change term.", "unknown");
   if (entry.mode === import_available_actions.LEGACY_REQUIRES_PROPOSAL_MODE)
     return deny(
       "mode_mismatch",

package/dist/lib/media-buy/action-assessment.mjs

@@ -10,11 +10,14 @@ import {
   liveActionFitsVersion,
   supportsChangeTermIdentity,
   withActionProposal,
-  packageActionStatus
+  packageActionStatus,
+  isOperationalMediaBuyAction,
+  supportsCreativeStartPolicyAction
 } from "./action-contracts.mjs";
 import { evaluateChangeTermConstraints } from "./action-constraints.mjs";
 import { decomposeUpdateMediaBuy, hasUnmappedMutation, mutationShapeIssue } from "./mutations.mjs";
 import { LEGACY_REQUIRES_PROPOSAL_MODE } from "./available-actions.mjs";
+import { ADCP_VERSION } from "../version.mjs";
 function assessProductAction(product, action) {
   if (product?.allowed_actions === void 0)
     return { status: "unknown", binding: false, message: "Product action information is absent." };
@@ -39,6 +42,13 @@ function assessActionAvailability(buy, action, options = {}) {
       "Invalid mutation field shape; validate against the selected wire schema.",
       "unknown"
     );
+  const startupControl = action === "update_creative_start_policy";
+  if (startupControl && options.request?.packages?.some(
+    (pkg) => pkg.start_requires_all_creatives_approved !== void 0 && typeof pkg.start_requires_all_creatives_approved !== "boolean"
+  ))
+    return deny("condition_unresolved", "The package start policy must be a boolean.", "unknown");
+  if (startupControl && !supportsCreativeStartPolicyAction(options.adcpVersion ?? ADCP_VERSION))
+    return deny("condition_unresolved", "Creative start policy controls require AdCP 3.3 or newer.", "unknown");
   if (!buy) return deny("condition_unresolved", "Current MediaBuy state is missing.", "unknown");
   if (options.request?.packages?.length) {
     const requested = options.request.packages.map((p) => p.package_id);
@@ -68,7 +78,7 @@ function assessActionAvailability(buy, action, options = {}) {
       "At least one requested field has no supported action mapping; executable-now assessment requires a fully mapped request.",
       "unknown"
     );
-  const metadataOnly = action === "update_name";
+  const metadataOnly = isOperationalMediaBuyAction(action);
   const proposal = buy.accepted_proposal;
   const terms = proposal?.commercial_terms?.change_terms;
   if (terms === void 0 && !metadataOnly)
@@ -90,7 +100,7 @@ function assessActionAvailability(buy, action, options = {}) {
   if (!metadataOnly && promise.status === "unknown") return deny("condition_unresolved", promise.message, "unknown");
   if (!metadataOnly && promise.status === "not_negotiated")
     return deny("not_supported_on_buy", "This action was not negotiated in the accepted proposal.");
-  const term = promise.status === "promised" ? promise.term : void 0;
+  const term = !metadataOnly && promise.status === "promised" ? promise.term : void 0;
   const packageLifecycle = ["pause", "resume"].includes(action) && options.request?.packages?.filter((p) => p.paused !== void 0 && (p.paused ? "pause" : "resume") === action);
   const scopedLifecycle = packageLifecycle && packageLifecycle.length > 0 && options.request?.paused === void 0;
   const packageControlStatuses = scopedLifecycle ? [...actionAllowedStatuses({ action: "pause" }), ...actionAllowedStatuses({ action: "resume" })] : [];
@@ -129,6 +139,24 @@ function assessActionAvailability(buy, action, options = {}) {
   if (liveActionIssues(entries).length)
     return deny("condition_unresolved", "The live action projection is invalid or ambiguous.", "unknown");
   const entry = entries.find((e) => e.action === action);
+  if (startupControl && entry) {
+    const ids = entry.applicable_package_ids;
+    if (!ids?.length || !buy.packages || new Set(buy.packages.map((pkg) => pkg.package_id)).size !== buy.packages.length || ids.some((id) => !buy.packages.some((pkg) => pkg.package_id === id)))
+      return deny(
+        "condition_unresolved",
+        "An exact current seller package scope is required for startup controls.",
+        "unknown"
+      );
+    for (const id of ids) {
+      const status = packageActionStatus(buy.packages.find((pkg) => pkg.package_id === id));
+      if (status === void 0)
+        return deny("condition_unresolved", "Current package lifecycle state is missing.", "unknown");
+      if (!NON_TERMINAL_ACTION_STATUSES.includes(status))
+        return deny("wrong_status", "The startup control is not available for a terminal package.");
+    }
+    if (entry.task !== "control_media_buy")
+      return deny("mode_mismatch", "Startup policy changes require the declared control_media_buy task.");
+  }
   if (options.adcpVersion && entry && !liveActionFitsVersion(entry, options.adcpVersion))
     return deny(
       "condition_unresolved",
@@ -148,7 +176,7 @@ function assessActionAvailability(buy, action, options = {}) {
   if (options.termsRefIsAlias && entry.change_term_id !== void 0 && entry.terms_ref !== void 0 && entry.terms_ref !== entry.change_term_id)
     return deny("condition_unresolved", "The deliberately emitted term aliases disagree.", "unknown");
   if (metadataOnly && entry.change_term_id !== void 0)
-    return deny("condition_unresolved", "Metadata-only actions cannot identify a commercial change term.", "unknown");
+    return deny("condition_unresolved", "Operational actions cannot identify a commercial change term.", "unknown");
   if (entry.mode === LEGACY_REQUIRES_PROPOSAL_MODE)
     return deny(
       "mode_mismatch",

package/dist/lib/media-buy/action-contracts.d.mts

@@ -1,6 +1,9 @@
 import type { ActionBuy, LiveMediaBuyAction, ActionProposal, MediaBuyAction, MediaBuyTask, ProposalChangeTerm, ProductActionTemplate, MediaBuyStatus } from './action-types.mjs';
 import type { SLAWindow } from './types.mjs';
 export declare const NON_TERMINAL_ACTION_STATUSES: readonly ["pending_creatives", "pending_start", "active", "paused"];
+/** These controls derive authority from the live seller projection, not commercial terms. */
+export declare function isOperationalMediaBuyAction(action: string): boolean;
+export declare function supportsCreativeStartPolicyAction(version: string): boolean;
 /** Canonical task alternatives. The live entry chooses among these; mode never selects a task. */
 export declare function mediaBuyActionTasks(action: string): readonly MediaBuyTask[];
 /** The canonical default, only usable with a known current right and validated live entry. */

package/dist/lib/media-buy/action-contracts.d.ts

@@ -1,6 +1,9 @@
 import type { ActionBuy, LiveMediaBuyAction, ActionProposal, MediaBuyAction, MediaBuyTask, ProposalChangeTerm, ProductActionTemplate, MediaBuyStatus } from './action-types';
 import type { SLAWindow } from './types';
 export declare const NON_TERMINAL_ACTION_STATUSES: readonly ["pending_creatives", "pending_start", "active", "paused"];
+/** These controls derive authority from the live seller projection, not commercial terms. */
+export declare function isOperationalMediaBuyAction(action: string): boolean;
+export declare function supportsCreativeStartPolicyAction(version: string): boolean;
 /** Canonical task alternatives. The live entry chooses among these; mode never selects a task. */
 export declare function mediaBuyActionTasks(action: string): readonly MediaBuyTask[];
 /** The canonical default, only usable with a known current right and validated live entry. */

package/dist/lib/media-buy/action-contracts.js

@@ -26,6 +26,7 @@ __export(action_contracts_exports, {
   defaultMediaBuyActionTask: () => defaultMediaBuyActionTask,
   elapsedDuration: () => elapsedDuration,
   findProductAction: () => findProductAction,
+  isOperationalMediaBuyAction: () => isOperationalMediaBuyAction,
   legacyActionSupported: () => legacyActionSupported,
   liveActionFitsVersion: () => liveActionFitsVersion,
   liveActionIssues: () => liveActionIssues,
@@ -35,6 +36,7 @@ __export(action_contracts_exports, {
   slaValid: () => slaValid,
   slaWithin: () => slaWithin,
   supportsChangeTermIdentity: () => supportsChangeTermIdentity,
+  supportsCreativeStartPolicyAction: () => supportsCreativeStartPolicyAction,
   supportsRc3Actions: () => supportsRc3Actions,
   withActionProposal: () => withActionProposal
 });
@@ -44,6 +46,24 @@ var import_legacy_action_ids = require('./legacy-action-ids.js');
 var import_media_buy_helpers = require('../server/media-buy-helpers.js');
 var import_available_actions = require('./available-actions.js');
 const NON_TERMINAL_ACTION_STATUSES = ["pending_creatives", "pending_start", "active", "paused"];
+function isOperationalMediaBuyAction(action) {
+  return action === "update_name" || action === "update_creative_start_policy";
+}
+function supportsCreativeStartPolicyAction(version) {
+  if (typeof version !== "string" || version.length > 256) return false;
+  const match = /^v?(\d+)\.(\d+)(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/.exec(version.trim());
+  if (!match) return false;
+  const core = [match[1], match[2], match[3] ?? "0"];
+  if (core.some((value) => !/^(?:0|[1-9]\d*)$/.test(value) || !Number.isSafeInteger(Number(value)))) return false;
+  const prerelease = match[4]?.split(".");
+  if (prerelease?.some((id) => !id || /^\d+$/.test(id) && id.length > 1 && id.startsWith("0"))) return false;
+  if (match[5]?.split(".").some((id) => !id)) return false;
+  const [major, minor, patch] = core.map(Number);
+  if (major !== 3) return major > 3;
+  if (minor !== 3) return minor > 3;
+  if (patch > 0 || !prerelease) return true;
+  return !/^\d+$/.test(prerelease[0]) && prerelease[0] >= "beta";
+}
 const MODES = ["self_serve", "conditional_self_serve", "seller_managed", "requires_approval"];
 const CANONICAL_TASKS = new Set(Object.values(import_action_metadata.CANONICAL_ACTION_TASKS).flat());
 const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
@@ -259,6 +279,7 @@ function supportsRc3Actions(version) {
   return !match[4] || /^rc\.(\d+)$/.test(match[4]) && Number(match[4].slice(3)) >= 3;
 }
 function liveActionFitsVersion(entry, version) {
+  if (entry.action === "update_creative_start_policy" && !supportsCreativeStartPolicyAction(version)) return false;
   if (/^3\.[01](?:\.|-|$)/.test(version) && (!legacyActionSupported(entry.action) || entry.task !== void 0))
     return false;
   if (!supportsChangeTermIdentity(version) && (entry.change_term_id !== void 0 || entry.mode === "seller_managed"))
@@ -267,7 +288,7 @@ function liveActionFitsVersion(entry, version) {
 }
 function actionFitsErrorDetails(action, version) {
   if (/^3\.[01](?:\.|-|$)/.test(version)) return legacyActionSupported(action);
-  return import_action_metadata.LEGACY_AVAILABLE_ACTIONS.includes(action) || action === "update_media_buy_frequency_cap" && supportsRc3Actions(version);
+  return import_action_metadata.LEGACY_AVAILABLE_ACTIONS.includes(action) || action === "update_media_buy_frequency_cap" && supportsRc3Actions(version) || action === "update_creative_start_policy" && supportsCreativeStartPolicyAction(version);
 }
 function withActionProposal(buy, options) {
   return buy.accepted_proposal === void 0 && options.proposal !== void 0 ? { ...buy, accepted_proposal: options.proposal } : buy;
@@ -290,6 +311,7 @@ function packageActionStatus(pkg) {
   defaultMediaBuyActionTask,
   elapsedDuration,
   findProductAction,
+  isOperationalMediaBuyAction,
   legacyActionSupported,
   liveActionFitsVersion,
   liveActionIssues,
@@ -299,6 +321,7 @@ function packageActionStatus(pkg) {
   slaValid,
   slaWithin,
   supportsChangeTermIdentity,
+  supportsCreativeStartPolicyAction,
   supportsRc3Actions,
   withActionProposal
 });

package/dist/lib/media-buy/action-contracts.mjs

@@ -8,6 +8,24 @@ import { V3_1_ACTION_IDS } from "./legacy-action-ids.mjs";
 import { validActionsForStatus } from "../server/media-buy-helpers.mjs";
 import { getRollupParent } from "./available-actions.mjs";
 const NON_TERMINAL_ACTION_STATUSES = ["pending_creatives", "pending_start", "active", "paused"];
+function isOperationalMediaBuyAction(action) {
+  return action === "update_name" || action === "update_creative_start_policy";
+}
+function supportsCreativeStartPolicyAction(version) {
+  if (typeof version !== "string" || version.length > 256) return false;
+  const match = /^v?(\d+)\.(\d+)(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/.exec(version.trim());
+  if (!match) return false;
+  const core = [match[1], match[2], match[3] ?? "0"];
+  if (core.some((value) => !/^(?:0|[1-9]\d*)$/.test(value) || !Number.isSafeInteger(Number(value)))) return false;
+  const prerelease = match[4]?.split(".");
+  if (prerelease?.some((id) => !id || /^\d+$/.test(id) && id.length > 1 && id.startsWith("0"))) return false;
+  if (match[5]?.split(".").some((id) => !id)) return false;
+  const [major, minor, patch] = core.map(Number);
+  if (major !== 3) return major > 3;
+  if (minor !== 3) return minor > 3;
+  if (patch > 0 || !prerelease) return true;
+  return !/^\d+$/.test(prerelease[0]) && prerelease[0] >= "beta";
+}
 const MODES = ["self_serve", "conditional_self_serve", "seller_managed", "requires_approval"];
 const CANONICAL_TASKS = new Set(Object.values(CANONICAL_ACTION_TASKS).flat());
 const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
@@ -223,6 +241,7 @@ function supportsRc3Actions(version) {
   return !match[4] || /^rc\.(\d+)$/.test(match[4]) && Number(match[4].slice(3)) >= 3;
 }
 function liveActionFitsVersion(entry, version) {
+  if (entry.action === "update_creative_start_policy" && !supportsCreativeStartPolicyAction(version)) return false;
   if (/^3\.[01](?:\.|-|$)/.test(version) && (!legacyActionSupported(entry.action) || entry.task !== void 0))
     return false;
   if (!supportsChangeTermIdentity(version) && (entry.change_term_id !== void 0 || entry.mode === "seller_managed"))
@@ -231,7 +250,7 @@ function liveActionFitsVersion(entry, version) {
 }
 function actionFitsErrorDetails(action, version) {
   if (/^3\.[01](?:\.|-|$)/.test(version)) return legacyActionSupported(action);
-  return LEGACY_AVAILABLE_ACTIONS.includes(action) || action === "update_media_buy_frequency_cap" && supportsRc3Actions(version);
+  return LEGACY_AVAILABLE_ACTIONS.includes(action) || action === "update_media_buy_frequency_cap" && supportsRc3Actions(version) || action === "update_creative_start_policy" && supportsCreativeStartPolicyAction(version);
 }
 function withActionProposal(buy, options) {
   return buy.accepted_proposal === void 0 && options.proposal !== void 0 ? { ...buy, accepted_proposal: options.proposal } : buy;
@@ -253,6 +272,7 @@ export {
   defaultMediaBuyActionTask,
   elapsedDuration,
   findProductAction,
+  isOperationalMediaBuyAction,
   legacyActionSupported,
   liveActionFitsVersion,
   liveActionIssues,
@@ -262,6 +282,7 @@ export {
   slaValid,
   slaWithin,
   supportsChangeTermIdentity,
+  supportsCreativeStartPolicyAction,
   supportsRc3Actions,
   withActionProposal
 };

package/dist/lib/media-buy/compatibility.js

@@ -6132,7 +6132,12 @@ class MediaBuyLifecycleCoordinator {
         });
         void new Promise((resolve) => setTimeout(resolve, 0)).then(async () => {
           while (!watchSignal.aborted) {
-            const task = await this.agent.getTaskStatus(sellerTaskId, settlementTransport, watchSignal, wireOptions);
+            const task = await this.agent.getTaskStatus(
+              sellerTaskId,
+              settlementTransport,
+              watchSignal,
+              wireOptions
+            );
             if (task.taskId !== sellerTaskId || task.taskType !== "create_media_buy") {
               throw this.legacyPurchaseAmbiguousError(
                 "The polled working seller task does not match the durably recorded create_media_buy task."

package/dist/lib/media-buy/compatibility.mjs

@@ -6120,7 +6120,12 @@ class MediaBuyLifecycleCoordinator {
         });
         void new Promise((resolve) => setTimeout(resolve, 0)).then(async () => {
           while (!watchSignal.aborted) {
-            const task = await this.agent.getTaskStatus(sellerTaskId, settlementTransport, watchSignal, wireOptions);
+            const task = await this.agent.getTaskStatus(
+              sellerTaskId,
+              settlementTransport,
+              watchSignal,
+              wireOptions
+            );
             if (task.taskId !== sellerTaskId || task.taskType !== "create_media_buy") {
               throw this.legacyPurchaseAmbiguousError(
                 "The polled working seller task does not match the durably recorded create_media_buy task."

package/dist/lib/media-buy/preflight.js

@@ -134,7 +134,7 @@ function preflightUpdateMediaBuy(currentBuy, request, options = {}) {
       continue;
     }
     const liveEntry = lookup?.entry;
-    if (strict || options.proposal !== void 0 || resolvedAction.action === "update_name") {
+    if (strict || options.proposal !== void 0 || (0, import_action_contracts.isOperationalMediaBuyAction)(resolvedAction.action)) {
       const assessment = (0, import_action_assessment.assessActionAvailability)(assessmentBuy, resolvedAction.action, { ...options, request });
       if (assessment.status === "currently_unavailable") {
         denials.push({ action: resolvedAction.action, reason: assessment.reason, assessment });

package/dist/lib/media-buy/preflight.mjs

@@ -5,7 +5,8 @@ import {
   liveActionFitsVersion,
   mediaBuyActionTasks,
   packageActionStatus,
-  actionAllowedStatuses
+  actionAllowedStatuses,
+  isOperationalMediaBuyAction
 } from "./action-contracts.mjs";
 import { assessActionAvailability } from "./action-assessment.mjs";
 import {
@@ -107,7 +108,7 @@ function preflightUpdateMediaBuy(currentBuy, request, options = {}) {
       continue;
     }
     const liveEntry = lookup?.entry;
-    if (strict || options.proposal !== void 0 || resolvedAction.action === "update_name") {
+    if (strict || options.proposal !== void 0 || isOperationalMediaBuyAction(resolvedAction.action)) {
       const assessment = assessActionAvailability(assessmentBuy, resolvedAction.action, { ...options, request });
       if (assessment.status === "currently_unavailable") {
         denials.push({ action: resolvedAction.action, reason: assessment.reason, assessment });

package/dist/lib/media-buy/types.d.mts

@@ -17,7 +17,9 @@ import type { CANONICAL_ACTION_TASKS } from './action-metadata.generated.mjs';
  * or `ACTION_NOT_ALLOWED.attempted_action`. `MediaBuyValidAction` remains the
  * correct type for the deprecated flat `valid_actions[]` list only.
  */
-export type MediaBuyActionId = MediaBuyAvailableAction['action'] | MediaBuyUpdateFieldAction | keyof typeof CANONICAL_ACTION_TASKS;
+export type MediaBuyActionId = MediaBuyAvailableAction['action'] | MediaBuyUpdateFieldAction | keyof typeof CANONICAL_ACTION_TASKS
+/** Runtime routes and bindings still come from the negotiated schema metadata. */
+ | 'update_creative_start_policy';
 /**
  * @deprecated Use `SLAWindow`. Kept as an import-compatibility alias for the
  * pre-codegen draft export name; the shape is the generated wire contract.
@@ -60,6 +62,7 @@ export interface MediaBuyActionContext {
         canceled?: boolean;
         paused?: boolean;
         status?: string;
+        start_requires_all_creatives_approved?: boolean;
         daily_budget_cap?: number | null;
         min_spend_target?: number | null;
     }>;
@@ -122,6 +125,8 @@ export interface UpdateMediaBuyRequestLike {
         end_time?: string;
         paused?: boolean;
         canceled?: true;
+        /** AdCP 3.3 initial package-start control; omission preserves the policy. */
+        start_requires_all_creatives_approved?: boolean;
         targeting_overlay?: NonNullable<ControlMediaBuyRequest['packages']>[number]['targeting_overlay'] | {
             frequency_cap?: unknown;
             [k: string]: unknown;

package/dist/lib/media-buy/types.d.ts

@@ -17,7 +17,9 @@ import type { CANONICAL_ACTION_TASKS } from './action-metadata.generated';
  * or `ACTION_NOT_ALLOWED.attempted_action`. `MediaBuyValidAction` remains the
  * correct type for the deprecated flat `valid_actions[]` list only.
  */
-export type MediaBuyActionId = MediaBuyAvailableAction['action'] | MediaBuyUpdateFieldAction | keyof typeof CANONICAL_ACTION_TASKS;
+export type MediaBuyActionId = MediaBuyAvailableAction['action'] | MediaBuyUpdateFieldAction | keyof typeof CANONICAL_ACTION_TASKS
+/** Runtime routes and bindings still come from the negotiated schema metadata. */
+ | 'update_creative_start_policy';
 /**
  * @deprecated Use `SLAWindow`. Kept as an import-compatibility alias for the
  * pre-codegen draft export name; the shape is the generated wire contract.
@@ -60,6 +62,7 @@ export interface MediaBuyActionContext {
         canceled?: boolean;
         paused?: boolean;
         status?: string;
+        start_requires_all_creatives_approved?: boolean;
         daily_budget_cap?: number | null;
         min_spend_target?: number | null;
     }>;
@@ -122,6 +125,8 @@ export interface UpdateMediaBuyRequestLike {
         end_time?: string;
         paused?: boolean;
         canceled?: true;
+        /** AdCP 3.3 initial package-start control; omission preserves the policy. */
+        start_requires_all_creatives_approved?: boolean;
         targeting_overlay?: NonNullable<ControlMediaBuyRequest['packages']>[number]['targeting_overlay'] | {
             frequency_cap?: unknown;
             [k: string]: unknown;

package/dist/lib/protocols/mcp-modern.d.mts

@@ -41,6 +41,8 @@ export interface ModernMCPConnectionOptions {
     /** Use the v2 SDK's negotiated legacy client instead of handing off to v1. */
     handleLegacy?: boolean;
 }
+/** `Retry-After` recorded on an MCP connect error by {@link withRetryAfter}, if any. */
+export declare function retryAfterOf(error: unknown): string | undefined;
 /**
  * Try a tool call using the MCP 2026-07-28 protocol era.
  *

package/dist/lib/protocols/mcp-modern.d.ts

@@ -41,6 +41,8 @@ export interface ModernMCPConnectionOptions {
     /** Use the v2 SDK's negotiated legacy client instead of handing off to v1. */
     handleLegacy?: boolean;
 }
+/** `Retry-After` recorded on an MCP connect error by {@link withRetryAfter}, if any. */
+export declare function retryAfterOf(error: unknown): string | undefined;
 /**
  * Try a tool call using the MCP 2026-07-28 protocol era.
  *

package/dist/lib/protocols/mcp-modern.js

@@ -20,6 +20,7 @@ var mcp_modern_exports = {};
 __export(mcp_modern_exports, {
   closeModernMCPConnections: () => closeModernMCPConnections,
   probeModernMCPConnection: () => probeModernMCPConnection,
+  retryAfterOf: () => retryAfterOf,
   tryCallModernMCPTool: () => tryCallModernMCPTool,
   tryListModernMCPTools: () => tryListModernMCPTools
 });
@@ -248,9 +249,15 @@ async function createNegotiatedClient(cacheKey, options, authHeaders, useCachedD
     getCapability: options.signingContext.getCapability,
     adcpVersion: options.signingContext.adcpVersion
   }) : diagnosticFetch;
+  const transportFetch = (0, import_rawResponseCapture.wrapFetchWithCapture)(withPerRequestTraceHeaders(signedFetch));
+  let throttleRetryAfter;
   const transport = new import_client.StreamableHTTPClientTransport(new URL(options.agentUrl), {
     requestInit: { headers: (0, import_mcp_call_context.splitConnectionHeaders)(authHeaders).identity, redirect: "manual" },
-    fetch: (0, import_rawResponseCapture.wrapFetchWithCapture)(withPerRequestTraceHeaders(signedFetch)),
+    fetch: async (input, init) => {
+      const response = await transportFetch(input, init);
+      throttleRetryAfter = response.status === 429 || response.status === 503 ? response.headers.get("retry-after") ?? void 0 : void 0;
+      return response;
+    },
     ...options.authProvider && {
       authProvider: options.authProvider
     }
@@ -293,8 +300,22 @@ async function createNegotiatedClient(cacheKey, options, authHeaders, useCachedD
     if (isNegotiationAuthFailure(error) && !skipProbe && presentedStaticCredential(authHeaders, options.authProvider)) {
       return createNegotiatedClient(cacheKey, options, authHeaders, useCachedDiscovery, true);
     }
-    throw error;
+    throw withRetryAfter(error, throttleRetryAfter);
+  }
+}
+function withRetryAfter(error, retryAfter) {
+  if (retryAfter === void 0 || !error || typeof error !== "object") return error;
+  const status = httpStatusOf(error);
+  if (status !== 429 && status !== 503) return error;
+  try {
+    Object.defineProperty(error, "retryAfter", { value: retryAfter, enumerable: false, configurable: true });
+  } catch {
   }
+  return error;
+}
+function retryAfterOf(error) {
+  const value = error && typeof error === "object" ? error.retryAfter : void 0;
+  return typeof value === "string" ? value : void 0;
 }
 async function getOrCreateModernConnection(cacheKey, options, authHeaders) {
   for (let attempt = 0; ; attempt++) {
@@ -314,12 +335,12 @@ function createSharedModernConnection(cacheKey, options, authHeaders) {
   const promise = createNegotiatedClient(cacheKey, options, authHeaders).then(async (client) => {
     if ((client.getProtocolEra() === "modern" || options.handleLegacy === true) && generation === connectionGeneration) {
       modernConnections.set(cacheKey, client);
-      (0, import_mcp_scope.registerMCPConnectionScopeCleanup)("modern", cacheKey, async () => {
+      (0, import_mcp_scope.registerMCPConnectionScopeCleanup)("modern", cacheKey, async (terminateSession) => {
         if (modernConnections.get(cacheKey) !== client) return;
         modernConnections.delete(cacheKey);
         legacyConnectionExpiresAt.delete(cacheKey);
         modernDiscoveries.delete(cacheKey);
-        await closeModernClient(client);
+        await closeModernClient(client, terminateSession);
       });
       if (client.getProtocolEra() === "legacy") {
         legacyConnectionExpiresAt.set(cacheKey, Date.now() + LEGACY_CLASSIFICATION_TTL_MS);
@@ -341,7 +362,10 @@ function createSharedModernConnection(cacheKey, options, authHeaders) {
   return promise;
 }
 async function retireFailedConnection(cacheKey, client, error) {
-  if ((0, import_abort.isAbortOrTimeoutError)(error)) return;
+  if ((0, import_abort.isAbortOrTimeoutError)(error)) {
+    (0, import_mcp_scope.markMCPConnectionScopeInterrupted)();
+    return;
+  }
   if (modernConnections.get(cacheKey) === client) {
     modernConnections.delete(cacheKey);
     legacyConnectionExpiresAt.delete(cacheKey);
@@ -510,6 +534,7 @@ async function probeModernMCPConnection(agentUrl, authToken, customHeaders, opti
     options.allowPrivateIp
   );
   const scoped = (0, import_mcp_connection_policy.shouldReuseMCPConnection)(options.fetchFn !== void 0);
+  if (isKnownLegacy(cacheKey)) return { connected: false };
   let client;
   return (0, import_mcp_call_context.runWithMCPCallContext)(
     callContextFor({ customHeaders, requestTimeoutMs: options.requestTimeoutMs }),
@@ -650,6 +675,7 @@ async function closeModernMCPConnections() {
 0 && (module.exports = {
   closeModernMCPConnections,
   probeModernMCPConnection,
+  retryAfterOf,
   tryCallModernMCPTool,
   tryListModernMCPTools
 });

package/dist/lib/protocols/mcp-modern.mjs

@@ -16,6 +16,7 @@ import { is401Error } from "../errors/index.mjs";
 import { withSpan, injectTraceHeaders } from "../observability/tracing.mjs";
 import {
   currentMCPConnectionScopeKey,
+  markMCPConnectionScopeInterrupted,
   isMCPConnectionScopeCacheKeyActive,
   registerMCPConnectionScopeCleanup,
   registerMCPConnectionScopePending
@@ -255,9 +256,15 @@ async function createNegotiatedClient(cacheKey, options, authHeaders, useCachedD
     getCapability: options.signingContext.getCapability,
     adcpVersion: options.signingContext.adcpVersion
   }) : diagnosticFetch;
+  const transportFetch = wrapFetchWithCapture(withPerRequestTraceHeaders(signedFetch));
+  let throttleRetryAfter;
   const transport = new StreamableHTTPClientTransport(new URL(options.agentUrl), {
     requestInit: { headers: splitConnectionHeaders(authHeaders).identity, redirect: "manual" },
-    fetch: wrapFetchWithCapture(withPerRequestTraceHeaders(signedFetch)),
+    fetch: async (input, init) => {
+      const response = await transportFetch(input, init);
+      throttleRetryAfter = response.status === 429 || response.status === 503 ? response.headers.get("retry-after") ?? void 0 : void 0;
+      return response;
+    },
     ...options.authProvider && {
       authProvider: options.authProvider
     }
@@ -300,8 +307,22 @@ async function createNegotiatedClient(cacheKey, options, authHeaders, useCachedD
     if (isNegotiationAuthFailure(error) && !skipProbe && presentedStaticCredential(authHeaders, options.authProvider)) {
       return createNegotiatedClient(cacheKey, options, authHeaders, useCachedDiscovery, true);
     }
-    throw error;
+    throw withRetryAfter(error, throttleRetryAfter);
+  }
+}
+function withRetryAfter(error, retryAfter) {
+  if (retryAfter === void 0 || !error || typeof error !== "object") return error;
+  const status = httpStatusOf(error);
+  if (status !== 429 && status !== 503) return error;
+  try {
+    Object.defineProperty(error, "retryAfter", { value: retryAfter, enumerable: false, configurable: true });
+  } catch {
   }
+  return error;
+}
+function retryAfterOf(error) {
+  const value = error && typeof error === "object" ? error.retryAfter : void 0;
+  return typeof value === "string" ? value : void 0;
 }
 async function getOrCreateModernConnection(cacheKey, options, authHeaders) {
   for (let attempt = 0; ; attempt++) {
@@ -321,12 +342,12 @@ function createSharedModernConnection(cacheKey, options, authHeaders) {
   const promise = createNegotiatedClient(cacheKey, options, authHeaders).then(async (client) => {
     if ((client.getProtocolEra() === "modern" || options.handleLegacy === true) && generation === connectionGeneration) {
       modernConnections.set(cacheKey, client);
-      registerMCPConnectionScopeCleanup("modern", cacheKey, async () => {
+      registerMCPConnectionScopeCleanup("modern", cacheKey, async (terminateSession) => {
         if (modernConnections.get(cacheKey) !== client) return;
         modernConnections.delete(cacheKey);
         legacyConnectionExpiresAt.delete(cacheKey);
         modernDiscoveries.delete(cacheKey);
-        await closeModernClient(client);
+        await closeModernClient(client, terminateSession);
       });
       if (client.getProtocolEra() === "legacy") {
         legacyConnectionExpiresAt.set(cacheKey, Date.now() + LEGACY_CLASSIFICATION_TTL_MS);
@@ -348,7 +369,10 @@ function createSharedModernConnection(cacheKey, options, authHeaders) {
   return promise;
 }
 async function retireFailedConnection(cacheKey, client, error) {
-  if (isAbortOrTimeoutError(error)) return;
+  if (isAbortOrTimeoutError(error)) {
+    markMCPConnectionScopeInterrupted();
+    return;
+  }
   if (modernConnections.get(cacheKey) === client) {
     modernConnections.delete(cacheKey);
     legacyConnectionExpiresAt.delete(cacheKey);
@@ -517,6 +541,7 @@ async function probeModernMCPConnection(agentUrl, authToken, customHeaders, opti
     options.allowPrivateIp
   );
   const scoped = shouldReuseMCPConnection(options.fetchFn !== void 0);
+  if (isKnownLegacy(cacheKey)) return { connected: false };
   let client;
   return runWithMCPCallContext(
     callContextFor({ customHeaders, requestTimeoutMs: options.requestTimeoutMs }),
@@ -656,6 +681,7 @@ async function closeModernMCPConnections() {
 export {
   closeModernMCPConnections,
   probeModernMCPConnection,
+  retryAfterOf,
   tryCallModernMCPTool,
   tryListModernMCPTools
 };