@adcp/client 4.20.0 → 4.22.0

package/storyboards/error_compliance.yaml

@@ -0,0 +1,231 @@
+id: error_compliance
+version: "1.0.0"
+title: "Error handling and compliance"
+category: media_buy_seller
+track: error_handling
+summary: "Validates that agents return properly structured AdCP errors with correct codes, recovery hints, and transport bindings."
+
+required_tools:
+  - get_products
+
+narrative: |
+  Every AdCP agent must handle invalid input gracefully. When a buyer sends a negative budget,
+  a nonexistent product ID, or a malformed request, the agent should return a structured error
+  response — not a stack trace or a generic 500.
+
+  AdCP defines three compliance levels for error responses:
+  - L1: isError flag set on the MCP response
+  - L2: JSON text fallback with adcp_error object in content
+  - L3: structuredContent.adcp_error binding (full compliance)
+
+  This storyboard sends intentionally bad input and validates that the agent rejects it with
+  the correct error code, recovery classification, and transport binding. Agents that use the
+  adcpError() helper from @adcp/client get L3 compliance automatically.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+  examples:
+    - "Any AdCP seller agent"
+
+caller:
+  role: buyer_agent
+  example: "Compliance test harness"
+
+phases:
+  - id: error_responses
+    title: "Error responses for invalid input"
+    narrative: |
+      The buyer sends requests with intentionally invalid data — negative budgets, missing
+      required fields, nonexistent product IDs. Each request should be rejected with a
+      structured error containing an appropriate AdCP error code.
+
+    steps:
+      - id: negative_budget
+        title: "Reject negative budget"
+        narrative: |
+          A negative budget is never valid. The agent must reject this with INVALID_REQUEST
+          or BUDGET_TOO_LOW and a correctable recovery hint so the buyer knows to fix the value.
+        task: create_media_buy
+        requires_tool: create_media_buy
+        expect_error: true
+        stateful: false
+        expected: |
+          Reject the request with an error containing:
+          - code: INVALID_REQUEST or BUDGET_TOO_LOW
+          - recovery: correctable
+          - field: packages[0].budget (optional but recommended)
+        sample_request:
+          idempotency_key: "error-test-negative-budget"
+          start_time: "2026-05-01T00:00:00Z"
+          end_time: "2026-05-31T23:59:59Z"
+          packages:
+            - product_id: "test-product"
+              budget: -500
+              pricing_option_id: "test-pricing"
+        validations:
+          - check: error_code
+            value: "INVALID_REQUEST"
+            description: "Error code is INVALID_REQUEST or BUDGET_TOO_LOW"
+
+      - id: nonexistent_product
+        title: "Reject nonexistent product ID"
+        narrative: |
+          The buyer references a product ID that does not exist on this platform.
+          The agent should return PRODUCT_NOT_FOUND or INVALID_REQUEST.
+        task: create_media_buy
+        requires_tool: create_media_buy
+        expect_error: true
+        stateful: false
+        expected: |
+          Reject the request with an error containing:
+          - code: PRODUCT_NOT_FOUND or INVALID_REQUEST
+          - recovery: correctable
+        sample_request:
+          idempotency_key: "error-test-nonexistent-product"
+          start_time: "2026-05-01T00:00:00Z"
+          end_time: "2026-05-31T23:59:59Z"
+          packages:
+            - product_id: "NONEXISTENT_PRODUCT_ID_12345"
+              budget: 1000
+              pricing_option_id: "nonexistent-pricing"
+        validations:
+          - check: error_code
+            value: "PRODUCT_NOT_FOUND"
+            description: "Error code is PRODUCT_NOT_FOUND or INVALID_REQUEST"
+
+      - id: missing_fields
+        title: "Handle empty get_products request"
+        narrative: |
+          The buyer sends an empty get_products request with no brief or brand.
+          The agent may accept it (permissive) or reject it (strict validation).
+          Both behaviors are acceptable — what matters is that the response is structured.
+        task: get_products
+        requires_tool: get_products
+        stateful: false
+        expected: |
+          Either:
+          - Return products (permissive mode)
+          - Return a structured error with INVALID_REQUEST (strict mode)
+          Both are acceptable. An unstructured error or crash is not.
+        sample_request: {}
+        validations:
+          - check: response_schema
+            description: "Response is a valid get-products-response or structured error"
+
+      - id: reversed_dates
+        title: "Reject end time before start time"
+        narrative: |
+          The buyer sends a create_media_buy with end_time before start_time.
+          The agent must reject this temporal inconsistency.
+        task: create_media_buy
+        requires_tool: create_media_buy
+        expect_error: true
+        stateful: false
+        expected: |
+          Reject the request with an error containing:
+          - code: INVALID_REQUEST
+          - recovery: correctable
+          - field: end_time (optional but recommended)
+        sample_request:
+          idempotency_key: "error-test-reversed-dates"
+          start_time: "2026-05-31T23:59:59Z"
+          end_time: "2026-05-01T00:00:00Z"
+          packages:
+            - product_id: "test-product"
+              budget: 1000
+              pricing_option_id: "test-pricing"
+        validations:
+          - check: error_code
+            value: "INVALID_REQUEST"
+            description: "Error code is INVALID_REQUEST for reversed date range"
+
+  - id: error_structure
+    title: "Error JSON structure validation"
+    narrative: |
+      Beyond returning the right error code, the error object itself must conform to the
+      AdCP error schema. Required fields: code (non-empty string), message (string).
+      Optional fields: recovery (transient|correctable|terminal), retry_after (non-negative
+      number), field (string), suggestion (string). Non-standard codes must use the X_ prefix.
+
+    steps:
+      - id: validate_error_shape
+        title: "Validate error JSON structure"
+        narrative: |
+          Provoke an error and inspect the JSON structure. The error object must have a
+          code and message at minimum. If recovery, retry_after, field, or suggestion are
+          present, they must have the correct types. Non-standard codes must use X_ prefix.
+        task: create_media_buy
+        requires_tool: create_media_buy
+        expect_error: true
+        stateful: false
+        expected: |
+          Error object with valid structure:
+          - code: non-empty string (standard AdCP code or X_-prefixed vendor code)
+          - message: string
+          - recovery: transient, correctable, or terminal (if present)
+          - retry_after: non-negative number (if present)
+          - field: string path to the offending field (if present)
+          - suggestion: string with remediation hint (if present)
+        sample_request:
+          idempotency_key: "error-test-structure"
+          start_time: "2026-05-01T00:00:00Z"
+          end_time: "2026-05-31T23:59:59Z"
+          packages:
+            - product_id: "NONEXISTENT_PRODUCT_ID_12345"
+              budget: 1000
+              pricing_option_id: "nonexistent-pricing"
+        validations:
+          - check: field_present
+            path: "adcp_error.code"
+            description: "Error has a code field"
+          - check: field_present
+            path: "adcp_error.message"
+            description: "Error has a message field"
+
+  - id: error_transport
+    title: "Error transport binding validation"
+    narrative: |
+      AdCP errors must be delivered through the correct MCP transport layers. The isError
+      flag signals the error to the MCP client, the JSON text content provides a fallback
+      for clients that do not support structuredContent, and structuredContent.adcp_error
+      provides the full typed error object.
+
+      Agents using the adcpError() helper from @adcp/client get all three layers automatically.
+
+    steps:
+      - id: validate_transport_binding
+        title: "Validate structuredContent.adcp_error binding"
+        narrative: |
+          Provoke an error and check that it appears in the correct transport layers:
+          - isError: true on the MCP response
+          - JSON text content with adcp_error (L2 fallback)
+          - structuredContent.adcp_error (L3 full compliance)
+
+          L2 is the minimum passing level. L3 is expected for agents using adcpError().
+        task: create_media_buy
+        requires_tool: create_media_buy
+        expect_error: true
+        stateful: false
+        expected: |
+          MCP response with:
+          - isError: true
+          - content[].text contains JSON with adcp_error (L2)
+          - structuredContent.adcp_error present (L3)
+          - Error code in structuredContent matches error code in text content (consistency)
+        sample_request:
+          idempotency_key: "error-test-transport"
+          start_time: "2026-05-01T00:00:00Z"
+          end_time: "2026-05-31T23:59:59Z"
+          packages:
+            - product_id: "NONEXISTENT_PRODUCT_ID_12345"
+              budget: 1000
+              pricing_option_id: "nonexistent-pricing"
+        validations:
+          - check: field_present
+            path: "adcp_error"
+            description: "structuredContent contains adcp_error object"
+          - check: error_code
+            value: "PRODUCT_NOT_FOUND"
+            description: "Error code is a valid AdCP standard code or X_-prefixed vendor code"

package/storyboards/governance_content_standards.yaml

@@ -0,0 +1,213 @@
+id: governance_content_standards
+version: "1.0.0"
+title: "Governance content standards"
+category: governance_content_standards
+summary: "Content standards discovery, calibration, and delivery validation."
+track: governance
+required_tools:
+  - list_content_standards
+
+narrative: |
+  You operate a governance agent that manages content standards — brand safety
+  configurations that define what content is acceptable for a brand's ads.
+  Buyer agents discover available standards, retrieve their details, calibrate
+  content against them, and validate delivery records for compliance.
+
+  This storyboard covers two concerns: discovering and inspecting content
+  standards, and the active calibration/validation workflow where the governance
+  agent evaluates content artifacts against those standards.
+
+agent:
+  interaction_model: governance
+  capabilities:
+    - manages_content_standards
+    - brand_safety
+    - content_calibration
+  examples:
+    - "Brand safety verification platforms"
+    - "Content classification services"
+    - "Publisher quality assurance tools"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity and content artifacts (URLs) for
+    calibration and validation testing. The governance agent must have at
+    least one content standards configuration available.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: content_standards_discovery
+    title: "Content standards discovery"
+    narrative: |
+      The buyer discovers what content standards configurations are available
+      from the governance agent, then retrieves the details of a specific
+      standard. This is the read-only exploration phase before any calibration
+      or validation occurs.
+
+    steps:
+      - id: list_content_standards
+        title: "List available content standards"
+        narrative: |
+          The buyer asks the governance agent for all available content
+          standards configurations. These represent brand safety rule sets
+          that content can be evaluated against — GARM floor categories,
+          custom brand policies, or industry-specific compliance rules.
+        task: list_content_standards
+        stateful: false
+        expected: |
+          Return available content standards with:
+          - standards: array of content standards summaries
+          - Each standard has standards_id, name, and optionally provider
+        sample_request:
+          context: "Discover available brand safety configurations"
+          max_results: 10
+        validations:
+          - check: response_schema
+            description: "Response matches list-content-standards response schema"
+          - check: field_present
+            path: "standards"
+            description: "Response contains a standards array"
+        context_outputs:
+          - path: "standards[0].standards_id"
+            key: "standards_id"
+
+      - id: get_content_standards
+        title: "Get content standards detail"
+        requires_tool: get_content_standards
+        narrative: |
+          The buyer retrieves full details of a specific content standards
+          configuration discovered in the previous step. The response includes
+          the complete rule set — categories, thresholds, and feature
+          definitions that the governance agent uses to evaluate content.
+        task: get_content_standards
+        stateful: true
+        expected: |
+          Return the content standards configuration with:
+          - standards_id: matches the requested ID
+          - name: human-readable label
+          - features: array of evaluation criteria
+        sample_request:
+          standards_id: "$context.standards_id"
+        context_inputs:
+          - key: "standards_id"
+            inject_at: "standards_id"
+        validations:
+          - check: response_schema
+            description: "Response matches get-content-standards response schema"
+          - check: field_present
+            path: "standards_id"
+            description: "Response contains the standards ID"
+
+      - id: get_invalid_content_standards
+        title: "Get invalid content standards (error expected)"
+        requires_tool: get_content_standards
+        narrative: |
+          The buyer requests a content standards configuration that does not
+          exist. The governance agent should reject the request with an error,
+          rather than returning empty or fabricated data.
+        task: get_content_standards
+        stateful: false
+        expect_error: true
+        expected: |
+          Return an error indicating the standards ID does not exist.
+        sample_request:
+          standards_id: "INVALID_STANDARDS_ID_DOES_NOT_EXIST_12345"
+        validations:
+          - check: error_code
+            value: "not_found"
+            description: "Agent rejects an invalid standards_id"
+
+  - id: content_calibration
+    title: "Content calibration and delivery validation"
+    requires_tool: calibrate_content
+    narrative: |
+      With a content standards configuration identified, the buyer submits
+      content artifacts for calibration — asking the governance agent to
+      evaluate whether specific pages or content items meet the brand safety
+      requirements. After calibration, the buyer validates delivery records
+      to confirm that ads were served alongside compliant content.
+
+    steps:
+      - id: calibrate_content
+        title: "Calibrate content against standards"
+        narrative: |
+          The buyer submits content artifacts (web pages, articles) for
+          evaluation against a specific content standards configuration.
+          The governance agent classifies each artifact and returns
+          calibration results — pass/fail per artifact, with scores or
+          category assignments.
+        task: calibrate_content
+        stateful: true
+        expected: |
+          Return calibration results with:
+          - session_id: identifier for this calibration session
+          - session_status: completed or in_progress
+          - Per-artifact evaluation results (pending or evaluated)
+        sample_request:
+          context: "Evaluate sample content for brand safety"
+          standards_id: "$context.standards_id"
+          artifacts:
+            - artifact_id: "test-artifact-1"
+              artifact_type: "webpage"
+              url: "https://example.com/article/safe-content"
+              title: "Safe Test Article"
+            - artifact_id: "test-artifact-2"
+              artifact_type: "webpage"
+              url: "https://example.com/article/test-content"
+              title: "Another Test Article"
+          feedback_type: "binary"
+        context_inputs:
+          - key: "standards_id"
+            inject_at: "standards_id"
+        validations:
+          - check: response_schema
+            description: "Response matches calibrate-content response schema"
+          - check: field_present
+            path: "session_id"
+            description: "Response contains a calibration session ID"
+        context_outputs:
+          - path: "session_id"
+            key: "calibration_session_id"
+
+      - id: validate_content_delivery
+        title: "Validate content delivery records"
+        requires_tool: validate_content_delivery
+        narrative: |
+          The buyer submits delivery records — evidence that ads were served
+          alongside specific content — for compliance validation. The
+          governance agent checks each record against the content standards
+          and returns pass/fail results with a summary.
+        task: validate_content_delivery
+        stateful: true
+        expected: |
+          Return validation results with:
+          - summary.total_records: number of records validated
+          - summary.passed_records: number that met standards
+          - summary.failed_records: number that did not meet standards
+          - Per-record validation details
+        sample_request:
+          context: "Validate delivery records against content standards"
+          standards_id: "$context.standards_id"
+          records:
+            - record_id: "test-record-1"
+              artifact:
+                artifact_id: "test-artifact-1"
+                artifact_type: "webpage"
+                url: "https://example.com/article/delivered-content"
+              delivered_at: "2026-04-01T12:00:00Z"
+        context_inputs:
+          - key: "standards_id"
+            inject_at: "standards_id"
+        validations:
+          - check: response_schema
+            description: "Response matches validate-content-delivery response schema"
+          - check: field_present
+            path: "summary"
+            description: "Response contains a validation summary"
+          - check: field_present
+            path: "summary.total_records"
+            description: "Summary includes total record count"