@loomwork/plugin-a2a 0.0.0-stage → 0.1.1

package/src/A2APeerClient.ts

@@ -0,0 +1,298 @@
+import type { TaintedValue } from "@loomwork/classify";
+import { tainted } from "@loomwork/classify";
+import { tool$ } from "@loomwork/core";
+import type { AgentDefinition, ToolDefinition } from "@loomwork/core";
+import { agent$ } from "@loomwork/core";
+import type { Effect, EffectContext, EffectRuntime } from "@loomwork/effect-runtime";
+import { z } from "zod";
+import { createA2AClientEffect } from "./A2AClientEffect";
+import type { A2AClientOptions } from "./A2AClientEffect";
+import { A2AEffect } from "./A2AEffect";
+import type { A2ATask, A2ATaskResult, AgentCard } from "./types";
+
+/**
+ * Turns a remote A2A agent (Google ADK, a LangGraph/CrewAI A2A shim, or another
+ * Loom `createA2AServer`) into a callable Loom tool. This is the outbound half
+ * of the bidirectional mesh — the A2A analogue of `McpClient.registerInto`.
+ *
+ * The remote agent is discovered via its AgentCard (`/.well-known/agent.json`)
+ * and registered into an `EffectRuntime` so Loom agents, steps and the planner
+ * can invoke it like any other tool.
+ */
+export interface A2APeerConfig<TTaint extends boolean = false> {
+  /** Base URL of the remote A2A agent (no trailing path). */
+  url: string;
+  /** Extra headers (auth etc.) sent on discovery and every task call. */
+  headers?: Record<string, string>;
+  /** Overall per-call timeout, forwarded to the underlying client effect. */
+  timeoutMs?: number;
+  /** Poll interval while waiting for the remote task to reach a terminal state. */
+  pollIntervalMs?: number;
+  /** Override the registered tool id. Defaults to a slug of the card name. */
+  toolId?: string;
+  /**
+   * Mark the peer's `content` as untrusted (ADR 0085), stamped `a2a:<toolId>`.
+   * The prompt boundary in `@loomwork/llm` then REFUSES it in any instruction
+   * position — system prompt, assistant turn, tool description — and fences it
+   * in a `user` message.
+   *
+   * A peer agent writes its own artifact text, and a peer is exactly as
+   * trustworthy as whoever operates it. This is the switch that makes that fact
+   * travel with the value.
+   *
+   * Everything the peer wrote as text is tainted: `content`, and `raw.artifacts` and `raw.error`,
+   * which hold the same words. Not the whole output, unlike `mcpInvoke$`: `raw.id` and `raw.status`
+   * feed control flow, and forcing an `unwrapTainted()` on code that never touches a prompt would be
+   * friction in the wrong place. `content` is the flattened text, so `peer.content` drops straight
+   * into an `LlmMessage` slot where the guard sees it.
+   *
+   * Typed, not just documented: the flag's literal type selects the output
+   * type, so a caller that does not opt in sees `A2APeerOutput` exactly as
+   * before and compiles unchanged.
+   */
+  taintResults?: TTaint;
+  /**
+   * Vouch for the peer's AgentCard text (ADR 0125 D14; the equivalent of MCP's `trustDescriptions`).
+   * Default false: an agent loop shows the model only a neutral placeholder for this peer's
+   * description, because the card is written by whoever operates the peer. Set it only for a peer you
+   * operate or trust; its card text then reaches the model as instructions, unguarded (a one-time
+   * `LOOM_AGENT_TRUSTED_TOOL_TEXT` warning says so).
+   */
+  trustDescriptions?: boolean;
+}
+
+/** Friendly input accepted by a peer tool — a plain prompt plus optional context. */
+export interface A2APeerInput {
+  prompt: string;
+  context?: unknown;
+}
+
+/** Peer tool output — flattened artifact text plus the raw A2A result. */
+export interface A2APeerOutput {
+  content: string;
+  raw: A2ATaskResult;
+}
+
+/** {@link A2APeerOutput} under `taintResults` — the text carries its provenance. */
+export interface TaintedA2APeerOutput {
+  content: TaintedValue<string>;
+  raw: Omit<A2ATaskResult, "artifacts" | "error"> & {
+    artifacts?: TaintedValue<NonNullable<A2ATaskResult["artifacts"]>>;
+    error?: TaintedValue<string>;
+  };
+}
+
+/**
+ * The output shape implied by the `taintResults` flag. A `boolean` (rather than
+ * a literal) distributes to the union, which is the honest answer when the flag
+ * is only known at runtime.
+ */
+export type A2APeerOutputFor<TTaint extends boolean> = TTaint extends true
+  ? TaintedA2APeerOutput
+  : A2APeerOutput;
+
+/** The trio produced when mapping a remote agent: card, tool definition, effect. */
+export interface MappedA2APeer<TTaint extends boolean = false> {
+  card: AgentCard;
+  definition: ToolDefinition<A2APeerInput, A2APeerOutputFor<TTaint>>;
+  effect: Effect<A2APeerInput, A2APeerOutputFor<TTaint>>;
+}
+
+/**
+ * Structural view of `@loomwork/registry`'s `AgentRegistry.register`. Declared here
+ * so `@loomwork/plugin-a2a` stays dependency-light and does not import the registry package
+ * (which itself avoids depending on a2a for the same reason).
+ */
+export interface PeerAgentRegistrar {
+  register(definition: AgentDefinition, card?: RegisteredPeerCard): unknown;
+}
+
+interface RegisteredPeerCard {
+  name: string;
+  description?: string;
+  url?: string;
+  version: string;
+  capabilities?: { streaming?: boolean };
+  skills?: Array<{ id: string; name: string; description?: string }>;
+}
+
+const peerInputSchema = z.object({
+  prompt: z.string(),
+  context: z.unknown().optional(),
+}) as z.ZodType<A2APeerInput>;
+
+// `content` validates BOTH shapes because one schema backs both flag settings.
+// It is the runtime contract; the conditional type is what narrows it per caller.
+const peerOutputSchema = z.object({
+  content: z.union([
+    z.string(),
+    z.object({ __loomTainted: z.object({ origin: z.string() }), value: z.string() }),
+  ]),
+  raw: z.unknown(),
+});
+
+/** Fetch a remote agent's AgentCard from its well-known discovery endpoint. */
+export async function fetchAgentCard(
+  url: string,
+  headers: Record<string, string> = {}
+): Promise<AgentCard> {
+  const resp = await fetch(`${url}/.well-known/agent.json`, {
+    headers: { accept: "application/json", ...headers },
+  });
+  if (!resp.ok) {
+    throw new Error(`A2A discovery failed ${resp.status}: ${await resp.text()}`);
+  }
+  return (await resp.json()) as AgentCard;
+}
+
+export class A2APeerClient<TTaint extends boolean = false> {
+  private card: AgentCard | undefined;
+
+  constructor(private readonly config: A2APeerConfig<TTaint>) {}
+
+  /** Fetch and cache the remote AgentCard. */
+  async discover(): Promise<AgentCard> {
+    if (this.card === undefined) {
+      this.card = await fetchAgentCard(this.config.url, this.config.headers);
+    }
+    return this.card;
+  }
+
+  /** Discover the peer and build its Loom tool definition + effect (no registration). */
+  async map(): Promise<MappedA2APeer<TTaint>> {
+    const card = await this.discover();
+    const toolId = this.config.toolId ?? slug(card.name);
+    const effect = this.buildEffect(toolId);
+
+    const definition = tool$<A2APeerInput, A2APeerOutputFor<TTaint>>({
+      id: toolId,
+      name: card.name,
+      description: describe(card),
+      kind: "a2a",
+      // R22 (ADR 0125 D7) — built from a REMOTE agent card: tool search must not rank or show its text.
+      origin: "remote",
+      ...(this.config.trustDescriptions === true && { trustJsonSchemaText: true }),
+      // loom's own static schema (not the card's): its `.describe()` text is loom-authored, so it is kept.
+      schemaOrigin: "local",
+      inputSchema: peerInputSchema,
+      outputSchema: peerOutputSchema as unknown as z.ZodType<A2APeerOutputFor<TTaint>>,
+    });
+
+    return { card, definition, effect };
+  }
+
+  /**
+   * Discover the peer, register it as an effect, and return the tool definition.
+   * Pass a registry to also expose the peer to the planner/intent layer.
+   */
+  async registerInto(
+    effectRuntime: EffectRuntime,
+    registry?: PeerAgentRegistrar
+  ): Promise<ToolDefinition<A2APeerInput, A2APeerOutputFor<TTaint>>> {
+    const { card, definition, effect } = await this.map();
+    effectRuntime.register(definition.id, effect);
+
+    if (registry !== undefined) {
+      const remoteAgent = agent$({
+        id: definition.id,
+        name: card.name,
+        ...(card.description !== undefined && { description: card.description }),
+        tools: [definition],
+        version: card.version,
+        capabilities: card.capabilities,
+        skills: card.skills,
+      });
+      registry.register(remoteAgent, toRegisteredCard(card));
+    }
+
+    return definition;
+  }
+
+  /** Adapter effect: friendly input -> A2ATask -> underlying client -> flattened output. */
+  private buildEffect(toolId: string): Effect<A2APeerInput, A2APeerOutputFor<TTaint>> {
+    const clientOptions: A2AClientOptions = {
+      ...(this.config.headers !== undefined && { headers: this.config.headers }),
+      ...(this.config.timeoutMs !== undefined && { timeoutMs: this.config.timeoutMs }),
+      ...(this.config.pollIntervalMs !== undefined && {
+        pollIntervalMs: this.config.pollIntervalMs,
+      }),
+    };
+    const client = createA2AClientEffect(this.config.url, clientOptions);
+
+    return new A2AEffect<A2APeerInput, A2APeerOutputFor<TTaint>>(
+      async (input: A2APeerInput, ctx: EffectContext): Promise<A2APeerOutputFor<TTaint>> => {
+        const task: A2ATask = {
+          // Deterministic id derived from the execution so replays stay stable.
+          // A transient call stamped as an execution (ctx.decide's scope) shares
+          // (executionId, stepId) with its siblings; callKey keeps their ids distinct.
+          id: `${ctx.executionId}:${ctx.stepId}${ctx.callKey !== undefined ? `:${ctx.callKey}` : ""}`,
+          message: { role: "user", parts: [{ type: "text", text: input.prompt }] },
+          ...(input.context !== undefined && { metadata: { context: input.context } }),
+        };
+
+        const result = await client.execute(task, ctx);
+        const content = artifactText(result);
+        // Taint at INGRESS — the wrapper IS the step output, so it is what
+        // STEP_COMPLETED records and what a replay hands back. The cast is the
+        // one place the conditional return type cannot be proved structurally.
+        if (this.config.taintResults !== true) {
+          return { content, raw: result } as A2APeerOutputFor<TTaint>;
+        }
+        const origin = `a2a:${toolId}`;
+        const { artifacts, error, ...state } = result;
+        return {
+          content: tainted(content, origin),
+          raw: {
+            ...state,
+            ...(artifacts !== undefined && { artifacts: tainted(artifacts, origin) }),
+            ...(error !== undefined && { error: tainted(error, origin) }),
+          },
+        } as A2APeerOutputFor<TTaint>;
+      }
+    );
+  }
+}
+
+/** Flatten all text parts across all artifacts of a completed/failed A2A result. */
+function artifactText(result: A2ATaskResult): string {
+  if (result.error !== undefined) {
+    return result.error;
+  }
+  return (result.artifacts ?? [])
+    .flatMap((artifact) => artifact.parts.map((part) => part.text))
+    .join("\n");
+}
+
+/** Build an LLM-facing tool description from the card's summary and skills. */
+function describe(card: AgentCard): string {
+  const base = card.description ?? card.name;
+  if (card.skills.length === 0) {
+    return base;
+  }
+  const skills = card.skills.map((s) => s.name).join(", ");
+  return `${base} (skills: ${skills})`;
+}
+
+function toRegisteredCard(card: AgentCard): RegisteredPeerCard {
+  return {
+    name: card.name,
+    ...(card.description !== undefined && { description: card.description }),
+    url: card.url,
+    version: card.version,
+    capabilities: card.capabilities,
+    skills: card.skills.map((s) => ({
+      id: s.id,
+      name: s.name,
+      ...(s.description !== undefined && { description: s.description }),
+    })),
+  };
+}
+
+function slug(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "a2a-peer"
+  );
+}

package/src/A2AServer.ts

@@ -0,0 +1,309 @@
+import { randomUUID } from "node:crypto";
+import * as http from "node:http";
+import { BadRequestError, exposeError } from "@loomwork/core";
+import type { PrincipalChain } from "@loomwork/effect-runtime";
+import type { RegisteredFlow, WorkflowRuntime } from "@loomwork/workflow-runtime";
+import { LoomAgentExecutor, hasActor } from "./AgentExecutor";
+import type { A2ATask, AgentCard } from "./types";
+
+export interface A2AServerOptions {
+  port?: number;
+  /**
+   * R12 — the interface to bind. Default `"127.0.0.1"` (loopback only): a server is reachable
+   * from this machine and nothing else until you widen it deliberately (`"0.0.0.0"`, `"::"`, or
+   * a specific interface address). Binding all interfaces was the old default.
+   */
+  host?: string;
+  /**
+   * R12 — the URL the agent card advertises, when it differs from the bind address (a server bound
+   * to `"0.0.0.0"` would otherwise advertise `localhost`, which no remote peer can reach). Set it
+   * to the externally reachable base URL (reverse proxy / load balancer). Default: derived from
+   * `host` and the bound port.
+   */
+  publicUrl?: string;
+  /**
+   * R12 — authenticate AND identify the caller in one step: return the caller's
+   * {@link PrincipalChain}, or `undefined` to refuse the request (401). Derive it from connection
+   * facts only (verified bearer token, mTLS peer) — never from the task body. This is the
+   * recommended gate: it also scopes task ownership to the principal (see below).
+   *
+   * The principal MUST carry a non-empty string `actor` (task ownership is keyed on it); any other
+   * principal is refused with 401 and a one-time warning. When both this and
+   * {@link resolvePrincipal} are set, THIS wins and `resolvePrincipal` is ignored.
+   */
+  authenticate?: (
+    req: http.IncomingMessage
+  ) => PrincipalChain | undefined | Promise<PrincipalChain | undefined>;
+  /**
+   * Gate the task routes (`POST /tasks/send`, `GET /tasks/:id`). Return `true` to allow. The
+   * agent-card route stays open. A boolean carries no identity, so every caller that passes it
+   * shares ONE task namespace unless `resolvePrincipal`/`authenticate` says who they are.
+   *
+   * R12 — the server REFUSES TO BE CREATED with neither `authenticate` nor `authorize` unless
+   * {@link insecure} is `true`.
+   */
+  authorize?: (req: http.IncomingMessage) => boolean | Promise<boolean>;
+  /**
+   * R12 — explicit opt-out of authentication: any caller that can reach the socket can submit
+   * tasks. Logs a loud warning at creation. Intended for local demos and tests; combine with the
+   * loopback default. Refused when {@link strict} is set.
+   */
+  insecure?: boolean;
+  /**
+   * R12 — `defineConfig`'s `security.strict`. Under strict the server is a config error unless it
+   * authenticates AND resolves a principal; `insecure: true` is refused; and a caller that
+   * resolves to no principal is refused (401). DEFAULTS from the runtime you pass
+   * (`workflowRuntime.requiresPrincipal`), so a strict runtime makes the server strict without
+   * this flag; set it explicitly to override.
+   */
+  strict?: boolean;
+  /** Where the insecure-mode warning goes. Default `console.warn`. */
+  warn?: (message: string) => void;
+  /**
+   * R3 — the AUTHENTICATED principal behind a request, derived from the same connection facts
+   * `authorize` checked (mTLS peer, verified bearer token, signed header) — NEVER from the task
+   * body. Applied to the runtime call for every task route (`/tasks/send`, `GET /tasks/:id`).
+   * Without it every task is anonymous, which a runtime that fails closed (`security.strict`)
+   * refuses (`ExecutionDeniedError`): an A2A server is an edge, and under strict an edge must
+   * say who is calling. Returning `undefined` for a request means "anonymous".
+   */
+  resolvePrincipal?: (
+    req: http.IncomingMessage
+  ) => PrincipalChain | undefined | Promise<PrincipalChain | undefined>;
+  /**
+   * Called with the real error behind a 500, alongside the `errorId` the caller was given.
+   * The response itself carries no internal detail, so this is the only place it surfaces —
+   * wire it to your logger or the detail is simply lost.
+   */
+  onError?: (errorId: string, err: unknown) => void;
+}
+
+export interface A2AServer {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  readonly url: string;
+}
+
+// Cap request bodies so an unauthenticated caller can't OOM the process by streaming a
+// huge (or endless) body into memory before parse. Matches the isolate broker's 10 MB cap.
+const MAX_BODY_BYTES = 10 * 1024 * 1024;
+// `task.id` becomes the executionId, which is embedded in event ids and carried in the
+// Postgres NOTIFY payload (itself capped at ~8 KB). Generous for a ULID or a UUID.
+const MAX_TASK_ID_LENGTH = 200;
+
+function parseBody(req: http.IncomingMessage): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    req.on("data", (chunk: Uint8Array) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        req.destroy();
+        reject(new BadRequestError(`request body exceeds ${MAX_BODY_BYTES} bytes`));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      try {
+        const raw = Buffer.concat(chunks);
+        resolve(JSON.parse(raw.toString("utf-8")) as unknown);
+      } catch {
+        // The caller's own malformed JSON — safe to name, and useless to hide.
+        reject(new BadRequestError("request body is not valid JSON"));
+      }
+    });
+    req.on("error", (err: Error) => reject(err));
+  });
+}
+
+function json(res: http.ServerResponse, status: number, body: unknown): void {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(payload);
+}
+
+export function createA2AServer(
+  workflowRuntime: WorkflowRuntime,
+  flow: RegisteredFlow,
+  agentCard: Omit<AgentCard, "url">,
+  options: A2AServerOptions = {}
+): A2AServer {
+  const port = options.port ?? 3001;
+  const host = options.host ?? "127.0.0.1";
+  const authenticated = options.authenticate !== undefined || options.authorize !== undefined;
+  const strict = options.strict ?? workflowRuntime.requiresPrincipal === true;
+  if (strict) {
+    if (options.insecure === true) {
+      throw new Error(
+        "createA2AServer: `insecure: true` is refused under security.strict — authenticate callers."
+      );
+    }
+    if (options.authenticate === undefined && options.resolvePrincipal === undefined) {
+      throw new Error(
+        "createA2AServer: security.strict requires `authenticate` (or `resolvePrincipal`) — every task must carry the caller's principal."
+      );
+    }
+  }
+  if (!authenticated && options.insecure !== true) {
+    throw new Error(
+      "createA2AServer: refusing to create an unauthenticated server. Supply `authenticate` (recommended) or `authorize`, or pass `insecure: true` to opt out explicitly."
+    );
+  }
+  if (!authenticated) {
+    (options.warn ?? ((m: string) => console.warn(m)))(
+      `[loom] WARNING: A2A server is running with insecure: true — NO authentication; any caller that can reach ${host}:${port} can submit and read tasks.`
+    );
+  }
+  const urlHost =
+    host === "0.0.0.0" || host === "::" ? "localhost" : host.includes(":") ? `[${host}]` : host;
+  let resolvedUrl = `http://${urlHost}:${port}`;
+  const warn = options.warn ?? ((m: string) => console.warn(m));
+  let warnedNoActor = false;
+
+  // The whole A2A layer is this one adapter; the server just moves bytes to it. Task ids are
+  // namespaced by principal (R12): the client's id is only a label within its own namespace.
+  const executor = new LoomAgentExecutor(workflowRuntime, flow, { namespaceByPrincipal: true });
+
+  const server = http.createServer((req: http.IncomingMessage, res: http.ServerResponse): void => {
+    void (async () => {
+      const url = req.url ?? "/";
+      const method = req.method ?? "GET";
+
+      try {
+        if (method === "GET" && url === "/.well-known/agent.json") {
+          json(res, 200, { ...agentCard, url: options.publicUrl ?? resolvedUrl });
+          return;
+        }
+
+        // Gate the task routes when an authorizer is wired; the agent card stays open.
+        if (options.authorize !== undefined && url !== "/.well-known/agent.json") {
+          if (!(await options.authorize(req))) {
+            json(res, 401, { error: "unauthorized" });
+            return;
+          }
+        }
+
+        // R12 — authenticate: identity or refusal.
+        let principal: PrincipalChain | undefined;
+        if (options.authenticate !== undefined) {
+          principal = await options.authenticate(req);
+          if (principal === undefined) {
+            json(res, 401, { error: "unauthorized" });
+            return;
+          }
+        }
+        // R3 — who is calling, resolved once per request, after `authorize`.
+        principal ??= await options.resolvePrincipal?.(req);
+        // R12 — fail closed: a principal that cannot be given its own namespace (no actor) must
+        // not be pooled with other such callers; under strict an unidentified caller is refused.
+        if (principal !== undefined && !hasActor(principal)) {
+          if (!warnedNoActor) {
+            warnedNoActor = true;
+            warn(
+              "[loom] A2A server: refusing a caller whose principal has no non-empty string `actor` — `authenticate`/`resolvePrincipal` must return an `actor` (task ownership is keyed on it)."
+            );
+          }
+          json(res, 401, { error: "unauthorized" });
+          return;
+        }
+        if (principal === undefined && strict) {
+          json(res, 401, { error: "unauthorized" });
+          return;
+        }
+        // The task namespace: the principal when known; one shared bucket for callers that were
+        // authorized but not identified; "anonymous" under `insecure`.
+        const call = {
+          ...(principal !== undefined && { principal }),
+          ...(principal === undefined && authenticated && { namespace: "authorized" }),
+        };
+
+        if (method === "POST" && url === "/tasks/send") {
+          const task = (await parseBody(req)) as A2ATask;
+          // `task.id` becomes the executionId VERBATIM, so it is screened here rather than
+          // only deep in the kernel — a rejected id should read as a 400 from the adapter,
+          // not surface as a 500 from the runtime.
+          if (typeof task?.id !== "string" || task.id.length === 0) {
+            json(res, 400, { error: "task.id must be a non-empty string" });
+            return;
+          }
+          // The kernel reserves `__loom_*` for its own control streams (retention lifecycle,
+          // erasure). An execution created there both corrupts that audit trail and becomes
+          // invisible to every enumerator, so retention never reclaims it.
+          if (task.id.startsWith("__loom_")) {
+            json(res, 400, { error: 'task.id must not use the reserved "__loom_" prefix' });
+            return;
+          }
+          // Bound it: the id is embedded in every event id and travels in the Postgres
+          // NOTIFY payload, which is itself capped — an unbounded id turns into failing
+          // appends rather than a rejected request.
+          if (task.id.length > MAX_TASK_ID_LENGTH) {
+            json(res, 400, { error: `task.id exceeds ${MAX_TASK_ID_LENGTH} characters` });
+            return;
+          }
+          const { id } = await executor.submit(task, call);
+          json(res, 202, { id });
+          return;
+        }
+
+        const taskMatch = /^\/tasks\/([^/]+)$/.exec(url);
+        if (method === "GET" && taskMatch !== null) {
+          const rawTaskId = taskMatch[1];
+          if (rawTaskId === undefined) {
+            json(res, 400, { error: "missing task id" });
+            return;
+          }
+          // The path segment is percent-encoded on the wire (a client MUST encode an id
+          // containing `/` or other reserved characters, or URL normalization upstream of this
+          // server — e.g. `fetch`'s own dot-segment collapsing — could otherwise turn an id like
+          // `../admin` into a request for a different route entirely). Decode it back to the
+          // real task id before it reaches the executor.
+          let taskId: string;
+          try {
+            taskId = decodeURIComponent(rawTaskId);
+          } catch {
+            json(res, 400, { error: "task id is not validly percent-encoded" });
+            return;
+          }
+          const result = await executor.get(taskId, call);
+          if (result === null) {
+            json(res, 404, { error: `task ${taskId} not found` });
+            return;
+          }
+          json(res, 200, result);
+          return;
+        }
+
+        json(res, 404, { error: "not found" });
+      } catch (err) {
+        const exposed = exposeError(err, randomUUID);
+        if (exposed.internal !== undefined) {
+          options.onError?.(exposed.body.errorId as string, exposed.internal);
+        }
+        json(res, exposed.status, exposed.body);
+      }
+    })();
+  });
+
+  return {
+    get url() {
+      return resolvedUrl;
+    },
+    start(): Promise<void> {
+      return new Promise((resolve) => {
+        server.listen(port, host, () => {
+          const addr = server.address();
+          if (addr !== null && typeof addr === "object") {
+            resolvedUrl = `http://${urlHost}:${addr.port}`;
+          }
+          resolve();
+        });
+      });
+    },
+    stop(): Promise<void> {
+      return new Promise((resolve, reject) => {
+        server.close((err?: Error) => (err !== undefined ? reject(err) : resolve()));
+      });
+    },
+  };
+}