@adcp/sdk 14.0.0-beta.10 → 14.0.0-beta.12

package/dist/lib/testing/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/lib/testing/types.ts"],"sourcesContent":["/**\n * Types for AdCP Agent E2E Testing\n */\n\nimport type { FormatReferenceStructuredObject as FormatID } from '../types/core.generated';\nimport type { ControllerDetection } from './test-controller';\nimport type { WebhookReceiver } from './storyboard/webhook-receiver';\nimport type { AdcpVersion } from '../version';\nimport type { TransportOptions, VersionEnvelopeMode } from '../protocols';\n\n// Test scenarios that can be run\nexport type TestScenario =\n  | 'health_check' // Just check if agent responds\n  | 'discovery' // get_products, list_creative_formats, list_authorized_properties\n  | 'create_media_buy' // Discovery + create a test media buy\n  | 'full_sales_flow' // Full lifecycle: discovery -> create -> update -> delivery\n  | 'reporting_flow' // Dedicated: create media buy -> get_media_buy_delivery validation\n  | 'creative_sync' // Test sync_creatives flow\n  | 'creative_inline' // Test inline creatives in create_media_buy\n  | 'creative_reference' // Build -> sync -> reference a creative via creative_ids\n  | 'pricing_models' // Test different pricing models the agent supports\n  | 'creative_flow' // Creative agent: list_formats -> build -> preview\n  | 'creative_lifecycle' // Creative agent: formats -> sync multiple -> list with/without snapshot -> build/preview\n  | 'signals_flow' // Signals agent: get_signals -> activate\n  // Edge case testing scenarios\n  | 'error_handling' // Test agent returns proper error responses\n  | 'validation' // Test schema validation (invalid inputs should be rejected)\n  | 'pricing_edge_cases' // Test auction vs fixed pricing, min spend, bid_price requirements\n  | 'temporal_validation' // Test date/time ordering and format validation\n  // Behavioral analysis scenarios\n  | 'behavior_analysis' // Analyze agent behavior: auth requirements, brief relevance, filtering\n  // Response consistency scenarios\n  | 'response_consistency' // Check for schema errors, pagination bugs, data mismatches\n  // v3 Governance protocol scenarios\n  | 'governance_property_lists' // Property list CRUD operations\n  | 'governance_content_standards' // Content standards lifecycle\n  | 'property_list_filters' // Property list filter round-trip: GARM, MFA, custom_tags, feature_requirements\n  // v3 Campaign governance scenarios\n  | 'campaign_governance' // Full lifecycle: sync_plans -> check -> execute -> report outcome\n  | 'campaign_governance_denied' // Denied flow: over-budget, unauthorized market\n  | 'campaign_governance_conditions' // Conditions flow: apply conditions -> re-check\n  | 'campaign_governance_delivery' // Delivery monitoring with drift detection\n  | 'seller_governance_context' // Seller persistence of governance_context\n  // v3 SI (Sponsored Intelligence) protocol scenarios\n  | 'si_session_lifecycle' // Full SI session: initiate -> messages -> terminate\n  | 'si_availability' // Check SI offering availability\n  | 'si_handoff' // ACP handoff flow: initiate -> purchase intent -> terminate with handoff_transaction\n  // v3 Capability discovery\n  | 'capability_discovery' // Verify get_adcp_capabilities response\n  // Schema compliance\n  | 'schema_compliance' // Validate v3 channel enum, pricing field names, format assets structure\n  // Audience management\n  | 'sync_audiences' // Test CRM audience sync flow\n  // State machine compliance\n  | 'media_buy_lifecycle' // Pause -> resume -> cancel state transitions\n  | 'terminal_state_enforcement' // Verify agents reject updates to terminal-state media buys\n  | 'package_lifecycle' // Package-level pause/resume independent of media buy status\n  // Error compliance (transport error mapping spec)\n  | 'error_codes' // Validate standard AdCP error codes in responses\n  | 'error_structure' // Validate error JSON structure against error.json schema\n  | 'error_transport' // Validate transport binding (structuredContent, text fallback)\n  // Deterministic state machine scenarios (require comply_test_controller)\n  | 'deterministic_creative' // Force creative status transitions via test controller\n  | 'deterministic_media_buy' // Force media buy status transitions via test controller\n  | 'deterministic_account' // Force account status transitions + operation gates\n  | 'deterministic_session' // Force SI session timeout/termination\n  | 'deterministic_delivery' // Simulate delivery data and verify reporting\n  | 'deterministic_budget' // Simulate budget spend and verify financials\n  | 'controller_validation' // Validate the test controller itself (error codes, edge cases)\n  // Brand rights protocol scenarios\n  | 'brand_identity' // Brand identity discovery (public and authorized access tiers)\n  | 'brand_rights_flow' // Brand rights: get_rights -> acquire_rights lifecycle\n  | 'creative_approval'; // Creative approval workflow for brand compliance\n\nexport interface TestOptions {\n  // Protocol to use for testing (default: 'mcp')\n  protocol?: 'mcp' | 'a2a';\n  /** Optional cancellation signal for discovery and storyboard helper calls. */\n  signal?: AbortSignal;\n  /**\n   * Runtime-only transport configuration for discovery and every storyboard\n   * or compliance tool call. In particular, `fetchFn` lets hosted runners\n   * enforce a request-scoped network policy without replacing global fetch.\n   */\n  transport?: TransportOptions;\n  /**\n   * AdCP protocol version the test client should speak. Storyboard runners\n   * set this from the compliance cache version instead of relying on the\n   * installed package default.\n   */\n  adcpVersion?: AdcpVersion | (string & {});\n  /**\n   * Route compact media-buy storyboard steps through the SDK compatibility\n   * coordinator. This lets the same compact-first storyboard exercise native\n   * 3.2 sellers and established v2.5–3.2 sellers without task-name branching.\n   * Mutating guarantee losses remain fail-closed unless named here.\n   */\n  mediaBuyLifecycleCompatibility?: import('../media-buy/compatibility').MediaBuyLifecycleCoordinatorOptions;\n  /**\n   * Optional wire-only AdCP version envelope override. Validation and schema\n   * selection continue to use `adcpVersion`; request envelopes use this value.\n   * Intended for hosted stable-line badges backed by prerelease caches.\n   */\n  wireAdcpVersion?: AdcpVersion | (string & {});\n  /**\n   * Version-envelope emission mode. Defaults to `auto`; 3.0 storyboards emit\n   * the legacy major marker only, while 3.1 storyboards also emit the exact\n   * `adcp_version` marker. Compliance discovery may negotiate `major-only`\n   * for strict pre-3.1 agents.\n   */\n  versionEnvelope?: VersionEnvelopeMode;\n  /**\n   * External schema bundle root used for request/response validation during\n   * storyboard and compliance runs. The root is registered against\n   * `adcpVersion` (or the storyboard/compliance version when omitted) and is\n   * authoritative over the SDK's generated Zod snapshot for the run.\n   */\n  schemaRoot?: string;\n  /**\n   * Whether strict AJV response-schema failures contribute to storyboard\n   * grading. Defaults to `true`, matching the hosted compliance grader.\n   *\n   * Set to `false` only for packaged-schema diagnostic migrations that need\n   * the historical lenient-Zod grade while inspecting\n   * `strict_validation_summary` and the per-validation `strict` verdicts.\n   * Strict validation still runs in that mode; it is informational rather\n   * than grading. An explicit external `schemaRoot` remains authoritative.\n   */\n  strictResponseSchemaValidation?: boolean;\n  /** Custom User-Agent string sent with all outbound requests */\n  userAgent?: string;\n  // Brand reference for product discovery (preferred over brand_manifest)\n  brand?: { domain: string; brand_id?: string };\n  // Custom brief for product discovery\n  brief?: string;\n  // Budget for test media buy (default: 1000)\n  budget?: number;\n  // Specific format IDs to test\n  format_ids?: string[];\n  // Test session ID for isolation\n  test_session_id?: string;\n  // Channels to focus on (if not specified, tests all agent supports)\n  channels?: string[];\n  // Specific pricing models to test\n  pricing_models?: string[];\n  /**\n   * Authentication for agents that require it.\n   *\n   * - `bearer`: raw token sent as `Authorization: Bearer <token>`.\n   * - `basic`: cleartext `username` and `password`, encoded internally.\n   * - `oauth`: saved OAuth tokens (access_token + refresh_token). MCP only.\n   *   The library auto-refreshes on 401. Obtain tokens interactively via\n   *   `adcp --save-auth <alias> --oauth`, then pass the saved blob here for\n   *   non-interactive reuse.\n   * - `oauth_client_credentials`: RFC 6749 §4.4 machine-to-machine flow.\n   *   The library exchanges the secret for a fresh access token before each\n   *   call (cached while valid). Supply `tokens` to seed the cache; omit to\n   *   exchange on first call.\n   */\n  auth?:\n    | { type: 'bearer'; token: string }\n    | { type: 'basic'; username: string; password: string }\n    | {\n        type: 'oauth';\n        tokens: import('../types/adcp').AgentOAuthTokens;\n        client?: import('../types/adcp').AgentOAuthClient;\n      }\n    | {\n        type: 'oauth_client_credentials';\n        credentials: import('../types/adcp').AgentOAuthClientCredentials;\n        tokens?: import('../types/adcp').AgentOAuthTokens;\n      };\n  /**\n   * Extra HTTP headers applied to every outbound request to the agent.\n   * Forwarded into `AgentConfig.headers`, so MCP and A2A transports both\n   * see them. `Authorization` and `x-adcp-auth` are reserved — auth wins.\n   *\n   * Typical use: tenant-routing headers (`x-adcp-tenant`, `Apx-Incoming-Host`)\n   * for multi-tenant agents fronted by a reverse proxy. The CLI exposes these\n   * via `-H KEY=VALUE` (repeatable) and persists them in `~/.adcp/config.json`.\n   */\n  headers?: Record<string, string>;\n  // Brand manifest for creative testing\n  brand_manifest?: {\n    name: string;\n    url?: string;\n    tagline?: string;\n    logos?: Array<{\n      url: string;\n      orientation?: 'square' | 'horizontal' | 'vertical' | 'stacked';\n      background?: 'dark-bg' | 'light-bg' | 'transparent-bg';\n      variant?: 'primary' | 'secondary' | 'icon' | 'wordmark' | 'full-lockup';\n      tags?: string[];\n      usage?: string;\n      width?: number;\n      height?: number;\n    }>;\n    colors?: Record<string, string>;\n    tone?: {\n      voice?: string;\n      attributes?: string[];\n      dos?: string[];\n      donts?: string[];\n    };\n    assets?: Array<{\n      asset_id: string;\n      asset_type: string;\n      url: string;\n      width?: number;\n      height?: number;\n      tags?: string[];\n    }>;\n  };\n  // For creative testing: test multiple formats programmatically\n  test_all_formats?: boolean;\n  // For creative testing: max formats to test when test_all_formats is true\n  max_formats_to_test?: number;\n  // For signals testing: specific signal types to test\n  signal_types?: string[];\n  // For governance testing: name for test property list\n  property_list_name?: string;\n  // For governance testing: specific content standards to test\n  content_standards_id?: string;\n  // For SI testing: specific offering ID to test\n  si_offering_id?: string;\n  // For SI testing: initial conversation context\n  si_context?: string;\n  /**\n   * Shared explicit account id for test scenarios that need an account-scoped\n   * request. Domain-specific account ids below take precedence when provided.\n   */\n  account_id?: string;\n  /**\n   * For media-buy testing: account ID to use with get_products,\n   * create_media_buy, sync_creatives, and related media-buy flows.\n   */\n  media_buy_account_id?: string;\n  // For audience testing: account ID to use with sync_audiences\n  audience_account_id?: string;\n  // When true, use sandbox mode. For implicit accounts, uses the natural key with\n  // sandbox: true. For explicit accounts, discovers sandbox accounts via list_accounts.\n  sandbox?: boolean;\n  /**\n   * When true, the runner injects `ext.adcp.disable_sandbox: true` on every\n   * outgoing request, signaling the agent under test to bypass any internal\n   * sandbox routing (env-var fallbacks, brand-domain heuristics, fixture\n   * substitutes) and exercise its real adapter path. Distinct from `sandbox`\n   * (which sets `account.sandbox: false` — a value, not a routing hint).\n   *\n   * Honored by adopters who explicitly read `ext.adcp.disable_sandbox`.\n   * Agents that don't recognize the field ignore it (per spec, `ext` is\n   * accepted-without-error). The pair (sandbox=false + disable_sandbox=true)\n   * is the strongest \"production path only\" signal the runner can send;\n   * `--no-sandbox` on `adcp storyboard run` sets both. Issue #841.\n   */\n  disable_sandbox?: boolean;\n  /**\n   * Fictional-entity test-kit data loaded from `test-kits/<name>.yaml`.\n   * Storyboard phases may skip based on fields here (e.g. `skip_if: \"!test_kit.auth.api_key\"`).\n   */\n  test_kit?: {\n    auth?: {\n      /** API key the runner presents on API-key probes. */\n      api_key?: string;\n      /** HTTP Basic credential the runner presents on Basic-auth probes. */\n      basic?: {\n        /** Username portion of the Basic credential. */\n        username?: string;\n        /** Password portion of the Basic credential. */\n        password?: string;\n        /** Unencoded `username:password` pair. */\n        credentials?: string;\n      };\n      /**\n       * Auth-required, read-only tool the runner uses for unauth + invalid-key probes.\n       * Required whenever `auth` is declared — no default is substituted. Must be one of\n       * the values in `PROBE_TASK_ALLOWLIST`. Kits that miss this or pick a task outside\n       * the allowlist fail at `comply()` / `runStoryboard()` entry with\n       * `TestKitValidationError`.\n       */\n      probe_task: string;\n    };\n    [key: string]: unknown;\n  };\n  /** @internal Pre-created client from comply() — avoids per-scenario MCP reconnection */\n  _client?: unknown;\n  /**\n   * @internal Pre-discovered profile from comply() — skips per-scenario discovery.\n   * @deprecated Use `StoryboardRunOptions.profile` for storyboard profile reuse.\n   */\n  _profile?: AgentProfile;\n  /**\n   * @internal Server-declared AdCP version learned during capability discovery.\n   * Storyboard response validation uses this for version-skew compatibility\n   * without forcing the transport client to pin a schema bundle that may not\n   * ship with the installed SDK.\n   */\n  _serverAdcpVersion?: string;\n  /** @internal Test controller capabilities from comply() — set when comply_test_controller detected */\n  _controllerCapabilities?: ControllerDetection;\n  /** @internal Pre-created webhook receiver, used for unit-test injection. When\n   *  present, the runner skips creating its own listener and does NOT close\n   *  the receiver after the run (caller-owned). Production callers pass\n   *  `webhook_receiver` instead. */\n  _webhookReceiver?: WebhookReceiver;\n}\n\nexport interface TestStepResult {\n  step: string;\n  task?: string;\n  passed: boolean;\n  duration_ms: number;\n  details?: string;\n  error?: string;\n  response_preview?: string;\n  // Structured data for collectObservations() — decoupled from response_preview display\n  observation_data?: Record<string, unknown>;\n  // For tracking what was created (for cleanup or follow-up)\n  created_id?: string;\n  // Deprecation or other warnings\n  warnings?: string[];\n  /** True when the step was skipped (including re-graded branch-set peers). */\n  skipped?: boolean;\n  /** Canonical skip reason when `skipped` is true; maps to `RunnerSkipReason`. */\n  skip_reason?: string;\n  /**\n   * Selection reason when a skipped-looking step was intentionally outside\n   * the caller's requested run. Summary artifacts use this to keep\n   * not-selected steps out of actionable skip-cause rollups.\n   */\n  selection_reason?: string;\n  /**\n   * Names the unmet runtime requirement when `skip_reason` is\n   * `'requirement_unmet'` (per adcp-client#1626). Carries the same value\n   * the storyboard authored in `Storyboard.requires`. Lets skip-cause\n   * aggregators sub-group not-applicable scenarios per-requirement\n   * without parsing the warning text. Absent for every other skip reason.\n   */\n  requirement?: string;\n}\n\nexport interface AgentProfile {\n  name: string;\n  tools: string[];\n  channels?: string[];\n  pricing_models?: string[];\n  format_ids?: string[];\n  delivery_types?: string[];\n  // For creative agents\n  supported_formats?: Array<{\n    format_id: FormatID;\n    name?: string;\n    required_assets?: string[];\n    optional_assets?: string[];\n  }>;\n  // For signals agents\n  supported_signals?: Array<{\n    signal_id: string;\n    name?: string;\n    type?: string;\n  }>;\n  // v3 capabilities\n  adcp_version?: 'v2' | 'v3';\n  /**\n   * AdCP major versions the agent declared in `get_adcp_capabilities.adcp.major_versions`.\n   * Drives version-gated storyboard filtering so a v3.0 agent isn't failed against a\n   * storyboard introduced in a later minor version.\n   */\n  adcp_major_versions?: number[];\n  /**\n   * Exact/release-precision versions from\n   * `get_adcp_capabilities.adcp.supported_versions`.\n   */\n  adcp_supported_versions?: string[];\n  /**\n   * Seller's full AdCP build version from\n   * `get_adcp_capabilities.adcp.build_version`.\n   */\n  adcp_build_version?: string;\n  supported_protocols?: string[];\n  /** Specialism claims from get_adcp_capabilities.specialisms */\n  specialisms?: string[];\n  supports_governance?: boolean;\n  supports_si?: boolean;\n  /**\n   * Populated when the agent advertises `get_adcp_capabilities` but the call failed\n   * or returned no data. Signals the compliance runner that the universal-only\n   * result is due to a broken caps probe, not an agent that lacks v3 support.\n   */\n  capabilities_probe_error?: string;\n  /**\n   * Schema violations found during the preflight `get_adcp_capabilities`\n   * call. Kept separately from `capabilities_probe_error`: an invalid\n   * response is still available for best-effort storyboard selection, while\n   * the runner surfaces each violation as a structured notice.\n   */\n  capabilities_schema_issues?: Array<{\n    /** RFC 6901 pointer into the capabilities response. */\n    pointer: string;\n    /** Validator-authored explanation of the violation. */\n    message: string;\n  }>;\n  /**\n   * Raw `get_adcp_capabilities` response body. Used by the storyboard runner to\n   * evaluate `requires_capability` predicates (e.g. `adcp.idempotency.supported`)\n   * that reference fields not extracted into the normalised profile shape above.\n   */\n  raw_capabilities?: unknown;\n  /**\n   * SDK version string the agent self-reported in `get_adcp_capabilities`, e.g.\n   * `\"@adcp/client@5.14.0\"`. Populated opportunistically — absent for hand-rolled\n   * agents that don't emit the field. Used by the storyboard runner to suffix\n   * shape-drift hints when the reported version predates the recommended helper.\n   */\n  library_version?: string;\n}\n\nexport interface TestResult {\n  agent_url: string;\n  scenario: TestScenario;\n  overall_passed: boolean;\n  steps?: TestStepResult[];\n  summary: string;\n  total_duration_ms: number;\n  tested_at: string;\n  // Agent profile discovered during testing\n  agent_profile?: AgentProfile;\n}\n\nexport interface SuiteResult {\n  agent_url: string;\n  agent_profile: AgentProfile;\n  /** Scenarios that were run */\n  scenarios_run: TestScenario[];\n  /** Scenarios skipped because the agent does not advertise the required tools */\n  scenarios_skipped: TestScenario[];\n  results: TestResult[];\n  /**\n   * True only when at least one scenario ran and none failed.\n   * False for both \"all failed\" and \"no applicable scenarios found\".\n   */\n  overall_passed: boolean;\n  passed_count: number;\n  failed_count: number;\n  /** Wall-clock time including capability discovery and all scenario runs */\n  total_duration_ms: number;\n  tested_at: string;\n}\n\n// Generic task result from executeTask\nexport interface TaskResult {\n  success: boolean;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- response shape varies by tool; typed per-access in scenarios\n  data?: any;\n  error?: string;\n  /** Structured AdCP error forwarded from the transport layer. Mirrors `TaskResultFailure.adcpError`. */\n  adcp_error?: import('../core/ConversationTypes').AdcpErrorInfo;\n  /**\n   * Internal: which MCP extraction path produced `data`. Set by the response\n   * unwrapper and the raw MCP probe so the storyboard runner can surface it\n   * in its output contract. Consumers outside the runner should treat this\n   * as implementation detail — it's NOT part of the public `AdCPResponse`.\n   */\n  _extraction_path?: 'structured_content' | 'text_fallback' | 'error' | 'none';\n}\n\n// Logger interface for library use\nexport interface Logger {\n  info: (context: object, message: string) => void;\n  error: (context: object, message: string) => void;\n  warn: (context: object, message: string) => void;\n  debug: (context: object, message: string) => void;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../../src/lib/testing/types.ts"],"sourcesContent":["/**\n * Types for AdCP Agent E2E Testing\n */\n\nimport type { FormatReferenceStructuredObject as FormatID } from '../types/core.generated';\nimport type { ControllerDetection } from './test-controller';\nimport type { WebhookReceiver } from './storyboard/webhook-receiver';\nimport type { AdcpVersion } from '../version';\nimport type { TransportOptions, VersionEnvelopeMode } from '../protocols';\nimport type { AgentRequestSigningConfig } from '../types/adcp';\n\n// Test scenarios that can be run\nexport type TestScenario =\n  | 'health_check' // Just check if agent responds\n  | 'discovery' // get_products, list_creative_formats, list_authorized_properties\n  | 'create_media_buy' // Discovery + create a test media buy\n  | 'full_sales_flow' // Full lifecycle: discovery -> create -> update -> delivery\n  | 'reporting_flow' // Dedicated: create media buy -> get_media_buy_delivery validation\n  | 'creative_sync' // Test sync_creatives flow\n  | 'creative_inline' // Test inline creatives in create_media_buy\n  | 'creative_reference' // Build -> sync -> reference a creative via creative_ids\n  | 'pricing_models' // Test different pricing models the agent supports\n  | 'creative_flow' // Creative agent: list_formats -> build -> preview\n  | 'creative_lifecycle' // Creative agent: formats -> sync multiple -> list with/without snapshot -> build/preview\n  | 'signals_flow' // Signals agent: get_signals -> activate\n  // Edge case testing scenarios\n  | 'error_handling' // Test agent returns proper error responses\n  | 'validation' // Test schema validation (invalid inputs should be rejected)\n  | 'pricing_edge_cases' // Test auction vs fixed pricing, min spend, bid_price requirements\n  | 'temporal_validation' // Test date/time ordering and format validation\n  // Behavioral analysis scenarios\n  | 'behavior_analysis' // Analyze agent behavior: auth requirements, brief relevance, filtering\n  // Response consistency scenarios\n  | 'response_consistency' // Check for schema errors, pagination bugs, data mismatches\n  // v3 Governance protocol scenarios\n  | 'governance_property_lists' // Property list CRUD operations\n  | 'governance_content_standards' // Content standards lifecycle\n  | 'property_list_filters' // Property list filter round-trip: GARM, MFA, custom_tags, feature_requirements\n  // v3 Campaign governance scenarios\n  | 'campaign_governance' // Full lifecycle: sync_plans -> check -> execute -> report outcome\n  | 'campaign_governance_denied' // Denied flow: over-budget, unauthorized market\n  | 'campaign_governance_conditions' // Conditions flow: apply conditions -> re-check\n  | 'campaign_governance_delivery' // Delivery monitoring with drift detection\n  | 'seller_governance_context' // Seller persistence of governance_context\n  // v3 SI (Sponsored Intelligence) protocol scenarios\n  | 'si_session_lifecycle' // Full SI session: initiate -> messages -> terminate\n  | 'si_availability' // Check SI offering availability\n  | 'si_handoff' // ACP handoff flow: initiate -> purchase intent -> terminate with handoff_transaction\n  // v3 Capability discovery\n  | 'capability_discovery' // Verify get_adcp_capabilities response\n  // Schema compliance\n  | 'schema_compliance' // Validate v3 channel enum, pricing field names, format assets structure\n  // Audience management\n  | 'sync_audiences' // Test CRM audience sync flow\n  // State machine compliance\n  | 'media_buy_lifecycle' // Pause -> resume -> cancel state transitions\n  | 'terminal_state_enforcement' // Verify agents reject updates to terminal-state media buys\n  | 'package_lifecycle' // Package-level pause/resume independent of media buy status\n  // Error compliance (transport error mapping spec)\n  | 'error_codes' // Validate standard AdCP error codes in responses\n  | 'error_structure' // Validate error JSON structure against error.json schema\n  | 'error_transport' // Validate transport binding (structuredContent, text fallback)\n  // Deterministic state machine scenarios (require comply_test_controller)\n  | 'deterministic_creative' // Force creative status transitions via test controller\n  | 'deterministic_media_buy' // Force media buy status transitions via test controller\n  | 'deterministic_account' // Force account status transitions + operation gates\n  | 'deterministic_session' // Force SI session timeout/termination\n  | 'deterministic_delivery' // Simulate delivery data and verify reporting\n  | 'deterministic_budget' // Simulate budget spend and verify financials\n  | 'controller_validation' // Validate the test controller itself (error codes, edge cases)\n  // Brand rights protocol scenarios\n  | 'brand_identity' // Brand identity discovery (public and authorized access tiers)\n  | 'brand_rights_flow' // Brand rights: get_rights -> acquire_rights lifecycle\n  | 'creative_approval'; // Creative approval workflow for brand compliance\n\nexport interface TestOptions {\n  // Protocol to use for testing (default: 'mcp')\n  protocol?: 'mcp' | 'a2a';\n  /** Optional cancellation signal for discovery and storyboard helper calls. */\n  signal?: AbortSignal;\n  /**\n   * Runtime-only transport configuration for discovery and every storyboard\n   * or compliance tool call. In particular, `fetchFn` lets hosted runners\n   * enforce a request-scoped network policy without replacing global fetch.\n   */\n  transport?: TransportOptions;\n  /**\n   * RFC 9421 identity used for ordinary functional test/storyboard calls.\n   * Distinct from `StoryboardRunOptions.request_signing`, which configures\n   * the dedicated verifier-vector grader. Compliance runners populate this\n   * automatically from `signed-requests-runner.yaml > functional_dispatch`\n   * only for sandbox runs; callers may provide their own key/provider for a\n   * different trusted environment.\n   */\n  functional_request_signing?: AgentRequestSigningConfig;\n  /**\n   * AdCP protocol version the test client should speak. Storyboard runners\n   * set this from the compliance cache version instead of relying on the\n   * installed package default.\n   */\n  adcpVersion?: AdcpVersion | (string & {});\n  /**\n   * Route compact media-buy storyboard steps through the SDK compatibility\n   * coordinator. This lets the same compact-first storyboard exercise native\n   * 3.2 sellers and established v2.5–3.2 sellers without task-name branching.\n   * Mutating guarantee losses remain fail-closed unless named here.\n   */\n  mediaBuyLifecycleCompatibility?: import('../media-buy/compatibility').MediaBuyLifecycleCoordinatorOptions;\n  /**\n   * Optional wire-only AdCP version envelope override. Validation and schema\n   * selection continue to use `adcpVersion`; request envelopes use this value.\n   * Intended for hosted stable-line badges backed by prerelease caches.\n   */\n  wireAdcpVersion?: AdcpVersion | (string & {});\n  /**\n   * Version-envelope emission mode. Defaults to `auto`; 3.0 storyboards emit\n   * the legacy major marker only, while 3.1 storyboards also emit the exact\n   * `adcp_version` marker. Compliance discovery may negotiate `major-only`\n   * for strict pre-3.1 agents.\n   */\n  versionEnvelope?: VersionEnvelopeMode;\n  /**\n   * External schema bundle root used for request/response validation during\n   * storyboard and compliance runs. The root is registered against\n   * `adcpVersion` (or the storyboard/compliance version when omitted) and is\n   * authoritative over the SDK's generated Zod snapshot for the run.\n   */\n  schemaRoot?: string;\n  /**\n   * Whether strict AJV response-schema failures contribute to storyboard\n   * grading. Defaults to `true`, matching the hosted compliance grader.\n   *\n   * Set to `false` only for packaged-schema diagnostic migrations that need\n   * the historical lenient-Zod grade while inspecting\n   * `strict_validation_summary` and the per-validation `strict` verdicts.\n   * Strict validation still runs in that mode; it is informational rather\n   * than grading. An explicit external `schemaRoot` remains authoritative.\n   */\n  strictResponseSchemaValidation?: boolean;\n  /** Custom User-Agent string sent with all outbound requests */\n  userAgent?: string;\n  // Brand reference for product discovery (preferred over brand_manifest)\n  brand?: { domain: string; brand_id?: string };\n  // Custom brief for product discovery\n  brief?: string;\n  // Budget for test media buy (default: 1000)\n  budget?: number;\n  // Specific format IDs to test\n  format_ids?: string[];\n  // Test session ID for isolation\n  test_session_id?: string;\n  // Channels to focus on (if not specified, tests all agent supports)\n  channels?: string[];\n  // Specific pricing models to test\n  pricing_models?: string[];\n  /**\n   * Authentication for agents that require it.\n   *\n   * - `bearer`: raw token sent as `Authorization: Bearer <token>`.\n   * - `basic`: cleartext `username` and `password`, encoded internally.\n   * - `oauth`: saved OAuth tokens (access_token + refresh_token). MCP only.\n   *   The library auto-refreshes on 401. Obtain tokens interactively via\n   *   `adcp --save-auth <alias> --oauth`, then pass the saved blob here for\n   *   non-interactive reuse.\n   * - `oauth_client_credentials`: RFC 6749 §4.4 machine-to-machine flow.\n   *   The library exchanges the secret for a fresh access token before each\n   *   call (cached while valid). Supply `tokens` to seed the cache; omit to\n   *   exchange on first call.\n   */\n  auth?:\n    | { type: 'bearer'; token: string }\n    | { type: 'basic'; username: string; password: string }\n    | {\n        type: 'oauth';\n        tokens: import('../types/adcp').AgentOAuthTokens;\n        client?: import('../types/adcp').AgentOAuthClient;\n      }\n    | {\n        type: 'oauth_client_credentials';\n        credentials: import('../types/adcp').AgentOAuthClientCredentials;\n        tokens?: import('../types/adcp').AgentOAuthTokens;\n      };\n  /**\n   * Extra HTTP headers applied to every outbound request to the agent.\n   * Forwarded into `AgentConfig.headers`, so MCP and A2A transports both\n   * see them. `Authorization` and `x-adcp-auth` are reserved — auth wins.\n   *\n   * Typical use: tenant-routing headers (`x-adcp-tenant`, `Apx-Incoming-Host`)\n   * for multi-tenant agents fronted by a reverse proxy. The CLI exposes these\n   * via `-H KEY=VALUE` (repeatable) and persists them in `~/.adcp/config.json`.\n   */\n  headers?: Record<string, string>;\n  // Brand manifest for creative testing\n  brand_manifest?: {\n    name: string;\n    url?: string;\n    tagline?: string;\n    logos?: Array<{\n      url: string;\n      orientation?: 'square' | 'horizontal' | 'vertical' | 'stacked';\n      background?: 'dark-bg' | 'light-bg' | 'transparent-bg';\n      variant?: 'primary' | 'secondary' | 'icon' | 'wordmark' | 'full-lockup';\n      tags?: string[];\n      usage?: string;\n      width?: number;\n      height?: number;\n    }>;\n    colors?: Record<string, string>;\n    tone?: {\n      voice?: string;\n      attributes?: string[];\n      dos?: string[];\n      donts?: string[];\n    };\n    assets?: Array<{\n      asset_id: string;\n      asset_type: string;\n      url: string;\n      width?: number;\n      height?: number;\n      tags?: string[];\n    }>;\n  };\n  // For creative testing: test multiple formats programmatically\n  test_all_formats?: boolean;\n  // For creative testing: max formats to test when test_all_formats is true\n  max_formats_to_test?: number;\n  // For signals testing: specific signal types to test\n  signal_types?: string[];\n  // For governance testing: name for test property list\n  property_list_name?: string;\n  // For governance testing: specific content standards to test\n  content_standards_id?: string;\n  // For SI testing: specific offering ID to test\n  si_offering_id?: string;\n  // For SI testing: initial conversation context\n  si_context?: string;\n  /**\n   * Shared explicit account id for test scenarios that need an account-scoped\n   * request. Domain-specific account ids below take precedence when provided.\n   */\n  account_id?: string;\n  /**\n   * For media-buy testing: account ID to use with get_products,\n   * create_media_buy, sync_creatives, and related media-buy flows.\n   */\n  media_buy_account_id?: string;\n  // For audience testing: account ID to use with sync_audiences\n  audience_account_id?: string;\n  // When true, use sandbox mode. For implicit accounts, uses the natural key with\n  // sandbox: true. For explicit accounts, discovers sandbox accounts via list_accounts.\n  sandbox?: boolean;\n  /**\n   * When true, the runner injects `ext.adcp.disable_sandbox: true` on every\n   * outgoing request, signaling the agent under test to bypass any internal\n   * sandbox routing (env-var fallbacks, brand-domain heuristics, fixture\n   * substitutes) and exercise its real adapter path. Distinct from `sandbox`\n   * (which sets `account.sandbox: false` — a value, not a routing hint).\n   *\n   * Honored by adopters who explicitly read `ext.adcp.disable_sandbox`.\n   * Agents that don't recognize the field ignore it (per spec, `ext` is\n   * accepted-without-error). The pair (sandbox=false + disable_sandbox=true)\n   * is the strongest \"production path only\" signal the runner can send;\n   * `--no-sandbox` on `adcp storyboard run` sets both. Issue #841.\n   */\n  disable_sandbox?: boolean;\n  /**\n   * Fictional-entity test-kit data loaded from `test-kits/<name>.yaml`.\n   * Storyboard phases may skip based on fields here (e.g. `skip_if: \"!test_kit.auth.api_key\"`).\n   */\n  test_kit?: {\n    auth?: {\n      /** API key the runner presents on API-key probes. */\n      api_key?: string;\n      /** HTTP Basic credential the runner presents on Basic-auth probes. */\n      basic?: {\n        /** Username portion of the Basic credential. */\n        username?: string;\n        /** Password portion of the Basic credential. */\n        password?: string;\n        /** Unencoded `username:password` pair. */\n        credentials?: string;\n      };\n      /**\n       * Auth-required, read-only tool the runner uses for unauth + invalid-key probes.\n       * Required whenever `auth` is declared — no default is substituted. Must be one of\n       * the values in `PROBE_TASK_ALLOWLIST`. Kits that miss this or pick a task outside\n       * the allowlist fail at `comply()` / `runStoryboard()` entry with\n       * `TestKitValidationError`.\n       */\n      probe_task: string;\n    };\n    [key: string]: unknown;\n  };\n  /** @internal Pre-created client from comply() — avoids per-scenario MCP reconnection */\n  _client?: unknown;\n  /**\n   * @internal Pre-discovered profile from comply() — skips per-scenario discovery.\n   * @deprecated Use `StoryboardRunOptions.profile` for storyboard profile reuse.\n   */\n  _profile?: AgentProfile;\n  /**\n   * @internal Server-declared AdCP version learned during capability discovery.\n   * Storyboard response validation uses this for version-skew compatibility\n   * without forcing the transport client to pin a schema bundle that may not\n   * ship with the installed SDK.\n   */\n  _serverAdcpVersion?: string;\n  /** @internal Test controller capabilities from comply() — set when comply_test_controller detected */\n  _controllerCapabilities?: ControllerDetection;\n  /** @internal Pre-created webhook receiver, used for unit-test injection. When\n   *  present, the runner skips creating its own listener and does NOT close\n   *  the receiver after the run (caller-owned). Production callers pass\n   *  `webhook_receiver` instead. */\n  _webhookReceiver?: WebhookReceiver;\n}\n\nexport interface TestStepResult {\n  step: string;\n  task?: string;\n  passed: boolean;\n  duration_ms: number;\n  details?: string;\n  error?: string;\n  response_preview?: string;\n  // Structured data for collectObservations() — decoupled from response_preview display\n  observation_data?: Record<string, unknown>;\n  // For tracking what was created (for cleanup or follow-up)\n  created_id?: string;\n  // Deprecation or other warnings\n  warnings?: string[];\n  /** True when the step was skipped (including re-graded branch-set peers). */\n  skipped?: boolean;\n  /** Canonical skip reason when `skipped` is true; maps to `RunnerSkipReason`. */\n  skip_reason?: string;\n  /**\n   * Selection reason when a skipped-looking step was intentionally outside\n   * the caller's requested run. Summary artifacts use this to keep\n   * not-selected steps out of actionable skip-cause rollups.\n   */\n  selection_reason?: string;\n  /**\n   * Names the unmet runtime requirement when `skip_reason` is\n   * `'requirement_unmet'` (per adcp-client#1626). Carries the same value\n   * the storyboard authored in `Storyboard.requires`. Lets skip-cause\n   * aggregators sub-group not-applicable scenarios per-requirement\n   * without parsing the warning text. Absent for every other skip reason.\n   */\n  requirement?: string;\n}\n\nexport interface AgentProfile {\n  name: string;\n  tools: string[];\n  channels?: string[];\n  pricing_models?: string[];\n  format_ids?: string[];\n  delivery_types?: string[];\n  // For creative agents\n  supported_formats?: Array<{\n    format_id: FormatID;\n    name?: string;\n    required_assets?: string[];\n    optional_assets?: string[];\n  }>;\n  // For signals agents\n  supported_signals?: Array<{\n    signal_id: string;\n    name?: string;\n    type?: string;\n  }>;\n  // v3 capabilities\n  adcp_version?: 'v2' | 'v3';\n  /**\n   * AdCP major versions the agent declared in `get_adcp_capabilities.adcp.major_versions`.\n   * Drives version-gated storyboard filtering so a v3.0 agent isn't failed against a\n   * storyboard introduced in a later minor version.\n   */\n  adcp_major_versions?: number[];\n  /**\n   * Exact/release-precision versions from\n   * `get_adcp_capabilities.adcp.supported_versions`.\n   */\n  adcp_supported_versions?: string[];\n  /**\n   * Seller's full AdCP build version from\n   * `get_adcp_capabilities.adcp.build_version`.\n   */\n  adcp_build_version?: string;\n  supported_protocols?: string[];\n  /** Specialism claims from get_adcp_capabilities.specialisms */\n  specialisms?: string[];\n  supports_governance?: boolean;\n  supports_si?: boolean;\n  /**\n   * Populated when the agent advertises `get_adcp_capabilities` but the call failed\n   * or returned no data. Signals the compliance runner that the universal-only\n   * result is due to a broken caps probe, not an agent that lacks v3 support.\n   */\n  capabilities_probe_error?: string;\n  /**\n   * Schema violations found during the preflight `get_adcp_capabilities`\n   * call. Kept separately from `capabilities_probe_error`: an invalid\n   * response is still available for best-effort storyboard selection, while\n   * the runner surfaces each violation as a structured notice.\n   */\n  capabilities_schema_issues?: Array<{\n    /** RFC 6901 pointer into the capabilities response. */\n    pointer: string;\n    /** Validator-authored explanation of the violation. */\n    message: string;\n  }>;\n  /**\n   * Raw `get_adcp_capabilities` response body. Used by the storyboard runner to\n   * evaluate `requires_capability` predicates (e.g. `adcp.idempotency.supported`)\n   * that reference fields not extracted into the normalised profile shape above.\n   */\n  raw_capabilities?: unknown;\n  /**\n   * SDK version string the agent self-reported in `get_adcp_capabilities`, e.g.\n   * `\"@adcp/client@5.14.0\"`. Populated opportunistically — absent for hand-rolled\n   * agents that don't emit the field. Used by the storyboard runner to suffix\n   * shape-drift hints when the reported version predates the recommended helper.\n   */\n  library_version?: string;\n}\n\nexport interface TestResult {\n  agent_url: string;\n  scenario: TestScenario;\n  overall_passed: boolean;\n  steps?: TestStepResult[];\n  summary: string;\n  total_duration_ms: number;\n  tested_at: string;\n  // Agent profile discovered during testing\n  agent_profile?: AgentProfile;\n}\n\nexport interface SuiteResult {\n  agent_url: string;\n  agent_profile: AgentProfile;\n  /** Scenarios that were run */\n  scenarios_run: TestScenario[];\n  /** Scenarios skipped because the agent does not advertise the required tools */\n  scenarios_skipped: TestScenario[];\n  results: TestResult[];\n  /**\n   * True only when at least one scenario ran and none failed.\n   * False for both \"all failed\" and \"no applicable scenarios found\".\n   */\n  overall_passed: boolean;\n  passed_count: number;\n  failed_count: number;\n  /** Wall-clock time including capability discovery and all scenario runs */\n  total_duration_ms: number;\n  tested_at: string;\n}\n\n// Generic task result from executeTask\nexport interface TaskResult {\n  success: boolean;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- response shape varies by tool; typed per-access in scenarios\n  data?: any;\n  error?: string;\n  /** Structured AdCP error forwarded from the transport layer. Mirrors `TaskResultFailure.adcpError`. */\n  adcp_error?: import('../core/ConversationTypes').AdcpErrorInfo;\n  /**\n   * Internal: which MCP extraction path produced `data`. Set by the response\n   * unwrapper and the raw MCP probe so the storyboard runner can surface it\n   * in its output contract. Consumers outside the runner should treat this\n   * as implementation detail — it's NOT part of the public `AdCPResponse`.\n   */\n  _extraction_path?: 'structured_content' | 'text_fallback' | 'error' | 'none';\n}\n\n// Logger interface for library use\nexport interface Logger {\n  info: (context: object, message: string) => void;\n  error: (context: object, message: string) => void;\n  warn: (context: object, message: string) => void;\n  debug: (context: object, message: string) => void;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/lib/types/comply-test-controller.d.ts

@@ -4706,12 +4706,6 @@ export interface CanonicalFormatNativeInFeed {
     buyer_asset_acceptance?: 'accepted' | 'rejected';
 }
 
-/**
- * Product carries one or more inline ProductFormatDeclarations, each narrowing a canonical format. This is the 3.1+ format-option path introduced by RFC #3305. A single-element `format_options` array is the 90% case; multi-element arrays declare that the product accepts any of the listed format options.
- */
-export interface CanonicalFormatProduct {
-}
-
 /**
  * Buyer supplies a pool of typed assets (multiple headlines, descriptions, images, videos, logos); the surface algorithmically composes combinations per placement. **Composition is algorithmic** — surface picks combinations and reports per-asset performance breakdowns. Covers Google Responsive Display Ads (RDA), Responsive Search Ads (RSA), Performance Max (PMax), Demand Gen, and Meta Advantage+ creative. Industry term: "Responsive" (Google) / "Advantage+ creative" (Meta) / "Dynamic Creative" (older Meta term). Distinct from `sponsored_placement` (catalog-driven, deterministic) and `agent_placement` (AI-surface composition). The structured `slots` field below enumerates expected canonical asset_group_id slots; per-slot count/length narrowing lives in flat parameters (`headlines_min`, `headline_max_chars`, etc.).
  */
@@ -7887,13 +7881,6 @@ export interface MultiSize {
     }[];
 }
 
-/**
- * @deprecated
- * Deprecated 3.x compatibility branch. Product references one or more named formats by structured format_id ({ agent_url, id }). New 3.2 products use format_options.
- */
-export interface NamedFormatProduct {
-}
-
 export interface NativeInFeedFormatDeclaration {
     format_kind: 'native_in_feed';
     params: CanonicalFormatNativeInFeed;
@@ -8672,7 +8659,7 @@ export type PricingOption = CPMPricingOption | VCPMPricingOption | CPCPricingOpt
 /**
  * Represents available advertising inventory
  */
-export type Product = {} & (NamedFormatProduct | CanonicalFormatProduct) & {
+export type Product = {
     /**
      * Opaque identifier for this buyable product. For a non-custom wholesale product, sellers MUST reuse the ID for the same logical catalog offer within the seller and declared cache_scope across reads and wholesale-feed webhooks; feed and pricing versions communicate temporal catalog mutation, while retirement or replacement may end the identity. Concurrent or request-bound configurations whose effective targeting, disclosed targeting modifications, forecast assumptions, terms, or overlay support differ MUST use distinguishable configured product IDs. For is_custom: true, the ID identifies only the request-specific discovery/refinement lineage and is not stable across independent contexts. Sellers MUST keep every issued configured ID resolvable for its promised lifetime. Pricing variants within one logical product are distinguished by pricing_option_id: a seller MUST mint a new pricing_option_id whenever a binding fixed price, floor, currency, model, or priced applicability changes, and MUST NOT reinterpret an issued option ID at a new price. Selecting product_id plus pricing_option_id in create_media_buy accepts that returned configuration and commercial option.
      */

package/dist/lib/types/core.generated.d.mts

@@ -12637,7 +12637,7 @@ export type BusinessEntity1 = BusinessEntity;
 /**
  * Represents available advertising inventory
  */
-export type Product = (NamedFormatProduct | CanonicalFormatProduct) & {
+export type Product = {
     /**
      * Opaque identifier for this buyable product. For a non-custom wholesale product, sellers MUST reuse the ID for the same logical catalog offer within the seller and declared cache_scope across reads and wholesale-feed webhooks; feed and pricing versions communicate temporal catalog mutation, while retirement or replacement may end the identity. Concurrent or request-bound configurations whose effective targeting, disclosed targeting modifications, forecast assumptions, terms, or overlay support differ MUST use distinguishable configured product IDs. For is_custom: true, the ID identifies only the request-specific discovery/refinement lineage and is not stable across independent contexts. Sellers MUST keep every issued configured ID resolvable for its promised lifetime. Pricing variants within one logical product are distinguished by pricing_option_id: a seller MUST mint a new pricing_option_id whenever a binding fixed price, floor, currency, model, or priced applicability changes, and MUST NOT reinterpret an issued option ID at a new price. Selecting product_id plus pricing_option_id in create_media_buy accepts that returned configuration and commercial option.
      */

package/dist/lib/types/core.generated.d.ts

@@ -12637,7 +12637,7 @@ export type BusinessEntity1 = BusinessEntity;
 /**
  * Represents available advertising inventory
  */
-export type Product = (NamedFormatProduct | CanonicalFormatProduct) & {
+export type Product = {
     /**
      * Opaque identifier for this buyable product. For a non-custom wholesale product, sellers MUST reuse the ID for the same logical catalog offer within the seller and declared cache_scope across reads and wholesale-feed webhooks; feed and pricing versions communicate temporal catalog mutation, while retirement or replacement may end the identity. Concurrent or request-bound configurations whose effective targeting, disclosed targeting modifications, forecast assumptions, terms, or overlay support differ MUST use distinguishable configured product IDs. For is_custom: true, the ID identifies only the request-specific discovery/refinement lineage and is not stable across independent contexts. Sellers MUST keep every issued configured ID resolvable for its promised lifetime. Pricing variants within one logical product are distinguished by pricing_option_id: a seller MUST mint a new pricing_option_id whenever a binding fixed price, floor, currency, model, or priced applicability changes, and MUST NOT reinterpret an issued option ID at a new price. Selecting product_id plus pricing_option_id in create_media_buy accepts that returned configuration and commercial option.
      */