Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/optional-tool-skips-stop-failing-dependents.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
"adcontextprotocol": patch
---

In three storyboards, a skipped optional tool no longer causes the stateful steps after it to fail.

- `provenance_audit_observation` (1.1.0): both audit-observation reads declare `sync_creatives`, the tool whose state they read, and each runs in its own phase after the sync. Sellers without `sync_creatives` skip the sync and both reads instead of failing them, and their verifier discovery is still graded.
- `create_media_buy_async_lifecycle` (1.1.0): each optional `get_task_status` and `list_tasks` read runs in its own phase, after the submit or completion phase it depends on. The completed-task reads keep the `force_task_completion` gate. A missing read no longer blocks the other read or the controller completion.
- `governance_agent_binding_acceptance` (1.1.0): the optional `comply_test_controller` read and the recovery `sync_governance` each run in their own phase after account setup. Sellers without the controller still have their recovery graded.
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
id: media_buy_seller/create_media_buy_async_lifecycle
version: "1.0.0"
version: "1.1.0"
introduced_in: "3.2"
title: "Seller exposes create_media_buy tasks through read and list lifecycle tools"
category: media_buy_seller
Expand Down Expand Up @@ -35,7 +35,9 @@ narrative: |
get_task_status and list_tasks are optional AdCP task-reconciliation tools.
Their steps use requires_tool so a baseline media-buy seller that does not
advertise either surface is not failed for omitting it. When advertised,
each surface is graded.
each surface is graded. Each read runs in its own phase and depends only on
the phases that created or completed the task, so an absent surface never
blocks the other surface or the controller completion.

agent:
interaction_model: media_buy_seller
Expand All @@ -53,9 +55,10 @@ caller:
prerequisites:
description: |
Seller exposes comply_test_controller in sandbox mode and advertises
force_create_media_buy_arm. The terminal phase also requires the seller to
advertise force_task_completion. Task read/list steps run only when the
corresponding optional tools are advertised.
force_create_media_buy_arm. The completion phase and the completed-task
reads also require the seller to advertise force_task_completion. Task
read/list steps run only when the corresponding optional tools are
advertised.
test_kit: "test-kits/acme-outdoor.yaml"
controller_seeding: true

Expand Down Expand Up @@ -187,11 +190,16 @@ phases:
path: "packages"
description: "Packages are issued only on terminal completion"

- id: reconcile_submitted_task
title: "Read the submitted task consistently"
# A missing_tool skip cascades prerequisite_failed onto stateful peers in the
# same phase and onto phases that depend on it. Keeping each optional read
# as the only stateful step of a phase, with explicit depends_on, keeps an
# absent surface not applicable instead of failing the steps after it.
- id: poll_submitted_task
title: "Poll the submitted task"
depends_on: [submit_async_media_buy]
narrative: |
Optional task-reconciliation surfaces must resolve the task identity from
create_media_buy and agree that it is still submitted.
get_task_status, when advertised, must resolve the task identity from
create_media_buy and report that it is still submitted.

steps:
- id: get_submitted_media_buy_task
Expand Down Expand Up @@ -234,6 +242,14 @@ phases:
value: "submitted"
description: "Task remains submitted before controller completion"

- id: list_submitted_task
title: "Discover the submitted task"
depends_on: [submit_async_media_buy]
narrative: |
list_tasks, when advertised, must discover the same task and report
that it is still submitted.

steps:
- id: list_submitted_media_buy_task
title: "Discover the submitted task through list_tasks"
task: list_tasks
Expand Down Expand Up @@ -283,14 +299,15 @@ phases:
value: "submitted"
description: "List and read surfaces agree on submitted status"

- id: complete_and_reconcile_task
title: "Complete the task and observe its terminal result"
- id: complete_task
title: "Complete the submitted task"
depends_on: [submit_async_media_buy]
requires_capability:
path: compliance_testing.scenarios
contains: force_task_completion
narrative: |
Resolve the submitted task with a valid media-buy response, then verify
get_task_status and list_tasks converge on the same completed identity.
Resolve the submitted task with a valid media-buy response so the read
surfaces can observe its terminal result.

steps:
- id: complete_async_media_buy_task
Expand Down Expand Up @@ -342,6 +359,17 @@ phases:
value: "completed"
description: "Controller reports the terminal task state"

- id: poll_completed_task
title: "Poll the completed task with its result"
depends_on: [submit_async_media_buy, complete_task]
requires_capability:
path: compliance_testing.scenarios
contains: force_task_completion
narrative: |
get_task_status, when advertised, must return the completed task with
the controller-supplied media-buy result.

steps:
- id: get_completed_media_buy_task
title: "Poll the completed task with its result"
task: get_task_status
Expand Down Expand Up @@ -391,6 +419,17 @@ phases:
value: "create_media_buy_async_lifecycle--terminal_result"
description: "Controller-supplied terminal context round-trips unchanged"

- id: list_completed_task
title: "Discover the completed task"
depends_on: [submit_async_media_buy, complete_task]
requires_capability:
path: compliance_testing.scenarios
contains: force_task_completion
narrative: |
list_tasks, when advertised, must report that the task completed under
the same identity.

steps:
- id: list_completed_media_buy_task
title: "Discover the completed task through list_tasks"
task: list_tasks
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
id: media_buy_seller/governance_agent_binding_acceptance
version: "1.0.0"
version: "1.1.0"
introduced_in: "3.2"
title: "Seller rejects an unacceptable governance-agent binding"
category: media_buy_seller
Expand Down Expand Up @@ -132,6 +132,14 @@ phases:
path: "accounts[0].governance_agents"
description: "A failed response never represents the rejected endpoint as persisted"

# comply_test_controller is optional for this storyboard. A
# missing_test_controller skip cascades prerequisite_failed onto stateful
# peers in its phase, so the controller read and the recovery each run in
# their own phase that depends only on the account setup.
- id: verify_retained_binding
title: "Confirm the accepted binding survived the rejection"
depends_on: [create_account]
steps:
- id: verify_prior_binding_retained
title: "Read the binding after the rejected replacement"
task: comply_test_controller
Expand All @@ -157,6 +165,10 @@ phases:
value: "$context.governance_agent_url"
description: "The rejected replacement did not erase or replace the accepted binding"

- id: recover_accepted_binding
title: "Retry with the advertised endpoint"
depends_on: [create_account]
steps:
- id: resync_accepted_governance_agent
title: "Retry with the advertised endpoint"
task: sync_governance
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
id: media_buy_seller/provenance_audit_observation
version: "1.0.1"
version: "1.1.0"
title: "Seller accepts a provenance carve-out claim surfaced as an audit observation"
category: media_buy_seller
summary: "Buyer submits AI-assisted creatives with human_oversight directed/edited and disclosure.required false. Seller invokes an on-list verifier, records OVERSIGHT_DISCLOSURE_CARVEOUT_CLAIMED audit observations, and accepts the creatives rather than treating the observations as rejections."
Expand Down Expand Up @@ -34,6 +34,10 @@ narrative: |
observation; public seller responses do not have to expose the seller's
internal audit log.

The audit queries read state that sync_creatives creates, so they declare
sync_creatives. A seller without sync_creatives skips the sync and both
queries, and its verifier discovery is still graded.

agent:
interaction_model: stateful_push
capabilities:
Expand Down Expand Up @@ -309,10 +313,23 @@ phases:
match: equals
value: false

# Each audit read consumes the state the sync creates, so it declares
# sync_creatives (adcp-client#3524 honors that ahead of the cascade). Each
# also sits alone in its phase: a runner without that precedence applies the
# sole-stateful exemption to a missing_tool skip and then grades the next
# read on its own requires_tool, instead of cascading prerequisite_failed.
- id: observe_directed_audit
title: "Read the directed carve-out audit observation"
depends_on: [accept_carveout_claim]
narrative: |
The sandbox controller exposes the audit observation the seller recorded
while accepting the directed creative.

steps:
- id: query_directed_audit_observation
title: "Assert directed carve-out audit observation"
task: comply_test_controller
requires_tool: comply_test_controller
requires_tool: sync_creatives
schema_ref: "compliance/comply-test-controller-request.json"
response_schema_ref: "compliance/comply-test-controller-response.json"
doc_ref: "/building/implementation/comply-test-controller"
Expand Down Expand Up @@ -354,10 +371,18 @@ phases:
value: false
description: "Observation records the disclosure.required false claim"

- id: observe_edited_audit
title: "Read the edited carve-out audit observation"
depends_on: [accept_carveout_claim]
narrative: |
The sandbox controller exposes the audit observation the seller recorded
while accepting the edited creative.

steps:
- id: query_edited_audit_observation
title: "Assert edited carve-out audit observation"
task: comply_test_controller
requires_tool: comply_test_controller
requires_tool: sync_creatives
schema_ref: "compliance/comply-test-controller-request.json"
response_schema_ref: "compliance/comply-test-controller-response.json"
doc_ref: "/building/implementation/comply-test-controller"
Expand Down
29 changes: 20 additions & 9 deletions tests/provenance-tool-gates.test.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ const SCENARIOS = [
'provenance_audit_observation',
];

test('provenance scenarios gate every optional-tool step by that tool', () => {
test('provenance scenarios gate every optional-tool step by the tool it depends on', () => {
let creativeSteps = 0;
let controllerSteps = 0;

Expand All @@ -21,14 +21,25 @@ test('provenance scenarios gate every optional-tool step by that tool', () => {
`${scenarioName}.yaml`,
);
const scenario = YAML.parse(fs.readFileSync(scenarioPath, 'utf8'));
for (const step of scenario.phases.flatMap((phase) => phase.steps)) {
if (step.task === 'sync_creatives') {
creativeSteps++;
assert.equal(step.requires_tool, 'sync_creatives', `${scenario.id}/${step.id}`);
}
if (step.task === 'comply_test_controller') {
controllerSteps++;
assert.equal(step.requires_tool, 'comply_test_controller', `${scenario.id}/${step.id}`);
for (const phase of scenario.phases) {
for (const step of phase.steps) {
if (step.task === 'sync_creatives') {
creativeSteps++;
assert.equal(step.requires_tool, 'sync_creatives', `${scenario.id}/${step.id}`);
}
if (step.task === 'comply_test_controller') {
controllerSteps++;
// Audit reads consume the state sync_creatives creates, so they name
// that tool; the storyboard-level controller requirement covers the
// controller itself. A separate phase keeps a skipped sync from
// cascading onto them on runners that grade the cascade first.
assert.equal(step.requires_tool, 'sync_creatives', `${scenario.id}/${step.id}`);
assert.ok(scenario.requires.includes('controller'), scenario.id);
assert.ok(
!phase.steps.some(peer => peer.task === 'sync_creatives'),
`${scenario.id}/${step.id} shares a phase with the sync it depends on`
);
}
}
}
}
Expand Down
Loading
Loading