@dynamicagents/core 0.9.0

package/dist/a2a/notify.d.ts

@@ -0,0 +1,106 @@
+import { type JWK } from "jose";
+import { type Task } from "@a2a-js/sdk";
+import type { PlainTask } from "./task.js";
+/**
+ * Outbound push-notification (accept + notify) helpers — the "notify" half of the
+ * async A2A contract. The gatekeeper dispatches `SendMessage` with a
+ * `taskPushNotificationConfig` (webhook `url` + validation `token`), we accept
+ * immediately with a `submitted` Task, and later POST the terminal Task back to
+ * that webhook. This module builds the Task shapes and signs + sends that
+ * callback.
+ *
+ * The callback is authenticated exactly like the AgentCard: a short-lived EdDSA
+ * JWT signed by `A2A_SIGNING_KEY`, whose protected header `kid`+`jku` must equal
+ * the card's signing `kid`+`jku` (see {@link file://./card.ts} `signCard`) — the
+ * gatekeeper pinned those at registration (Trust-On-First-Use) and verifies the
+ * callback token against that same public JWKS. No shared secret crosses the
+ * boundary; only our public key is ever used to verify.
+ */
+/**
+ * The two shared values on this hop — the signature algorithm and the header
+ * carrying the per-task validation `token` — come from
+ * `@dynamicagents/g2a-protocol`, the same package the gatekeeper reads them from.
+ *
+ * The header used to be declared here and again in slack-gatekeeper, each with a
+ * comment naming the other file. It is a slightly different case from the claim
+ * names: the value is `@a2a-js/sdk`'s own default for `tokenHeaderName`, not
+ * Dynamic Agents' choice, but the SDK never *exports* it — it exists only as an
+ * inline fallback — so neither side could import it and both wrote it down.
+ *
+ * Re-exported so `@dynamicagents/core/a2a` keeps being where an agent finds it.
+ */
+export { NOTIFICATION_TOKEN_HEADER } from "@dynamicagents/g2a-protocol";
+/**
+ * The `submitted` Task we return synchronously to accept a turn (A2A §7.2). The
+ * gatekeeper only requires a non-empty `id`; the actual reply follows later via the
+ * callback.
+ */
+export declare function buildSubmittedTask(taskId: string, contextId: string): PlainTask;
+/**
+ * The terminal `completed` Task for a turn the agent deliberately did not
+ * answer — a turn an `AgentPlugin.shouldHandleTurn` gate declined, or whatever
+ * else a host treats as "nothing to say". Same shape as
+ * {@link buildSubmittedTask}: **no `status.message` at all**.
+ *
+ * The callback is still POSTed. The gatekeeper's pending row has to resolve — we
+ * simply hand it nothing to post to Slack. There is no `messageId` because there
+ * is no message, so unlike {@link buildCompletedTask} nothing needs a stable id
+ * for the gatekeeper to dedupe on: a `notify`-step retry re-delivers no content and
+ * is idempotent by construction.
+ */
+export declare function buildNoReplyCompletedTask(taskId: string, contextId: string): PlainTask;
+/**
+ * A non-terminal `working` Task snapshot carrying an intermediate content message.
+ * Streamed live from the DO as the tool loop emits content before the final reply.
+ *
+ * `messageId` is derived from `${taskId}:${key}` — stable across re-runs (see
+ * {@link agentTextMessage}) so the gatekeeper dedupes correctly on workflow replay.
+ *
+ * `key` is a **semantic** string, not a step counter, and the distinction is
+ * load-bearing: an agent that runs several rounds per task emits progress from
+ * each, so a bare index makes round 0's third step and round 1's third step the
+ * same message to the gatekeeper — it dedupes the second away and the user watches
+ * a task go quiet. A caller that genuinely has one flat sequence can pass
+ * `String(i)`; one with rounds should key on both (`r1:step:3`), and milestones
+ * on what they are (`ack:1`).
+ */
+export declare function buildWorkingTask(taskId: string, contextId: string, text: string, key: string): PlainTask;
+/**
+ * The terminal `completed` Task POSTed to the gatekeeper callback. The `messageId` is
+ * deterministic (`${taskId}:final`, not a fresh UUID) because this is built in the
+ * workflow body, which re-runs on replay: a random id would change on a notify-step
+ * retry and the gatekeeper would dedupe the final message as a new one and double-post.
+ */
+export declare function buildCompletedTask(taskId: string, contextId: string, reply: string): PlainTask;
+/**
+ * The terminal `failed` Task POSTed to the gatekeeper callback — an unexpected,
+ * non-transient failure aborted the turn.
+ *
+ * A2A v1.0 gives a task no structured error (`TaskStatus` is only
+ * `{state, message, timestamp}`), so the state *is* the failure signal and `text`
+ * is the only place to explain. Keep that text user-safe: the gatekeeper renders it
+ * to a human, under its own "⚠️ *Agent …* (failed):" prefix.
+ *
+ * Shares the `${taskId}:final` messageId with {@link buildCompletedTask} by
+ * design: a Task terminates exactly once and the two states are mutually
+ * exclusive, so only one of them is ever built and posted — and a notify retry
+ * re-posts that same one under the same dedupe key.
+ */
+export declare function buildFailedTask(taskId: string, contextId: string, text: string): PlainTask;
+/**
+ * Sign the callback JWT the gatekeeper verifies against our pinned card key. The
+ * protected header mirrors the card signature (`kid`+`jku`); `aud` must equal the
+ * exact webhook URL the gatekeeper handed us in the `taskPushNotificationConfig`.
+ */
+export declare function signCallbackJwt(privateJwk: JWK & {
+    kid: string;
+}, opts: {
+    jku: string;
+    aud: string;
+}): Promise<string>;
+/**
+ * POST a Task snapshot to the gatekeeper's push-notification webhook, wrapped in the
+ * v1.0 `StreamResponse` envelope. Returns the raw `Response` so the caller (the
+ * workflow's `notify` step) can decide whether a non-2xx warrants a retry.
+ */
+export declare function postNotification(url: string, token: string, jwt: string, task: Task): Promise<Response>;

package/dist/a2a/notify.js

@@ -0,0 +1,180 @@
+import { SignJWT } from "jose";
+import { TaskState } from "@a2a-js/sdk";
+import { V1PushNotificationSerializer } from "@a2a-js/sdk/server";
+import { A2A_JWS_ALG, NOTIFICATION_TOKEN_HEADER } from "@dynamicagents/g2a-protocol";
+import { agentTextMessage } from "./parts.js";
+/**
+ * Outbound push-notification (accept + notify) helpers — the "notify" half of the
+ * async A2A contract. The gatekeeper dispatches `SendMessage` with a
+ * `taskPushNotificationConfig` (webhook `url` + validation `token`), we accept
+ * immediately with a `submitted` Task, and later POST the terminal Task back to
+ * that webhook. This module builds the Task shapes and signs + sends that
+ * callback.
+ *
+ * The callback is authenticated exactly like the AgentCard: a short-lived EdDSA
+ * JWT signed by `A2A_SIGNING_KEY`, whose protected header `kid`+`jku` must equal
+ * the card's signing `kid`+`jku` (see {@link file://./card.ts} `signCard`) — the
+ * gatekeeper pinned those at registration (Trust-On-First-Use) and verifies the
+ * callback token against that same public JWKS. No shared secret crosses the
+ * boundary; only our public key is ever used to verify.
+ */
+/**
+ * The two shared values on this hop — the signature algorithm and the header
+ * carrying the per-task validation `token` — come from
+ * `@dynamicagents/g2a-protocol`, the same package the gatekeeper reads them from.
+ *
+ * The header used to be declared here and again in slack-gatekeeper, each with a
+ * comment naming the other file. It is a slightly different case from the claim
+ * names: the value is `@a2a-js/sdk`'s own default for `tokenHeaderName`, not
+ * Dynamic Agents' choice, but the SDK never *exports* it — it exists only as an
+ * inline fallback — so neither side could import it and both wrote it down.
+ *
+ * Re-exported so `@dynamicagents/core/a2a` keeps being where an agent finds it.
+ */
+export { NOTIFICATION_TOKEN_HEADER } from "@dynamicagents/g2a-protocol";
+/**
+ * Callback-JWT lifetime. The gatekeeper enforces `maxTokenAge: 10m` with a 60s clock
+ * tolerance, so keep this comfortably under that.
+ */
+const CALLBACK_TOKEN_TTL = "5m";
+/**
+ * The SDK's canonical v1.0 push-notification body encoder: the `StreamResponse`
+ * envelope as protobuf-JSON, with content type `application/a2a+json`. v1.0
+ * moved push notifications onto the same envelope the streaming transports use
+ * (v0.3 POSTed a bare `Task`), so the encoding is the SDK's rather than ours —
+ * the gatekeeper decodes it with `StreamResponse.fromJSON`.
+ */
+const PUSH_SERIALIZER = new V1PushNotificationSerializer();
+/** A Task snapshot in `state` carrying no message — nothing to say, only a state change. */
+function buildBareTask(taskId, contextId, state) {
+    return {
+        id: taskId,
+        contextId,
+        status: {
+            state,
+            message: undefined,
+            timestamp: new Date().toISOString()
+        },
+        artifacts: [],
+        history: [],
+        metadata: undefined
+    };
+}
+/**
+ * The `submitted` Task we return synchronously to accept a turn (A2A §7.2). The
+ * gatekeeper only requires a non-empty `id`; the actual reply follows later via the
+ * callback.
+ */
+export function buildSubmittedTask(taskId, contextId) {
+    return buildBareTask(taskId, contextId, TaskState.TASK_STATE_SUBMITTED);
+}
+/**
+ * The terminal `completed` Task for a turn the agent deliberately did not
+ * answer — a turn an `AgentPlugin.shouldHandleTurn` gate declined, or whatever
+ * else a host treats as "nothing to say". Same shape as
+ * {@link buildSubmittedTask}: **no `status.message` at all**.
+ *
+ * The callback is still POSTed. The gatekeeper's pending row has to resolve — we
+ * simply hand it nothing to post to Slack. There is no `messageId` because there
+ * is no message, so unlike {@link buildCompletedTask} nothing needs a stable id
+ * for the gatekeeper to dedupe on: a `notify`-step retry re-delivers no content and
+ * is idempotent by construction.
+ */
+export function buildNoReplyCompletedTask(taskId, contextId) {
+    return buildBareTask(taskId, contextId, TaskState.TASK_STATE_COMPLETED);
+}
+/**
+ * A Task snapshot POSTed to the gatekeeper callback in a given `state`, carrying one
+ * `agent` message. The gatekeeper reads the reply from `status.message.parts`, so
+ * the text lives there.
+ */
+function buildTaskUpdate(taskId, contextId, state, text, messageId) {
+    const task = buildBareTask(taskId, contextId, state);
+    task.status.message = agentTextMessage({
+        messageId,
+        text,
+        contextId,
+        taskId
+    });
+    return task;
+}
+/**
+ * A non-terminal `working` Task snapshot carrying an intermediate content message.
+ * Streamed live from the DO as the tool loop emits content before the final reply.
+ *
+ * `messageId` is derived from `${taskId}:${key}` — stable across re-runs (see
+ * {@link agentTextMessage}) so the gatekeeper dedupes correctly on workflow replay.
+ *
+ * `key` is a **semantic** string, not a step counter, and the distinction is
+ * load-bearing: an agent that runs several rounds per task emits progress from
+ * each, so a bare index makes round 0's third step and round 1's third step the
+ * same message to the gatekeeper — it dedupes the second away and the user watches
+ * a task go quiet. A caller that genuinely has one flat sequence can pass
+ * `String(i)`; one with rounds should key on both (`r1:step:3`), and milestones
+ * on what they are (`ack:1`).
+ */
+export function buildWorkingTask(taskId, contextId, text, key) {
+    return buildTaskUpdate(taskId, contextId, TaskState.TASK_STATE_WORKING, text, `${taskId}:${key}`);
+}
+/**
+ * The terminal `completed` Task POSTed to the gatekeeper callback. The `messageId` is
+ * deterministic (`${taskId}:final`, not a fresh UUID) because this is built in the
+ * workflow body, which re-runs on replay: a random id would change on a notify-step
+ * retry and the gatekeeper would dedupe the final message as a new one and double-post.
+ */
+export function buildCompletedTask(taskId, contextId, reply) {
+    return buildTaskUpdate(taskId, contextId, TaskState.TASK_STATE_COMPLETED, reply, `${taskId}:final`);
+}
+/**
+ * The terminal `failed` Task POSTed to the gatekeeper callback — an unexpected,
+ * non-transient failure aborted the turn.
+ *
+ * A2A v1.0 gives a task no structured error (`TaskStatus` is only
+ * `{state, message, timestamp}`), so the state *is* the failure signal and `text`
+ * is the only place to explain. Keep that text user-safe: the gatekeeper renders it
+ * to a human, under its own "⚠️ *Agent …* (failed):" prefix.
+ *
+ * Shares the `${taskId}:final` messageId with {@link buildCompletedTask} by
+ * design: a Task terminates exactly once and the two states are mutually
+ * exclusive, so only one of them is ever built and posted — and a notify retry
+ * re-posts that same one under the same dedupe key.
+ */
+export function buildFailedTask(taskId, contextId, text) {
+    return buildTaskUpdate(taskId, contextId, TaskState.TASK_STATE_FAILED, text, `${taskId}:final`);
+}
+/**
+ * Sign the callback JWT the gatekeeper verifies against our pinned card key. The
+ * protected header mirrors the card signature (`kid`+`jku`); `aud` must equal the
+ * exact webhook URL the gatekeeper handed us in the `taskPushNotificationConfig`.
+ */
+export async function signCallbackJwt(privateJwk, opts) {
+    return new SignJWT({})
+        .setProtectedHeader({
+        alg: A2A_JWS_ALG,
+        kid: privateJwk.kid,
+        jku: opts.jku
+    })
+        .setAudience(opts.aud)
+        .setIssuedAt()
+        .setExpirationTime(CALLBACK_TOKEN_TTL)
+        .sign(privateJwk);
+}
+/**
+ * POST a Task snapshot to the gatekeeper's push-notification webhook, wrapped in the
+ * v1.0 `StreamResponse` envelope. Returns the raw `Response` so the caller (the
+ * workflow's `notify` step) can decide whether a non-2xx warrants a retry.
+ */
+export async function postNotification(url, token, jwt, task) {
+    const { body, contentType } = PUSH_SERIALIZER.serialize({
+        payload: { $case: "task", value: task }
+    });
+    return fetch(url, {
+        method: "POST",
+        headers: {
+            "content-type": contentType,
+            authorization: `Bearer ${jwt}`,
+            [NOTIFICATION_TOKEN_HEADER]: token
+        },
+        body
+    });
+}

package/dist/a2a/parts.d.ts

@@ -0,0 +1,45 @@
+import { type Message, type Part } from "@a2a-js/sdk";
+import type { PlainMessage, PlainPart } from "./task.js";
+/**
+ * A `text` part carrying `text`. Typed as the narrowed {@link PlainPart} (which
+ * widens to `Part` for free) so a message built here can cross the DO RPC
+ * boundary — see {@link file://./task.ts}.
+ */
+export declare function textPart(text: string): PlainPart;
+/** Concatenate the text of every `text` part, trimming surrounding whitespace. */
+export declare function partsText(parts: Part[] | undefined): string;
+/** The plain-text content of an inbound A2A message (what the caller said). */
+export declare function textOf(message: Message): string;
+/**
+ * Bounds the inbound user text carried in a durable Workflow payload (UTF-8).
+ * Workflow params have a platform size limit, and a caller's message is the one
+ * unbounded thing that goes into them.
+ */
+export declare const MAX_INBOUND_TEXT_BYTES: number;
+/** Invalid inbound content that must not cross the A2A-to-workflow boundary. */
+export declare class InboundPartError extends Error {
+    constructor(message: string);
+}
+/**
+ * Extract and validate the user-turn text. Rejects a message with no usable
+ * text, and enforces a single UTF-8 size bound *before* the text enters a
+ * workflow payload — past that point the failure is a workflow that will not
+ * start, with no request left to answer on.
+ *
+ * File and data parts are deliberately out of scope: only text crosses into the
+ * agent runtime.
+ */
+export declare function inboundText(message: Message): string;
+/**
+ * An `agent`-role message carrying one text part, with the proto-required
+ * fields this agent never sets filled in. `messageId` is the gatekeeper's dedupe
+ * key, so callers pass a **stable** id (never a fresh random per attempt) — a
+ * callback the workflow/DO re-runs must reuse the same id or the gatekeeper
+ * treats the replay as a new message and double-posts.
+ */
+export declare function agentTextMessage(input: {
+    messageId: string;
+    text: string;
+    contextId: string;
+    taskId: string;
+}): PlainMessage;

package/dist/a2a/parts.js

@@ -0,0 +1,94 @@
+import { Role } from "@a2a-js/sdk";
+/**
+ * Constructors and readers for A2A v1.0 message content — the one place the
+ * adapter reaches into the `@a2a-js/sdk` message shape. Everything past
+ * {@link file://./executor.ts A2AExecutor} works in plain strings, so the agent
+ * runtime never sees an A2A type.
+ *
+ * The v1.0 data model is generated from the protobuf schema, so the wire types
+ * are "all fields present": a `Part` carries a `content` oneof discriminated by
+ * `$case` (plus `filename`/`mediaType`) instead of v0.3's `kind`, and a
+ * `Message` carries empty strings and empty arrays rather than omitted
+ * optionals. Hand-writing those literals at every call site is noisy and easy to
+ * get subtly wrong, so every part/message this agent emits is built here.
+ */
+/** Media type stamped on the text parts this agent emits. */
+const TEXT_MEDIA_TYPE = "text/plain";
+/**
+ * A `text` part carrying `text`. Typed as the narrowed {@link PlainPart} (which
+ * widens to `Part` for free) so a message built here can cross the DO RPC
+ * boundary — see {@link file://./task.ts}.
+ */
+export function textPart(text) {
+    return {
+        content: { $case: "text", value: text },
+        metadata: undefined,
+        filename: "",
+        mediaType: TEXT_MEDIA_TYPE
+    };
+}
+/** Concatenate the text of every `text` part, trimming surrounding whitespace. */
+export function partsText(parts) {
+    let out = "";
+    for (const part of parts ?? []) {
+        if (part.content?.$case === "text")
+            out += part.content.value;
+    }
+    return out.trim();
+}
+/** The plain-text content of an inbound A2A message (what the caller said). */
+export function textOf(message) {
+    return partsText(message.parts);
+}
+/**
+ * Bounds the inbound user text carried in a durable Workflow payload (UTF-8).
+ * Workflow params have a platform size limit, and a caller's message is the one
+ * unbounded thing that goes into them.
+ */
+export const MAX_INBOUND_TEXT_BYTES = 256 * 1024;
+const encoder = new TextEncoder();
+/** Invalid inbound content that must not cross the A2A-to-workflow boundary. */
+export class InboundPartError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InboundPartError";
+    }
+}
+/**
+ * Extract and validate the user-turn text. Rejects a message with no usable
+ * text, and enforces a single UTF-8 size bound *before* the text enters a
+ * workflow payload — past that point the failure is a workflow that will not
+ * start, with no request left to answer on.
+ *
+ * File and data parts are deliberately out of scope: only text crosses into the
+ * agent runtime.
+ */
+export function inboundText(message) {
+    const text = textOf(message);
+    if (!text) {
+        throw new InboundPartError("message has no usable text");
+    }
+    if (encoder.encode(text).byteLength > MAX_INBOUND_TEXT_BYTES) {
+        throw new InboundPartError("message text exceeds the size limit");
+    }
+    return text;
+}
+/**
+ * An `agent`-role message carrying one text part, with the proto-required
+ * fields this agent never sets filled in. `messageId` is the gatekeeper's dedupe
+ * key, so callers pass a **stable** id (never a fresh random per attempt) — a
+ * callback the workflow/DO re-runs must reuse the same id or the gatekeeper
+ * treats the replay as a new message and double-posts.
+ */
+export function agentTextMessage(input) {
+    return {
+        messageId: input.messageId,
+        role: Role.ROLE_AGENT,
+        parts: [textPart(input.text)],
+        contextId: input.contextId,
+        taskId: input.taskId,
+        metadata: undefined,
+        extensions: [],
+        referenceTaskIds: []
+    };
+}

package/dist/a2a/push.d.ts

@@ -0,0 +1,70 @@
+import type { Task } from "@a2a-js/sdk";
+import type { OnContent } from "../agent/inference.js";
+/**
+ * The gatekeeper callback channel for one accepted turn.
+ *
+ * Every agent that accepts asynchronously has to do the same four things with
+ * the push config the gatekeeper handed it: sign a callback JWT against the
+ * deployment's card key, POST `working` snapshots as the model reasons, POST the
+ * terminal Task, and never let a failed progress post take down a turn. That was
+ * written out longhand in four places across two agents in the starter — twice as
+ * a `streamWorking` closure inside a Durable Object, twice as a `notify` step
+ * inside a Workflow — with the signing, the header names and the swallow-and-log
+ * discipline duplicated each time.
+ *
+ * It is one object here because none of it is per-agent. What *is* per-agent is
+ * the notification **key**, and that is the one thing a caller supplies.
+ */
+/**
+ * Everything needed to call a gatekeeper back about one task.
+ *
+ * RPC-serializable by construction: it crosses the Workflow → Durable Object
+ * boundary on every turn, so it holds only strings.
+ */
+export interface TurnPushContext {
+    /** The accepted task id (echoed on every callback of this turn). */
+    taskId: string;
+    /** A2A context id, echoed on every callback. */
+    contextId: string;
+    /** Gatekeeper push-notification webhook (also the callback JWT `aud`). */
+    pushUrl: string;
+    /** Per-task validation token the gatekeeper set; echoed in the callback header. */
+    pushToken: string;
+    /** This agent's card-signing JWKS URL — the callback JWT `jku` (pinned key). */
+    jku: string;
+}
+export interface PushChannel {
+    /**
+     * POST one `working` Task snapshot, keyed by a stable semantic `key`.
+     *
+     * **Best-effort**: every failure is logged and swallowed, so a progress post
+     * can never abort generation or fail a durable step. The key is what lets the
+     * gatekeeper dedupe a re-posted event on replay, so it must be derived from
+     * position (`r2:step:3`), never from content or a clock.
+     */
+    working(text: string, key: string): Promise<void>;
+    /**
+     * An {@link OnContent} sink that posts each intermediate message as a
+     * `working` snapshot, signing the JWT once and reusing it across the turn.
+     *
+     * `key` maps a 0-based step ordinal to its notification key. An agent running
+     * one turn per task can use the bare index; an agent with rounds **must**
+     * include the round, or two rounds of one task collide on the gatekeeper.
+     */
+    stream(key: (stepIndex: number) => string): OnContent;
+    /**
+     * POST the terminal Task. **Throws on a non-2xx** so the calling Workflow step
+     * retries — the opposite of {@link working}, because this is the delivery the
+     * whole turn exists for.
+     */
+    deliver(task: Task): Promise<void>;
+}
+/**
+ * Build the callback channel for one turn.
+ *
+ * `signingKey` is the deployment's Ed25519 private JWK as JSON — `A2A_SIGNING_KEY`
+ * by default. There is one per origin, not one per agent: the card sits at a
+ * well-known URI, which RFC 8615 defines per-authority, so this origin publishes
+ * one card and the gatekeeper pins one key for every agent on it.
+ */
+export declare function createPushChannel(signingKey: string, push: TurnPushContext): PushChannel;

package/dist/a2a/push.js

@@ -0,0 +1,53 @@
+import { parsePrivateJwk } from "./card.js";
+import { buildWorkingTask, postNotification, signCallbackJwt } from "./notify.js";
+/**
+ * Build the callback channel for one turn.
+ *
+ * `signingKey` is the deployment's Ed25519 private JWK as JSON — `A2A_SIGNING_KEY`
+ * by default. There is one per origin, not one per agent: the card sits at a
+ * well-known URI, which RFC 8615 defines per-authority, so this origin publishes
+ * one card and the gatekeeper pins one key for every agent on it.
+ */
+export function createPushChannel(signingKey, push) {
+    // Signed lazily and reused: one turn can post many progress snapshots, and
+    // re-signing per message costs a key import each time for no benefit.
+    let jwt;
+    const sign = () => (jwt ??= signCallbackJwt(parsePrivateJwk(signingKey), {
+        jku: push.jku,
+        aud: push.pushUrl
+    }));
+    const post = async (task) => postNotification(push.pushUrl, push.pushToken, await sign(), task);
+    const working = async (text, key) => {
+        try {
+            const res = await post(buildWorkingTask(push.taskId, push.contextId, text, key));
+            if (!res.ok) {
+                console.warn("[push] working notification non-2xx", {
+                    taskId: push.taskId,
+                    key,
+                    status: res.status
+                });
+            }
+        }
+        catch (err) {
+            // Swallowed on purpose, including a signing failure: a turn that cannot
+            // report its progress is still a turn that should deliver its answer.
+            console.warn("[push] working notification failed", {
+                taskId: push.taskId,
+                key,
+                err: String(err)
+            });
+        }
+    };
+    return {
+        working,
+        stream(key) {
+            return (text, stepIndex) => working(text, key(stepIndex));
+        },
+        async deliver(task) {
+            const res = await post(task);
+            if (!res.ok) {
+                throw new Error(`gatekeeper notification failed: HTTP ${res.status}`);
+            }
+        }
+    };
+}

package/dist/a2a/self-origin.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 declare class SelfOrigin {
+    private 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: string | undefined): void;
+    /** The pinned origin, or `undefined` when nothing has carried one yet. */
+    peek(): string | undefined;
+    /**
+     * 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(): string;
+}