From 69827f3a6ecc46fe91fc52cce1d4d827322280ad Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Tue, 17 Nov 2026 21:04:49 -0500 Subject: [PATCH 1/2] fix(training-agent): enforce execute_only, governance_context error codes and plan regions in check_governance The reference governance agent did not enforce three rules the campaign governance specification states as governance-agent obligations (#9075): - An execute_only delegate may act only on a pre-approved action. An intent check from such a delegate that would open a new action or increase committed spend now gets a critical delegation_authority finding, so it is denied in every governance mode. - A governance_context the agent did not issue, or one presented with a plan_id for another plan, is now PERMISSION_DENIED instead of VALIDATION_ERROR, checked before plan resolution and whether or not plan_id is present or exists. - Plan regions are now evaluated. At intent, no geography, country-level geography only, or a region outside the plan returns conditions naming the region constraint; at execution, a purchase or modification that does not deliver inside the plan's regions is denied. Closes #9075 Co-Authored-By: Claude Opus 5.5 --- .../src/training-agent/governance-handlers.ts | 216 ++++++++++++++++- ...nt-governance-context-verification.test.ts | 105 +++++++++ ...nt-governance-delegation-authority.test.ts | 219 ++++++++++++++++++ .../training-agent-governance-regions.test.ts | 186 +++++++++++++++ server/tests/unit/training-agent.test.ts | 4 +- 5 files changed, 724 insertions(+), 6 deletions(-) create mode 100644 server/tests/unit/training-agent-governance-context-verification.test.ts create mode 100644 server/tests/unit/training-agent-governance-delegation-authority.test.ts create mode 100644 server/tests/unit/training-agent-governance-regions.test.ts diff --git a/server/src/training-agent/governance-handlers.ts b/server/src/training-agent/governance-handlers.ts index 2b087a6cb0..a780e2c596 100644 --- a/server/src/training-agent/governance-handlers.ts +++ b/server/src/training-agent/governance-handlers.ts @@ -256,6 +256,48 @@ function sessionBuyCommitments(session: SessionState, plan: GovernancePlanState) ); } +/** + * The pre-approved action an intent check acts on, for an `execute_only` + * delegate (specification.mdx "Delegation"; enums/delegation-authority.json). + * A pre-approved action is one whose opaque action binding already holds an + * approved intent check in this plan's lifecycle. The intent check names it + * either through the media buy that binding governs (`payload.media_buy_id`, + * or the `media_buy_id` of an update or cancellation proposal), or, for + * `accept_proposal`, through a proposal an approved intent check already + * authorized. + */ +function findPreApprovedAction( + session: SessionState, + plan: GovernancePlanState, + mediaBuyId: string | undefined, + proposalId: string | undefined, +): { intent: GovernanceCheckState; via: 'media_buy' | 'proposal' } | undefined { + const onPlan = (entry: { planId: string; planOwnerAgentUrl?: string }) => + entry.planId === plan.planId && entry.planOwnerAgentUrl === plan.ownerAgentUrl; + const checks = [...session.governanceChecks.values()].filter(onPlan); + const isApprovedIntent = (check: GovernanceCheckState) => + check.binding === 'proposed' && check.status === 'approved' && check.governanceBindingId !== undefined; + if (mediaBuyId) { + const buyKey = mediaBuyId.slice(0, 255); + const bindingIds = new Set(); + for (const check of checks) { + if (check.mediaBuyId?.slice(0, 255) === buyKey && check.governanceBindingId) bindingIds.add(check.governanceBindingId); + } + for (const outcome of session.governanceOutcomes.values()) { + if (onPlan(outcome) && outcome.mediaBuyId === buyKey && outcome.governanceBindingId) { + bindingIds.add(outcome.governanceBindingId); + } + } + const intent = checks.find(check => isApprovedIntent(check) && bindingIds.has(check.governanceBindingId!)); + if (intent) return { intent, via: 'media_buy' }; + } + if (proposalId) { + const intent = checks.find(check => isApprovedIntent(check) && check.authorizedProposalId === proposalId); + if (intent) return { intent, via: 'proposal' }; + } + return undefined; +} + /** * Evaluate one action against the plan's budget periods and translate the * result into critical findings. The action's flight is resolved even when the @@ -512,6 +554,8 @@ interface GovernanceCanonicalProposal { proposal_status: string; commercial_terms: Record; terms_digest: string; + /** The existing buy an update or cancellation proposal changes. */ + media_buy_id?: unknown; } interface CheckPayload { @@ -522,13 +566,16 @@ interface CheckPayload { budget?: number; channels?: string[]; canceled?: boolean; + targeting_overlay?: { geo_regions?: unknown }; }>; new_packages?: Array<{ budget?: number }>; budget?: number | { total?: number }; total_budget?: number | { amount?: number }; - geo?: { countries?: string[] }; - targeting?: { countries?: string[] }; + geo?: { countries?: string[]; regions?: unknown }; + targeting?: { countries?: string[]; geo_regions?: unknown }; + targeting_overlay?: { geo_regions?: unknown }; countries?: string[]; + regions?: unknown; channels?: string[]; channel?: string; start_time?: string; @@ -630,7 +677,7 @@ interface PlannedDeliveryInput { media_buy_id?: string; proposal_id?: string; proposal_terms_digest?: string; - geo?: { countries?: string[] }; + geo?: { countries?: string[]; regions?: unknown }; channels?: string[]; start_time?: string; end_time?: string; @@ -1446,11 +1493,21 @@ export async function handleCheckGovernance(args: ToolArgs, ctx: TrainingContext : sellerCredentialPlanScopeError(ctx, planId); if (credentialError) return credentialError; } + // A presented governance_context, and its match with plan_id, is verified + // before plan access is resolved. A context this agent did not issue, or + // one issued for another plan, is a credential failure: PERMISSION_DENIED + // whether or not plan_id names a plan (specification.mdx "Governance-agent + // obligations"; error-code.json PERMISSION_DENIED). An intent-shaped request + // that carries a context is malformed instead, and is rejected below. + const intentShapedRequest = req.tool !== undefined && req.payload !== undefined; + if (governanceContext && !priorCheck && !intentShapedRequest) { + return { errors: [{ code: 'PERMISSION_DENIED', message: 'governance_context was not issued by this governance agent or is no longer known.' }] }; + } if (!planId) { return { errors: [{ code: 'PLAN_NOT_FOUND', message: 'No plan could be resolved from plan_id or governance_context.' }] }; } if (req.plan_id && priorCheck && req.plan_id !== priorCheck.planId) { - return { errors: [{ code: 'VALIDATION_ERROR', message: 'plan_id does not match the governance_context binding.' }] }; + return { errors: [{ code: 'PERMISSION_DENIED', message: 'governance_context was issued for a different plan than plan_id.' }] }; } if (req.plan_id && priorConsultationCheck && req.plan_id !== priorConsultationCheck.planId) { return { errors: [{ code: 'VALIDATION_ERROR', message: 'plan_id does not match the consultation_context.' }] }; @@ -1721,7 +1778,7 @@ export async function handleCheckGovernance(args: ToolArgs, ctx: TrainingContext if (binding === 'committed' && !priorCheck) { return { - errors: [{ code: 'VALIDATION_ERROR', message: 'governance_context is unknown or expired.' }], + errors: [{ code: 'PERMISSION_DENIED', message: 'governance_context was not issued by this governance agent or is no longer known.' }], }; } @@ -2170,6 +2227,44 @@ export async function handleCheckGovernance(args: ToolArgs, ctx: TrainingContext } } + // Delegation authority level. An execute_only delegate acts only on a + // pre-approved action, which includes accept_proposal for it; an intent + // check that would open a new action or increase committed spend is + // denied. The finding is a delegations failure, so it is denied in every + // governance mode (adcp#8733 A4, C2). + if (callerDelegation?.authority === 'execute_only') { + const proposalMediaBuyId = req.proposal?.proposal_kind !== 'new_media_buy' + ? req.proposal?.media_buy_id + : undefined; + const targetMediaBuyId = typeof policyPayload.media_buy_id === 'string' + ? policyPayload.media_buy_id + : typeof proposalMediaBuyId === 'string' + ? proposalMediaBuyId + : undefined; + const preApproved = findPreApprovedAction(session, plan, targetMediaBuyId, req.proposal?.proposal_id); + if (!preApproved) { + findings.push({ + categoryId: 'delegation_authority', + severity: 'critical', + explanation: `Delegated agent ${caller} has execute_only authority and may act only on a pre-approved action; this ${tool} intent would open a new governed action.`, + }); + } else { + // Acting on a pre-approved media buy, any positive commitment is new + // spend on top of it. Re-authorizing a pre-approved proposal may carry + // what that proposal's approved intent already authorized, no more. + const preApprovedCommitment = preApproved.via === 'proposal' ? preApproved.intent.authorizedBudget ?? 0 : 0; + if (payloadBudget !== undefined && payloadBudget > preApprovedCommitment) { + findings.push({ + categoryId: 'delegation_authority', + severity: 'critical', + explanation: preApproved.via === 'proposal' + ? `Delegated agent ${caller} has execute_only authority and cannot increase committed spend: this ${tool} intent commits $${payloadBudget}, more than the $${preApprovedCommitment} the pre-approved proposal authorized.` + : `Delegated agent ${caller} has execute_only authority and cannot increase committed spend: this ${tool} intent adds $${payloadBudget} to pre-approved media buy ${targetMediaBuyId}.`, + }); + } + } + } + // Budget compliance categoriesEvaluated.push('budget_authority'); if (payloadBudget !== undefined) { @@ -2258,6 +2353,37 @@ export async function handleCheckGovernance(args: ToolArgs, ctx: TrainingContext } } + // A regions-restricted plan admits only actions that target its regions. + // No geography, or country-level geography only, targets the whole country + // and is outside the plan, as is a region the plan does not list. At intent + // that is a counterproposal naming the region constraint. A modification + // that states no regions keeps the buy's existing geography, so only the + // regions it states are compared. + if (plan.regions?.length) { + const planRegions = plan.regions; + const planRegionSet = new Set(planRegions); + const isModification = typeof policyPayload.media_buy_id === 'string' + || (req.proposal !== undefined && req.proposal.proposal_kind !== 'new_media_buy'); + const regionScopes = req.proposal + ? extractProposalRegionScopes(req.proposal) + : extractRegionScopes(policyPayload); + for (const scope of regionScopes) { + const outside = scope.regions.filter(region => !planRegionSet.has(region)); + const countryWide = scope.regions.length === 0; + if (countryWide ? isModification : outside.length === 0) continue; + const inPlan = scope.regions.filter(region => planRegionSet.has(region)); + const reason = countryWide + ? `Plan is restricted to regions ${planRegions.join(', ')}; an action without region-level targeting targets the whole country.` + : `Regions ${outside.join(', ')} are outside the plan's regions ${planRegions.join(', ')}.`; + findings.push({ categoryId: 'geo_compliance', severity: 'warning', explanation: reason }); + conditions.push({ + field: scope.field, + requiredValue: inPlan.length > 0 ? inPlan : [...planRegions], + reason, + }); + } + } + // Channel compliance categoriesEvaluated.push('channel_compliance'); if (payloadChannels.length > 0 && plan.channels?.allowed?.length) { @@ -2401,6 +2527,29 @@ export async function handleCheckGovernance(args: ToolArgs, ctx: TrainingContext } } + // On a regions-restricted plan, a purchase or modification must state + // region-level delivery inside the plan's regions: none, or country-level + // only, delivers country-wide and is denied. A delivery check reports on a + // commitment already authorized, so only the regions it states are compared. + if (plan.regions?.length) { + const planRegionSet = new Set(plan.regions); + const pdRegions = stringList(plannedDelivery.geo?.regions) ?? []; + const outside = pdRegions.filter(region => !planRegionSet.has(region)); + if (pdRegions.length === 0 && phase !== 'delivery') { + findings.push({ + categoryId: 'geo_compliance', + severity: 'critical', + explanation: `Planned delivery states no region-level geography, so it delivers country-wide; the plan is restricted to regions ${plan.regions.join(', ')}.`, + }); + } else if (outside.length > 0) { + findings.push({ + categoryId: 'geo_compliance', + severity: 'critical', + explanation: `Planned delivery includes regions outside the plan: ${outside.join(', ')}. Plan allows: ${plan.regions.join(', ')}.`, + }); + } + } + const pdChannels = plannedDelivery.channels || []; if (pdChannels.length > 0 && plan.channels?.allowed?.length) { const allowedSet = new Set(plan.channels.allowed); @@ -4291,6 +4440,63 @@ function extractFromPayload(payload: CheckPayload): ExtractedFields { }; } +/** One place an action states its region-level geography. */ +interface RegionScope { + /** Request path a `conditions` entry names, rooted at the check_governance arguments. */ + field: string; + /** ISO 3166-2 codes stated there. Empty means country-level or no geography. */ + regions: string[]; +} + +function stringList(value: unknown): string[] | undefined { + return Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : undefined; +} + +/** + * The region-level geography of an intent payload. Top-level geography covers + * the whole action; otherwise each live package is its own scope, because a + * package without `targeting_overlay.geo_regions` delivers country-wide. + */ +function extractRegionScopes(payload: CheckPayload): RegionScope[] { + const topLevel: Array<[string, unknown]> = [ + ['payload.geo.regions', payload.geo?.regions], + ['payload.targeting.geo_regions', payload.targeting?.geo_regions], + ['payload.targeting_overlay.geo_regions', payload.targeting_overlay?.geo_regions], + ['payload.regions', payload.regions], + ]; + for (const [field, value] of topLevel) { + const regions = stringList(value); + if (regions) return [{ field, regions }]; + } + const packages = (payload.packages ?? []) + .map((pkg, index) => ({ pkg, index })) + .filter(({ pkg }) => pkg && !pkg.canceled); + if (packages.length > 0) { + return packages.map(({ pkg, index }) => ({ + field: `payload.packages.${index}.targeting_overlay.geo_regions`, + regions: stringList(pkg.targeting_overlay?.geo_regions) ?? [], + })); + } + return [{ field: 'payload.geo.regions', regions: [] }]; +} + +/** The region-level geography of each purchase in a proposal being accepted. */ +function extractProposalRegionScopes(proposal: GovernanceCanonicalProposal): RegionScope[] { + const purchases = Array.isArray(proposal.commercial_terms.purchases) ? proposal.commercial_terms.purchases : []; + const scopes = purchases.flatMap((purchase, index) => { + if (!purchase || typeof purchase !== 'object' || Array.isArray(purchase)) return []; + const targeting = (purchase as Record).targeting_overlay; + const geoRegions = targeting && typeof targeting === 'object' && !Array.isArray(targeting) + ? (targeting as Record).geo_regions + : undefined; + return [{ + field: `proposal.commercial_terms.purchases.${index}.targeting_overlay.geo_regions`, + regions: stringList(geoRegions) ?? [], + }]; + }); + return scopes.length > 0 ? scopes : [{ field: 'proposal.commercial_terms.purchases', regions: [] }]; +} + function extractBudget(payload: CheckPayload): { amount: number; fieldPath: string } | undefined { // Try total_budget.amount first, then total_budget as bare number if (payload.total_budget !== undefined) { diff --git a/server/tests/unit/training-agent-governance-context-verification.test.ts b/server/tests/unit/training-agent-governance-context-verification.test.ts new file mode 100644 index 0000000000..d17752b17c --- /dev/null +++ b/server/tests/unit/training-agent-governance-context-verification.test.ts @@ -0,0 +1,105 @@ +/** + * A presented `governance_context`, and its match with `plan_id`, is verified + * before plan access is resolved (adcp#9075, specification.mdx + * "Governance-agent obligations"; error-code.json PERMISSION_DENIED). A + * context this agent did not issue, or one issued for another plan, is + * PERMISSION_DENIED whether or not plan_id exists. + */ +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import '../../src/training-agent/task-handlers.js'; +import { handleCheckGovernance, handleSyncPlans } from '../../src/training-agent/governance-handlers.js'; +import { clearSessions, runWithSessionContext } from '../../src/training-agent/state.js'; +import type { TrainingContext } from '../../src/training-agent/types.js'; + +const OWNER = 'https://owner.example'; +const SELLER = 'https://seller.example'; +const OWNER_CTX: TrainingContext = { mode: 'open', authenticatedAgentUrl: OWNER }; +const SELLER_CTX: TrainingContext = { mode: 'open', authenticatedAgentUrl: SELLER }; +const PLAN = { + plan_id: 'plan-context-a', + brand: { domain: 'context-verification.example' }, + objectives: 'Verify governance_context before plan access.', + budget: { total: 100_000, currency: 'USD', reallocation_threshold: 100_000 }, + flight: { start: '2027-01-01T00:00:00Z', end: '2027-12-31T23:59:59Z' }, +}; +const OTHER_PLAN = { ...PLAN, plan_id: 'plan-context-b' }; +// Opaque to the caller; any string this agent never issued. +const FABRICATED_CONTEXT = 'gc_fabricated_never_issued_by_this_agent'; + +type Result = Record; + +async function approvedIntentContext(): Promise { + const synced = await handleSyncPlans({ plans: [PLAN, OTHER_PLAN] }, OWNER_CTX) as Result; + expect(synced.errors).toBeUndefined(); + const intent = await handleCheckGovernance({ + plan_id: PLAN.plan_id, + caller: OWNER, + target_agent: SELLER, + tool: 'create_media_buy', + payload: { total_budget: { amount: 10_000, currency: 'USD' } }, + }, OWNER_CTX) as Result; + expect(intent.verdict, JSON.stringify(intent)).toBe('approved'); + return intent.governance_context; +} + +function executionCheck(governanceContext: string, planId?: string): Promise { + return handleCheckGovernance({ + ...(planId !== undefined && { plan_id: planId }), + caller: SELLER, + governance_context: governanceContext, + phase: 'purchase', + planned_delivery: { media_buy_id: 'mb_context', total_budget: 10_000, currency: 'USD' }, + }, SELLER_CTX) as Promise; +} + +describe('check_governance governance_context verification', () => { + beforeEach(() => clearSessions()); + afterEach(() => clearSessions()); + + it.each([ + ['an existing plan_id', PLAN.plan_id], + ['a plan_id that does not exist', 'plan-does-not-exist'], + ['no plan_id', undefined], + ])('returns PERMISSION_DENIED for a context it did not issue, with %s', async (_label, planId) => { + await runWithSessionContext(async () => { + await approvedIntentContext(); + const result = await executionCheck(FABRICATED_CONTEXT, planId); + expect(result.errors?.[0]?.code, JSON.stringify(result)).toBe('PERMISSION_DENIED'); + expect(result.verdict).toBeUndefined(); + }); + }); + + it.each([ + ['another existing plan', OTHER_PLAN.plan_id], + ['a plan_id that does not exist', 'plan-does-not-exist'], + ])('returns PERMISSION_DENIED for a context issued for a different plan than %s', async (_label, planId) => { + await runWithSessionContext(async () => { + const context = await approvedIntentContext(); + const result = await executionCheck(context, planId); + expect(result.errors?.[0]?.code, JSON.stringify(result)).toBe('PERMISSION_DENIED'); + }); + }); + + it('still accepts the context with its own plan_id', async () => { + await runWithSessionContext(async () => { + const context = await approvedIntentContext(); + const result = await executionCheck(context, PLAN.plan_id); + expect(result.verdict, JSON.stringify(result)).toBe('approved'); + }); + }); + + it('keeps an intent check that carries a context a malformed request', async () => { + await runWithSessionContext(async () => { + await approvedIntentContext(); + const result = await handleCheckGovernance({ + plan_id: PLAN.plan_id, + caller: OWNER, + target_agent: SELLER, + tool: 'create_media_buy', + payload: { total_budget: { amount: 10_000, currency: 'USD' } }, + governance_context: FABRICATED_CONTEXT, + }, OWNER_CTX) as Result; + expect(result.errors?.[0]?.code, JSON.stringify(result)).toBe('VALIDATION_ERROR'); + }); + }); +}); diff --git a/server/tests/unit/training-agent-governance-delegation-authority.test.ts b/server/tests/unit/training-agent-governance-delegation-authority.test.ts new file mode 100644 index 0000000000..4896c6ede3 --- /dev/null +++ b/server/tests/unit/training-agent-governance-delegation-authority.test.ts @@ -0,0 +1,219 @@ +/** + * `delegations[].authority: "execute_only"` (adcp#9075, specification.mdx + * "Delegation"; enums/delegation-authority.json). An execute_only delegate acts + * only on a pre-approved action, one whose action binding already holds an + * approved intent check, which includes accept_proposal for it. An intent + * check from such a delegate that would open a new action or increase + * committed spend is denied with a finding, in every governance mode. + */ +import { createHash } from 'node:crypto'; +import { canonicalize } from '@adcp/sdk'; +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import '../../src/training-agent/task-handlers.js'; +import { handleCheckGovernance, handleSyncPlans } from '../../src/training-agent/governance-handlers.js'; +import { clearSessions, runWithSessionContext } from '../../src/training-agent/state.js'; +import type { TrainingContext } from '../../src/training-agent/types.js'; + +const OWNER = 'https://owner.example'; +const DELEGATE = 'https://agency.example'; +const SELLER = 'https://seller.example'; +const OWNER_CTX: TrainingContext = { mode: 'open', authenticatedAgentUrl: OWNER }; +const DELEGATE_CTX: TrainingContext = { mode: 'open', authenticatedAgentUrl: DELEGATE }; +const SELLER_CTX: TrainingContext = { mode: 'open', authenticatedAgentUrl: SELLER }; +const PLAN = { + plan_id: 'plan-execute-only', + brand: { domain: 'execute-only.example' }, + objectives: 'An agency executes what the brand already approved.', + budget: { total: 100_000, currency: 'USD', reallocation_threshold: 100_000 }, + flight: { start: '2027-01-01T00:00:00Z', end: '2027-12-31T23:59:59Z' }, + countries: ['US'], +}; + +type Result = Record; + +async function sync(authority = 'execute_only', mode = 'enforce') { + const result = await handleSyncPlans({ + plans: [{ + ...PLAN, + mode, + delegations: [{ agent_url: DELEGATE, authority, budget_limit: { amount: 25_000, currency: 'USD' } }], + }], + }, OWNER_CTX) as Result; + expect(result.errors).toBeUndefined(); +} + +function createIntent(caller: string, ctx: TrainingContext, amount: number): Promise { + return handleCheckGovernance({ + plan_id: PLAN.plan_id, + caller, + target_agent: SELLER, + tool: 'create_media_buy', + payload: { total_budget: { amount, currency: 'USD' }, geo: { countries: ['US'] } }, + }, ctx) as Promise; +} + +/** The brand opens and the seller commits a buy: a pre-approved action. */ +async function ownerBuy(mediaBuyId: string) { + const intent = await createIntent(OWNER, OWNER_CTX, 10_000); + expect(intent.verdict, JSON.stringify(intent)).toBe('approved'); + const purchase = await handleCheckGovernance({ + caller: SELLER, + governance_context: intent.governance_context, + phase: 'purchase', + planned_delivery: { media_buy_id: mediaBuyId, total_budget: 10_000, currency: 'USD' }, + }, SELLER_CTX) as Result; + expect(purchase.verdict, JSON.stringify(purchase)).toBe('approved'); +} + +function updateIntent(mediaBuyId: string, amount: number): Promise { + return handleCheckGovernance({ + plan_id: PLAN.plan_id, + caller: DELEGATE, + target_agent: SELLER, + tool: 'update_media_buy', + payload: { media_buy_id: mediaBuyId, end_time: '2027-06-30T23:59:59Z' }, + proposed_commitment: { amount, currency: 'USD' }, + }, DELEGATE_CTX) as Promise; +} + +function proposal( + proposalId: string, + kind: 'new_media_buy' | 'media_buy_update', + extra: Record = {}, +): Record { + const commercialTerms = { + purchases: [{ + product_id: 'display_q2', + budget: 20_000, + start_time: '2027-04-01T00:00:00Z', + end_time: '2027-06-30T23:59:59Z', + targeting_overlay: { geo_countries: ['US'] }, + }], + start_time: '2027-04-01T00:00:00Z', + end_time: '2027-06-30T23:59:59Z', + total_budget: { amount: 20_000, currency: 'USD' }, + }; + return { + proposal_id: proposalId, + proposal_kind: kind, + proposal_status: 'committed', + commercial_terms: commercialTerms, + terms_digest: `sha256:${createHash('sha256').update(canonicalize(commercialTerms), 'utf8').digest('base64url')}`, + ...extra, + }; +} + +function acceptIntent( + caller: string, + ctx: TrainingContext, + accepted: Record, + amount: number, +): Promise { + return handleCheckGovernance({ + plan_id: PLAN.plan_id, + caller, + target_agent: SELLER, + tool: 'accept_proposal', + payload: { proposal_id: accepted.proposal_id, proposal_terms_digest: accepted.terms_digest }, + proposal: accepted, + proposed_commitment: { amount, currency: 'USD' }, + }, ctx) as Promise; +} + +function expectExecuteOnlyDenial(result: Result, explanation: string) { + expect(result.errors, JSON.stringify(result)).toBeUndefined(); + expect(result.verdict).toBe('denied'); + expect(result.governance_context).toBeUndefined(); + expect(result.findings).toContainEqual(expect.objectContaining({ + category_id: 'delegation_authority', + severity: 'critical', + explanation: expect.stringContaining(explanation), + })); +} + +describe('check_governance execute_only delegation authority', () => { + beforeEach(() => clearSessions()); + afterEach(() => clearSessions()); + + it.each(['enforce', 'advisory', 'audit'])('denies a new action from an execute_only delegate in %s mode', async mode => { + await runWithSessionContext(async () => { + await sync('execute_only', mode); + expectExecuteOnlyDenial( + await createIntent(DELEGATE, DELEGATE_CTX, 20_000), + 'would open a new governed action', + ); + }); + }); + + it('lets a full delegate open the same action', async () => { + await runWithSessionContext(async () => { + await sync('full'); + const result = await createIntent(DELEGATE, DELEGATE_CTX, 20_000); + expect(result.verdict, JSON.stringify(result)).toBe('approved'); + expect(result.governance_context).toBeDefined(); + }); + }); + + it('lets an execute_only delegate act on a pre-approved buy without new spend', async () => { + await runWithSessionContext(async () => { + await sync(); + await ownerBuy('mb_pre_approved'); + const result = await updateIntent('mb_pre_approved', 0); + expect(result.verdict, JSON.stringify(result)).toBe('approved'); + expect(result.governance_context).toBeDefined(); + }); + }); + + it('denies an execute_only delegate that increases committed spend on a pre-approved buy', async () => { + await runWithSessionContext(async () => { + await sync(); + await ownerBuy('mb_pre_approved'); + expectExecuteOnlyDenial(await updateIntent('mb_pre_approved', 5_000), 'cannot increase committed spend'); + }); + }); + + it('denies an execute_only delegate acting on a buy no approved intent governs', async () => { + await runWithSessionContext(async () => { + await sync(); + await ownerBuy('mb_pre_approved'); + expectExecuteOnlyDenial(await updateIntent('mb_never_approved', 0), 'would open a new governed action'); + }); + }); + + it('lets an execute_only delegate accept a proposal whose acceptance the brand approved', async () => { + await runWithSessionContext(async () => { + await sync(); + const approvedProposal = proposal('proposal_pre_approved', 'new_media_buy'); + const ownerAccept = await acceptIntent(OWNER, OWNER_CTX, approvedProposal, 20_000); + expect(ownerAccept.verdict, JSON.stringify(ownerAccept)).toBe('approved'); + + const delegateAccept = await acceptIntent(DELEGATE, DELEGATE_CTX, approvedProposal, 20_000); + expect(delegateAccept.verdict, JSON.stringify(delegateAccept)).toBe('approved'); + + expectExecuteOnlyDenial( + await acceptIntent(DELEGATE, DELEGATE_CTX, proposal('proposal_never_approved', 'new_media_buy'), 20_000), + 'would open a new governed action', + ); + }); + }); + + it('lets an execute_only delegate accept a no-cost update proposal for a pre-approved buy', async () => { + await runWithSessionContext(async () => { + await sync(); + await ownerBuy('mb_pre_approved'); + const update = proposal('proposal_update', 'media_buy_update', { + media_buy_id: 'mb_pre_approved', + parent_proposal_id: 'proposal_parent', + base_media_buy_revision: 1, + }); + + const noCost = await acceptIntent(DELEGATE, DELEGATE_CTX, update, 0); + expect(noCost.verdict, JSON.stringify(noCost)).toBe('approved'); + + expectExecuteOnlyDenial( + await acceptIntent(DELEGATE, DELEGATE_CTX, update, 5_000), + 'cannot increase committed spend', + ); + }); + }); +}); diff --git a/server/tests/unit/training-agent-governance-regions.test.ts b/server/tests/unit/training-agent-governance-regions.test.ts new file mode 100644 index 0000000000..c041b1a25d --- /dev/null +++ b/server/tests/unit/training-agent-governance-regions.test.ts @@ -0,0 +1,186 @@ +/** + * Plan `regions` as geo enforcement (adcp#9075, specification.mdx "Policy + * resolution"). An action with no geography, or with country-level geography + * only, targets the whole country and is outside a regions-restricted plan, as + * is a region the plan does not list: an intent check returns `conditions` + * naming the region constraint, and an execution check returns `denied`. + */ +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import '../../src/training-agent/task-handlers.js'; +import { handleCheckGovernance, handleSyncPlans } from '../../src/training-agent/governance-handlers.js'; +import { clearSessions, runWithSessionContext } from '../../src/training-agent/state.js'; +import type { TrainingContext } from '../../src/training-agent/types.js'; + +const OWNER = 'https://owner.example'; +const SELLER = 'https://seller.example'; +const OWNER_CTX: TrainingContext = { mode: 'open', authenticatedAgentUrl: OWNER }; +const SELLER_CTX: TrainingContext = { mode: 'open', authenticatedAgentUrl: SELLER }; +const PLAN = { + plan_id: 'plan-regions', + brand: { domain: 'regions.example' }, + objectives: 'A campaign limited to Massachusetts.', + budget: { total: 100_000, currency: 'USD', reallocation_threshold: 100_000 }, + flight: { start: '2027-01-01T00:00:00Z', end: '2027-12-31T23:59:59Z' }, + countries: ['US'], + regions: ['US-MA'], +}; + +type Result = Record; + +async function sync(extra: Record = {}) { + const result = await handleSyncPlans({ plans: [{ ...PLAN, ...extra }] }, OWNER_CTX) as Result; + expect(result.errors).toBeUndefined(); +} + +function intent(payload: Record, extra: Record = {}): Promise { + return handleCheckGovernance({ + plan_id: PLAN.plan_id, + caller: OWNER, + target_agent: SELLER, + tool: 'create_media_buy', + payload: payload.packages ? payload : { total_budget: { amount: 10_000, currency: 'USD' }, ...payload }, + ...extra, + }, OWNER_CTX) as Promise; +} + +function purchase(governanceContext: string, geo?: Record): Promise { + return handleCheckGovernance({ + caller: SELLER, + governance_context: governanceContext, + phase: 'purchase', + planned_delivery: { + media_buy_id: 'mb_regions', + total_budget: 10_000, + currency: 'USD', + ...(geo && { geo }), + }, + }, SELLER_CTX) as Promise; +} + +function expectRegionConditions(result: Result, field: string, reason: string) { + expect(result.errors, JSON.stringify(result)).toBeUndefined(); + expect(result.verdict).toBe('conditions'); + expect(result.governance_context).toBeUndefined(); + expect(result.conditions).toEqual([ + expect.objectContaining({ field, reason: expect.stringContaining(reason) }), + ]); + expect(result.findings).toContainEqual(expect.objectContaining({ category_id: 'geo_compliance' })); +} + +describe('check_governance plan regions', () => { + beforeEach(() => clearSessions()); + afterEach(() => clearSessions()); + + it('returns conditions for an intent with no geography', async () => { + await runWithSessionContext(async () => { + await sync(); + const result = await intent({}); + expectRegionConditions(result, 'payload.geo.regions', 'targets the whole country'); + expect(result.conditions[0].required_value).toEqual(['US-MA']); + }); + }); + + it('returns conditions for an intent with country-level geography only', async () => { + await runWithSessionContext(async () => { + await sync(); + expectRegionConditions( + await intent({ geo: { countries: ['US'] } }), + 'payload.geo.regions', + 'targets the whole country', + ); + }); + }); + + it('returns conditions for an intent that names a region outside the plan', async () => { + await runWithSessionContext(async () => { + await sync(); + expectRegionConditions( + await intent({ geo: { countries: ['US'], regions: ['US-NY'] } }), + 'payload.geo.regions', + 'US-NY', + ); + }); + }); + + it('approves an intent that targets only the plan regions', async () => { + await runWithSessionContext(async () => { + await sync(); + const result = await intent({ geo: { countries: ['US'], regions: ['US-MA'] } }); + expect(result.verdict, JSON.stringify(result)).toBe('approved'); + }); + }); + + it('conditions only the package that delivers country-wide', async () => { + await runWithSessionContext(async () => { + await sync(); + const result = await intent({ + packages: [ + { budget: 5_000, targeting_overlay: { geo_countries: ['US'], geo_regions: ['US-MA'] } }, + { budget: 5_000, targeting_overlay: { geo_countries: ['US'] } }, + ], + }); + expectRegionConditions(result, 'payload.packages.1.targeting_overlay.geo_regions', 'targets the whole country'); + }); + }); + + it('does not require regions on a modification that leaves geography unchanged', async () => { + await runWithSessionContext(async () => { + await sync(); + const result = await handleCheckGovernance({ + plan_id: PLAN.plan_id, + caller: OWNER, + target_agent: SELLER, + tool: 'update_media_buy', + payload: { media_buy_id: 'mb_regions', end_time: '2027-06-30T23:59:59Z' }, + proposed_commitment: { amount: 0, currency: 'USD' }, + }, OWNER_CTX) as Result; + expect(result.verdict, JSON.stringify(result)).toBe('approved'); + }); + }); + + it('leaves a plan without regions at country-level enforcement', async () => { + await runWithSessionContext(async () => { + await sync({ regions: undefined }); + const result = await intent({ geo: { countries: ['US'] } }); + expect(result.verdict, JSON.stringify(result)).toBe('approved'); + }); + }); + + it('denies an execution check whose planned delivery is country-level only', async () => { + await runWithSessionContext(async () => { + await sync(); + const approved = await intent({ geo: { countries: ['US'], regions: ['US-MA'] } }); + expect(approved.verdict, JSON.stringify(approved)).toBe('approved'); + const result = await purchase(approved.governance_context, { countries: ['US'] }); + expect(result.verdict, JSON.stringify(result)).toBe('denied'); + expect(result.findings).toContainEqual(expect.objectContaining({ + category_id: 'geo_compliance', + severity: 'critical', + explanation: expect.stringContaining('country-wide'), + })); + }); + }); + + it('denies an execution check whose planned delivery names a region outside the plan', async () => { + await runWithSessionContext(async () => { + await sync(); + const approved = await intent({ geo: { countries: ['US'], regions: ['US-MA'] } }); + const result = await purchase(approved.governance_context, { countries: ['US'], regions: ['US-MA', 'US-NY'] }); + expect(result.verdict, JSON.stringify(result)).toBe('denied'); + expect(result.findings).toContainEqual(expect.objectContaining({ + category_id: 'geo_compliance', + severity: 'critical', + explanation: expect.stringContaining('US-NY'), + })); + }); + }); + + it('approves an execution check that delivers inside the plan regions', async () => { + await runWithSessionContext(async () => { + await sync(); + const approved = await intent({ geo: { countries: ['US'], regions: ['US-MA'] } }); + const result = await purchase(approved.governance_context, { countries: ['US'], regions: ['US-MA'] }); + expect(result.verdict, JSON.stringify(result)).toBe('approved'); + }); + }); +}); diff --git a/server/tests/unit/training-agent.test.ts b/server/tests/unit/training-agent.test.ts index f7c15c0680..11abbcce31 100644 --- a/server/tests/unit/training-agent.test.ts +++ b/server/tests/unit/training-agent.test.ts @@ -18990,9 +18990,11 @@ describe('check_governance delegation enforcement', () => { budget: { total: 100000, currency: 'USD', reallocation_threshold: 1000000 }, flight: { start: '2027-01-01T00:00:00Z', end: '2027-12-31T23:59:59Z' }, countries: ['US', 'GB', 'DE'], + // These cases open new actions, which an execute_only delegate cannot do; + // training-agent-governance-delegation-authority.test.ts covers that level. delegations: [{ agent_url: 'https://delegated.example', - authority: 'execute_only', + authority: 'full', budget_limit: { amount: 25000, currency: 'USD' }, markets: ['US', 'GB'], }], From b6f3991ba231643111ea88214f688218520aa850 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Tue, 17 Nov 2026 21:49:16 -0500 Subject: [PATCH 2/2] fix(training-agent): keep a geography-unchanged modification inside a regions plan at execution A modification that states no regions keeps the buy's existing geography. The intent check already allowed it; the execution check now does too, and compares only the regions it states, as a delivery check does. Only a purchase must state region-level delivery. Co-Authored-By: Claude Opus 5.5 --- .../src/training-agent/governance-handlers.ts | 12 +++--- .../training-agent-governance-regions.test.ts | 40 +++++++++++++++++++ 2 files changed, 47 insertions(+), 5 deletions(-) diff --git a/server/src/training-agent/governance-handlers.ts b/server/src/training-agent/governance-handlers.ts index a780e2c596..53515bf719 100644 --- a/server/src/training-agent/governance-handlers.ts +++ b/server/src/training-agent/governance-handlers.ts @@ -2527,15 +2527,17 @@ export async function handleCheckGovernance(args: ToolArgs, ctx: TrainingContext } } - // On a regions-restricted plan, a purchase or modification must state - // region-level delivery inside the plan's regions: none, or country-level - // only, delivers country-wide and is denied. A delivery check reports on a - // commitment already authorized, so only the regions it states are compared. + // On a regions-restricted plan, a purchase must state region-level + // delivery inside the plan's regions: none, or country-level only, delivers + // country-wide and is denied. A modification that states no regions keeps + // the buy's existing geography, as at intent, and a delivery check reports + // on a commitment already authorized, so for both only the regions stated + // are compared. if (plan.regions?.length) { const planRegionSet = new Set(plan.regions); const pdRegions = stringList(plannedDelivery.geo?.regions) ?? []; const outside = pdRegions.filter(region => !planRegionSet.has(region)); - if (pdRegions.length === 0 && phase !== 'delivery') { + if (pdRegions.length === 0 && phase === 'purchase') { findings.push({ categoryId: 'geo_compliance', severity: 'critical', diff --git a/server/tests/unit/training-agent-governance-regions.test.ts b/server/tests/unit/training-agent-governance-regions.test.ts index c041b1a25d..9f15f9a7e3 100644 --- a/server/tests/unit/training-agent-governance-regions.test.ts +++ b/server/tests/unit/training-agent-governance-regions.test.ts @@ -175,6 +175,46 @@ describe('check_governance plan regions', () => { }); }); + it('approves a modification execution check that leaves geography unchanged, but not one that names an outside region', async () => { + await runWithSessionContext(async () => { + await sync(); + const update = () => handleCheckGovernance({ + plan_id: PLAN.plan_id, + caller: OWNER, + target_agent: SELLER, + tool: 'update_media_buy', + payload: { media_buy_id: 'mb_regions', end_time: '2027-06-30T23:59:59Z' }, + proposed_commitment: { amount: 0, currency: 'USD' }, + }, OWNER_CTX) as Promise; + const modification = (governanceContext: string, geo?: Record) => handleCheckGovernance({ + caller: SELLER, + governance_context: governanceContext, + phase: 'modification', + execution_commitment: { amount: 0, currency: 'USD' }, + planned_delivery: { + media_buy_id: 'mb_regions', + end_time: '2027-06-30T23:59:59Z', + currency: 'USD', + ...(geo && { geo }), + }, + }, SELLER_CTX) as Promise; + + const unchanged = await update(); + expect(unchanged.verdict, JSON.stringify(unchanged)).toBe('approved'); + const unchangedExecution = await modification(unchanged.governance_context); + expect(unchangedExecution.verdict, JSON.stringify(unchangedExecution)).toBe('approved'); + + const widened = await update(); + const widenedExecution = await modification(widened.governance_context, { regions: ['US-NY'] }); + expect(widenedExecution.verdict, JSON.stringify(widenedExecution)).toBe('denied'); + expect(widenedExecution.findings).toContainEqual(expect.objectContaining({ + category_id: 'geo_compliance', + severity: 'critical', + explanation: expect.stringContaining('US-NY'), + })); + }); + }); + it('approves an execution check that delivers inside the plan regions', async () => { await runWithSessionContext(async () => { await sync();