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
5 changes: 5 additions & 0 deletions .changeset/test-agent-3-3-preview-collections-docs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"adcontextprotocol": patch
---

Docs: the 3.3 beta program page lists the experimental collection surfaces the public test agent now serves at its `3.3-beta.3` preview: collection cards through `include_collections`, `list_collections` and the collection card webhooks, `get_brand_identity` collection links, and the `seed_collection` controller scenario that drives the webhooks.
9 changes: 7 additions & 2 deletions docs/reference/3-3-beta.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -92,9 +92,14 @@ At the preview pin, `/sales/mcp` serves the experimental 3.3 surfaces the traini
- account requests (`account.requests`): `request_account`, and `account_requests` on `list_accounts`;
- the caller's `authorization`, with `authorized_at` and `regranted_at`, and `revision` on each `list_accounts` account;
- principal-level reporting subscriptions (`media_buy.reporting_subscriptions`): the `reporting_subscriptions` section of `sync_principal` and `get_principal`, and `subscription_coverage` on `get_reporting_status`;
- the `reporting_subscription_probe` controller scenario, which revokes, reduces, and restores grants and advances a per-caller sandbox clock.
- the `reporting_subscription_probe` controller scenario, which revokes, reduces, and restores grants and advances a per-caller sandbox clock;
- collection cards (`media_buy.collection_cards`): `include_collections` on `get_products`, `list_products`, `request_proposals` and `refine_proposals`, with images, samples, links, talent `brand_ref` and follower counts on the CreatorLoop creator channels;
- the collection catalog (`media_buy.collection_catalog`): `list_collections`, and the `collection_card.*` and `collection_catalog.bulk_change` webhooks registered through `sync_accounts`;
- the `seed_collection` controller scenario, which changes the caller's cards (a sample, a removal, a follower sweep) so the card webhooks fire.

`tools/list` includes `request_account` only when the listing is pinned to the preview (`params._meta.adcp_version`, as `@adcp/sdk` sends it). Hold policy, `extend_hold`, and response collections are not served yet ([#8181](https://github.com/adcontextprotocol/adcp/issues/8181)).
At the same pin, `/brand/mcp` returns `collections` on `get_brand_identity` for the creators (`brand.collection_links`).

`tools/list` includes `request_account` and `list_collections` only when the listing is pinned to the preview (`params._meta.adcp_version`, as `@adcp/sdk` sends it). Hold policy and `extend_hold` are not served yet ([#8181](https://github.com/adcontextprotocol/adcp/issues/8181)).

With `@adcp/sdk`, use 17.0.0-beta.11 or later, which negotiates exactly `3.3-beta.3`. Earlier 17.0.0 betas bundle an older beta, so they settle on 3.2 with the test agent.

Expand Down
42 changes: 41 additions & 1 deletion server/src/training-agent/account-handlers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ import {
proveAccountWebhookControl,
} from './webhook-challenge.js';
import { emitAccountNotificationWebhook } from './webhooks.js';
import { isCollectionCardEventType, supportsCollections33 } from './collections/card-catalog.js';
import { clearSharedAccountResources } from './shared-account-resources.js';
import { createLogger } from '../logger.js';
import {
Expand Down Expand Up @@ -921,6 +922,9 @@ async function normalizeNotificationConfigs(
existing: NotificationConfigState[];
dryRun: boolean;
proofDeadlineMs: number;
/** Collection card events (experimental, 3.3) are registrable only on
* the 3.3 wire, where the seller declares them. */
servedAdcpVersion?: string;
},
): Promise<NotificationConfigState[] | { error: Record<string, unknown> } | undefined> {
if (input.notification_configs === undefined) return undefined;
Expand Down Expand Up @@ -982,7 +986,8 @@ async function normalizeNotificationConfigs(
}
seenEventTypes.add(eventType);
}
const invalidIndex = config.event_types.findIndex(t => !ACCOUNT_ANCHORED_NOTIFICATION_TYPES.has(t));
const invalidIndex = config.event_types.findIndex(t => !ACCOUNT_ANCHORED_NOTIFICATION_TYPES.has(t)
&& !(isCollectionCardEventType(t) && supportsCollections33(options.servedAdcpVersion)));
if (invalidIndex !== -1) {
return {
error: validationFailure(
Expand Down Expand Up @@ -1126,6 +1131,39 @@ export function getAccountNotificationSubscribers(
return out;
}

/**
* Every active subscriber to `notificationType` on any account the principal
* holds, across its session partitions. For seller-wide changes the
* principal can see on every account, such as its collection cards.
*/
export function getPrincipalNotificationSubscribers(
principal: string | undefined,
notificationType: string,
): AccountNotificationSubscriber[] {
const prefix = `${principalScope(principal)}\u001F`;
const out: AccountNotificationSubscriber[] = [];
const seen = new Set<string>();
for (const [storeKey, accounts] of accountStore) {
if (!storeKey.startsWith(prefix)) continue;
for (const account of accounts.values()) {
for (const config of account.notificationConfigs) {
if (!config.active || !config.eventTypes.includes(notificationType)) continue;
const subscriberKey = `${account.accountId}\u001F${config.subscriberId}`;
if (seen.has(subscriberKey)) continue;
seen.add(subscriberKey);
out.push({
accountId: account.accountId,
subscriberId: config.subscriberId,
url: config.url,
eventTypes: [...config.eventTypes],
authentication: config.authentication,
});
}
}
}
return out;
}

/**
* Server-internal fan-out for account business changes. Unlike the
* request-principal helper above, this enumerates every independently proven
Expand Down Expand Up @@ -1862,6 +1900,7 @@ export async function handleSyncAccounts(args: ToolArgs, ctx: TrainingContext) {
existing: existing.notificationConfigs,
dryRun: req.dry_run === true,
proofDeadlineMs,
servedAdcpVersion: ctx.servedAdcpVersion,
});
if (notificationConfigs && 'error' in notificationConfigs) {
results.push(notificationConfigs.error);
Expand Down Expand Up @@ -2135,6 +2174,7 @@ export async function handleSyncAccounts(args: ToolArgs, ctx: TrainingContext) {
existing: existing?.notificationConfigs ?? [],
dryRun: req.dry_run === true,
proofDeadlineMs,
servedAdcpVersion: ctx.servedAdcpVersion,
});
if (notificationConfigs && 'error' in notificationConfigs) {
results.push(notificationConfigs.error);
Expand Down
15 changes: 13 additions & 2 deletions server/src/training-agent/brand-handlers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ import { resolveGovernanceAgentsForAccount } from './account-handlers.js';
import { getCanonicalBase, getTrainingGovernanceIssuer } from './canonical-base.js';
import { decodeOffsetCursor, encodeOffsetCursor } from './pagination.js';
import { sourceSchemaDocument } from './source-schema.js';
import { creatorBrandEntries, withCollectionLinks } from './collections/brand-links.js';

async function governedCommitmentRejection(
governanceContext: string,
Expand Down Expand Up @@ -626,6 +627,10 @@ const BRAND_MAP = new Map<string, AnyBrand>([
...ADVERTISER_BRANDS.map(b => [b.brand_id, b] as [string, AnyBrand]),
]);

const CREATOR_BRAND_MAP = new Map<string, AnyBrand>(
creatorBrandEntries().map(brand => [brand.brand_id, brand as AnyBrand]),
);

// Fields that are always returned (public, not selectable)
const PUBLIC_FIELDS = ['description', 'industries', 'keller_type', 'logos', 'tagline'] as const;
const AUTHORIZED_FIELDS = ['colors', 'fonts', 'visual_guidelines', 'tone', 'voice_synthesis', 'assets', 'rights'] as const;
Expand Down Expand Up @@ -936,7 +941,9 @@ export function handleGetBrandIdentity(
const fields = req.fields;
const authorized = req.authorized ?? false;

const talent = BRAND_MAP.get(brandId);
// Creator identities behind CreatorLoop collections resolve by id only;
// search_brands keeps its roster.
const talent = BRAND_MAP.get(brandId) ?? CREATOR_BRAND_MAP.get(brandId);
if (!talent) {
return { errors: [{ code: 'REFERENCE_NOT_FOUND', message: `No brand with id '${brandId}'`, field: 'brand_id' }] };
}
Expand Down Expand Up @@ -968,7 +975,11 @@ export function handleGetBrandIdentity(
response.available_fields = withheld;
}

return response;
// Experimental 3.3 brand.collection_links: the creator's channels. Only
// the /brand tenant declares the feature.
return ctx.tenantId === 'brand'
? withCollectionLinks(response, brandId, fields, ctx.servedAdcpVersion)
: response;
}

function computeMatchScore(
Expand Down
105 changes: 105 additions & 0 deletions server/src/training-agent/collections/brand-links.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
/**
* Creator identities on the /brand tenant and their collection links
* (experimental `brand.collection_links`, #8141).
*
* A CreatorLoop collection's `talent[].brand_ref` names the creator's brand
* identity under the CreatorLoop Talent house. `get_brand_identity` for that
* brand returns, on the 3.3 wire, `collections`: the creator's channels as
* `{publisher_domain, collection_id}` links. A `brand_ref` is confirmed only
* when the identity lists the same key back
* (get_brand_identity.mdx, "People behind collections"). The fixtures keep
* one creator unconfirmed: the collection claims the identity, and the
* identity lists a different channel.
*/

import { getAgentUrl } from '../config.js';
import { CREATOR_PUBLISHER } from '../creators.js';
import {
CREATOR_CARD_FIXTURES,
CREATOR_TALENT_HOUSE,
OFF_PLATFORM_COLLECTION_LINKS,
} from './card-fixtures.js';
import { supportsCollections33 } from './card-catalog.js';

export interface CreatorBrandEntry {
brand_id: string;
house: { domain: string; name: string };
names: Array<Record<string, string>>;
description: string;
industries: string[];
keller_type: string;
tagline: string;
logos: Array<{ url: string; variant?: string }>;
tone: { voice: string; attributes: string[]; dos: string[]; donts: string[] };
}

export interface CollectionLink {
publisher_domain: string;
collection_id: string;
name: string;
role?: string;
seller_agent_url?: string;
}

function showFor(showId: string) {
return CREATOR_PUBLISHER.shows?.find(show => show.showId === showId);
}

let entries: CreatorBrandEntry[] | undefined;

/** Brand identities for the creators whose collections carry a brand_ref. */
export function creatorBrandEntries(): CreatorBrandEntry[] {
entries ??= CREATOR_CARD_FIXTURES.filter(fixture => fixture.brandRef).map(fixture => {
const show = showFor(fixture.showId);
const name = show?.talent?.find(person => person.role === 'creator')?.name ?? fixture.slug;
return {
brand_id: fixture.slug,
house: { ...CREATOR_TALENT_HOUSE },
names: [{ en: name }],
description: fixture.bio,
industries: [],
keller_type: 'independent',
tagline: '',
// The person's picture: always public (get_brand_identity.mdx).
logos: [{ url: `https://picsum.photos/seed/creatorloop-${fixture.slug}-avatar/800/800`, variant: 'primary' }],
tone: { voice: '', attributes: [], dos: [], donts: [] },
};
});
return entries;
}

/** The channels a creator identity lists, or undefined for other brands. */
export function collectionLinksFor(brandId: string): CollectionLink[] | undefined {
const fixture = CREATOR_CARD_FIXTURES.find(candidate => candidate.slug === brandId && candidate.brandRef);
if (!fixture) return undefined;
if (!fixture.brandConfirms) {
const offPlatform = OFF_PLATFORM_COLLECTION_LINKS[brandId];
return offPlatform ? [{ ...offPlatform, role: 'creator' }] : [];
}
const show = showFor(fixture.showId);
return [{
publisher_domain: CREATOR_PUBLISHER.domain,
collection_id: fixture.showId,
name: show?.name ?? fixture.showId,
role: 'creator',
seller_agent_url: `${getAgentUrl()}/sales/mcp`,
}];
}

/**
* Add `collections` to a get_brand_identity response for a caller served 3.3
* or later, when the request did not narrow `fields` to exclude it. Mutates
* and returns the response.
*/
export function withCollectionLinks<T extends Record<string, unknown>>(
response: T,
brandId: string,
fields: unknown,
servedAdcpVersion: string | undefined,
): T {
if (!supportsCollections33(servedAdcpVersion)) return response;
if (Array.isArray(fields) && !fields.includes('collections')) return response;
const links = collectionLinksFor(brandId);
if (links && links.length > 0) (response as Record<string, unknown>).collections = links;
return response;
}
48 changes: 48 additions & 0 deletions server/src/training-agent/collections/capabilities.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
/**
* Capability declarations for the experimental 3.3 collection surfaces, added
* only when the caller is served 3.3 or later:
*
* - /sales: `media_buy.collection_cards` (cards in product and proposal
* reads), `media_buy.collection_catalog` (list_collections and the card
* webhooks), and the three card event types in
* `wholesale_feed_webhooks.event_types`.
* - /brand: `brand.collection_links` (`collections` on get_brand_identity).
*/

import {
BRAND_COLLECTION_LINKS_FEATURE,
COLLECTION_CARD_EVENT_TYPES,
COLLECTION_CARDS_FEATURE,
COLLECTION_CATALOG_FEATURE,
supportsCollections33,
} from './card-catalog.js';

interface CapabilitiesShape {
experimental_features?: unknown;
wholesale_feed_webhooks?: Record<string, unknown>;
}

function addFeatures(structured: CapabilitiesShape, features: readonly string[]): void {
const current = Array.isArray(structured.experimental_features)
? structured.experimental_features.filter((feature): feature is string => typeof feature === 'string')
: [];
for (const feature of features) if (!current.includes(feature)) current.push(feature);
structured.experimental_features = current;
}

export function projectCollectionCapabilities(
structured: CapabilitiesShape,
tenantId: string,
servedVersion: string | undefined,
): void {
if (!supportsCollections33(servedVersion)) return;
if (tenantId === 'sales') {
addFeatures(structured, [COLLECTION_CARDS_FEATURE, COLLECTION_CATALOG_FEATURE]);
const webhooks = structured.wholesale_feed_webhooks;
if (webhooks && Array.isArray(webhooks.event_types)) {
webhooks.event_types = [...new Set([...(webhooks.event_types as string[]), ...COLLECTION_CARD_EVENT_TYPES])];
}
} else if (tenantId === 'brand') {
addFeatures(structured, [BRAND_COLLECTION_LINKS_FEATURE]);
}
}
Loading
Loading