@dynamicagents/core 0.9.0

package/dist/a2a/caller-token.js

@@ -0,0 +1,61 @@
+import { importJWK, SignJWT } from "jose";
+import { A2A_JWS_ALG, IDENTITY_CLAIM, TENANT_CLAIM, jwksUrl } from "@dynamicagents/g2a-protocol";
+import { parsePrivateJwk } from "./card.js";
+/** Default lifetime: long enough for clock skew, short enough to be worthless from a log. */
+const DEFAULT_TTL_SECONDS = 120;
+/**
+ * `importJWK` does real work and this is on the per-request path.
+ *
+ * Keyed by the raw secret so a rotated key invalidates the entry rather than
+ * being ignored for the life of the isolate.
+ */
+let cached;
+async function signingKeyFor(raw) {
+    if (cached?.raw === raw)
+        return cached;
+    const jwk = parsePrivateJwk(raw);
+    // Not cast to `CryptoKey`: `importJWK` returns a union, and asserting the
+    // branch would be a lie the day this key is anything but Ed25519.
+    const key = await importJWK(jwk, A2A_JWS_ALG);
+    cached = { raw, key, kid: jwk.kid };
+    return cached;
+}
+/**
+ * Sign a short-lived token identifying **this agent as a caller** to another
+ * service that trusts its card key.
+ *
+ * The production sibling of `makeGatekeeperToken`, which core previously shipped
+ * only from `/testing` — so an agent that had to call out mint-signed had to
+ * hand-write this shape, and every deployment that did so wrote its own subtly
+ * different version of the `iss`/`jku` agreement above.
+ *
+ * Distinct from {@link signCallbackJwt}, which carries **no** claims: that one
+ * proves "the agent you called is calling you back about this task", where this
+ * proves "this is who I am and which tenant I speak for".
+ */
+export async function signCallerToken(options) {
+    const { key, kid } = await signingKeyFor(options.signingKey);
+    // Normalized for the same reason `audience` is, and it has to happen before
+    // both uses: `jku` names only the origin, so an `issuer` carrying a trailing
+    // slash or a path would sign an `iss` that disagrees with it — and a verifier
+    // comparing `iss` byte-for-byte against a normalized origin allowlist rejects
+    // the token even though the two URLs share an origin.
+    const issuer = new URL(options.issuer).origin;
+    return new SignJWT({
+        [IDENTITY_CLAIM]: options.identity,
+        [TENANT_CLAIM]: options.tenant
+    })
+        .setProtectedHeader({
+        alg: A2A_JWS_ALG,
+        kid,
+        // Where the far side fetches the public half. A verifier must check this
+        // origin against its own allowlist *before* fetching, which is what stops
+        // a forged token nominating an attacker-controlled JWKS.
+        jku: jwksUrl(issuer)
+    })
+        .setIssuer(issuer)
+        .setAudience(new URL(options.audience).origin)
+        .setIssuedAt()
+        .setExpirationTime(`${options.ttlSeconds ?? DEFAULT_TTL_SECONDS}s`)
+        .sign(key);
+}

package/dist/a2a/caller.d.ts

@@ -0,0 +1,23 @@
+import type { GatekeeperIdentity } from "./verify.js";
+/**
+ * Per-request system-prompt suffix describing the verified calling gatekeeper-agent
+ * instance, from the gatekeeper identity JWT.
+ *
+ * Core ships this and not a soul, and the line between them is the point: a soul
+ * is prompt copy expressing who an agent *is*, which nobody else can write for
+ * you. This is a **rendering of a protocol fact** — who the gatekeeper proved it was
+ * — and that fact has one correct rendering. Two agents disagreeing about how to
+ * describe their caller would be a bug, not a personality. It is the same
+ * category as `renderSubagentPrompt`'s budget section, which core also owns.
+ *
+ * **Advisory context only.** This is the calling *agent instance*, not the human
+ * on the other end of it, so an agent's soul must never let the model read it as
+ * "who you're talking to" — point the model at whatever speaker wrapper the
+ * gatekeeper applies instead.
+ *
+ * Deliberately neutral about what a workspace is: `GatekeeperIdentity.workspaceId`
+ * is whatever the calling gatekeeper partitions by, and core does not know that it
+ * is a Slack team. Override `DynamicAgent.callerContext` for a deployment that
+ * wants to name it.
+ */
+export declare function callerContext(identity: GatekeeperIdentity): string;

package/dist/a2a/caller.js

@@ -0,0 +1,33 @@
+/**
+ * Per-request system-prompt suffix describing the verified calling gatekeeper-agent
+ * instance, from the gatekeeper identity JWT.
+ *
+ * Core ships this and not a soul, and the line between them is the point: a soul
+ * is prompt copy expressing who an agent *is*, which nobody else can write for
+ * you. This is a **rendering of a protocol fact** — who the gatekeeper proved it was
+ * — and that fact has one correct rendering. Two agents disagreeing about how to
+ * describe their caller would be a bug, not a personality. It is the same
+ * category as `renderSubagentPrompt`'s budget section, which core also owns.
+ *
+ * **Advisory context only.** This is the calling *agent instance*, not the human
+ * on the other end of it, so an agent's soul must never let the model read it as
+ * "who you're talking to" — point the model at whatever speaker wrapper the
+ * gatekeeper applies instead.
+ *
+ * Deliberately neutral about what a workspace is: `GatekeeperIdentity.workspaceId`
+ * is whatever the calling gatekeeper partitions by, and core does not know that it
+ * is a Slack team. Override `DynamicAgent.callerContext` for a deployment that
+ * wants to name it.
+ */
+export function callerContext(identity) {
+    const label = identity.name ?? identity.key;
+    if (!label) {
+        return "\n\nCalling agent instance: unknown (the gatekeeper did not include an agent identity).";
+    }
+    const withKind = identity.kind ? `${label} (${identity.kind})` : label;
+    const lines = ["", "", `Calling agent instance: ${withKind}.`];
+    if (identity.workspaceId != null) {
+        lines.push(`Calling workspace: ${identity.workspaceId}.`);
+    }
+    return lines.join("\n");
+}

package/dist/a2a/card.d.ts

@@ -0,0 +1,158 @@
+import type { JWK } from "jose";
+import { AgentCard } from "@a2a-js/sdk";
+/**
+ * The card signature uses the one algorithm every Dynamic Agents A2A signature uses,
+ * and the default RPC path is the one the gatekeeper also knows. Both come from
+ * `@dynamicagents/g2a-protocol` — see {@link file://./verify.ts} for why that is a
+ * separate package rather than a constant declared on each side.
+ */
+export { A2A_RPC_PATH } from "@dynamicagents/g2a-protocol";
+/**
+ * The transport-independent half of an {@link AgentCard} — everything that does
+ * not depend on the request origin. {@link buildBaseCard} adds
+ * `supportedInterfaces` and the security fields.
+ *
+ * Derived from the SDK `AgentCard` rather than hand-declared so a protocol field
+ * that gains a requirement fails the build here instead of silently going
+ * unadvertised.
+ */
+export type AgentManifest = Pick<AgentCard, "name" | "description" | "version" | "capabilities" | "defaultInputModes" | "defaultOutputModes" | "skills">;
+/**
+ * An AgentCard in its **protobuf-JSON** encoding — the form served at the
+ * well-known path and the exact document a signature is computed over. Distinct
+ * from the in-memory `AgentCard`: the wire form omits proto defaults and renders
+ * oneofs (`securitySchemes`, `Part.content`) as a single key rather than a
+ * `$case` tag.
+ */
+export type WireAgentCard = Record<string, unknown>;
+export interface CardSigningConfig {
+    /** Ed25519 private JWK (with `kid`) that signs the card. */
+    privateJwk: JWK & {
+        kid: string;
+    };
+    /** Public URL serving this agent's JWKS — embedded as the JWS `jku`. */
+    jku: string;
+}
+export interface BuildCardOptions {
+    /** Origin the card is served from; the interface `url` is built under it. */
+    origin: string;
+    /** Path this agent answers JSON-RPC on. Defaults to {@link A2A_RPC_PATH}. */
+    rpcPath?: string;
+    /**
+     * The tenant this card describes, advertised on its interface entry.
+     *
+     * Several agents share one endpoint here, so `tenant` is what says *which*
+     * one — A2A spec §8.3.2 requires a client to echo the declared value on every
+     * request, and this Worker refuses a request that does not.
+     *
+     * Omitted for the **root stub card**, which describes the origin rather than
+     * any agent: it advertises the endpoint and `extendedAgentCard`, and a caller
+     * reaches a real agent by asking for its tenant.
+     */
+    tenant?: string;
+    /**
+     * Advertise the gatekeeper's Bearer-JWT scheme in `securitySchemes`.
+     *
+     * **Defaults to `false` for historical reasons that no longer hold — see
+     * below before relying on the default.**
+     *
+     * `SecurityScheme` is the card's only protobuf *oneof*, and in earlier SDK
+     * releases `SecurityScheme.fromJSON` read only the wire spelling
+     * (`{ httpAuthSecurityScheme: … }`) and not the decoded `$case` form. A
+     * verifier that decodes the fetched card and then canonicalizes it through
+     * `toJSON(fromJSON(card))` decodes twice, and the second pass collapsed
+     * `{ gatekeeperJwt: { httpAuthSecurityScheme: … } }` to `{ gatekeeperJwt: {} }` — a
+     * different document from the one that was signed, so the signature failed.
+     * slack-gatekeeper's `canonicalCardPayload` double-decodes exactly this way.
+     *
+     * **As of the pinned `@a2a-js/sdk` (1.0.1) that is fixed.** `card.spec.ts`
+     * asserts it directly: an advertised-schemes card is a fixed point under
+     * repeated decoding, and its signature verifies both as served and after a
+     * double decode. So the safety argument for the `false` default is gone, and
+     * the remaining reason to keep it is deployment ordering — a gatekeeper pinned to
+     * an older SDK copy would still collapse the oneof. Flip the default once the
+     * gatekeepers in play are known to be on ≥1.0.1; the specs will hold the line if
+     * a later SDK regresses.
+     *
+     * `securityRequirements` is unaffected either way — it is a plain map, not a
+     * oneof — so the card always declares that auth is *required*, it just may not
+     * describe the scheme.
+     */
+    advertiseSecuritySchemes?: boolean;
+}
+/**
+ * Build the (unsigned) AgentCard.
+ *
+ * v1.0 replaced the card's flat `url` / `preferredTransport` / `protocolVersion`
+ * fields with an ordered `supportedInterfaces` list, where each entry pins its
+ * own protocol binding *and* protocol version. That per-interface
+ * `protocolVersion` is what a client's transport factory matches on and what the
+ * Worker validates the `A2A-Version` request header against, so it must be the
+ * real protocol version rather than the agent's own version string.
+ */
+export declare function buildBaseCard(manifest: AgentManifest, opts: BuildCardOptions): AgentCard;
+/**
+ * Sign the card with a detached-payload EdDSA flattened JWS, returning the
+ * signed **wire** card to serve. v1.0 standardized this (A2A spec §8.4), so the
+ * canonicalization and JWS construction are the SDK's rather than a local
+ * scheme: a JCS (RFC 8785) canonicalization of the card with `signatures`
+ * removed, under a protected header carrying `alg`, `kid` and `typ` (all three
+ * are required — the SDK verifier rejects a signature missing any of them).
+ *
+ * The card is normalized to its wire form *before* signing because that is what
+ * the verifier canonicalizes: `verifyAgentCardSignature` re-encodes whatever
+ * document it fetched through `AgentCard.toJSON(AgentCard.fromJSON(card))`.
+ * Signing the in-memory proto object instead would canonicalize `$case` tags and
+ * proto defaults that never appear on the wire, and every signature would fail.
+ *
+ * A verifying gatekeeper strips the `signatures` array, recomputes the canonical
+ * payload, and verifies — pinning this key's `kid`+`jku` on first registration
+ * (Trust-On-First-Use).
+ */
+export declare function signCard(card: AgentCard, cfg: CardSigningConfig): Promise<WireAgentCard>;
+/**
+ * The same signature, attached to the **in-memory** card instead of the wire
+ * one — for a caller that hands the card to something which will encode it
+ * itself.
+ *
+ * That caller is `GetExtendedAgentCard`. The SDK's JSON-RPC transport runs
+ * `AgentCard.toJSON()` over whatever the extended-card provider returns, so
+ * returning {@link signCard}'s wire card means `toJSON` runs over a document
+ * that has already been encoded. For most cards that is a no-op and looks fine
+ * — which is the trap. `securitySchemes` is a protobuf *oneof*: encoding it
+ * twice collapses `{ gatekeeperJwt: { httpAuthSecurityScheme: … } }` to
+ * `{ gatekeeperJwt: {} }`, the served document stops matching the one that was
+ * signed, and every signature verification fails.
+ *
+ * So the double encode is latent today only because
+ * {@link BuildCardOptions.advertiseSecuritySchemes} defaults to `false`; it
+ * would surface the day that flag is flipped, as a signature failure with
+ * nothing pointing back here. Returning the in-memory card lets the SDK do the
+ * single encode the signature was computed over, and is correct either way.
+ *
+ * `card.spec.ts` pins both halves.
+ */
+export declare function signCardInPlace(card: AgentCard, cfg: CardSigningConfig): Promise<AgentCard>;
+/**
+ * The card's protobuf-JSON encoding. Typed back as `AgentCard` for the SDK
+ * signer, which is generic over "the document to canonicalize" rather than over
+ * the in-memory shape specifically.
+ *
+ * Encode-only — never `toJSON(fromJSON(card))`. `fromJSON` reads the *wire*
+ * spelling of a oneof, so running it over an in-memory card silently drops every
+ * `$case`-tagged field. The verifier's round trip is the mirror image and stable:
+ * it decodes the document it fetched and re-encodes it to exactly this.
+ */
+export declare function wireCard(card: AgentCard): AgentCard;
+/**
+ * Parse and validate the `A2A_SIGNING_KEY` secret into the private JWK used to
+ * sign the card. Throws if the JWK is missing its `kid` (required for the JWS
+ * protected header and gatekeeper key-pinning).
+ */
+export declare function parsePrivateJwk(raw: string): CardSigningConfig["privateJwk"];
+/** Public card-signing JWKS (served at the `jku`): the private JWK minus `d`. */
+export declare function publicCardJwks(privateJwk: JWK & {
+    kid: string;
+}): {
+    keys: JWK[];
+};

package/dist/a2a/card.js

@@ -0,0 +1,163 @@
+import { A2A_PROTOCOL_VERSION, AgentCard, generateAgentCardSignature } from "@a2a-js/sdk";
+import { A2A_JWS_ALG, A2A_RPC_PATH, endpointUrl } from "@dynamicagents/g2a-protocol";
+/**
+ * The card signature uses the one algorithm every Dynamic Agents A2A signature uses,
+ * and the default RPC path is the one the gatekeeper also knows. Both come from
+ * `@dynamicagents/g2a-protocol` — see {@link file://./verify.ts} for why that is a
+ * separate package rather than a constant declared on each side.
+ */
+export { A2A_RPC_PATH } from "@dynamicagents/g2a-protocol";
+/**
+ * The `httpAuthSecurityScheme` describing the gatekeeper's Bearer JWT, and the
+ * requirement that references it. Split out so the requirement can be advertised
+ * even when {@link BuildCardOptions.advertiseSecuritySchemes} keeps the scheme
+ * itself off the wire.
+ */
+const GATEKEEPER_SCHEME_ID = "gatekeeperJwt";
+/**
+ * Build the (unsigned) AgentCard.
+ *
+ * v1.0 replaced the card's flat `url` / `preferredTransport` / `protocolVersion`
+ * fields with an ordered `supportedInterfaces` list, where each entry pins its
+ * own protocol binding *and* protocol version. That per-interface
+ * `protocolVersion` is what a client's transport factory matches on and what the
+ * Worker validates the `A2A-Version` request header against, so it must be the
+ * real protocol version rather than the agent's own version string.
+ */
+export function buildBaseCard(manifest, opts) {
+    const rpcPath = opts.rpcPath ?? A2A_RPC_PATH;
+    return {
+        ...manifest,
+        capabilities: {
+            // `extensions` is required on the proto type but absent from most
+            // hand-written manifests, so it is defaulted before the spread rather
+            // than after — a manifest that declares extensions keeps them.
+            extensions: [],
+            ...manifest.capabilities,
+            // Forced on, not inherited from the manifest: an agent here is *only*
+            // reachable as a tenant, and its card *only* through
+            // `GetExtendedAgentCard`. The SDK gates that method on this flag, reading
+            // it off whichever card the request handler was built with (spec §3.3.4 —
+            // it MUST return `UnsupportedOperationError` when unset), so every card
+            // this Worker serves has to carry it, the stub and the tenants alike.
+            extendedAgentCard: true
+        },
+        supportedInterfaces: [
+            {
+                // The gatekeeper reads this URL off the card and mints `aud` from it with
+                // `audienceFor`; this Worker derives its expected audience the same
+                // way. `endpointUrl` is what makes those provably equal — the protocol
+                // package pins `audienceFor(endpointUrl(o, p)) === endpointUrl(o, p)`
+                // for every path, rather than leaving both sides to concatenate.
+                url: endpointUrl(opts.origin, rpcPath),
+                protocolBinding: "JSONRPC",
+                protocolVersion: A2A_PROTOCOL_VERSION,
+                tenant: opts.tenant ?? ""
+            }
+        ],
+        provider: undefined,
+        documentationUrl: undefined,
+        iconUrl: undefined,
+        securitySchemes: opts.advertiseSecuritySchemes
+            ? {
+                [GATEKEEPER_SCHEME_ID]: {
+                    scheme: {
+                        $case: "httpAuthSecurityScheme",
+                        value: { description: "", scheme: "bearer", bearerFormat: "JWT" }
+                    }
+                }
+            }
+            : {},
+        // v0.3's `security: [{ gatekeeperJwt: [] }]`. The empty `list` means the scheme
+        // is required but carries no scopes. Safe to advertise unconditionally: this
+        // is a plain map, so it survives the round trip that eats `securitySchemes`.
+        securityRequirements: [
+            { schemes: { [GATEKEEPER_SCHEME_ID]: { list: [] } } }
+        ],
+        signatures: []
+    };
+}
+/**
+ * Sign the card with a detached-payload EdDSA flattened JWS, returning the
+ * signed **wire** card to serve. v1.0 standardized this (A2A spec §8.4), so the
+ * canonicalization and JWS construction are the SDK's rather than a local
+ * scheme: a JCS (RFC 8785) canonicalization of the card with `signatures`
+ * removed, under a protected header carrying `alg`, `kid` and `typ` (all three
+ * are required — the SDK verifier rejects a signature missing any of them).
+ *
+ * The card is normalized to its wire form *before* signing because that is what
+ * the verifier canonicalizes: `verifyAgentCardSignature` re-encodes whatever
+ * document it fetched through `AgentCard.toJSON(AgentCard.fromJSON(card))`.
+ * Signing the in-memory proto object instead would canonicalize `$case` tags and
+ * proto defaults that never appear on the wire, and every signature would fail.
+ *
+ * A verifying gatekeeper strips the `signatures` array, recomputes the canonical
+ * payload, and verifies — pinning this key's `kid`+`jku` on first registration
+ * (Trust-On-First-Use).
+ */
+export async function signCard(card, cfg) {
+    const sign = generateAgentCardSignature(cfg.privateJwk, {
+        alg: A2A_JWS_ALG,
+        kid: cfg.privateJwk.kid,
+        typ: "JOSE",
+        jku: cfg.jku
+    });
+    const signed = await sign(wireCard(card));
+    return signed;
+}
+/**
+ * The same signature, attached to the **in-memory** card instead of the wire
+ * one — for a caller that hands the card to something which will encode it
+ * itself.
+ *
+ * That caller is `GetExtendedAgentCard`. The SDK's JSON-RPC transport runs
+ * `AgentCard.toJSON()` over whatever the extended-card provider returns, so
+ * returning {@link signCard}'s wire card means `toJSON` runs over a document
+ * that has already been encoded. For most cards that is a no-op and looks fine
+ * — which is the trap. `securitySchemes` is a protobuf *oneof*: encoding it
+ * twice collapses `{ gatekeeperJwt: { httpAuthSecurityScheme: … } }` to
+ * `{ gatekeeperJwt: {} }`, the served document stops matching the one that was
+ * signed, and every signature verification fails.
+ *
+ * So the double encode is latent today only because
+ * {@link BuildCardOptions.advertiseSecuritySchemes} defaults to `false`; it
+ * would surface the day that flag is flipped, as a signature failure with
+ * nothing pointing back here. Returning the in-memory card lets the SDK do the
+ * single encode the signature was computed over, and is correct either way.
+ *
+ * `card.spec.ts` pins both halves.
+ */
+export async function signCardInPlace(card, cfg) {
+    const signed = await signCard(card, cfg);
+    return { ...card, signatures: signed.signatures };
+}
+/**
+ * The card's protobuf-JSON encoding. Typed back as `AgentCard` for the SDK
+ * signer, which is generic over "the document to canonicalize" rather than over
+ * the in-memory shape specifically.
+ *
+ * Encode-only — never `toJSON(fromJSON(card))`. `fromJSON` reads the *wire*
+ * spelling of a oneof, so running it over an in-memory card silently drops every
+ * `$case`-tagged field. The verifier's round trip is the mirror image and stable:
+ * it decodes the document it fetched and re-encodes it to exactly this.
+ */
+export function wireCard(card) {
+    return AgentCard.toJSON(card);
+}
+/**
+ * Parse and validate the `A2A_SIGNING_KEY` secret into the private JWK used to
+ * sign the card. Throws if the JWK is missing its `kid` (required for the JWS
+ * protected header and gatekeeper key-pinning).
+ */
+export function parsePrivateJwk(raw) {
+    const jwk = JSON.parse(raw);
+    if (!jwk.kid)
+        throw new Error("A2A_SIGNING_KEY must include a `kid`");
+    return jwk;
+}
+/** Public card-signing JWKS (served at the `jku`): the private JWK minus `d`. */
+export function publicCardJwks(privateJwk) {
+    const { d: _d, ...pub } = privateJwk;
+    void _d;
+    return { keys: [{ ...pub, use: "sig", alg: A2A_JWS_ALG }] };
+}

package/dist/a2a/context.d.ts

@@ -0,0 +1,19 @@
+import { type ServerCallContext } from "@a2a-js/sdk/server";
+import type { GatekeeperIdentity } from "./verify.js";
+/**
+ * Build the call context for one verified JSON-RPC request. The default builder
+ * stashes the raw headers in the context's state bag, so an executor can reach
+ * them the same way it would under the Express binding.
+ *
+ * `tenant` names which agent on this origin the call is for. The SDK's
+ * `JsonRpcTransportHandler` would also lift it off `params.tenant` on its own,
+ * but only when the context arrives without one — so passing it here is not
+ * redundant: this Worker has already parsed, authorized and routed on the
+ * tenant before a handler exists to receive the context, and setting it keeps
+ * the value the executor and task store see identical to the one that chose
+ * them. It is also what reaches the extended-card provider, which the SDK calls
+ * with the context alone.
+ */
+export declare function buildCallContext(request: Request, identity: GatekeeperIdentity, tenant: string): ServerCallContext;
+/** Echo back the extensions the handler actually activated (spec §14.2.2). */
+export declare function extensionHeaders(context: ServerCallContext): HeadersInit;

package/dist/a2a/context.js

@@ -0,0 +1,61 @@
+import { A2A_VERSION_HEADER, Extensions, HTTP_EXTENSION_HEADER } from "@a2a-js/sdk";
+import { defaultServerCallContextBuilder } from "@a2a-js/sdk/server";
+/**
+ * The per-call {@link ServerCallContext} bridge for a Workers `fetch` handler.
+ *
+ * v1.0 made the call context mandatory on every request-handler and task-store
+ * method, and the SDK only ships Express and gRPC bindings that build one; this
+ * is the equivalent seam for `fetch`.
+ */
+/**
+ * The verified calling gatekeeper-agent, as the SDK's {@link User}. `userName` is
+ * the canonical instance key (e.g. `custom:7:analytics`) — the same value the
+ * agent Durable Object is keyed by, so the SDK's owner-scoped bookkeeping lines
+ * up with the isolation this Worker already enforces by routing.
+ */
+class GatekeeperUser {
+    identity;
+    constructor(identity) {
+        this.identity = identity;
+    }
+    get isAuthenticated() {
+        return true;
+    }
+    get userName() {
+        // The Worker rejects a keyless identity (400) before a context is built.
+        return this.identity.key ?? "";
+    }
+}
+/**
+ * Build the call context for one verified JSON-RPC request. The default builder
+ * stashes the raw headers in the context's state bag, so an executor can reach
+ * them the same way it would under the Express binding.
+ *
+ * `tenant` names which agent on this origin the call is for. The SDK's
+ * `JsonRpcTransportHandler` would also lift it off `params.tenant` on its own,
+ * but only when the context arrives without one — so passing it here is not
+ * redundant: this Worker has already parsed, authorized and routed on the
+ * tenant before a handler exists to receive the context, and setting it keeps
+ * the value the executor and task store see identical to the one that chose
+ * them. It is also what reaches the extended-card provider, which the SDK calls
+ * with the context alone.
+ */
+export function buildCallContext(request, identity, tenant) {
+    const headers = {};
+    for (const [name, value] of request.headers)
+        headers[name] = value;
+    return defaultServerCallContextBuilder({
+        extensions: Extensions.parseServiceParameter(request.headers.get(HTTP_EXTENSION_HEADER) ?? undefined),
+        user: new GatekeeperUser(identity),
+        headers,
+        requestedVersion: request.headers.get(A2A_VERSION_HEADER) ?? undefined,
+        tenant
+    });
+}
+/** Echo back the extensions the handler actually activated (spec §14.2.2). */
+export function extensionHeaders(context) {
+    const activated = context.activatedExtensions;
+    if (!activated?.length)
+        return {};
+    return { [HTTP_EXTENSION_HEADER]: Extensions.toServiceParameter(activated) };
+}