@vallum/standards 0.0.0-prerelease

package/README.md

@@ -0,0 +1,56 @@
+# @vallum/standards
+
+Standards bridge adapters for Vallum.
+
+Current surface:
+
+- x402 v2 payment requirement to Agent Transaction Manifest mapping.
+- Local mock x402 facilitator flow wired through the Vallum policy
+  gateway evaluator.
+- x402 external payment receipt linkage and log-safe payment metadata redaction.
+- AP2 checkout/payment mandate to Agent Transaction Manifest mapping.
+- Local mock AP2 mandate flow wired through the Vallum policy gateway
+  evaluator.
+- AP2 receipt evidence linkage, dispute evidence pointers, and log-safe
+  mandate metadata redaction.
+- A2A Agent Card mapping from Vallum Agent Profiles using current
+  discovery fields, auth declarations, supported interfaces, modes, and skills.
+- A2A public-card hardening that fails closed for revoked/expired profiles,
+  unsupported local protocol versions, malformed auth declarations, and private
+  profile fields in public metadata.
+- A2A Agent Card JWS signing and trusted-key verification helpers for local
+  signed-card proof.
+- A2A well-known response helpers for serving local Agent Cards at the
+  canonical `/.well-known/agent-card.json` path.
+- A2A JWKS response helpers for serving explicitly configured public signing
+  keys at the canonical `/.well-known/jwks.json` path without private key
+  material.
+- Local/mock A2A task and message operation helpers for send-message,
+  get-task, list-tasks, and cancel-task semantics, gated by Vallum
+  manifest/policy metadata and log-safe redaction.
+- Local HTTP-shaped A2A handler for public Agent Card discovery and
+  bearer-authenticated task send/get/list/cancel routes.
+- Authenticated local A2A extended Agent Card access through the HTTP-shaped
+  handler when an extended card is explicitly configured.
+- Local A2A push notification configuration CRUD that accepts public HTTPS
+  callback URLs while rejecting webhook credential storage and unsafe local
+  destinations.
+- Local injected A2A push delivery envelopes that POST sanitized task payloads
+  through an explicit transport without default outbound webhook calls.
+- Opt-in A2A push HTTP transport helper that posts sanitized task payloads only
+  when explicitly injected, rejects unsafe callback URLs before network
+  contact, does not emit authorization headers, uses manual redirect handling,
+  applies a timeout, and returns status-only results.
+- Local A2A push retry and in-memory attempt observability for explicitly
+  injected transports, recording status-only attempt metadata without request
+  bodies or credential material.
+- Loopback-only Node HTTP server helper for deterministic local A2A discovery
+  and task route smoke proof, including optional local JWKS serving, with
+  explicit unsafe opt-in required for non-loopback binds.
+
+This package does not operate a production x402 facilitator, replace AP2, hold
+payment credentials, sign payment payloads, submit live settlement
+transactions, operate a live public A2A task/message server, publish public A2A
+discovery, prove public A2A push/webhook infrastructure, operate production
+push queues/workers, prove external A2A conformance or live A2A discovery,
+provide production Agent Card key management, or replace the A2A protocol.

package/dist/a2a.d.ts

@@ -0,0 +1 @@
+export { A2A_AGENT_CARD_MEDIA_TYPE, A2A_AGENT_CARD_PROTOCOL_VERSION, A2A_AGENT_CARD_WELL_KNOWN_PATH, AGENTIC_VALLUM_A2A_PROFILE_EXTENSION_URI, A2AAgentCardError, createA2AAgentCardWellKnownResponse, createA2AAgentCardFromProfile, canonicalizeA2AAgentCard, handleA2AAgentCardWellKnownRequest, signA2AAgentCard, verifyA2AAgentCardSignature, type A2AAgentCapabilities, type A2AAgentCard, type A2AAgentCardErrorCode, type A2AAgentCardSignature, type A2AAgentCardSignatureAlgorithm, type A2AAgentCardSignatureVerification, type A2AAgentCardWellKnownOptions, type A2AAgentCardWellKnownResponse, type A2AAgentExtension, type A2AAgentInterface, type A2AAgentProvider, type A2AAgentSkill, type A2AWellKnownErrorCode, type A2AWellKnownErrorResponse, type A2AWellKnownRequest, type A2AWellKnownResponse, type A2AProtocolBinding, type A2ASecurityRequirement, type A2ASecurityScheme, type CreateA2AAgentCardOptions, type SignA2AAgentCardOptions, type SignedA2AAgentCard, type VerifyA2AAgentCardSignatureOptions, } from "@vallum/registry";

package/dist/a2a.js

@@ -0,0 +1 @@
+export { A2A_AGENT_CARD_MEDIA_TYPE, A2A_AGENT_CARD_PROTOCOL_VERSION, A2A_AGENT_CARD_WELL_KNOWN_PATH, AGENTIC_VALLUM_A2A_PROFILE_EXTENSION_URI, A2AAgentCardError, createA2AAgentCardWellKnownResponse, createA2AAgentCardFromProfile, canonicalizeA2AAgentCard, handleA2AAgentCardWellKnownRequest, signA2AAgentCard, verifyA2AAgentCardSignature, } from "@vallum/registry";

package/dist/a2aHttp.d.ts

@@ -0,0 +1,63 @@
+import { type A2AAgentCardWellKnownOptions } from "@vallum/registry";
+import type { AgentActionPolicy } from "@vallum/policy-gateway";
+import { type A2APushNotificationTransport, type A2ATaskPushNotificationConfig, type LocalA2APushNotificationStore } from "./a2aPush.js";
+import { type A2ATask, type A2AProcessMessageContext, type A2AProcessMessageResult, type LocalA2ATaskStore } from "./a2aTask.js";
+export interface A2AHttpRequest {
+    readonly method?: string;
+    readonly path?: string;
+    readonly headers?: Record<string, string | undefined>;
+    readonly body?: unknown;
+}
+export type A2AHttpResponseBody = {
+    readonly kind: "agent-card";
+    readonly [key: string]: unknown;
+} | {
+    readonly kind: "task";
+    readonly task: A2ATask;
+    readonly policyDecision?: unknown;
+} | {
+    readonly kind: "task-list";
+    readonly tasks: readonly A2ATask[];
+} | {
+    readonly kind: "push-config";
+    readonly config: A2ATaskPushNotificationConfig;
+} | {
+    readonly kind: "push-config-list";
+    readonly configs: readonly A2ATaskPushNotificationConfig[];
+    readonly nextPageToken?: string;
+} | {
+    readonly kind: "push-config-deleted";
+    readonly taskId: string;
+    readonly id: string;
+    readonly deleted: boolean;
+} | {
+    readonly error: {
+        readonly code: A2AHttpErrorCode | string;
+        readonly message: string;
+    };
+};
+export interface A2AHttpResponse {
+    readonly status: 200 | 400 | 401 | 404 | 405 | 409 | 410 | 415 | 501 | 503;
+    readonly headers: Record<string, string>;
+    readonly body: A2AHttpResponseBody;
+    readonly json: string;
+}
+export type A2AHttpErrorCode = "A2A_AUTH_NOT_CONFIGURED" | "A2A_AUTH_REQUIRED" | "A2A_BODY_INVALID" | "A2A_EXTENDED_AGENT_CARD_NOT_CONFIGURED" | "A2A_ROUTE_NOT_FOUND" | "A2A_METHOD_NOT_ALLOWED" | "A2A_VERSION_NOT_SUPPORTED" | "A2A_OPERATION_UNSUPPORTED" | "A2A_POLICY_NOT_CONFIGURED" | "A2A_INTERNAL_ERROR";
+export interface LocalA2AHttpHandlerOptions {
+    readonly store: LocalA2ATaskStore;
+    readonly agentCardProfile?: unknown;
+    readonly agentCardOptions?: A2AAgentCardWellKnownOptions;
+    readonly extendedAgentCardProfile?: unknown;
+    readonly extendedAgentCardOptions?: A2AAgentCardWellKnownOptions;
+    readonly taskAuthToken?: string;
+    readonly taskPolicy?: AgentActionPolicy;
+    readonly pushNotificationStore?: LocalA2APushNotificationStore;
+    readonly pushNotificationTransport?: A2APushNotificationTransport;
+    readonly now?: () => Date;
+    readonly processMessage?: (context: A2AProcessMessageContext) => Promise<A2AProcessMessageResult> | A2AProcessMessageResult;
+}
+export declare const A2A_HTTP_SEND_MESSAGE_PATH: "/message:send";
+export declare const A2A_HTTP_STREAM_MESSAGE_PATH: "/message:stream";
+export declare const A2A_HTTP_EXTENDED_AGENT_CARD_PATH: "/extendedAgentCard";
+export declare const A2A_HTTP_TASKS_PATH: "/tasks";
+export declare function handleLocalA2AHttpRequest(request: A2AHttpRequest, options: LocalA2AHttpHandlerOptions): Promise<A2AHttpResponse>;

package/dist/a2aHttp.js

@@ -0,0 +1,338 @@
+import { A2A_AGENT_CARD_WELL_KNOWN_PATH, handleA2AAgentCardWellKnownRequest, } from "@vallum/registry";
+import { A2APushNotificationError, createA2APushNotificationConfig, deleteA2APushNotificationConfig, deliverA2APushNotifications, getA2APushNotificationConfig, listA2APushNotificationConfigs, } from "./a2aPush.js";
+import { A2A_TASK_MEDIA_TYPE, A2A_TASK_PROTOCOL_VERSION, A2ATaskError, cancelA2ATask, getA2ATask, listA2ATasks, sendA2AMessage, } from "./a2aTask.js";
+export const A2A_HTTP_SEND_MESSAGE_PATH = "/message:send";
+export const A2A_HTTP_STREAM_MESSAGE_PATH = "/message:stream";
+export const A2A_HTTP_EXTENDED_AGENT_CARD_PATH = "/extendedAgentCard";
+export const A2A_HTTP_TASKS_PATH = "/tasks";
+export async function handleLocalA2AHttpRequest(request, options) {
+    const method = normalizeMethod(request.method);
+    const url = parsePath(request.path);
+    if (url.pathname === A2A_AGENT_CARD_WELL_KNOWN_PATH) {
+        return handleAgentCardRequest(method, url.pathname, options.agentCardProfile, {
+            ...publicAgentCardOptions(options),
+        });
+    }
+    const auth = authorizeTaskRequest(request, options);
+    if (auth)
+        return auth;
+    const versionError = validateProtocolVersion(request);
+    if (versionError)
+        return versionError;
+    if (url.pathname === A2A_HTTP_STREAM_MESSAGE_PATH) {
+        return errorResponse(501, "A2A_OPERATION_UNSUPPORTED", "A2A streaming is supported by the local Node SSE server, not by this pure HTTP response handler.");
+    }
+    try {
+        if (url.pathname === A2A_HTTP_EXTENDED_AGENT_CARD_PATH) {
+            if (method !== "GET")
+                return methodNotAllowed(["GET"]);
+            return handleExtendedAgentCardRequest(options);
+        }
+        const pushRoute = matchPushNotificationRoute(url.pathname);
+        if (pushRoute)
+            return handlePushNotificationRoute(method, url, request, options, pushRoute);
+        if (url.pathname === A2A_HTTP_SEND_MESSAGE_PATH) {
+            if (method !== "POST")
+                return methodNotAllowed(["POST"]);
+            return await handleSendMessage(request, options);
+        }
+        if (url.pathname === A2A_HTTP_TASKS_PATH) {
+            if (method !== "GET")
+                return methodNotAllowed(["GET"]);
+            return ok({
+                kind: "task-list",
+                ...listA2ATasks({
+                    store: options.store,
+                    contextId: optionalQuery(url, "contextId"),
+                    state: optionalQuery(url, "state"),
+                    includeArtifacts: booleanQuery(url, "includeArtifacts"),
+                    historyLength: numberQuery(url, "historyLength"),
+                    pageSize: numberQuery(url, "pageSize"),
+                }),
+            });
+        }
+        const taskRoute = matchTaskRoute(url.pathname);
+        if (taskRoute) {
+            if (taskRoute.action === "get") {
+                if (method !== "GET")
+                    return methodNotAllowed(["GET"]);
+                return ok({
+                    kind: "task",
+                    ...getA2ATask({
+                        store: options.store,
+                        id: taskRoute.taskId,
+                        includeArtifacts: booleanQuery(url, "includeArtifacts"),
+                        historyLength: numberQuery(url, "historyLength"),
+                    }),
+                });
+            }
+            if (method !== "POST")
+                return methodNotAllowed(["POST"]);
+            const result = cancelA2ATask({
+                store: options.store,
+                id: taskRoute.taskId,
+                now: options.now?.(),
+                includeArtifacts: booleanQuery(url, "includeArtifacts"),
+            });
+            await maybeDeliverPushNotifications(result.task, options);
+            return ok({
+                kind: "task",
+                ...result,
+            });
+        }
+        return errorResponse(404, "A2A_ROUTE_NOT_FOUND", "A2A route was not found.");
+    }
+    catch (error) {
+        if (error instanceof A2ATaskError) {
+            return errorResponse(error.status, error.code, error.message);
+        }
+        if (error instanceof A2APushNotificationError) {
+            return errorResponse(error.status, error.code, error.message);
+        }
+        return errorResponse(400, "A2A_BODY_INVALID", "A2A request body is invalid.");
+    }
+}
+function publicAgentCardOptions(options) {
+    const base = {
+        ...options.agentCardOptions,
+        now: options.agentCardOptions?.now ?? options.now?.(),
+    };
+    if (options.extendedAgentCardProfile === undefined)
+        return base;
+    return {
+        ...base,
+        capabilities: {
+            ...base.capabilities,
+            extendedAgentCard: true,
+        },
+    };
+}
+function handleAgentCardRequest(method, path, profile, options = {}) {
+    const response = handleA2AAgentCardWellKnownRequest({ method, path }, profile, options);
+    if (response.status === 200) {
+        return {
+            status: 200,
+            headers: response.headers,
+            body: {
+                kind: "agent-card",
+                ...response.body,
+            },
+            json: response.json,
+        };
+    }
+    return {
+        status: response.status,
+        headers: response.headers,
+        body: JSON.parse(response.json),
+        json: response.json,
+    };
+}
+function handleExtendedAgentCardRequest(options) {
+    if (options.extendedAgentCardProfile === undefined) {
+        return errorResponse(501, "A2A_EXTENDED_AGENT_CARD_NOT_CONFIGURED", "A2A extended Agent Card is not configured for this local Vallum server.");
+    }
+    return handleAgentCardRequest("GET", A2A_AGENT_CARD_WELL_KNOWN_PATH, options.extendedAgentCardProfile, {
+        ...options.extendedAgentCardOptions,
+        now: options.extendedAgentCardOptions?.now ?? options.now?.(),
+    });
+}
+async function handleSendMessage(request, options) {
+    if (!options.taskPolicy) {
+        return errorResponse(503, "A2A_POLICY_NOT_CONFIGURED", "A2A task endpoint policy is not configured.");
+    }
+    const body = parseBody(request.body);
+    if (!isSendMessageBody(body)) {
+        return errorResponse(400, "A2A_BODY_INVALID", "A2A request body is invalid.");
+    }
+    const result = await sendA2AMessage({
+        store: options.store,
+        protocolVersion: body.protocolVersion ?? A2A_TASK_PROTOCOL_VERSION,
+        message: body.message,
+        manifest: body.manifest,
+        policy: body.message.taskId ? undefined : options.taskPolicy,
+        now: options.now?.(),
+        contextId: body.contextId,
+        processMessage: options.processMessage,
+    });
+    await maybeDeliverPushNotifications(result.task, options);
+    return ok({
+        kind: "task",
+        ...result,
+    });
+}
+function handlePushNotificationRoute(method, url, request, options, route) {
+    if (!options.pushNotificationStore) {
+        return errorResponse(501, "A2A_OPERATION_UNSUPPORTED", "A2A push notification configuration is not enabled for this local Vallum server.");
+    }
+    getA2ATask({ store: options.store, id: route.taskId });
+    if (!route.configId) {
+        if (method === "POST") {
+            return ok({
+                kind: "push-config",
+                config: createA2APushNotificationConfig({
+                    store: options.pushNotificationStore,
+                    taskId: route.taskId,
+                    value: parseBody(request.body),
+                    now: options.now?.(),
+                }),
+            });
+        }
+        if (method === "GET") {
+            return ok({
+                kind: "push-config-list",
+                ...listA2APushNotificationConfigs({
+                    store: options.pushNotificationStore,
+                    taskId: route.taskId,
+                    pageSize: numberQuery(url, "pageSize"),
+                }),
+            });
+        }
+        return methodNotAllowed(["GET", "POST"]);
+    }
+    if (method === "GET") {
+        return ok({
+            kind: "push-config",
+            config: getA2APushNotificationConfig({
+                store: options.pushNotificationStore,
+                taskId: route.taskId,
+                id: route.configId,
+            }),
+        });
+    }
+    if (method === "DELETE") {
+        return ok({
+            kind: "push-config-deleted",
+            ...deleteA2APushNotificationConfig({
+                store: options.pushNotificationStore,
+                taskId: route.taskId,
+                id: route.configId,
+            }),
+        });
+    }
+    return methodNotAllowed(["DELETE", "GET"]);
+}
+async function maybeDeliverPushNotifications(task, options) {
+    if (!options.pushNotificationStore || !options.pushNotificationTransport)
+        return;
+    await deliverA2APushNotifications({
+        store: options.pushNotificationStore,
+        task,
+        transport: options.pushNotificationTransport,
+    });
+}
+function authorizeTaskRequest(request, options) {
+    if (!options.taskAuthToken || options.taskAuthToken.trim() === "") {
+        return errorResponse(503, "A2A_AUTH_NOT_CONFIGURED", "A2A task endpoint authentication is not configured.");
+    }
+    const authorization = header(request.headers, "authorization");
+    if (authorization !== `Bearer ${options.taskAuthToken}`) {
+        return errorResponse(401, "A2A_AUTH_REQUIRED", "A2A task endpoints require bearer authentication.");
+    }
+    return undefined;
+}
+function validateProtocolVersion(request) {
+    const version = header(request.headers, "a2a-version");
+    if (version !== undefined && version !== A2A_TASK_PROTOCOL_VERSION) {
+        return errorResponse(400, "A2A_VERSION_NOT_SUPPORTED", "A2A protocol version is unsupported.");
+    }
+    return undefined;
+}
+function ok(body) {
+    return {
+        status: 200,
+        headers: {
+            "content-type": `${A2A_TASK_MEDIA_TYPE}; charset=utf-8`,
+            "cache-control": "no-store",
+        },
+        body,
+        json: `${JSON.stringify(body)}\n`,
+    };
+}
+function errorResponse(status, code, message, headers = {}) {
+    const body = { error: { code, message } };
+    return {
+        status,
+        headers: {
+            "content-type": "application/json; charset=utf-8",
+            "cache-control": "no-store",
+            ...headers,
+        },
+        body,
+        json: `${JSON.stringify(body)}\n`,
+    };
+}
+function methodNotAllowed(allowed) {
+    return errorResponse(405, "A2A_METHOD_NOT_ALLOWED", "A2A route does not support this method.", { allow: allowed.join(", ") });
+}
+function parseBody(body) {
+    if (typeof body !== "string")
+        return body;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        throw new A2ATaskError("A2A_MESSAGE_INVALID", "A2A request body is invalid.");
+    }
+}
+function isSendMessageBody(value) {
+    if (!isRecord(value))
+        return false;
+    return isRecord(value.message);
+}
+function matchTaskRoute(pathname) {
+    const parts = pathname.split("/").filter(Boolean);
+    if (parts.length !== 2 || parts[0] !== "tasks")
+        return undefined;
+    const taskPart = parts[1] ?? "";
+    if (taskPart.endsWith(":cancel")) {
+        return { taskId: decodeURIComponent(taskPart.slice(0, -":cancel".length)), action: "cancel" };
+    }
+    return { taskId: decodeURIComponent(taskPart), action: "get" };
+}
+function matchPushNotificationRoute(pathname) {
+    const parts = pathname.split("/").filter(Boolean);
+    if (parts.length !== 3 && parts.length !== 4)
+        return undefined;
+    if (parts[0] !== "tasks" || parts[2] !== "pushNotificationConfigs")
+        return undefined;
+    return {
+        taskId: decodeURIComponent(parts[1] ?? ""),
+        ...(parts[3] ? { configId: decodeURIComponent(parts[3]) } : {}),
+    };
+}
+function parsePath(path = "/") {
+    try {
+        return new URL(path, "https://agent.local");
+    }
+    catch {
+        return new URL("/", "https://agent.local");
+    }
+}
+function normalizeMethod(method = "GET") {
+    return method.trim().toUpperCase();
+}
+function header(headers, name) {
+    const found = Object.entries(headers ?? {})
+        .find(([key]) => key.toLowerCase() === name.toLowerCase());
+    return found?.[1];
+}
+function booleanQuery(url, name) {
+    const value = url.searchParams.get(name);
+    if (value === null)
+        return undefined;
+    return value === "true";
+}
+function numberQuery(url, name) {
+    const value = url.searchParams.get(name);
+    if (value === null || value.trim() === "")
+        return undefined;
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
+}
+function optionalQuery(url, name) {
+    const value = url.searchParams.get(name);
+    return value === null || value.trim() === "" ? undefined : value;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/dist/a2aNodeServer.d.ts

@@ -0,0 +1,17 @@
+import { type A2APublicJwksOptions } from "@vallum/registry";
+import { type LocalA2AHttpHandlerOptions } from "./a2aHttp.js";
+export interface LocalA2ANodeServerOptions extends LocalA2AHttpHandlerOptions {
+    readonly host?: string;
+    readonly port?: number;
+    readonly maxBodyBytes?: number;
+    readonly allowNonLoopbackHost?: boolean;
+    readonly publicJwks?: A2APublicJwksOptions;
+}
+export interface LocalA2ANodeServer {
+    readonly baseUrl: string;
+    readonly host: string;
+    readonly port: number;
+    readonly boundToLoopback: boolean;
+    readonly close: () => Promise<void>;
+}
+export declare function startLocalA2ANodeServer(options: LocalA2ANodeServerOptions): Promise<LocalA2ANodeServer>;

package/dist/a2aNodeServer.js

@@ -0,0 +1,156 @@
+import { createServer } from "node:http";
+import { A2A_JWKS_WELL_KNOWN_PATH, handleA2APublicJwksRequest, } from "@vallum/registry";
+import { A2A_HTTP_SEND_MESSAGE_PATH, A2A_HTTP_STREAM_MESSAGE_PATH, handleLocalA2AHttpRequest, } from "./a2aHttp.js";
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_MAX_BODY_BYTES = 64_000;
+export async function startLocalA2ANodeServer(options) {
+    const host = options.host ?? DEFAULT_HOST;
+    if (!options.allowNonLoopbackHost && !isLoopbackHost(host)) {
+        throw new Error("A2A local Node server refuses non-loopback hosts without explicit opt-in.");
+    }
+    const server = createServer(async (request, response) => {
+        try {
+            const body = await readBody(request, options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES);
+            if (requestPathname(request.url) === A2A_JWKS_WELL_KNOWN_PATH) {
+                const handled = handleA2APublicJwksRequest({
+                    method: request.method,
+                    path: request.url,
+                }, options.publicJwks ?? { keys: [] });
+                writeHandledResponse(response, handled.status, handled.headers, handled.json);
+                return;
+            }
+            if (requestPathname(request.url) === A2A_HTTP_STREAM_MESSAGE_PATH) {
+                const handled = await handleLocalA2AHttpRequest({
+                    method: request.method,
+                    path: A2A_HTTP_SEND_MESSAGE_PATH,
+                    headers: normalizeHeaders(request.headers),
+                    body,
+                }, options);
+                if (handled.status !== 200) {
+                    writeHandledResponse(response, handled.status, handled.headers, handled.json);
+                    return;
+                }
+                writeServerSentEvents(response, [{ event: "task", data: handled.body }]);
+                return;
+            }
+            const handled = await handleLocalA2AHttpRequest({
+                method: request.method,
+                path: request.url,
+                headers: normalizeHeaders(request.headers),
+                body,
+            }, options);
+            writeHandledResponse(response, handled.status, handled.headers, handled.json);
+        }
+        catch (error) {
+            const status = error instanceof BodyTooLargeError ? 413 : 400;
+            writeHandledResponse(response, status, {
+                "content-type": "application/json; charset=utf-8",
+                "cache-control": "no-store",
+            }, `${JSON.stringify({
+                error: {
+                    code: error instanceof BodyTooLargeError ? "A2A_BODY_TOO_LARGE" : "A2A_BODY_INVALID",
+                    message: error instanceof BodyTooLargeError
+                        ? "A2A request body is too large."
+                        : "A2A request body is invalid.",
+                },
+            })}\n`);
+        }
+    });
+    await listen(server, host, options.port ?? 0);
+    const address = server.address();
+    if (!isAddressInfo(address)) {
+        await closeServer(server);
+        throw new Error("A2A local Node server did not bind to a TCP address.");
+    }
+    const addressHost = address.address === "::1" ? "[::1]" : address.address;
+    return {
+        baseUrl: `http://${addressHost}:${address.port}`,
+        host: address.address,
+        port: address.port,
+        boundToLoopback: isLoopbackHost(address.address),
+        close: () => closeServer(server),
+    };
+}
+function listen(server, host, port) {
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+}
+function closeServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => error ? reject(error) : resolve());
+    });
+}
+function writeHandledResponse(response, status, headers, body) {
+    response.statusCode = status;
+    for (const [name, value] of Object.entries(headers)) {
+        response.setHeader(name, value);
+    }
+    response.end(body);
+}
+function writeServerSentEvents(response, events) {
+    response.statusCode = 200;
+    response.setHeader("content-type", "text/event-stream; charset=utf-8");
+    response.setHeader("cache-control", "no-store");
+    response.setHeader("connection", "keep-alive");
+    response.setHeader("x-accel-buffering", "no");
+    for (const event of events) {
+        response.write(`event: ${event.event}\n`);
+        response.write(`data: ${JSON.stringify(event.data)}\n\n`);
+    }
+    response.end();
+}
+function normalizeHeaders(headers) {
+    const normalized = {};
+    for (const [name, value] of Object.entries(headers)) {
+        normalized[name] = Array.isArray(value) ? value.join(", ") : value;
+    }
+    return normalized;
+}
+async function readBody(request, maxBodyBytes) {
+    if (request.method === "GET" || request.method === "HEAD")
+        return undefined;
+    const chunks = [];
+    let byteLength = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        byteLength += buffer.byteLength;
+        if (byteLength > maxBodyBytes) {
+            throw new BodyTooLargeError();
+        }
+        chunks.push(buffer);
+    }
+    if (chunks.length === 0)
+        return undefined;
+    const body = Buffer.concat(chunks).toString("utf8");
+    return body.trim() === "" ? undefined : body;
+}
+function isLoopbackHost(host) {
+    const normalized = host.trim().toLowerCase();
+    return normalized === "127.0.0.1" || normalized === "::1" || normalized === "localhost";
+}
+function requestPathname(url = "/") {
+    try {
+        return new URL(url, "http://127.0.0.1").pathname;
+    }
+    catch {
+        return "/";
+    }
+}
+function isAddressInfo(value) {
+    return Boolean(value)
+        && typeof value === "object"
+        && value !== null
+        && "address" in value
+        && "port" in value;
+}
+class BodyTooLargeError extends Error {
+    constructor() {
+        super("A2A request body is too large.");
+        this.name = "BodyTooLargeError";
+    }
+}