@adcp/sdk 6.5.0 → 6.7.0

package/compliance/cache/{3.0.1 → 3.0.5}/specialisms/sales-social/index.yaml

@@ -150,6 +150,13 @@ phases:
         response_schema_ref: "account/list-accounts-response.json"
         doc_ref: "/accounts/tasks/list_accounts"
         stateful: true
+        # Explicit-mode social platforms (Snap, Meta, TikTok) pre-provision
+        # advertiser accounts out-of-band — `sync_accounts` is intentionally
+        # missing_tool, with `list_accounts` as the canonical alternative.
+        # Declaring the substitution here lets the runner waive the
+        # downstream missing_tool cascade when list_accounts passes.
+        # See adcontextprotocol/adcp#3734.
+        provides_state_for: sync_accounts
         expected: |
           Return accounts matching the query:
           - accounts array with status, account_id, brand, operator

package/compliance/cache/{3.0.1 → 3.0.5}/universal/runner-output-contract.yaml

@@ -70,7 +70,8 @@ validation_result:
     field carries the transport failure).
   required_fields:
     - check                   # Validation kind from storyboard-schema.yaml:
-                              # response_schema | field_present | field_value |
+                              # response_schema | field_present |
+                              # envelope_field_present | field_value |
                               # field_value_or_absent | status_code | http_status |
                               # http_status_in | error_code | on_401_require_header |
                               # resource_equals_agent_url | any_of | refs_resolve
@@ -91,6 +92,8 @@ validation_result:
                               #   field_value_or_absent → value or allowed_values array
                               #                          from the storyboard validation
                               #   field_present        → the path that should resolve
+                              #   envelope_field_present → the path that should resolve
+                              #                          in the protocol envelope
                               #   status_code          → expected status
                               #   error_code           → expected error code
                               #   any_of               → array of acceptable forms
@@ -105,6 +108,9 @@ validation_result:
                               #   field_present        → null (the field was missing)
                               #                          or the observed non-object
                               #                          value
+                              #   envelope_field_present → null (the field was missing)
+                              #                          or the observed non-object
+                              #                          value (scoped to envelope)
     - schema_id               # $id of the response schema applied. Required
                               # when check == response_schema, null otherwise.
     - schema_url              # Resolvable URL the implementor can fetch to
@@ -245,7 +251,8 @@ skip_result:
     - reason                  # not_applicable | no_phases |
                               # prerequisite_failed | missing_tool |
                               # missing_test_controller |
-                              # unsatisfied_contract | peer_branch_taken
+                              # unsatisfied_contract | peer_branch_taken |
+                              # peer_substituted
     - detail                  # human-readable explanation citing the
                               # declared supported_protocols / specialisms
                               # and, if relevant, the missing tool,
@@ -291,8 +298,20 @@ skip_result:
       gaps (agent doesn't support a protocol) and runtime branch routing
       (agent took the other path) are different signals and must not be
       conflated in dashboards or summaries.
-
-  detailed_reason_mapping:
+    peer_substituted: |
+      The step would otherwise grade `missing_tool` or
+      `missing_test_controller`, but a same-phase peer step declared
+      `provides_state_for: <this_step_id>` (see storyboard-schema.yaml >
+      `provides_state_for`) and passed — the substitute established
+      equivalent state for downstream stateful steps, so the cascade is
+      waived. detail MUST follow the shape
+      "<this_step_id> state provided by <peer_phase_id>.<peer_step_id>"
+      so downstream tooling can parse which substitute carried the state.
+      Kept distinct from peer_branch_taken (branch-set routing for
+      mutually exclusive behaviors) and not_applicable (coverage gap):
+      this signal indicates the agent did declare the specialism but
+      offers an interchangeable tool that the storyboard accepts as an
+      equivalent state contract.
     description: |
       Runners MAY internally track narrower skip reasons (e.g., a grader
       distinguishing `rate_abuse_opt_out` from `live_side_effect_opt_in_required`).

package/compliance/cache/{3.0.1 → 3.0.5}/universal/storyboard-schema.yaml

@@ -53,6 +53,60 @@
 #     MUST exist in the source tree at build time. Duplicate IDs
 #     across files are a build-time error.)
 #
+# default_agent: string (optional — logical agent key used by multi-agent
+#   storyboard runners to route steps that do not have a unique specialism
+#   claimant in the runtime agents map. Resolved by the runner against the
+#   `agents` option passed to `runStoryboard({ agents: { sales: …, governance: …, … } })`.
+#
+#   Key shape: free-form non-empty string, matched verbatim against the
+#   runtime `agents` map's keys. The spec does NOT constrain the key to the
+#   specialism enum (`sales`, `signals`, `governance`, `creative`, `brand`)
+#   because production multi-agent topologies legitimately fan out per-property
+#   (`nyt_sales`, `wsj_sales`), per-region (`sales_eu`, `sales_us`), or
+#   per-brand-rights-holder. Authors choose the convention that matches their
+#   operator's CI invocation; portability across operators is the author's
+#   concern, not the spec's.
+#
+#   When to set it. Storyboards that exercise cross-domain tools — e.g.,
+#   `sync_creatives`, `list_creative_formats` — do not name a single specialism
+#   the runner can match. The author has the most context for which logical
+#   tenant should receive these calls (usually "wherever the seller is":
+#   `sales`). Encoding `default_agent: sales` once in the YAML beats
+#   re-asserting it on every CI invocation. (Note: `comply_test_controller`
+#   is routed via `prerequisites.controller_seeding`, not this field — the
+#   controller is a back-channel, not a specialism claimant.)
+#
+#   Resolution order (runner contract — see adcp-client#1066, adcp-client#1355):
+#     1. Step-level `agent:` override (if declared on the step).
+#     2. Specialism-claimant match against the runtime agents map (matched
+#        via each agent's `get_adcp_capabilities.supported_protocols`):
+#          - Exactly one agent claims the step's task's specialism → route there.
+#          - Zero claimants → fall through to slot 3.
+#          - Two or more claimants → runner MUST grade the step `unrouted_step`
+#            rather than picking arbitrarily. Multi-claim is an operator-config
+#            error; the storyboard cannot disambiguate it. Slot 3/4 do NOT
+#            rescue this case — silently picking one would mask the misconfig.
+#     3. Storyboard-level `default_agent` (THIS field) resolved against the
+#        runtime agents map. When the field is set but the key is absent from
+#        the map, the runner MUST grade the step `default_agent_unresolved`
+#        and MUST NOT fall through to slot 4 — silent fallback would invisibly
+#        override the storyboard author's encoded intent. Slot 4 fires only
+#        when the storyboard does NOT declare this field.
+#     4. Run-options `default_agent` passed to `runStoryboard({ default_agent })`.
+#        Same key-resolution rule as slot 3: set-but-unmatched grades
+#        `default_agent_unresolved`; unset falls through to slot 5.
+#     5. Fail-fast — runner raises `unrouted_step` and grades the step failed.
+#
+#   Single-agent runs ignore this field entirely — there is no map to resolve
+#   against, every step routes to the only configured agent. Authors SHOULD
+#   still declare it for clarity; multi-agent runners treat it as advisory and
+#   single-agent runners as a no-op.
+#
+#   Validation. The `<key>` MUST be a non-empty string. Validation that the
+#   key resolves to a configured tenant is a runtime concern (per the slot 3
+#   rule above), not a schema concern — the same storyboard runs against
+#   different topologies.)
+#
 # agent:
 #   interaction_model: enum (stateless_transform | stateful_preloaded | stateful_push | stateless_generate | media_buy_seller | marketplace_catalog | owned_signals | si_platform | brand_rights_holder | governance_agent)
 #   capabilities: string[] (AdCP capability flags: supports_transformation, has_creative_library, supports_generation, sells_media, accepts_briefs, supports_guaranteed, supports_non_guaranteed, catalog_signals)
@@ -272,6 +326,54 @@
 #     "prior_step.<step_id>.passed"   → true if the named prior step in the same storyboard passed
 #   Storyboard authors should prefer expressing gating through step ordering when possible.
 #
+# provides_state_for: string | string[] (optional — declares that this step's pass
+#   establishes equivalent state for the named peer step(s) in the same phase. Used
+#   to rescue the cascade-skip default when one of two interchangeable stateful
+#   steps is missing on the agent: e.g., explicit-mode sellers that pre-provision
+#   accounts out-of-band declare `sync_accounts` as missing_tool but expose
+#   `list_accounts` as the canonical alternative — declaring
+#   `provides_state_for: sync_accounts` on `list_accounts` tells the runner that
+#   the substitute's pass satisfies the same downstream state contract.
+#
+#   Grammar parallels `contributes_to`: declared on the substitute step, names
+#   the target peer(s) whose state it provides. The two fields are independent —
+#   `contributes_to` flows branch-set flags into a later `assert_contribution`;
+#   `provides_state_for` waives a peer's missing-tool / missing-test-controller
+#   cascade so downstream stateful steps still run.
+#
+#   Array semantics: `provides_state_for: [A, B]` is ALL-OF — one substitute pass
+#   establishes state for both A and B simultaneously. ANY-OF semantics are not
+#   supported; if a substitute only conditionally satisfies a peer, model it as
+#   two separate substitute steps.
+#
+#   Validation rules (enforced by lint:storyboard-provides-state-for, fail at
+#   parse time):
+#     - Same-phase only. The target step MUST live in the same phase as the
+#       substitute step. Cross-phase substitution is rejected; a cross-phase
+#       state contract belongs in `context_outputs` / `context_inputs`, not
+#       this field.
+#     - Target step must exist in the same phase by `id`.
+#     - Target step MUST declare `stateful: true`. Stateless peers don't
+#       carry a state contract to substitute for.
+#     - Substitute step MUST declare `stateful: true`. A stateless step
+#       cannot establish equivalent state on the agent side.
+#     - Self-references (`provides_state_for: <own_id>`) are rejected.
+#     - Cycles (A→B and B→A in the same phase) are rejected. The peer-graph
+#       per phase MUST be acyclic.
+#
+#   Runner behavior (see runner-output-contract.yaml > skip_result.reasons.peer_substituted):
+#     - When the substitute step passes AND the target peer would otherwise
+#       grade `missing_tool` / `missing_test_controller`, the runner MUST
+#       grade the target peer with skip reason `peer_substituted` (not
+#       `missing_tool`) and MUST NOT cascade `prerequisite_failed` to
+#       downstream stateful steps in subsequent phases.
+#     - When the substitute step itself fails or is skipped, the cascade
+#       proceeds as if `provides_state_for` were absent — the substitute
+#       did not establish the state it claimed.
+#
+#   See adcontextprotocol/adcp#3734 (mechanism rationale) and
+#   adcp-client#1130 (the cascade-skip default this field rescues).
+#
 # context_outputs: array of ContextOutput objects (optional — capture values from
 #   this step's response into the runner's context accumulator so later steps can
 #   reference them via $context.<name>). Each entry:
@@ -575,7 +677,10 @@
 #
 # --- Validation ---
 #
-# check: string (what to validate: "response_schema", "field_present", "field_value",
+# check: string (what to validate: "response_schema", "field_present",
+#                "envelope_field_present" (walks protocol-envelope.json instead of
+#                response_schema_ref — use for top-level envelope fields like `status`),
+#                "field_value",
 #                "field_value_or_absent", "status_code", "http_status", "http_status_in",
 #                "error_code", "on_401_require_header", "resource_equals_agent_url",
 #                "any_of", "refs_resolve", "a2a_submitted_artifact")

package/compliance/cache/{3.0.1 → 3.0.5}/universal/v3-envelope-integrity.yaml

@@ -15,7 +15,9 @@ narrative: |
   docs/building/implementation/task-lifecycle.mdx.
 
   This storyboard documents the machine-check assertion and asserts the canonical v3
-  `status` field is present. The explicit envelope-root field-absence checks
+  `status` field is present using the `envelope_field_present` check type (added in
+  adcp-client#1045), which walks the protocol envelope rather than the inner response
+  schema. The explicit envelope-root field-absence checks
   (asserting task_status and response_status are absent) require `field_absent`
   runner support in @adcp/client — those checks are marked TODO below and are not
   executed until the runner ships that check type. The schema-level constraint
@@ -82,7 +84,7 @@ phases:
         validations:
           - check: response_schema
             description: "Response matches get-adcp-capabilities-response.json schema"
-          - check: field_present
+          - check: envelope_field_present
             path: "status"
             description: "Envelope carries the canonical v3 status field"
           # TODO: restore these as field_absent checks once @adcp/client runner ships

package/dist/lib/adapters/implicit-account-store.d.ts

@@ -0,0 +1,170 @@
+/**
+ * InMemoryImplicitAccountStore
+ *
+ * Reference implementation of `AccountStore` for `resolution: 'implicit'`
+ * platforms. Platforms using this resolution mode require buyers to call
+ * `sync_accounts` before any tool that needs tenant context; subsequent
+ * requests resolve the account from the caller's auth principal rather
+ * than from an inline `ext.account_ref`.
+ *
+ * Use this in tests and as a copy-and-adapt starting point for durable
+ * implementations. See `docs/guides/account-resolution.md` for key
+ * derivation guidance, error contracts, and TTL recommendations.
+ *
+ * **Picking an AccountStore?** Three reference shapes by *who creates the
+ * account*:
+ * - **Buyer self-onboards via `sync_accounts`** → `InMemoryImplicitAccountStore`
+ *   (this file, Shape A).
+ * - **Upstream OAuth API owns the roster** → `createOAuthPassthroughResolver`
+ *   (Shape B, returns just `resolve`).
+ * - **Publisher ops curates the roster** → `createRosterAccountStore`
+ *   (Shape C, complete AccountStore).
+ *
+ * @see docs/guides/account-resolution.md
+ * @public
+ */
+import type { AccountReference } from '../types/tools.generated';
+import type { Account, AccountStore, ResolvedAuthInfo, ResolveContext, SyncAccountsResultRow } from '../server/decisioning';
+/**
+ * Default key-extraction function for the auth-principal→account mapping.
+ *
+ * Canonical choices by credential kind:
+ * - `'oauth'`   → `oauth:<client_id>`   (OAuth 2.0 client identity; stable across token rotations)
+ * - `'api_key'` → `api_key:<key_id>`   (API-key identity; stable until key is revoked)
+ * - `'http_sig'`→ `http_sig:<agent_url>` (verified caller URL; the most durable identity)
+ *
+ * Adopters who key on `authInfo.sub` or `authInfo.extra` instead MUST
+ * document that choice — those fields are grant-specific and may not be
+ * stable across credential rotations.
+ */
+export declare function defaultImplicitKeyFn(authInfo: ResolvedAuthInfo): string | undefined;
+/**
+ * Constructor options for `InMemoryImplicitAccountStore`.
+ * @public
+ */
+export interface ImplicitAccountStoreOptions<TCtxMeta = Record<string, unknown>> {
+    /**
+     * Convert a buyer-supplied `AccountReference` (from `sync_accounts`) to the
+     * seller's `Account<TCtxMeta>`. Called once per ref in `upsert()`.
+     *
+     * **Default:** builds a synthetic account from the ref fields. Suitable
+     * for tests; replace for production (call your platform's account-lookup
+     * or account-creation API here).
+     */
+    buildAccount?: (ref: AccountReference, ctx?: ResolveContext) => Account<TCtxMeta> | Promise<Account<TCtxMeta>>;
+    /**
+     * Extract the principal key from `ResolvedAuthInfo`. The returned string
+     * is the lookup key for the `authInfo → accounts` mapping.
+     *
+     * **Default:** `defaultImplicitKeyFn` — uses `credential.client_id`
+     * (oauth), `credential.key_id` (api_key), or `credential.agent_url`
+     * (http_sig). Stable across token rotations within the same credential
+     * kind.
+     *
+     * Override when your platform keys on a custom claim (e.g., a
+     * `sub`-derived tenant ID in `authInfo.extra`).
+     */
+    keyFn?: (authInfo: ResolvedAuthInfo) => string | undefined;
+    /**
+     * Sync-linkage TTL in milliseconds. Entries stored by `upsert()` expire
+     * after this duration; `resolve()` returns `null` (→ `ACCOUNT_NOT_FOUND`)
+     * for expired entries, prompting the buyer to call `sync_accounts` again.
+     *
+     * **Default:** `86_400_000` (24 hours). Align with your platform's session
+     * or token lifetime; longer TTLs risk serving stale account state.
+     *
+     * Distinct from `AccountStore.refreshToken` — that refreshes the upstream
+     * OAuth token mid-request. This TTL governs how long the sync-linkage
+     * itself is valid before a fresh `sync_accounts` is required.
+     */
+    ttlMs?: number;
+}
+/**
+ * In-memory `AccountStore` for `resolution: 'implicit'` platforms.
+ *
+ * Wire contract:
+ * 1. Buyer calls `sync_accounts` → framework calls `upsert()` → store records
+ *    `authKey → accounts[]`.
+ * 2. Buyer calls any tool (e.g. `create_media_buy`) without `ext.account_ref`
+ *    → framework calls `resolve(undefined, ctx)` → store looks up by `authKey`.
+ * 3. If no prior sync: `resolve()` returns `null` → framework emits
+ *    `ACCOUNT_NOT_FOUND`. Do NOT return `AUTH_REQUIRED` — that signals
+ *    missing credentials, not a missing pre-sync.
+ *
+ * This class is intentionally minimal. Copy-and-adapt for durable stores
+ * (Postgres, Redis); see `docs/guides/account-resolution.md` for the DDL
+ * reference and the key-derivation rationale.
+ *
+ * @example
+ * ```ts
+ * import { InMemoryImplicitAccountStore } from '@adcp/sdk/server';
+ *
+ * const accountStore = new InMemoryImplicitAccountStore({
+ *   buildAccount: async (ref, ctx) => {
+ *     const upstream = await myPlatform.findOrCreate(ref, ctx?.authInfo);
+ *     return {
+ *       id: upstream.id,
+ *       name: upstream.name,
+ *       status: 'active',
+ *       ctx_metadata: { upstreamId: upstream.id },
+ *     };
+ *   },
+ * });
+ *
+ * // Wire into createAdcpServer:
+ * createAdcpServer({ accounts: accountStore, ... });
+ * ```
+ *
+ * @public
+ */
+export declare class InMemoryImplicitAccountStore<TCtxMeta = Record<string, unknown>> implements AccountStore<TCtxMeta> {
+    readonly resolution: "implicit";
+    private _store;
+    private _keyFn;
+    private _ttlMs;
+    private _buildAccount;
+    constructor(options?: ImplicitAccountStoreOptions<TCtxMeta>);
+    /**
+     * Resolve the caller's account from the auth-principal→account mapping
+     * populated by a prior `sync_accounts` call.
+     *
+     * Returns `null` (→ `ACCOUNT_NOT_FOUND`) when:
+     * - No prior `sync_accounts` was called for this principal
+     * - The stored entry has exceeded `ttlMs`
+     * - `ctx.authInfo` is absent or carries no extractable key
+     *
+     * **Multi-account note.** When a buyer synced multiple refs in one
+     * `sync_accounts` call, this implementation returns the _first_ stored
+     * account. If your platform requires per-request account disambiguation
+     * (e.g., different brands on the same buyer), switch to `'explicit'` mode
+     * so buyers pass `ext.account_ref` on each request, or override `keyFn`
+     * to encode the brand into the key.
+     */
+    resolve(_ref: AccountReference | undefined, ctx?: ResolveContext): Promise<Account<TCtxMeta> | null>;
+    /**
+     * Process a `sync_accounts` payload: build accounts from refs and store
+     * them under the caller's auth key.
+     *
+     * The auth key is extracted from `ctx.authInfo` via `keyFn`. When the
+     * key cannot be derived (no credential or unrecognized credential kind),
+     * all refs are returned as `SYNC_FAILED` rows — a silent-success-then-
+     * mystery-failure sequence is worse than an explicit error. Check your
+     * `authenticate` callback and `keyFn` if you see this error.
+     *
+     * When `ctx.authInfo` is absent (unauthenticated call), all refs fail
+     * with `UNAUTHENTICATED`. Your `authenticate` callback in
+     * `serve({ authenticate })` should reject unauthenticated requests before
+     * reaching this method.
+     */
+    upsert(refs: AccountReference[], ctx?: ResolveContext): Promise<SyncAccountsResultRow[]>;
+    /** Remove all stored sync linkages. */
+    clear(): void;
+    /**
+     * Return the auth key that would be derived from `authInfo`.
+     * Useful in tests to assert that a specific principal's linkage was stored.
+     */
+    authKey(authInfo: ResolvedAuthInfo): string | undefined;
+    /** Return the number of principal → accounts linkages currently stored. */
+    get size(): number;
+}
+//# sourceMappingURL=implicit-account-store.d.ts.map

package/dist/lib/adapters/implicit-account-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"implicit-account-store.d.ts","sourceRoot":"","sources":["../../../src/lib/adapters/implicit-account-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAkB,MAAM,0BAA0B,CAAC;AACjF,OAAO,KAAK,EACV,OAAO,EACP,YAAY,EAEZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAM/B;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAWnF;AAiBD;;;GAGG;AACH,MAAM,WAAW,2BAA2B,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC7E;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,CAAC,EAAE,cAAc,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE/G;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,CAAC;IAE3D;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,4BAA4B,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,YAAW,YAAY,CAAC,QAAQ,CAAC;IAC7G,QAAQ,CAAC,UAAU,EAAG,UAAU,CAAU;IAE1C,OAAO,CAAC,MAAM,CAA4C;IAC1D,OAAO,CAAC,MAAM,CAAqD;IACnE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAG+B;gBAExC,OAAO,CAAC,EAAE,2BAA2B,CAAC,QAAQ,CAAC;IAQ3D;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,EAAE,GAAG,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAc1G;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,IAAI,EAAE,gBAAgB,EAAE,EAAE,GAAG,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAqH9F,uCAAuC;IACvC,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS;IAIvD,2EAA2E;IAC3E,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}