Skip to content

Training agent: enforce execute_only delegations, governance_context error codes and plan regions in check_governance #9075

Closed

Description

@lukasz-pubx

Summary

The reference agent (server/src/training-agent) does not enforce three campaign-governance rules that the specification states as obligations on the governance agent. Two of them were named in the review of #9006 (comment, review comment). The third is the same kind of gap and was found in the same sweep.

  1. An execute_only delegate can open a new action. The agent stores delegations[].authority and never reads it.
  2. An execution check with an unknown governance_context, or one issued for another plan, returns VALIDATION_ERROR. The specification says PERMISSION_DENIED.
  3. A plan's regions are stored and never evaluated, so a regions-restricted plan approves country-wide actions.

None of these needs a specification change. Implementers compare their governance agents against this one, so each gap gives them a wrong baseline.

Current state

All paths are at b8b5097, the head of #9006, because that PR adds two of the sentences quoted here. Line numbers will move when it merges. Re-verify them at implementation time.

1. execute_only is not enforced

The rule. docs/governance/campaign/specification.mdx:340:

A pre-approved action is one whose opaque action binding already holds an approved intent check in this plan's lifecycle: an execute_only delegate MAY act only on such an action, which includes accept_proposal for it. The governance agent MUST deny an intent check from an execute_only delegate that would create a new binding or increase committed spend.

static/schemas/source/enums/delegation-authority.json:14 says the same in the enum description.

The agent. In server/src/training-agent/governance-handlers.ts:

  • :827 accepts authority on the tool schema, and :1353 stores it on the plan.
  • :2095-2165, the delegation evaluation, reads agentUrl, expiresAt, budgetLimit and markets. It does not read authority. No other code under server/src/training-agent reads it.

A test pins the wrong behaviour. server/tests/unit/training-agent.test.ts:18991 defines a plan whose only delegation is authority: 'execute_only'. The test at :19010, "approves delegation within budget limit", sends a fresh intent from that delegate and expects approved with a governance_context.

2. governance_context failures return the wrong error code

The rule. docs/governance/campaign/specification.mdx:215:

The governance agent verifies a presented governance_context, and its match with plan_id, before it resolves plan access. A context that fails verification or was issued for another plan is PERMISSION_DENIED, whether or not plan_id exists.

static/schemas/source/enums/error-code.json:217 defines PERMISSION_DENIED to include a governance_context token that "is missing, fails verification, or was issued for a different plan, seller, or phase".

The agent. In handleCheckGovernance, governance-handlers.ts:

  • :1453: a plan_id that differs from the plan the context was issued for returns VALIDATION_ERROR, "plan_id does not match the governance_context binding."
  • :1724: an execution check whose context matches no stored check returns VALIDATION_ERROR, "governance_context is unknown or expired."
  • :1737: an expired context returns PERMISSION_DENIED. This case is already right.

The order is already right. Both checks run before the PLAN_NOT_FOUND return at :1929. Only the code is wrong.

The agent is inconsistent with itself. The seller-side tools return PERMISSION_DENIED for a fabricated context. training-agent.test.ts:24276 asserts it for create_media_buy, and :17234 for activate_signal.

3. Plan regions are not evaluated

The rule. docs/governance/campaign/specification.mdx:487:

The plan's countries and regions fields also serve as geo enforcement: the governance agent MUST reject governed actions targeting markets outside the plan's allowed geography. A plan with regions: ["US-MA"] rejects actions not explicitly targeting Massachusetts, even if they are otherwise compliant. An action with no geographic targeting, or with country-level targeting only, is treated as targeting the whole country and is outside a regions-restricted plan: an intent check returns conditions naming the region constraint, and an execution check returns denied.

The first two sentences are on main today. #9006 adds the third.

The agent. In governance-handlers.ts:

  • :797 accepts regions, and :1350 stores it. Nothing reads it afterwards.
  • extractFromPayload returns countries, channels, flight and the budget. It does not extract a region, although static/schemas/source/core/targeting.json:34 defines geo_regions.
  • plan.countries is enforced with a geo_compliance finding at :2249 for intent checks and at :2392 for execution checks. plan.regions has no equivalent.

Problem

1. A restricted delegate commits new spend. A brand delegates an agency with authority: "execute_only" and a budget_limit of 25,000. The brand's intent is that the agency carries out actions the brand already approved. The agency sends a fresh create_media_buy intent for 20,000. The agent returns approved and issues a governance_context. The seller's execution check passes and the buy is committed. The specification says the governance agent MUST deny that intent check.

2. A credential failure looks like a malformed request. A seller runs an execution check with a context that the governance agent did not issue, or with a valid context and the wrong plan_id. The agent answers VALIDATION_ERROR. A client that branches on the code treats this as a request to correct and resend. The same agent answers PERMISSION_DENIED when the same fabricated context reaches create_media_buy.

3. A state-restricted plan approves a national buy. A plan has countries: ["US"] and regions: ["US-MA"]. The buyer sends an intent that targets the whole United States. The country check passes, the region is never compared, and the agent returns approved. The specification says conditions at intent and denied at execution.

Proposed change

All changes are in server/src/training-agent/governance-handlers.ts and its tests.

  1. execute_only. In the delegation evaluation, when the caller's delegation has authority: "execute_only", add a critical delegation_authority finding to an intent check that would create a new action binding or increase committed spend. An intent check on a binding that already holds an approved intent check stays allowed, and so does accept_proposal for it. The finding is critical, so the verdict is denied in every governance mode, as for the budget_limit and markets failures.
  2. governance_context. Return PERMISSION_DENIED at the two sites above. Keep both checks ahead of plan resolution.
  3. regions. Extract geo_regions from the payload. When the plan has regions, an action with no geography, with country-level geography only, or with a region outside the plan's list gets a geo_compliance finding, the category the countries check uses. An intent check returns conditions that name the region constraint. An execution check returns denied.

Tests and fixtures affected

  • training-agent.test.ts:18991-19090: the delegation tests use an execute_only delegate for fresh intents. Either the fixture changes to authority: 'full', or the expectations change. New cases cover an execute_only delegate that opens a new binding (denied), that raises committed spend on an existing binding (denied), and that acts on a pre-approved binding (allowed).
  • New cases for an unknown context and for a context issued for another plan, both expecting PERMISSION_DENIED.
  • New cases for a regions-restricted plan: no geography, country only, a region outside the list, and a region inside it.
  • Storyboards: no file under static/compliance/source uses execute_only outside the plan_hash test vectors, and I found no storyboard that expects VALIDATION_ERROR for a bad context. The storyboard matrix should confirm that.

Compatibility

This changes what the public test agent returns. A caller that relied on any of the three behaviours sees a different answer:

  • A fresh intent from an execute_only delegate changes from approved to denied.
  • A bad governance_context on check_governance changes from VALIDATION_ERROR to PERMISSION_DENIED.
  • A country-wide action on a regions-restricted plan changes from approved to conditions or denied.

No schema, wire field or error code is added. Each new answer is the one the specification already requires.

Open questions

  1. propose_only. The table at specification.mdx:338 says such a delegate "cannot execute without explicit approval". No normative sentence says what the governance agent returns. The agent does not read this level either. This issue leaves it alone unless the maintainers want a rule stated first.
  2. "Increase committed spend". For an execute_only delegate, does an update_media_buy intent that lowers or keeps the commitment on a pre-approved binding stay allowed? The sentence denies only an increase, and the proposal above follows it.
  3. consultation_context. A plan_id that does not match a presented consultation_context returns VALIDATION_ERROR at :1456. The specification sentence covers only governance_context. Should the two contexts behave the same?
  4. A region outside the list, at intent. The specification gives conditions for an action with no geography or with country-level geography. It does not say whether an intent that names a different region, such as US-NY on a US-MA plan, is conditions or denied. The proposal above uses conditions for all three.

Not in this issue

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions