@nylorun/agents 0.30.0-beta → 0.31.0-beta

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @nylorun/agents
 
+## 0.31.0-beta
+
+### Minor Changes
+
+- d48b6ef: An A2A client for the Nylorun profile v2 (A2A-E12, E13, E16), on `@nylorun/agents/a2a` and the package root.
+
+  - **`createA2aClient({ url, key?, subject?, scopes?, headers?, fetch?, extensions?, cardUrl? })`**: `send`, `get`, `list`, `listAll`, `cancel`, `answer` (an interaction under `interactions/v1`), `card` and `call`, as A2A 1.0 JSON-RPC with `A2A-Version: 1.0` and the five profile extensions activated by `A2A-Extensions`. A subject is sent as `Nylorun-Subject` with `Nylorun-Scopes: sessions:own`. A JSON-RPC error is thrown as `A2aError` (`code`, `message`, `reason` from `google.rpc.ErrorInfo`); an HTTP refusal stays a `RuntimeError`.
+  - **`verifyA2aPush({ secret, headers, body, toleranceSeconds?, token? })`**: checks a push delivery's Standard Webhooks signature (`whsec_` secret, several signatures allowed, 300 s tolerance) with Web Crypto, and returns its `StreamResponse`; `A2aPushVerificationError` otherwise.
+  - **`A2A_EXTENSIONS`** and the readers `readInteraction`, `readProgress`, `readTelemetry`, `readEffects`, `readFiles` and `readExtension`, with the profile's types and the A2A 1.0 types (`Task`, `StreamResponse`, `AgentCard`, …; the root's namespace `A2a`).
+  - **`listTurnChanges({ baseUrl, key, changedAfter?, sessionId?, limit? })`**: the Runtime's change feed, `GET /v1/turns` (Host feature `turns`).
+  - **SSE idle timeout:** `session.observe` drops a connection that sends nothing, keepalives included, for `idleTimeoutMs` (default 45 s; `0` never) and reopens it from `Last-Event-ID`.
+
+### Patch Changes
+
+- d48b6ef: An agent manifest names the model its agent runs on (Host feature `agent-model`).
+
+  - **`harness.model`**: `<provider>/<model>`, such as `anthropic/claude-sonnet-4-5` (the provider's id, a `/`, then the model's id, which may hold a `/`; at most 200 characters). In an agent folder it is `model:` in `AGENT.md`'s frontmatter; the compiler refuses any other shape (`value_invalid`) and a `model` in an agent under `agents/`, which runs on the root agent's. `harness.manifest.json` takes it too, and the composer keeps it.
+  - **A new session starts on it.** A session opened on a version that names a model gets it as its own model (`GET /v1/sessions/{id}/model` answers `source: "session"`), as `PUT /v1/sessions/{id}/model` would choose it, when the provider is connected and its catalog lists the model. Otherwise the session has none and the Tenant's model applies; nothing fails. Sessions opened by the A2A server and by triggers get it too. An explicit choice still replaces it, and an open session keeps its model across versions.
+  - `agentModelChoice` and `AgentModelSchema` in `@nylorun/core/contracts`.
+  - The JSON Schema documents that gained the field are published at new ids: `agent-manifest/v8.1.json`, `harness-manifest/v1.1.json` and `agent-folder/v1/agent-md.1.json`; the old ids are retired. `manifestSchemaVersion` stays 8.
+
+- Pin core to the tested release.
+- Updated dependencies [d48b6ef]
+- Updated dependencies [d48b6ef]
+- Updated dependencies [d48b6ef]
+- Updated dependencies [d48b6ef]
+- Updated dependencies [d48b6ef]
+  - @nylorun/core@0.32.0-beta
+
 ## 0.30.0-beta
 
 ### Minor Changes

package/README.md

@@ -556,7 +556,7 @@ default release registry). Host contract:
 [HOST_CONTRACT.md](../../runtime/harness/HOST_CONTRACT.md). Vocabulary (turn loop vs
 workflow Loop): [runtime/harness/src/CONTEXT.md](../../runtime/harness/src/CONTEXT.md).
 
-Use `session.observe({ cursor, signal })` for resumable canonical events, `session.inspect()` for waiting/uncertain state, and `approve`, `respond` or `cancel` to answer or stop a turn. `cancel` takes an idempotency key; `approve(interactionId, approved)` and `respond(interactionId, value)` make one of their own when given none, so give them a stable one (`{ idempotencyKey }`) when you may retry. Retry the same semantic command with the same key. `ownerUserId` must come from trusted server authentication. Application credentials are not browser credentials; browser applications need an authorized backend. Definition authoring is browser-bundleable.
+Use `session.observe({ cursor, signal })` for resumable canonical events (a connection that sends nothing, not even its 15-second keepalive, for `idleTimeoutMs`, default 45 s, is dropped and reopened from the last event's `Last-Event-ID`; `0` never times out), `session.inspect()` for waiting/uncertain state, and `approve`, `respond` or `cancel` to answer or stop a turn. `cancel` takes an idempotency key; `approve(interactionId, approved)` and `respond(interactionId, value)` make one of their own when given none, so give them a stable one (`{ idempotencyKey }`) when you may retry. Retry the same semantic command with the same key. `ownerUserId` must come from trusted server authentication. Application credentials are not browser credentials; browser applications need an authorized backend. Definition authoring is browser-bundleable.
 
 Connection defaults follow `resolveConnection` (options → environment → Project
 link). Agents do not hash the manifest; a session pins the manifest version its Agent runs
@@ -701,16 +701,144 @@ What the Runtime answers (Host feature `a2a-endpoint`):
   `url` is `ContentTypeNotSupportedError`; a file of any type is accepted, and
   the agent's harness decides how its model sees it.
 - Clients must send `A2A-Version: 1.0` (header or `?A2A-Version=`).
-- Not yet: `ListTasks`, streaming and `SubscribeToTask`
-  (`UnsupportedOperationError`; the card says `streaming: false`), push
-  notifications, the extended card, and approvals. An agent that pauses for an
-  approval shows `INPUT_REQUIRED`, refuses a reply, and can be canceled, so do
-  not publish agents whose tools the Tenant's tool policy asks about yet.
+- Before Host feature `a2a-profile-v2`: no `ListTasks`, push notifications or
+  approvals. An agent that pauses for an approval shows `INPUT_REQUIRED`,
+  refuses a reply, and can be canceled, so on such a Runtime do not publish
+  agents whose tools the Tenant's tool policy asks about. Never: streaming and
+  `SubscribeToTask` (`UnsupportedOperationError`; the card says
+  `streaming: false`) and the extended card.
 - The handler calls the Runtime as the partner's subject with the scope
   `sessions:own` only, so one partner never reaches another's tasks. It sends
   no header the partner chose except `A2A-Version` and `A2A-Extensions`. Without
   `a2a-endpoint` on the Runtime it answers `502` (`runtime_feature_missing`).
 
+### Calling an agent: the A2A client
+
+`createA2aClient` calls one A2A agent's JSON-RPC endpoint: a Runtime's
+`/v1/a2a/agents/{agentId}`, a gateway's, or any A2A 1.0 agent. It sends
+`A2A-Version: 1.0` and activates the
+[Nylorun profile v2](https://docs.nylorun.com/a2a/profile/v2) extensions with
+`A2A-Extensions` (all five by default). It is plain `fetch` and loads no A2A
+package; it is also exported from the package root.
+
+<!-- doc-test: typescript -->
+```ts
+import { createA2aClient, readInteraction, readProgress } from "@nylorun/agents/a2a";
+
+const a2a = createA2aClient({
+  url: "https://agents.example.com/v1/a2a/agents/coding",
+  key: process.env.NYLORUN_SERVER_KEY, // Authorization: Bearer
+  subject: "u:org_1:user_1", // Nylorun-Subject, with Nylorun-Scopes: sessions:own
+});
+
+const task = await a2a.send({
+  messageId: crypto.randomUUID(), // the idempotency key: a retry answers the same task
+  parts: [{ text: "Build the portal from the wikis" }],
+  returnImmediately: true,
+  push: { url: "https://bot.example.com/a2a/push", token: "per-task-token" },
+});
+
+const latest = await a2a.get(task.id, { historyLength: 0 });
+console.log(readProgress(latest)?.steps);
+const open = readInteraction(latest); // an approval pauses the task as AUTH_REQUIRED
+if (open?.kind === "approval")
+  await a2a.answer({
+    taskId: latest.id,
+    contextId: latest.contextId,
+    interactionId: open.interactionId,
+    approved: true,
+    messageId: crypto.randomUUID(),
+  });
+```
+
+| Method | A2A operation |
+| --- | --- |
+| `send({ messageId, contextId?, taskId?, parts, metadata?, extensions?, delivery?, push?, returnImmediately?, historyLength?, traceparent? })` | `SendMessage`, answered with the task. A message to a busy context is queued; `delivery: "reject"` asks for `CONTEXT_BUSY` instead. `traceparent` joins the task to your trace |
+| `get(taskId, { historyLength? })` | `GetTask` |
+| `list({ contextId?, status?, statusTimestampAfter?, pageSize?, pageToken? })`, `listAll(...)` | `ListTasks`: one page, or every task page after page |
+| `cancel(taskId)` | `CancelTask` |
+| `answer({ taskId, contextId, interactionId, approved? \| value?, messageId })` | Answers an open interaction under `interactions/v1`: `approved` for an approval or a connection, `value` for a question |
+| `card()` | The Agent Card: `{url}/card` on a Runtime, else `{url}/.well-known/agent-card.json` (`cardUrl` overrides) |
+| `call(method, params)` | Any other JSON-RPC method |
+
+An error the agent answers in JSON-RPC is thrown as `A2aError` with its
+`code` (e.g. `-32001`), `message` and `reason` from `google.rpc.ErrorInfo`
+(e.g. `TASK_NOT_FOUND`, `CONTEXT_BUSY`). An HTTP refusal (`401`, an unknown
+agent's `404`, `429`) is a `RuntimeError` with its `status`.
+
+**Pushes.** Each delivery is a `POST` of one A2A `StreamResponse`, signed with
+[Standard Webhooks](https://www.standardwebhooks.com) and the installation's
+`whsec_` webhook secret. Verify the raw body before you parse it:
+
+<!-- doc-test: typescript -->
+```ts
+import { createServer } from "node:http";
+import { A2aPushVerificationError, readFiles, readTelemetry, verifyA2aPush } from "@nylorun/agents/a2a";
+
+createServer(async (req, res) => {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk as Buffer);
+  try {
+    const update = await verifyA2aPush({
+      secret: process.env.A2A_PUSH_SECRET!, // whsec_…
+      headers: req.headers,
+      body: Buffer.concat(chunks).toString("utf8"),
+      token: "per-task-token", // optional: X-A2A-Notification-Token must match
+    });
+    // Order status updates by status.timestamp: a delivery may come twice or late.
+    if ("statusUpdate" in update) console.log(update.statusUpdate.status.state, readTelemetry(update));
+    if ("artifactUpdate" in update) console.log(readFiles(update));
+    res.writeHead(204).end();
+  } catch (error) {
+    res.writeHead(error instanceof A2aPushVerificationError ? 401 : 500).end();
+  }
+}).listen(3000);
+```
+
+`verifyA2aPush` checks `webhook-id`, `webhook-timestamp` (at most
+`toleranceSeconds`, default 300, from now, either way) and every `v1,`
+signature in `webhook-signature` (several are allowed, as during a rotation),
+in constant time with Web Crypto, and returns the parsed `StreamResponse`. A
+failure is `A2aPushVerificationError` with its `reason`.
+
+**Profile v2 readers.** Each takes a task, a `StreamResponse`, a status
+update, a status, a message or an artifact, and returns `undefined` (`[]` for
+files) when the data is missing, as from an agent outside Nylorun:
+
+| Reader | Extension (`A2A_EXTENSIONS`) | Returns |
+| --- | --- | --- |
+| `readInteraction` | `interactions` | `{ interactionId, kind, prompt?, detail? }`: `approval`, `question` or `connection` |
+| `readProgress` | `progress` | `{ steps: [{ label, state, note? }] }`, the whole plan |
+| `readTelemetry` | `telemetry` | `{ totals?: { steps, tokens, costUsd }, traceId? }`, on the terminal update |
+| `readEffects` | `effects` | `{ uncertain? }`: the effect whose outcome was lost |
+| `readFiles` | `files` | `[{ artifact, file: { kind, path?, version?, size?, sha256? } }]` |
+| `readExtension(source, uri)` | any | The raw data under `uri` |
+
+**The change feed.** `listTurnChanges` reads a Runtime's `GET /v1/turns`
+(Host feature `turns`): the turns that changed after a cursor, in the order
+they changed. Poll it with the last `cursor` to find what a lost push would
+have said:
+
+<!-- doc-test: typescript -->
+```ts
+import { listTurnChanges } from "@nylorun/agents";
+
+let cursor: string | undefined;
+const page = await listTurnChanges({
+  baseUrl: "https://agents.example.com",
+  key: process.env.NYLORUN_SERVER_KEY!, // the whole Tenant; add `subject` for one subject's turns
+  ...(cursor ? { changedAfter: cursor } : {}),
+  limit: 200,
+});
+for (const turn of page.turns) console.log(turn.status, turn.a2a?.taskId, turn.totals?.costUsd);
+cursor = page.cursor; // returned even when nothing changed
+```
+
+The A2A 1.0 types (`Task`, `Message`, `Part`, `Artifact`,
+`TaskStatusUpdateEvent`, `TaskArtifactUpdateEvent`, `StreamResponse`,
+`AgentCard`, `ListTasksResult`, `TaskState`) are exported from
+`@nylorun/agents/a2a`, and from the root as the namespace `A2a` (`A2a.Task`).
+
 ## Files: artifacts and message parts
 
 Files users upload or agents make are **artifacts** (protocol 6): an id, a name and

package/dist/a2a/client-api.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The A2A client side of `@nylorun/agents/a2a`, also exported from the package root: it loads
+ * no Node-only module (the gateway's `toNodeListener` does).
+ */
+export { A2A_VERSION, A2aError, createA2aClient, listTurnChanges, } from "./client.js";
+export type { A2aAnswerOptions, A2aClient, A2aClientOptions, A2aListOptions, A2aSendOptions, ListTurnChangesOptions, TurnChange, TurnChangesPage, } from "./client.js";
+export { A2aPushVerificationError, verifyA2aPush } from "./push.js";
+export type { A2aPushFailure, PushHeaders, VerifyA2aPushOptions } from "./push.js";
+export { A2A_EXTENSIONS, A2A_PROFILE_EXTENSIONS, readEffects, readExtension, readFiles, readInteraction, readProgress, readTelemetry, } from "./profile.js";
+export type { A2aEffects, A2aExtensionUri, A2aFile, A2aFileArtifact, A2aInteraction, A2aPlanStep, A2aPlanStepState, A2aProgress, A2aTelemetry, } from "./profile.js";

package/dist/a2a/client-api.js

@@ -0,0 +1,7 @@
+/**
+ * The A2A client side of `@nylorun/agents/a2a`, also exported from the package root: it loads
+ * no Node-only module (the gateway's `toNodeListener` does).
+ */
+export { A2A_VERSION, A2aError, createA2aClient, listTurnChanges, } from "./client.js";
+export { A2aPushVerificationError, verifyA2aPush } from "./push.js";
+export { A2A_EXTENSIONS, A2A_PROFILE_EXTENSIONS, readEffects, readExtension, readFiles, readInteraction, readProgress, readTelemetry, } from "./profile.js";

package/dist/a2a/client.d.ts

@@ -0,0 +1,178 @@
+import { type SubjectScope } from "@nylorun/core/contracts";
+import type { AgentCard, ListTasksResult, Metadata, Part, PushNotificationConfig, Task, TaskState } from "./types.js";
+/** The A2A version the client speaks (`A2A-Version`). */
+export declare const A2A_VERSION = "1.0";
+/**
+ * An error the agent answered in JSON-RPC: `code` is the JSON-RPC or A2A code (e.g. `-32001`
+ * for a task that is not found), `reason` the `google.rpc.ErrorInfo` reason (e.g.
+ * `TASK_NOT_FOUND`, `CONTEXT_BUSY`). HTTP-level refusals (`401`, `404` for an unknown agent,
+ * `429`) are `RuntimeError`s, as everywhere in the SDK.
+ */
+export declare class A2aError extends Error {
+    readonly code: number;
+    readonly reason: string | undefined;
+    /** `google.rpc.ErrorInfo` metadata. */
+    readonly metadata: Readonly<Record<string, string>>;
+    /** The error's `data` as sent. */
+    readonly data?: unknown;
+    constructor(code: number, message: string, reason: string | undefined, 
+    /** `google.rpc.ErrorInfo` metadata. */
+    metadata?: Readonly<Record<string, string>>, 
+    /** The error's `data` as sent. */
+    data?: unknown);
+}
+export interface A2aClientOptions {
+    /** The agent's A2A endpoint, e.g. `${runtimeUrl}/v1/a2a/agents/${agentId}`. */
+    url: string;
+    /** A Nylorun application key, sent as `Authorization: Bearer`. */
+    key?: string;
+    /**
+     * The subject the calls act for (`Nylorun-Subject`, with `Nylorun-Scopes`): its own
+     * contexts and tasks only. Required by the Runtime with an application key, e.g.
+     * `u:<org>:<user>`.
+     */
+    subject?: string;
+    /** The subject's scopes. Default `["sessions:own"]`. */
+    scopes?: readonly SubjectScope[];
+    /** Sent on every request, e.g. a gateway's partner key. */
+    headers?: Readonly<Record<string, string>>;
+    fetch?: typeof fetch;
+    /** The extensions to activate (`A2A-Extensions`). Default: all five of profile v2. */
+    extensions?: readonly string[];
+    /**
+     * Where the Agent Card is. Default: `${url}/card` for a Runtime's `/v1/a2a/agents/{id}`,
+     * else `${url}/.well-known/agent-card.json` (the gateway's).
+     */
+    cardUrl?: string;
+}
+export interface A2aSendOptions {
+    /** The idempotency key: a retried message answers with the same task. */
+    messageId: string;
+    /** Omit to start a new context. */
+    contextId?: string;
+    /** To continue an interrupted task. */
+    taskId?: string;
+    parts: Part[];
+    metadata?: Metadata;
+    /** The extension URIs whose data `metadata` carries (the message's `extensions`). */
+    extensions?: string[];
+    /**
+     * What a message to a busy context does: `queue` (profile v2's default) is answered with the
+     * task that will take it; `reject` is `A2aError` with reason `CONTEXT_BUSY`. Sent as
+     * `metadata.delivery`.
+     */
+    delivery?: "queue" | "reject";
+    /** Where the agent pushes this task's updates; verify each with `verifyA2aPush`. */
+    push?: PushNotificationConfig;
+    /** Answer at once with the task (`SUBMITTED` or `WORKING`) instead of waiting. */
+    returnImmediately?: boolean;
+    historyLength?: number;
+    acceptedOutputModes?: string[];
+    /** W3C trace context: the task joins the caller's trace. */
+    traceparent?: string;
+    signal?: AbortSignal;
+}
+export interface A2aListOptions {
+    contextId?: string;
+    status?: TaskState;
+    /** ISO 8601: tasks whose status changed after this time. */
+    statusTimestampAfter?: string;
+    /** At most 100; the agent's default is 50. */
+    pageSize?: number;
+    pageToken?: string;
+    historyLength?: number;
+    signal?: AbortSignal;
+}
+export interface A2aAnswerOptions {
+    taskId: string;
+    contextId: string;
+    /** The `interactionId` from `readInteraction`. */
+    interactionId: string;
+    /** For an approval. */
+    approved?: boolean;
+    /** For a question. */
+    value?: unknown;
+    messageId: string;
+    signal?: AbortSignal;
+}
+export interface A2aClient {
+    readonly url: string;
+    /** `SendMessage`: the task that runs (or will run) the message. */
+    send(options: A2aSendOptions): Promise<Task>;
+    /** `GetTask`. */
+    get(taskId: string, options?: {
+        historyLength?: number;
+        signal?: AbortSignal;
+    }): Promise<Task>;
+    /** `ListTasks`: one page of the caller's tasks, newest change first. */
+    list(options?: A2aListOptions): Promise<ListTasksResult>;
+    /** Every task `list` matches, page after page. */
+    listAll(options?: Omit<A2aListOptions, "pageToken">): AsyncGenerator<Task>;
+    /** `CancelTask`. */
+    cancel(taskId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Task>;
+    /**
+     * Answers an open interaction (`interactions/v1`) on its task: `approved` for an approval or
+     * a connection, `value` for a question.
+     */
+    answer(options: A2aAnswerOptions): Promise<Task>;
+    /** The agent's card. */
+    card(options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentCard>;
+    /** One JSON-RPC call, for operations the client has no method for. */
+    call<T = unknown>(method: string, params: Record<string, unknown>, options?: {
+        headers?: Readonly<Record<string, string>>;
+        signal?: AbortSignal;
+    }): Promise<T>;
+}
+export declare function createA2aClient(options: A2aClientOptions): A2aClient;
+/** One turn as the change feed lists it (Host feature `turns`). */
+export interface TurnChange {
+    turnId: string;
+    sessionId: string;
+    agentId: string;
+    status: "running" | "paused" | "completed" | "failed" | "cancelled";
+    startedAt: string;
+    endedAt: string | null;
+    /** When it last changed: a turn reappears each time it changes. */
+    changedAt: string;
+    totals: {
+        steps: number;
+        tokens: number;
+        costUsd: number;
+    } | null;
+    /** The A2A context and task it is, when it came in over A2A. */
+    a2a: {
+        contextId: string;
+        taskId: string;
+    } | null;
+}
+export interface TurnChangesPage {
+    turns: TurnChange[];
+    /** Pass as `changedAfter` next time; returned even when `turns` is empty. */
+    cursor: string;
+    hasMore: boolean;
+}
+export interface ListTurnChangesOptions {
+    /** The Runtime's URL, e.g. `https://agents.example`. */
+    baseUrl: string;
+    /** An application key sees the whole Tenant; with `subject`, only that subject's sessions. */
+    key: string;
+    subject?: string;
+    scopes?: readonly SubjectScope[];
+    /** The `cursor` of the previous page. Omit to start from the beginning. */
+    changedAfter?: string;
+    /** One session's turns instead of the feed. */
+    sessionId?: string;
+    /** 1 to 500; the Runtime's default is 100. */
+    limit?: number;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}
+/**
+ * `GET /v1/turns`: the turns that changed after `changedAfter`, in the order they changed. Call
+ * it on an interval with the last `cursor` to find what a lost push would have said.
+ */
+export declare function listTurnChanges(options: ListTurnChangesOptions): Promise<TurnChangesPage>;

package/dist/a2a/client.js

@@ -0,0 +1,227 @@
+/**
+ * An A2A 1.0 client for one agent's JSON-RPC endpoint (a Nylorun Runtime's
+ * `/v1/a2a/agents/{agentId}`, the SDK gateway, or any A2A agent), with the Nylorun profile v2's
+ * extensions activated, and the Runtime's change feed (`GET /v1/turns`). Plain `fetch`: it loads
+ * no A2A package and needs no Runtime client.
+ */
+import { SCOPES_HEADER, SUBJECT_HEADER } from "@nylorun/core/compatibility";
+import { parseSubjectHeaders } from "@nylorun/core/contracts";
+import { readBody, requestHeaders } from "@nylorun/core/transport";
+import { RuntimeError } from "../http.js";
+import { A2A_EXTENSIONS, A2A_PROFILE_EXTENSIONS } from "./profile.js";
+/** The A2A version the client speaks (`A2A-Version`). */
+export const A2A_VERSION = "1.0";
+/**
+ * An error the agent answered in JSON-RPC: `code` is the JSON-RPC or A2A code (e.g. `-32001`
+ * for a task that is not found), `reason` the `google.rpc.ErrorInfo` reason (e.g.
+ * `TASK_NOT_FOUND`, `CONTEXT_BUSY`). HTTP-level refusals (`401`, `404` for an unknown agent,
+ * `429`) are `RuntimeError`s, as everywhere in the SDK.
+ */
+export class A2aError extends Error {
+    code;
+    reason;
+    metadata;
+    data;
+    constructor(code, message, reason, 
+    /** `google.rpc.ErrorInfo` metadata. */
+    metadata = {}, 
+    /** The error's `data` as sent. */
+    data) {
+        super(message);
+        this.code = code;
+        this.reason = reason;
+        this.metadata = metadata;
+        this.data = data;
+        this.name = "A2aError";
+    }
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The `A2aError` a JSON-RPC error object stands for, or `undefined` when it isn't one. */
+function errorOf(body) {
+    if (!isObject(body) || !isObject(body.error))
+        return undefined;
+    const { code, message, data } = body.error;
+    if (typeof code !== "number")
+        return undefined;
+    const info = Array.isArray(data)
+        ? data.find((entry) => isObject(entry) && entry["@type"] === "type.googleapis.com/google.rpc.ErrorInfo")
+        : undefined;
+    const metadata = {};
+    if (info && isObject(info.metadata))
+        for (const [name, value] of Object.entries(info.metadata))
+            if (typeof value === "string")
+                metadata[name] = value;
+    return new A2aError(code, typeof message === "string" ? message : `A2A error ${code}`, info && typeof info.reason === "string" ? info.reason : undefined, metadata, data);
+}
+function fetcherOf(fetcher) {
+    // Called as a method on a page's window would otherwise lose `this`.
+    return fetcher ?? ((input, init) => globalThis.fetch(input, init));
+}
+const RUNTIME_ENDPOINT = /\/v1\/a2a\/agents\/[^/]+$/;
+export function createA2aClient(options) {
+    const url = options.url.replace(/\/+$/, "");
+    if (!/^https?:\/\//.test(url))
+        throw new TypeError("createA2aClient: url must be an http(s) URL");
+    const fetcher = fetcherOf(options.fetch);
+    const base = {
+        ...options.headers,
+        ...requestHeaders(options.key),
+        "A2A-Version": A2A_VERSION,
+    };
+    if (options.subject !== undefined) {
+        const parsed = parseSubjectHeaders(options.subject, [...(options.scopes ?? ["sessions:own"])].join(" "));
+        if (!parsed.ok)
+            throw new TypeError(parsed.message);
+        base[SUBJECT_HEADER] = options.subject;
+        base[SCOPES_HEADER] = [...parsed.scopes].join(" ");
+    }
+    const extensions = [...(options.extensions ?? A2A_PROFILE_EXTENSIONS)];
+    if (extensions.length > 0)
+        base["A2A-Extensions"] = extensions.join(", ");
+    const cardUrl = options.cardUrl ??
+        (RUNTIME_ENDPOINT.test(new URL(url).pathname) ? `${url}/card` : `${url}/.well-known/agent-card.json`);
+    async function call(method, params, init = {}) {
+        const response = await fetcher(url, {
+            method: "POST",
+            headers: { ...base, ...init.headers, "Content-Type": "application/json" },
+            body: JSON.stringify({ jsonrpc: "2.0", id: crypto.randomUUID(), method, params }),
+            redirect: "error",
+            ...(init.signal ? { signal: init.signal } : {}),
+        });
+        const body = await readBody(response);
+        // Some agents answer a JSON-RPC error with an HTTP error status: it is still an A2A error.
+        const error = errorOf(body);
+        if (error)
+            throw error;
+        if (!response.ok)
+            throw new RuntimeError(response.status, body);
+        if (!isObject(body) || !("result" in body))
+            throw new A2aError(-32603, "The agent's answer is not a JSON-RPC response", undefined, {}, body);
+        return body.result;
+    }
+    async function sendMessage(message, options) {
+        const configuration = {};
+        if (options.returnImmediately !== undefined)
+            configuration.returnImmediately = options.returnImmediately;
+        if (options.push)
+            configuration.taskPushNotificationConfig = { ...options.push };
+        if (options.historyLength !== undefined)
+            configuration.historyLength = options.historyLength;
+        if (options.acceptedOutputModes)
+            configuration.acceptedOutputModes = [...options.acceptedOutputModes];
+        const result = await call("SendMessage", { message, ...(Object.keys(configuration).length ? { configuration } : {}) }, {
+            ...(options.traceparent ? { headers: { traceparent: options.traceparent } } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        if (isObject(result) && isObject(result.task))
+            return result.task;
+        throw new A2aError(-32603, "The agent answered with a message, not a task", undefined, {}, result);
+    }
+    async function list(listOptions = {}) {
+        const { signal, ...params } = listOptions;
+        return call("ListTasks", { ...params }, signal ? { signal } : {});
+    }
+    return {
+        url,
+        call,
+        send(send) {
+            const metadata = {
+                ...send.metadata,
+                ...(send.delivery ? { delivery: send.delivery } : {}),
+            };
+            return sendMessage({
+                messageId: send.messageId,
+                role: "ROLE_USER",
+                parts: send.parts,
+                ...(send.contextId !== undefined ? { contextId: send.contextId } : {}),
+                ...(send.taskId !== undefined ? { taskId: send.taskId } : {}),
+                ...(send.extensions?.length ? { extensions: [...send.extensions] } : {}),
+                ...(Object.keys(metadata).length ? { metadata } : {}),
+            }, send);
+        },
+        get(taskId, getOptions = {}) {
+            return call("GetTask", {
+                id: taskId,
+                ...(getOptions.historyLength !== undefined
+                    ? { historyLength: getOptions.historyLength }
+                    : {}),
+            }, getOptions.signal ? { signal: getOptions.signal } : {});
+        },
+        list,
+        async *listAll(listOptions = {}) {
+            let pageToken;
+            do {
+                const page = await list({ ...listOptions, ...(pageToken ? { pageToken } : {}) });
+                yield* page.tasks;
+                pageToken = page.nextPageToken || undefined;
+            } while (pageToken);
+        },
+        cancel(taskId, cancelOptions = {}) {
+            return call("CancelTask", { id: taskId }, cancelOptions.signal ? { signal: cancelOptions.signal } : {});
+        },
+        async answer(answer) {
+            const hasApproval = answer.approved !== undefined;
+            const hasValue = answer.value !== undefined;
+            if (hasApproval === hasValue)
+                throw new TypeError("answer: give exactly one of approved and value");
+            const reply = hasApproval ? { approved: answer.approved } : { value: answer.value };
+            return sendMessage({
+                messageId: answer.messageId,
+                role: "ROLE_USER",
+                taskId: answer.taskId,
+                contextId: answer.contextId,
+                parts: [{ data: reply }],
+                extensions: [A2A_EXTENSIONS.interactions],
+                metadata: {
+                    [A2A_EXTENSIONS.interactions]: { interactionId: answer.interactionId, ...reply },
+                },
+            }, answer.signal ? { signal: answer.signal } : {});
+        },
+        async card(cardOptions = {}) {
+            const { "A2A-Extensions": _extensions, ...headers } = base;
+            const response = await fetcher(cardUrl, {
+                headers,
+                redirect: "error",
+                ...(cardOptions.signal ? { signal: cardOptions.signal } : {}),
+            });
+            const body = await readBody(response);
+            if (!response.ok)
+                throw new RuntimeError(response.status, body);
+            return body;
+        },
+    };
+}
+/**
+ * `GET /v1/turns`: the turns that changed after `changedAfter`, in the order they changed. Call
+ * it on an interval with the last `cursor` to find what a lost push would have said.
+ */
+export async function listTurnChanges(options) {
+    const baseUrl = options.baseUrl.replace(/\/+$/, "");
+    if (!/^https?:\/\//.test(baseUrl))
+        throw new TypeError("listTurnChanges: baseUrl must be an http(s) URL");
+    const query = new URLSearchParams();
+    if (options.changedAfter !== undefined)
+        query.set("changedAfter", options.changedAfter);
+    if (options.sessionId !== undefined)
+        query.set("sessionId", options.sessionId);
+    if (options.limit !== undefined)
+        query.set("limit", String(options.limit));
+    const headers = { ...requestHeaders(options.key) };
+    if (options.subject !== undefined) {
+        const parsed = parseSubjectHeaders(options.subject, [...(options.scopes ?? ["sessions:own"])].join(" "));
+        if (!parsed.ok)
+            throw new TypeError(parsed.message);
+        headers[SUBJECT_HEADER] = options.subject;
+        headers[SCOPES_HEADER] = [...parsed.scopes].join(" ");
+    }
+    const search = query.size ? `?${query}` : "";
+    const response = await fetcherOf(options.fetch)(`${baseUrl}/v1/turns${search}`, {
+        headers,
+        redirect: "error",
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    const body = await readBody(response);
+    if (!response.ok)
+        throw new RuntimeError(response.status, body);
+    return body;
+}

package/dist/a2a/handler.js

@@ -104,7 +104,13 @@ export function createA2aHandler(options) {
             if (response.ok)
                 return new Response(response.body, {
                     status: response.status,
-                    headers: { "content-type": response.headers.get("content-type") ?? "application/json" },
+                    headers: {
+                        "content-type": response.headers.get("content-type") ?? "application/json",
+                        // The extensions the agent activated (A2A §4.6), echoed to the partner.
+                        ...(response.headers.get("a2a-extensions")
+                            ? { "A2A-Extensions": response.headers.get("a2a-extensions") }
+                            : {}),
+                    },
                 });
             await response.body?.cancel().catch(() => { });
             if (response.status === 404)

package/dist/a2a/index.d.ts

@@ -1,8 +1,11 @@
 /**
  * `@nylorun/agents/a2a`: serve the Tenant's agents to A2A clients through the app's own server
- * (gateway mode). The handler forwards A2A requests to the Runtime, which speaks the protocol;
- * this entry point loads no A2A package.
+ * (gateway mode), and call A2A agents with the Nylorun profile v2 (the client, push
+ * verification, the extensions' readers and the change feed). The handler forwards A2A requests
+ * to the Runtime, which speaks the protocol; this entry point loads no A2A package.
  */
 export { createA2aHandler } from "./handler.js";
 export type { A2aCaller, A2aCardOptions, A2aHandler, A2aHandlerOptions, } from "./handler.js";
 export { toNodeListener } from "../ag-ui/node.js";
+export * from "./client-api.js";
+export type { AgentCapabilities, AgentCard, AgentExtension, AgentInterface, AgentSkill, Artifact, ListTasksResult, Message, Metadata, Part, PushNotificationConfig, Role, StreamResponse, Task, TaskArtifactUpdateEvent, TaskState, TaskStatus, TaskStatusUpdateEvent, } from "./types.js";