@dynamicagents/core 0.9.0

package/dist/a2a/self-origin.js

@@ -0,0 +1,114 @@
+/**
+ * This deployment's own public origin — learned from the request path, never
+ * configured.
+ *
+ * ## Why an agent needs it at all
+ *
+ * A Worker that only *answers* never needs to know its own name.
+ * {@link file://../worker/index.ts createA2AWorker} derives its audience, its
+ * card and its `jku` from `new URL(request.url).origin`, and none of it outlives
+ * the request. An agent that **calls out** mint-signed does need it:
+ * {@link file://./caller-token.ts signCallerToken} puts it in `iss` and derives
+ * the token's `jku` from it. That call happens inside a Durable Object, where
+ * there is no `Request` — which is the whole difficulty.
+ *
+ * The obvious answer is a `SELF_ORIGIN` secret, and it is the wrong one. It
+ * restates a value the request already carries, and it has to be kept
+ * byte-identical by hand with the origin allowlist on the far side, in every
+ * environment, forever. Every sibling that tried it took it back out —
+ * `slack-gatekeeper` discovers its own origin from the first signature-verified
+ * request rather than being told, and a verifying Worker that once carried a
+ * configured audience replaced it with `url.origin`.
+ *
+ * ## Where the value comes from
+ *
+ * Core already sends the origin into the Durable Object on every turn, one field
+ * short of this use. `A2AExecutor` computes `jku` as `${origin}${jwksPath}` and
+ * it rides {@link file://./push.ts TurnPushContext} through the Workflow into
+ * `runTaskTurn` and `executeSubtaskChunk`.
+ *
+ * That is the same origin `signCallerToken` needs, and not by coincidence: a
+ * caller token's `jku` **must** be the JWKS the verifier fetches, and `iss` must
+ * agree with it — the third check in {@link file://./verify.ts verify.ts}. An
+ * origin derived from anywhere else is exactly what that check exists to catch,
+ * so deriving it from the `jku` core already serves makes the agreement
+ * structural instead of clerical.
+ *
+ * ## Pinned on the first turn, and in memory
+ *
+ * The first origin an isolate is told wins, and later ones are ignored. That is
+ * not laziness about staleness — it is what makes the value safe to *read*.
+ *
+ * A Durable Object's input gate stays open across a non-storage await, and this
+ * package runs concurrent RPCs into one object by design (`round/workflow.ts`
+ * runs a round's branches under `Promise.all`). Mutable instance state can
+ * therefore change while a turn is awaiting a model call, and the credential
+ * thunks that read this are lazy — they run several frames below the turn, when
+ * the client is built. Pinned, the field is immutable after its first write, so
+ * every concurrent reader in the isolate gets the same string and no turn can
+ * sign as another turn's origin.
+ *
+ * The cost of pinning is what an agent does not have: several identities. An
+ * agent has one endpoint — the one its card advertises, the one a gatekeeper calls
+ * and a verifier allowlists — so there is nothing to follow. Note the asymmetry
+ * with a *verifier*, which derives the audience it expects per request and must
+ * not cache it: a verifier has to accept every hostname it answers on, while a
+ * signer needs one stable identity.
+ *
+ * Nothing is persisted, which is what keeps a pin from outliving its truth. An
+ * isolate is fresh on every `wrangler deploy` and recycles on its own, so a moved
+ * deployment re-learns its origin from the next turn it serves.
+ */
+export class SelfOrigin {
+    observed;
+    /**
+     * Offer the origin of an absolute URL seen on the request path — a `jku`, an
+     * endpoint, or a bare origin. Only `.origin` is kept, so a path or a trailing
+     * slash cannot reach a token claim.
+     *
+     * **The first usable value wins**; every later call is a no-op, including one
+     * naming a different origin. Called at each RPC entry and again when the push
+     * channel is built, so most calls are already no-ops — but the reason for the
+     * pin is the read side, not the write side. See the note above the class.
+     *
+     * Silently ignores anything unusable (absent, relative, or a scheme that has
+     * no meaningful origin), and an unusable value never pins: the parse comes
+     * first and the field is assigned only on success. This runs at the top of a
+     * turn, where a diagnostic value must never be the thing that fails it; the
+     * throw belongs at {@link require}, where something actually wanted the value.
+     */
+    note(url) {
+        if (this.observed || !url)
+            return;
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            return;
+        }
+        if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+            return;
+        this.observed = parsed.origin;
+    }
+    /** The pinned origin, or `undefined` when nothing has carried one yet. */
+    peek() {
+        return this.observed;
+    }
+    /**
+     * The pinned origin, for a caller that cannot proceed without it.
+     *
+     * Throws naming the timing, because that is what the mistake always is: the
+     * value arrives with a turn, so `onStart`, a constructor and a scheduled
+     * callback all run before any request has said what this deployment is called.
+     */
+    require() {
+        if (!this.observed) {
+            throw new Error("this deployment's own origin is not known on this instance yet: it is " +
+                "learned from the `jku` that arrives with every turn, so it is " +
+                "available inside a turn or a subtask chunk — not from onStart, a " +
+                "constructor or a scheduled callback");
+        }
+        return this.observed;
+    }
+}

package/dist/a2a/task-store.d.ts

@@ -0,0 +1,44 @@
+import type { TaskStore } from "@a2a-js/sdk/server";
+import { type ListTasksRequest, type ListTasksResponse, type Task } from "@a2a-js/sdk";
+import type { GatekeeperIdentity } from "./verify.js";
+import type { AgentResolver } from "./agent-stub.js";
+/**
+ * A durable {@link TaskStore} for the a2a-js `DefaultRequestHandler`, backed by
+ * the caller's agent Durable Object (via native RPC) instead of the SDK's
+ * per-request `InMemoryTaskStore`.
+ *
+ * Task state must survive the accept → async callback gap (and answer
+ * `GetTask`/`CancelTask`/`ListTasks` across requests), so it lives in the same
+ * per-caller DO that owns the Session — keyed by the verified `identity.key`,
+ * exactly like {@link file://./executor.ts A2AExecutor}. A workflow updates the
+ * same rows through its own DO RPC calls, so this store and the workflow share
+ * one source of truth.
+ *
+ * v1.0 passes a `ServerCallContext` to every method so a shared store can scope
+ * rows by tenant/owner. This store needs none of that: the DO instance it routes
+ * to *is* the scope, resolved from the caller identity the Worker verified, so a
+ * task is unreachable from any other caller by construction.
+ */
+export declare class DurableTaskStore implements TaskStore {
+    private readonly identity;
+    private readonly resolveAgent;
+    constructor(identity: GatekeeperIdentity, resolveAgent: AgentResolver);
+    load(taskId: string): Promise<Task | undefined>;
+    save(task: Task): Promise<void>;
+    /**
+     * `ListTasks` (new in v1.0): this caller's tasks, newest first, with the
+     * spec's optional `contextId` / `status` / `statusTimestampAfter` filters
+     * applied in SQL.
+     *
+     * The page token is the row offset as a decimal string. Offset paging can skip
+     * or repeat a row if tasks are written mid-scan, which is acceptable here: the
+     * listing is a diagnostic view over an append-mostly table, and the alternative
+     * (a keyset cursor) buys stability this caller has no use for.
+     *
+     * An agent whose DO does not implement `listTasks` answers the RPC with the
+     * protocol's own "unsupported" error rather than a binding-level failure — the
+     * capability is genuinely optional, and one of the two predecessor agents
+     * shipped without it for its whole life.
+     */
+    list(params: ListTasksRequest): Promise<ListTasksResponse>;
+}

package/dist/a2a/task-store.js

@@ -0,0 +1,99 @@
+import { UnsupportedOperationError } from "@a2a-js/sdk/errors";
+import { TaskState } from "@a2a-js/sdk";
+/**
+ * A durable {@link TaskStore} for the a2a-js `DefaultRequestHandler`, backed by
+ * the caller's agent Durable Object (via native RPC) instead of the SDK's
+ * per-request `InMemoryTaskStore`.
+ *
+ * Task state must survive the accept → async callback gap (and answer
+ * `GetTask`/`CancelTask`/`ListTasks` across requests), so it lives in the same
+ * per-caller DO that owns the Session — keyed by the verified `identity.key`,
+ * exactly like {@link file://./executor.ts A2AExecutor}. A workflow updates the
+ * same rows through its own DO RPC calls, so this store and the workflow share
+ * one source of truth.
+ *
+ * v1.0 passes a `ServerCallContext` to every method so a shared store can scope
+ * rows by tenant/owner. This store needs none of that: the DO instance it routes
+ * to *is* the scope, resolved from the caller identity the Worker verified, so a
+ * task is unreachable from any other caller by construction.
+ */
+export class DurableTaskStore {
+    identity;
+    resolveAgent;
+    constructor(identity, resolveAgent) {
+        this.identity = identity;
+        this.resolveAgent = resolveAgent;
+    }
+    async load(taskId) {
+        return ((await this.resolveAgent(this.identity).getTask(taskId)) ?? undefined);
+    }
+    async save(task) {
+        await this.resolveAgent(this.identity).saveTask(task);
+    }
+    /**
+     * `ListTasks` (new in v1.0): this caller's tasks, newest first, with the
+     * spec's optional `contextId` / `status` / `statusTimestampAfter` filters
+     * applied in SQL.
+     *
+     * The page token is the row offset as a decimal string. Offset paging can skip
+     * or repeat a row if tasks are written mid-scan, which is acceptable here: the
+     * listing is a diagnostic view over an append-mostly table, and the alternative
+     * (a keyset cursor) buys stability this caller has no use for.
+     *
+     * An agent whose DO does not implement `listTasks` answers the RPC with the
+     * protocol's own "unsupported" error rather than a binding-level failure — the
+     * capability is genuinely optional, and one of the two predecessor agents
+     * shipped without it for its whole life.
+     */
+    async list(params) {
+        const agent = this.resolveAgent(this.identity);
+        if (!agent.listTasks) {
+            throw new UnsupportedOperationError({
+                message: "this agent does not support ListTasks"
+            });
+        }
+        const pageSize = clampPageSize(params.pageSize);
+        const offset = parseOffset(params.pageToken);
+        const { tasks, totalSize } = await agent.listTasks({
+            contextId: params.contextId,
+            // The proto default (`UNSPECIFIED`) is the spec's "no status filter".
+            state: params.status === TaskState.TASK_STATE_UNSPECIFIED
+                ? undefined
+                : params.status,
+            updatedAfter: parseTimestamp(params.statusTimestampAfter),
+            includeArtifacts: params.includeArtifacts === true,
+            historyLength: params.historyLength,
+            limit: pageSize,
+            offset
+        });
+        const nextOffset = offset + tasks.length;
+        return {
+            tasks,
+            nextPageToken: nextOffset < totalSize ? String(nextOffset) : "",
+            pageSize,
+            totalSize
+        };
+    }
+}
+/** Page size bounds from the `ListTasks` spec: default 50, min 1, max 100. */
+function clampPageSize(pageSize) {
+    if (pageSize === undefined)
+        return 50;
+    return Math.min(100, Math.max(1, Math.trunc(pageSize)));
+}
+/** Row offset from a page token; an unparseable token restarts at the first page. */
+function parseOffset(pageToken) {
+    const offset = Number.parseInt(pageToken, 10);
+    return Number.isSafeInteger(offset) && offset > 0 ? offset : 0;
+}
+/**
+ * `statusTimestampAfter` (ISO 8601) as epoch milliseconds, matching the
+ * `updated_at` column the store filters on — that column is stamped on every
+ * status write, so it tracks `status.timestamp`.
+ */
+function parseTimestamp(iso) {
+    if (!iso)
+        return undefined;
+    const ms = Date.parse(iso);
+    return Number.isNaN(ms) ? undefined : ms;
+}

package/dist/a2a/task.d.ts

@@ -0,0 +1,85 @@
+import { type Role, type TaskState } from "@a2a-js/sdk";
+/**
+ * The A2A `Task` (and its nested types) as they cross the DO RPC boundary.
+ *
+ * Two constraints shape these, and the SDK types satisfy neither directly:
+ *
+ *  1. **Serializability.** A v1.0 `Part` carries a `content` oneof whose `raw`
+ *     arm is a `Buffer`; its methods fail Cloudflare's `Rpc.Serializable`
+ *     constraint and collapse the generated DO-stub return types to `never`.
+ *     Pinning `content` to its `text` arm removes that arm — and this agent only
+ *     ever produces, and only ever receives, text (see {@link file://./parts.ts}).
+ *  2. **Instantiation depth.** These are written out as plain interfaces rather
+ *     than derived with `Omit<Task, …> & { … }`. The v1.0 model is deep enough
+ *     that layering mapped types under Cloudflare's own RPC type mapping exceeds
+ *     TypeScript's instantiation limit at the stub call sites.
+ *
+ * Each of these widens to its SDK counterpart for free, so no cast is needed at
+ * the a2a-js edges (`AgentEvent.task`, `TaskStore.load`/`list`); the
+ * {@link _Widens} guard below fails the build if that ever stops holding.
+ * Runtime is unaffected — tasks are JSON-round-tripped in storage, so any field
+ * the SDK adds survives even though these types don't name it.
+ */
+/**
+ * The A2A extension `metadata` bag as this agent handles it: never set. Its SDK
+ * type is an open `{ [key: string]: any }` map, which is both what collapses the
+ * DO-stub types (`unknown` members fail `Rpc.Serializable`) and what pushes the
+ * stub-mapped `Task` past TypeScript's instantiation limit. Pinning it to
+ * `undefined` keeps both in check and still widens to the SDK type. Metadata a
+ * caller sent is not erased — stored tasks are JSON blobs, so it round-trips
+ * untouched; it is simply invisible to this agent, which never reads it.
+ */
+type A2AMetadata = undefined;
+/** A `Part` restricted to the text arm of its `content` oneof. */
+export interface PlainPart {
+    content: {
+        $case: "text";
+        value: string;
+    };
+    metadata: A2AMetadata;
+    filename: string;
+    mediaType: string;
+}
+/** A `Message` whose parts are all {@link PlainPart}. */
+export interface PlainMessage {
+    messageId: string;
+    contextId: string;
+    taskId: string;
+    role: Role;
+    parts: PlainPart[];
+    metadata: A2AMetadata;
+    extensions: string[];
+    referenceTaskIds: string[];
+}
+/** An `Artifact` whose parts are all {@link PlainPart}. */
+export interface PlainArtifact {
+    artifactId: string;
+    name: string;
+    description: string;
+    parts: PlainPart[];
+    metadata: A2AMetadata;
+    extensions: string[];
+}
+/** A `TaskStatus` whose message is a {@link PlainMessage}. */
+export interface PlainStatus {
+    state: TaskState;
+    message: PlainMessage | undefined;
+    timestamp: string | undefined;
+}
+/** A `Task` built entirely from the plain types above. */
+export interface PlainTask {
+    id: string;
+    contextId: string;
+    status: PlainStatus;
+    artifacts: PlainArtifact[];
+    history: PlainMessage[];
+    metadata: A2AMetadata;
+}
+/**
+ * A task state rendered for humans and for the `notify_tasks.state` column
+ * (`TASK_STATE_INPUT_REQUIRED` → `input-required`). v1.0 states are numeric enum
+ * members, so anything stored or displayed goes through the protobuf JSON name
+ * first. Matches slack-gatekeeper's `taskStateLabel`.
+ */
+export declare function taskStateLabel(state: TaskState): string;
+export {};

package/dist/a2a/task.js

@@ -0,0 +1,15 @@
+import { taskStateToJSON } from "@a2a-js/sdk";
+const _assertWidens = true;
+void _assertWidens;
+/**
+ * A task state rendered for humans and for the `notify_tasks.state` column
+ * (`TASK_STATE_INPUT_REQUIRED` → `input-required`). v1.0 states are numeric enum
+ * members, so anything stored or displayed goes through the protobuf JSON name
+ * first. Matches slack-gatekeeper's `taskStateLabel`.
+ */
+export function taskStateLabel(state) {
+    return taskStateToJSON(state)
+        .replace(/^TASK_STATE_/, "")
+        .toLowerCase()
+        .replace(/_/g, "-");
+}

package/dist/a2a/verify.d.ts

@@ -0,0 +1,80 @@
+import { type JWTPayload } from "jose";
+import { type GatekeeperIdentity } from "@dynamicagents/g2a-protocol";
+/**
+ * Verify the gatekeeper identity JWT (the "B authenticates A" half of zero-trust).
+ *
+ * The gatekeeper signs a short-lived EdDSA JWT and sends it as a Bearer token on
+ * every A2A call. Per RFC 7515 §4.1.2 it embeds a `jku` header pointing at its
+ * public JWKS, so remote agents don't need a separately configured JWKS URL —
+ * they read `jku` straight from the token and verify the key from there.
+ *
+ * Security: the `jku` origin is validated against the allowed origins before
+ * fetching, preventing key-injection attacks (an attacker cannot point `jku` at
+ * their own JWKS and have it accepted).
+ *
+ * **This file is a guardian.** The four checks below — `jku` present → origin
+ * allowlist → `iss` origin equals `jku` origin → `jwtVerify` pinned to EdDSA —
+ * are the whole zero-trust contract, and they arrived here byte-identical from
+ * two independently-evolved agents. Do not weaken any of them, do not make any
+ * of them optional, and do not add a bypass for local development: run a local
+ * gatekeeper instead.
+ */
+/**
+ * The wire contract — claim names, algorithm, identity shape — comes from
+ * `@dynamicagents/g2a-protocol`, which the gatekeeper also depends on directly.
+ *
+ * It used to be declared here and again in the gatekeeper, each with a comment
+ * saying it must match the other, because the gatekeeper is not an agent and must
+ * not import this package. That failed exactly as it always does: the two sides
+ * drifted onto different claim namespaces, verification read an empty tenant, and
+ * every request 401'd with both builds green.
+ *
+ * The namespace moved again in g2a-protocol 0.3.0, to `dynamicagents.dev` — the
+ * same class of change, made deliberately this time. It is survivable only
+ * because both sides now read it from one package: bump the protocol dependency
+ * and ship core and `slack-gatekeeper` in the same deploy.
+ *
+ * Re-exported below so nothing downstream of `@dynamicagents/core/a2a` has to know
+ * the split happened — an agent still imports these from here.
+ */
+export { IDENTITY_CLAIM, TENANT_CLAIM, type GatekeeperIdentity } from "@dynamicagents/g2a-protocol";
+/** Thrown when a gatekeeper token is missing or fails verification. */
+export declare class GatekeeperAuthError extends Error {
+    constructor(message: string);
+}
+/** Extract the Bearer token from an `Authorization` header, or null. */
+export declare function bearerToken(request: Request): string | null;
+export interface VerifyOptions {
+    /** Allowed gatekeeper origins — validates both the `jku` domain and `iss` claim. */
+    allowedOrigins: string[];
+    audience: string;
+    /** Claim carrying the caller identity. Defaults to {@link IDENTITY_CLAIM}. */
+    identityClaim?: string;
+    /** Claim carrying the authorized tenant. Defaults to {@link TENANT_CLAIM}. */
+    tenantClaim?: string;
+}
+/**
+ * Normalize configured gatekeeper origins to the HTTPS origins emitted in gatekeeper
+ * JWT `jku` and `iss` claims. This accepts a hostname, `http://` URL, or URL
+ * with a trailing slash while keeping the verification allowlist exact.
+ */
+export declare function normalizeGatekeeperOrigins(origins: string[]): string[];
+/**
+ * Verify a gatekeeper JWT and return its payload, parsed identity and authorized
+ * tenant.
+ *
+ * The `jku` JWK Set URL is read directly from the token's protected header
+ * (RFC 7515 §4.1.2) and validated against the allowlist before fetching, so no
+ * separate JWKS URL configuration is needed on the remote side.
+ *
+ * `tenant` is returned rather than enforced: this function stays a pure
+ * signature/origin question, and only the caller knows which tenant the request
+ * actually addressed. {@link createA2AWorker} compares the two.
+ *
+ * Throws {@link GatekeeperAuthError} on any failure.
+ */
+export declare function verifyGatekeeperToken(token: string, opts: VerifyOptions): Promise<{
+    payload: JWTPayload;
+    identity: GatekeeperIdentity;
+    tenant: string;
+}>;

package/dist/a2a/verify.js

@@ -0,0 +1,143 @@
+import { createRemoteJWKSet, decodeJwt, decodeProtectedHeader, jwtVerify } from "jose";
+import { A2A_JWS_ALG, readIdentityClaim, readTenantClaim } from "@dynamicagents/g2a-protocol";
+/**
+ * Verify the gatekeeper identity JWT (the "B authenticates A" half of zero-trust).
+ *
+ * The gatekeeper signs a short-lived EdDSA JWT and sends it as a Bearer token on
+ * every A2A call. Per RFC 7515 §4.1.2 it embeds a `jku` header pointing at its
+ * public JWKS, so remote agents don't need a separately configured JWKS URL —
+ * they read `jku` straight from the token and verify the key from there.
+ *
+ * Security: the `jku` origin is validated against the allowed origins before
+ * fetching, preventing key-injection attacks (an attacker cannot point `jku` at
+ * their own JWKS and have it accepted).
+ *
+ * **This file is a guardian.** The four checks below — `jku` present → origin
+ * allowlist → `iss` origin equals `jku` origin → `jwtVerify` pinned to EdDSA —
+ * are the whole zero-trust contract, and they arrived here byte-identical from
+ * two independently-evolved agents. Do not weaken any of them, do not make any
+ * of them optional, and do not add a bypass for local development: run a local
+ * gatekeeper instead.
+ */
+/**
+ * The wire contract — claim names, algorithm, identity shape — comes from
+ * `@dynamicagents/g2a-protocol`, which the gatekeeper also depends on directly.
+ *
+ * It used to be declared here and again in the gatekeeper, each with a comment
+ * saying it must match the other, because the gatekeeper is not an agent and must
+ * not import this package. That failed exactly as it always does: the two sides
+ * drifted onto different claim namespaces, verification read an empty tenant, and
+ * every request 401'd with both builds green.
+ *
+ * The namespace moved again in g2a-protocol 0.3.0, to `dynamicagents.dev` — the
+ * same class of change, made deliberately this time. It is survivable only
+ * because both sides now read it from one package: bump the protocol dependency
+ * and ship core and `slack-gatekeeper` in the same deploy.
+ *
+ * Re-exported below so nothing downstream of `@dynamicagents/core/a2a` has to know
+ * the split happened — an agent still imports these from here.
+ */
+export { IDENTITY_CLAIM, TENANT_CLAIM } from "@dynamicagents/g2a-protocol";
+/** Thrown when a gatekeeper token is missing or fails verification. */
+export class GatekeeperAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GatekeeperAuthError";
+    }
+}
+// jose's remote JWKS helper caches keys + handles rotation; build one per URL
+// and reuse it across requests in the same isolate.
+const jwksByUrl = new Map();
+function jwksFor(url) {
+    let set = jwksByUrl.get(url);
+    if (!set) {
+        set = createRemoteJWKSet(new URL(url));
+        jwksByUrl.set(url, set);
+    }
+    return set;
+}
+/** Extract the Bearer token from an `Authorization` header, or null. */
+export function bearerToken(request) {
+    const header = request.headers.get("authorization") ?? "";
+    const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+    return match ? match[1] : null;
+}
+/**
+ * Normalize configured gatekeeper origins to the HTTPS origins emitted in gatekeeper
+ * JWT `jku` and `iss` claims. This accepts a hostname, `http://` URL, or URL
+ * with a trailing slash while keeping the verification allowlist exact.
+ */
+export function normalizeGatekeeperOrigins(origins) {
+    return origins.map((origin) => {
+        const trimmed = origin.trim();
+        if (!trimmed) {
+            throw new GatekeeperAuthError("allowed gatekeeper origin cannot be empty");
+        }
+        try {
+            return new URL(`https://${trimmed.replace(/^https?:\/\//i, "")}`).origin;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new GatekeeperAuthError(`invalid allowed gatekeeper origin '${origin}': ${message}`);
+        }
+    });
+}
+/**
+ * Verify a gatekeeper JWT and return its payload, parsed identity and authorized
+ * tenant.
+ *
+ * The `jku` JWK Set URL is read directly from the token's protected header
+ * (RFC 7515 §4.1.2) and validated against the allowlist before fetching, so no
+ * separate JWKS URL configuration is needed on the remote side.
+ *
+ * `tenant` is returned rather than enforced: this function stays a pure
+ * signature/origin question, and only the caller knows which tenant the request
+ * actually addressed. {@link createA2AWorker} compares the two.
+ *
+ * Throws {@link GatekeeperAuthError} on any failure.
+ */
+export async function verifyGatekeeperToken(token, opts) {
+    try {
+        const allowedOrigins = normalizeGatekeeperOrigins(opts.allowedOrigins);
+        // Extract jku from the protected header — this is the standard way the
+        // gatekeeper advertises where to fetch its public key (RFC 7515 §4.1.2).
+        const header = decodeProtectedHeader(token);
+        const jku = header.jku;
+        if (!jku) {
+            throw new GatekeeperAuthError("gatekeeper JWT missing jku header (RFC 7515 §4.1.2)");
+        }
+        // Security: validate the jku origin before fetching. Without this an
+        // attacker could forge a token with jku pointing at their own JWKS.
+        const jkuOrigin = new URL(jku).origin;
+        if (!allowedOrigins.includes(jkuOrigin)) {
+            throw new GatekeeperAuthError(`jku origin '${jkuOrigin}' is not in the allowed gatekeeper origins`);
+        }
+        // Prevent one listed gatekeeper from impersonating another: the origin where
+        // keys are fetched must match the origin that issued the token.
+        const rawIss = decodeJwt(token).iss ?? "";
+        const issOrigin = new URL(rawIss).origin;
+        if (issOrigin !== jkuOrigin) {
+            throw new GatekeeperAuthError(`jku origin '${jkuOrigin}' does not match iss origin '${issOrigin}'`);
+        }
+        const { payload } = await jwtVerify(token, jwksFor(jku), {
+            issuer: allowedOrigins,
+            audience: opts.audience,
+            algorithms: [A2A_JWS_ALG]
+        });
+        // Read through the protocol package's readers rather than indexing the
+        // payload here: they are where "an absent or malformed claim yields an
+        // empty value, never a default" has its single implementation, and the
+        // emptiness is load-bearing — `createA2AWorker` compares the tenant against
+        // the one the request body addressed, and `""` matches none of them.
+        return {
+            payload,
+            identity: readIdentityClaim(payload, opts.identityClaim),
+            tenant: readTenantClaim(payload, opts.tenantClaim)
+        };
+    }
+    catch (err) {
+        if (err instanceof GatekeeperAuthError)
+            throw err;
+        throw new GatekeeperAuthError(err.message);
+    }
+}

package/dist/agent/budget.d.ts

@@ -0,0 +1,46 @@
+/**
+ * One round's turn allowance, carried as a single mutable object rather than as a
+ * number threaded down and a count threaded back up.
+ *
+ * The distinction matters because a round is not one model call. Each slot may
+ * repair a rejected decomposition several times before the round moves on to the
+ * fallback, and every one of those attempts *restarts* the round from the same
+ * messages — so a failed attempt is work redone, with whatever tool side effects
+ * it already had. They all spend the same allowance. When that allowance was a
+ * plain number, keeping later attempts honest meant remembering to decrement it
+ * between each pair, and forgetting let one round cost a multiple of its budget.
+ * Sharing one object removes the thing there was to forget.
+ *
+ * `spent` is mutated where the turn is actually spent (the model loop's
+ * `onStepEnd`) and read where it actually matters (the RPC return that the
+ * Workflow meters against the Task). Nothing in between carries it.
+ */
+/** One round's allowance and what it has spent, across every attempt in the round. */
+export interface TurnBudget {
+    /** What this round was allowed when it started: the Task's unspent turns. */
+    readonly allowance: number;
+    /** Turns spent so far. Mutated by the model loop, one per completed step. */
+    spent: number;
+}
+/** A fresh budget for a round that may spend `allowance` turns. */
+export declare const newTurnBudget: (allowance: number) => TurnBudget;
+/**
+ * Steps one `generateText` attempt may spend, given what the run has already used.
+ *
+ * Must be evaluated **per attempt**: `isStepCount` counts steps within a single
+ * call, so an allowance computed once and shared with later attempts would hand
+ * each of them the turns its predecessors already burned.
+ *
+ * The `Math.max(1, …)` floor is load-bearing, not defensive. A primary that
+ * consumed the entire remainder still leaves the fallback one step, because an
+ * attempt with nothing to spend cannot reach an ending — which fails the round and
+ * costs the caller its answer, a far worse trade than one turn. So a round may
+ * exceed its allowance by exactly one, and never by more.
+ *
+ * The bound survives repair attempts because only an attempt that *starts* already
+ * at the allowance can overrun, and only by the one step of this floor: an attempt
+ * that starts under it is capped at the exact remainder, and `runTurn` refuses to
+ * open a repair once the allowance is gone. That leaves the fallback's first
+ * attempt as the only one that can ever begin overdrawn.
+ */
+export declare const stepAllowance: (maxTurns: number, spent: number) => number;

package/dist/agent/budget.js

@@ -0,0 +1,42 @@
+/**
+ * One round's turn allowance, carried as a single mutable object rather than as a
+ * number threaded down and a count threaded back up.
+ *
+ * The distinction matters because a round is not one model call. Each slot may
+ * repair a rejected decomposition several times before the round moves on to the
+ * fallback, and every one of those attempts *restarts* the round from the same
+ * messages — so a failed attempt is work redone, with whatever tool side effects
+ * it already had. They all spend the same allowance. When that allowance was a
+ * plain number, keeping later attempts honest meant remembering to decrement it
+ * between each pair, and forgetting let one round cost a multiple of its budget.
+ * Sharing one object removes the thing there was to forget.
+ *
+ * `spent` is mutated where the turn is actually spent (the model loop's
+ * `onStepEnd`) and read where it actually matters (the RPC return that the
+ * Workflow meters against the Task). Nothing in between carries it.
+ */
+/** A fresh budget for a round that may spend `allowance` turns. */
+export const newTurnBudget = (allowance) => ({
+    allowance,
+    spent: 0
+});
+/**
+ * Steps one `generateText` attempt may spend, given what the run has already used.
+ *
+ * Must be evaluated **per attempt**: `isStepCount` counts steps within a single
+ * call, so an allowance computed once and shared with later attempts would hand
+ * each of them the turns its predecessors already burned.
+ *
+ * The `Math.max(1, …)` floor is load-bearing, not defensive. A primary that
+ * consumed the entire remainder still leaves the fallback one step, because an
+ * attempt with nothing to spend cannot reach an ending — which fails the round and
+ * costs the caller its answer, a far worse trade than one turn. So a round may
+ * exceed its allowance by exactly one, and never by more.
+ *
+ * The bound survives repair attempts because only an attempt that *starts* already
+ * at the allowance can overrun, and only by the one step of this floor: an attempt
+ * that starts under it is capped at the exact remainder, and `runTurn` refuses to
+ * open a repair once the allowance is gone. That leaves the fallback's first
+ * attempt as the only one that can ever begin overdrawn.
+ */
+export const stepAllowance = (maxTurns, spent) => Math.max(1, maxTurns - spent);