stitchkit 0.55.0 → 0.56.1

package/dist/testing.js

@@ -1,8 +1,13 @@
 import {
-  assertToolName,
-  assertUniqueToolName,
-  toToolName
-} from "./index-k4dftwf7.js";
+  RealtimeRequestDisconnectedError,
+  RealtimeRequestInvalidAcknowledgementError,
+  RealtimeRequestTimeoutError
+} from "./index-557by2db.js";
+import {
+  mcpProjectionCandidate,
+  prepareProjectedMcpTools,
+  projectToolSurface
+} from "./index-6y759j86.js";
 import {
   toJsonSchema
 } from "./index-cby4ar3v.js";
@@ -24,6 +29,7 @@ import { createHash } from "node:crypto";
 import { z } from "zod";
 var HttpMethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
 var ToolTransportSchema = z.enum(["MCP", "AGENT", "CLI"]);
+var SurfaceTransportSchema = z.enum(["HTTP", "MCP", "AGENT", "CLI", "REALTIME"]);
 var SurfaceSchemaDigestsSchema = z.object({
   params: z.string().nullable(),
   input: z.string().nullable(),
@@ -38,8 +44,19 @@ var SurfaceManifestOperationSchema = z.object({
   scope: z.string().nullable(),
   description: z.string(),
   schemas: SurfaceSchemaDigestsSchema,
-  http: z.array(z.object({ method: HttpMethodSchema, path: z.string() })),
-  tools: z.partialRecord(ToolTransportSchema, z.string())
+  http: z.array(z.object({ method: HttpMethodSchema, path: z.string() }))
+});
+var SurfaceManifestToolSchema = z.object({
+  kind: z.enum(["contract", "runtime"]),
+  service: z.string(),
+  action: z.string(),
+  name: z.string(),
+  input: z.string()
+});
+var SurfaceManifestToolSurfaceSchema = z.object({
+  transport: ToolTransportSchema,
+  surface: z.string().nullable(),
+  tools: z.array(SurfaceManifestToolSchema)
 });
 var SurfaceManifestCliCommandSchema = z.object({
   name: z.string(),
@@ -49,12 +66,26 @@ var SurfaceManifestCliCommandSchema = z.object({
 });
 var SurfaceManifestExtensionSchema = z.object({
   name: z.string(),
-  transport: z.enum(["HTTP", "MCP", "AGENT", "CLI"])
+  transport: SurfaceTransportSchema
+});
+var SurfaceRealtimeSchemaPairSchema = z.object({
+  input: z.string(),
+  output: z.string()
+});
+var SurfaceManifestRealtimeEventSchema = z.object({
+  contract: z.string(),
+  direction: z.enum(["serverToClient", "clientToServer"]),
+  event: z.string(),
+  args: SurfaceRealtimeSchemaPairSchema,
+  acknowledgement: SurfaceRealtimeSchemaPairSchema.nullable()
 });
 var SurfaceManifestSchema = z.object({
-  manifestVersion: z.literal(1),
+  manifestVersion: z.literal(2),
   digestVersion: z.literal(1),
   operations: z.array(SurfaceManifestOperationSchema),
+  toolSurfaces: z.array(SurfaceManifestToolSurfaceSchema),
+  realtimeContracts: z.array(z.string()),
+  realtime: z.array(SurfaceManifestRealtimeEventSchema),
   cliOnly: z.array(SurfaceManifestCliCommandSchema),
   extensions: z.array(SurfaceManifestExtensionSchema)
 });
@@ -100,6 +131,9 @@ function schemaDigest(schema, io) {
     return null;
   return digestValue(canonicalSchemaValue(toJsonSchema(schema, io, "any")));
 }
+function presentationDigest(schema) {
+  return digestValue(canonicalSchemaValue(schema));
+}
 function multipartDigest(value) {
   return value === undefined ? null : digestValue(value);
 }
@@ -110,114 +144,202 @@ function joinPath(...parts) {
 function operationKey(kind, service, action) {
   return `${kind}\x00${service}\x00${action}`;
 }
-function uniqueToolServices(config) {
-  const services = new Set;
-  for (const service of config.services ?? [])
-    services.add(service);
-  for (const group of config.groups ?? []) {
-    for (const service of group.services)
-      services.add(service);
-  }
-  return [...services];
+function operationFrom(kind, source) {
+  return {
+    kind,
+    service: source.serviceName,
+    action: source.key,
+    method: source.method,
+    scope: source.scope ?? null,
+    description: source.desc,
+    schemas: {
+      params: schemaDigest(source.paramsSchema, "input"),
+      input: schemaDigest(source.inputSchema, "input"),
+      output: schemaDigest(source.outputSchema, "output"),
+      multipart: multipartDigest(source.multipart)
+    },
+    http: []
+  };
+}
+function operationFingerprint(source) {
+  const mcp = source.mcp ? {
+    inputRequired: source.mcp.inputRequired.map((request) => ({
+      key: request.key,
+      message: request.message,
+      schema: schemaDigest(request.schema, "input")
+    }))
+  } : null;
+  return serializeSurfaceValue({
+    method: source.method,
+    serviceName: source.serviceName,
+    key: source.key,
+    desc: source.desc,
+    scope: source.scope ?? null,
+    path: source.path ?? null,
+    expose: source.expose ? [...source.expose].sort(compareCodepoints) : null,
+    toolName: source.toolName ?? null,
+    annotations: source.annotations ?? null,
+    ui: source.ui ?? null,
+    mcp,
+    rawBody: source.rawBody ?? false,
+    rawResponse: source.rawResponse ?? false,
+    responseMeta: source.responseMeta ?? null,
+    maxJsonBodyBytes: source.maxJsonBodyBytes ?? null,
+    idempotent: source.idempotent ?? false,
+    contentType: source.contentType ?? null,
+    meta: source.meta ?? null,
+    schemas: {
+      params: schemaDigest(source.paramsSchema, "input"),
+      input: schemaDigest(source.inputSchema, "input"),
+      output: schemaDigest(source.outputSchema, "output"),
+      multipart: multipartDigest(source.multipart)
+    }
+  });
+}
+function sortTools(tools) {
+  return tools.sort((left, right) => compareCodepoints(left.name, right.name) || compareCodepoints(left.service, right.service) || compareCodepoints(left.action, right.action) || compareCodepoints(left.kind, right.kind));
 }
 function buildSurfaceManifest(config) {
   const operations = new Map;
-  const addContract = (service, prefix) => {
+  const operationFingerprints = new Map;
+  const operationDefinitions = new Map;
+  const addOperation = (kind, source) => {
+    const candidate = operationFrom(kind, source);
+    const key = operationKey(kind, candidate.service, candidate.action);
+    const definition = source.definitionToken ?? source;
+    const existing = operations.get(key);
+    if (!existing) {
+      operations.set(key, candidate);
+      operationFingerprints.set(key, operationFingerprint(source));
+      operationDefinitions.set(key, definition);
+      return candidate;
+    }
+    if (operationDefinitions.get(key) !== definition || operationFingerprints.get(key) !== operationFingerprint(source)) {
+      throw new Error(`Conflicting ${kind} operation identity ${candidate.service}.${candidate.action}`);
+    }
+    return existing;
+  };
+  const addHttp = (service, prefix) => {
     for (const method of Object.values(service.methods)) {
-      const key = operationKey("contract", service.name, method.key);
-      const existing = operations.get(key);
-      const http = !method.expose || method.expose.includes("HTTP") ? [{ method: method.method, path: joinPath(prefix, service.prefix, method.path) }] : [];
-      if (existing) {
-        existing.http.push(...http);
+      const operation = addOperation("contract", method);
+      if (method.expose && !method.expose.includes("HTTP"))
         continue;
-      }
-      operations.set(key, {
-        kind: "contract",
-        service: service.name,
-        action: method.key,
+      const route = {
         method: method.method,
-        scope: method.scope ?? service.scope ?? null,
-        description: method.desc,
-        schemas: {
-          params: schemaDigest(method.paramsSchema, "input"),
-          input: schemaDigest(method.inputSchema, "input"),
-          output: schemaDigest(method.outputSchema, "output"),
-          multipart: multipartDigest(method.multipart)
-        },
-        http,
-        tools: {}
-      });
+        path: joinPath(prefix, service.prefix, method.path)
+      };
+      if (!operation.http.some((entry) => entry.method === route.method && entry.path === route.path)) {
+        operation.http.push(route);
+      }
     }
   };
   for (const service of config.services ?? []) {
-    addContract(service, config.scopePrefixes?.[service.scope] ?? "");
+    addHttp(service, config.scopePrefixes?.[service.scope] ?? "");
   }
   for (const group of config.groups ?? []) {
     for (const service of group.services)
-      addContract(service, group.pathPrefix ?? "");
+      addHttp(service, group.pathPrefix ?? "");
   }
-  for (const definition of config.runtimeTools ?? []) {
-    const identity = definition.identity;
-    const key = operationKey("runtime", identity.serviceName, identity.action);
-    if (operations.has(key)) {
-      throw new Error(`Duplicate runtime operation identity ${identity.serviceName}.${identity.action}`);
+  const toolSurfaces = [];
+  const addToolProjection = (transport, surface, projection, presentation = {}) => {
+    const projected = projectToolSurface(projection, transport, transport === "MCP" ? config.mcpPreparation ?? {} : presentation);
+    const collected = transport === "MCP" ? prepareProjectedMcpTools(projected.map(mcpProjectionCandidate), config.mcpPreparation ?? {}).map((prepared) => ({
+      ...prepared.tool,
+      presentationSchema: prepared.inputSchema
+    })) : projected;
+    const tools = [];
+    for (const entry of collected) {
+      const source = entry.kind === "contract" ? entry.source : {
+        definitionToken: entry.source,
+        method: entry.source.identity.method,
+        serviceName: entry.source.identity.serviceName,
+        key: entry.source.identity.action,
+        desc: entry.source.description,
+        ...entry.source.identity.scope !== undefined && {
+          scope: entry.source.identity.scope
+        },
+        inputSchema: entry.source.input,
+        ...entry.source.output !== undefined && {
+          outputSchema: entry.source.output
+        },
+        toolName: entry.source.name,
+        expose: entry.source.transports,
+        ...entry.source.annotations !== undefined && {
+          annotations: entry.source.annotations
+        },
+        ...entry.source.ui !== undefined && { ui: entry.source.ui },
+        ...entry.source.identity.meta !== undefined && {
+          meta: entry.source.identity.meta
+        },
+        ...entry.source.mcp !== undefined && { mcp: entry.source.mcp }
+      };
+      const operation = addOperation(entry.kind, source);
+      tools.push({
+        kind: entry.kind,
+        service: operation.service,
+        action: operation.action,
+        name: entry.name,
+        input: presentationDigest(entry.presentationSchema)
+      });
     }
-    operations.set(key, {
-      kind: "runtime",
-      service: identity.serviceName,
-      action: identity.action,
-      method: identity.method,
-      scope: identity.scope ?? null,
-      description: definition.description,
-      schemas: {
-        params: null,
-        input: schemaDigest(definition.input, "input"),
-        output: schemaDigest(definition.output, "output"),
-        multipart: null
-      },
-      http: [],
-      tools: {}
-    });
-  }
-  const usedNames = {
-    MCP: new Set,
-    AGENT: new Set,
-    CLI: new Set
+    toolSurfaces.push({ transport, surface, tools: sortTools(tools) });
   };
-  const addTool = (operation, name, transport) => {
-    if (transport !== "CLI")
-      assertToolName(name, operation.service, operation.action);
-    const surface = transport === "CLI" ? "CLI command" : transport === "MCP" ? "MCP tool name" : "agent tool name";
-    assertUniqueToolName(name, usedNames[transport].has(name), surface);
-    usedNames[transport].add(name);
-    operation.tools[transport] = name;
+  const shared = {
+    services: config.services,
+    runtimeTools: config.runtimeTools
   };
-  for (const service of uniqueToolServices(config)) {
-    for (const method of Object.values(service.methods)) {
-      if (method.multipart || method.rawBody || method.rawResponse || method.responseMeta)
-        continue;
-      const operation = operations.get(operationKey("contract", service.name, method.key));
-      if (!operation)
-        continue;
-      const name = method.toolName ?? toToolName(service.name, method.key);
-      if (!method.expose || method.expose.includes("MCP"))
-        addTool(operation, name, "MCP");
-      if (!method.expose || method.expose.includes("AGENT"))
-        addTool(operation, name, "AGENT");
-      if (method.expose?.includes("CLI"))
-        addTool(operation, name, "CLI");
+  const explicitMcp = config.toolSurfaces?.MCP;
+  const namedMcp = config.mcpSurfaces;
+  if (explicitMcp && namedMcp) {
+    throw new Error("Surface manifest MCP topology must use either one direct surface or named surfaces");
+  }
+  if (explicitMcp)
+    addToolProjection("MCP", null, explicitMcp);
+  if (namedMcp) {
+    for (const name of Object.keys(namedMcp).sort(compareCodepoints)) {
+      const projection = namedMcp[name];
+      if (projection)
+        addToolProjection("MCP", name, projection);
     }
   }
-  for (const definition of config.runtimeTools ?? []) {
-    const operation = operations.get(operationKey("runtime", definition.identity.serviceName, definition.identity.action));
-    if (!operation)
+  if (!explicitMcp && !namedMcp)
+    addToolProjection("MCP", null, shared);
+  const agent = config.toolSurfaces?.AGENT;
+  addToolProjection("AGENT", null, agent ?? shared, agent ?? {});
+  addToolProjection("CLI", null, config.toolSurfaces?.CLI ?? shared);
+  const realtime = [];
+  const realtimeContracts = Object.keys(config.realtime ?? {}).sort(compareCodepoints);
+  for (const contractName of realtimeContracts) {
+    const contract = config.realtime?.[contractName];
+    if (!contract)
       continue;
-    const transports = definition.transports ?? [
-      "MCP",
-      "AGENT"
-    ];
-    for (const transport of transports)
-      addTool(operation, definition.name, transport);
+    for (const direction of ["serverToClient", "clientToServer"]) {
+      const registry = contract[direction];
+      for (const event of Object.keys(registry).sort(compareCodepoints)) {
+        const definition = registry[event];
+        if (!definition)
+          continue;
+        const argsInput = schemaDigest(definition.args, "input");
+        const argsOutput = schemaDigest(definition.args, "output");
+        if (!argsInput || !argsOutput)
+          throw new Error("Realtime args schema digest missing");
+        let acknowledgement = null;
+        if (definition.ack) {
+          const input = schemaDigest(definition.ack, "input");
+          const output = schemaDigest(definition.ack, "output");
+          if (!input || !output)
+            throw new Error("Realtime ack schema digest missing");
+          acknowledgement = { input, output };
+        }
+        realtime.push({
+          contract: contractName,
+          direction,
+          event,
+          args: { input: argsInput, output: argsOutput },
+          acknowledgement
+        });
+      }
+    }
   }
   const cliOnly = (config.cliCommands ?? []).map((command) => ({
     name: command.name,
@@ -225,10 +347,16 @@ function buildSurfaceManifest(config) {
     input: schemaDigest(command.input, "input") ?? digestValue({}),
     output: schemaDigest(command.output, "output")
   })).sort((left, right) => compareCodepoints(left.name, right.name));
+  for (const operation of operations.values()) {
+    operation.http.sort((left, right) => compareCodepoints(left.path, right.path) || compareCodepoints(left.method, right.method));
+  }
   return SurfaceManifestSchema.parse({
-    manifestVersion: 1,
+    manifestVersion: 2,
     digestVersion: 1,
     operations: [...operations.values()].sort((left, right) => compareCodepoints(left.service, right.service) || compareCodepoints(left.action, right.action) || compareCodepoints(left.kind, right.kind)),
+    toolSurfaces: toolSurfaces.sort((left, right) => compareCodepoints(left.transport, right.transport) || compareCodepoints(left.surface ?? "", right.surface ?? "")),
+    realtimeContracts,
+    realtime,
     cliOnly,
     extensions: [...config.extensions ?? []].sort((left, right) => compareCodepoints(left.transport, right.transport) || compareCodepoints(left.name, right.name))
   });
@@ -244,13 +372,182 @@ actual: ${actual}`);
 }
 
 // src/testing/surface-conformance.ts
-var ProbeOutcomeSchema = z2.enum(["success", "validation_error", "domain_error", "aborted"]);
-var TransportObservationSchema = z2.object({
-  outcome: ProbeOutcomeSchema,
+var RealtimeRejectionObservationSchema = z2.object({
+  direction: z2.enum([
+    "client-inbound",
+    "client-outbound",
+    "server-inbound",
+    "server-outbound"
+  ]),
+  phase: z2.enum(["arguments", "acknowledgement"]),
+  reason: z2.enum([
+    "unknown-event",
+    "invalid-arguments",
+    "invalid-acknowledgement-value",
+    "missing-acknowledgement"
+  ]),
+  fault: z2.enum(["peer", "local"])
+});
+var ObservationFields = {
   code: z2.string().optional(),
   data: z2.unknown().optional(),
-  diagnostic: z2.string().optional()
+  diagnostic: z2.string().optional(),
+  handlerCalls: z2.number().int().nonnegative().optional()
+};
+var RealtimeDisconnectObservationSchema = z2.object({
+  phase: z2.enum(["before-invoke", "in-flight"])
 });
+var TransportObservationSchema = z2.discriminatedUnion("outcome", [
+  z2.object({ outcome: z2.literal("success"), ...ObservationFields }),
+  z2.object({ outcome: z2.literal("validation_error"), ...ObservationFields }),
+  z2.object({ outcome: z2.literal("domain_error"), ...ObservationFields }),
+  z2.object({ outcome: z2.literal("aborted"), ...ObservationFields }),
+  z2.object({
+    outcome: z2.literal("realtime_rejected"),
+    ...ObservationFields,
+    rejection: RealtimeRejectionObservationSchema
+  }),
+  z2.object({
+    outcome: z2.literal("disconnected"),
+    ...ObservationFields,
+    disconnect: RealtimeDisconnectObservationSchema
+  }),
+  z2.object({ outcome: z2.literal("timeout"), ...ObservationFields })
+]);
+function scenarioOutcome(scenario) {
+  if (scenario === "event" || scenario === "acknowledgement")
+    return "success";
+  if (scenario === "invalid_arguments" || scenario === "invalid_acknowledgement") {
+    return "realtime_rejected";
+  }
+  if (scenario === "disconnected" || scenario === "in_flight_disconnect") {
+    return "disconnected";
+  }
+  return "timeout";
+}
+function assertScenarioExpectation(scenario, expected) {
+  const outcome = scenarioOutcome(scenario);
+  if (expected.outcome !== outcome) {
+    throw new TypeError(`Realtime probe scenario "${scenario}" requires outcome "${outcome}"`);
+  }
+  if (expected.outcome === "realtime_rejected" && (scenario === "invalid_arguments" && expected.rejection.phase !== "arguments" || scenario === "invalid_acknowledgement" && expected.rejection.phase !== "acknowledgement")) {
+    throw new TypeError(`Realtime probe scenario "${scenario}" has incompatible rejection phase`);
+  }
+  if (scenario === "invalid_arguments" && expected.handlerCalls !== 0) {
+    throw new TypeError('Realtime probe scenario "invalid_arguments" requires handlerCalls: 0');
+  }
+  if (expected.outcome === "disconnected") {
+    const phase = scenario === "disconnected" ? "before-invoke" : "in-flight";
+    if (expected.disconnect.phase !== phase) {
+      throw new TypeError(`Realtime probe scenario "${scenario}" requires disconnect phase "${phase}"`);
+    }
+  }
+}
+function defineRealtimeProbe(config) {
+  const expected = TransportObservationSchema.parse(config.expected);
+  assertScenarioExpectation(config.scenario, expected);
+  return {
+    name: config.name,
+    fixture: { scenario: config.scenario, value: config.fixture },
+    transports: ["REALTIME"],
+    expected: { REALTIME: expected },
+    setup: config.setup,
+    teardown: config.teardown
+  };
+}
+function rejectionObservation(rejected) {
+  return RealtimeRejectionObservationSchema.parse(rejected);
+}
+function createRealtimeProbeDriver({
+  bind,
+  handlerCalls
+}) {
+  return {
+    async invoke(fixture, signal) {
+      let rejected;
+      const currentRejection = () => rejected;
+      const adapter = bind((event) => {
+        rejected = event;
+      }, fixture);
+      const connectedBefore = adapter.connected();
+      const callsBefore = handlerCalls?.();
+      const withCalls = (observation) => {
+        if (callsBefore === undefined || !handlerCalls)
+          return observation;
+        return { ...observation, handlerCalls: handlerCalls() - callsBefore };
+      };
+      try {
+        signal.throwIfAborted();
+        const data = await adapter.invoke(fixture, signal);
+        const observedRejection = currentRejection();
+        if (observedRejection) {
+          return withCalls({
+            outcome: "realtime_rejected",
+            code: observedRejection.error.code,
+            rejection: rejectionObservation(observedRejection)
+          });
+        }
+        return withCalls({
+          outcome: "success",
+          ...data !== undefined && { data }
+        });
+      } catch (error) {
+        const observedRejection = currentRejection();
+        if (observedRejection) {
+          return withCalls({
+            outcome: "realtime_rejected",
+            code: error instanceof RealtimeRequestInvalidAcknowledgementError ? error.code : observedRejection.error.code,
+            rejection: rejectionObservation(observedRejection)
+          });
+        }
+        if (error instanceof RealtimeRequestInvalidAcknowledgementError) {
+          return withCalls({
+            outcome: "realtime_rejected",
+            code: error.code,
+            rejection: {
+              direction: "client-inbound",
+              phase: "acknowledgement",
+              reason: "invalid-acknowledgement-value",
+              fault: "peer"
+            }
+          });
+        }
+        if (error instanceof RealtimeRequestDisconnectedError) {
+          return withCalls({
+            outcome: "disconnected",
+            code: error.code,
+            disconnect: {
+              phase: connectedBefore ? "in-flight" : "before-invoke"
+            }
+          });
+        }
+        if (error instanceof RealtimeRequestTimeoutError) {
+          return withCalls({ outcome: "timeout", code: error.code });
+        }
+        if (signal.aborted && error === signal.reason) {
+          return withCalls({ outcome: "aborted" });
+        }
+        const parsedRejection = RealtimeRejectionObservationSchema.safeParse(typeof error === "object" && error !== null && "details" in error ? error.details : undefined);
+        if (parsedRejection.success) {
+          const code2 = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "REALTIME_CONTRACT_VIOLATION";
+          return withCalls({
+            outcome: "realtime_rejected",
+            code: code2,
+            rejection: parsedRejection.data
+          });
+        }
+        const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : undefined;
+        return withCalls({
+          outcome: "domain_error",
+          ...code !== undefined && { code },
+          diagnostic: error instanceof Error ? error.message : String(error)
+        });
+      } finally {
+        await adapter.dispose?.();
+      }
+    }
+  };
+}
 function sorted(values) {
   return [...values].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
 }
@@ -266,11 +563,12 @@ actual: ${actual.join(", ") || "(empty)"}`);
 function openApiOperations(document) {
   return Object.entries(document.paths).flatMap(([path, item]) => Object.keys(item).filter((method) => ["get", "post", "put", "patch", "delete", "head"].includes(method)).map((method) => `${method.toUpperCase()}:${path}`));
 }
-function expectedToolNames(operations, transport) {
-  return operations.flatMap((operation) => {
-    const name = operation.tools[transport];
-    return name ? [name] : [];
-  });
+function expectedToolNames(manifest, transport, surface) {
+  const projection = manifest.toolSurfaces.find((candidate) => candidate.transport === transport && candidate.surface === surface);
+  if (!projection) {
+    throw new Error(`${transport} surface "${surface ?? "(default)"}" is not declared in the manifest`);
+  }
+  return projection.tools.map((tool) => tool.name);
 }
 function assertSurfaceDiscovery(manifest, observed) {
   if (observed.openApi) {
@@ -278,13 +576,31 @@ function assertSurfaceDiscovery(manifest, observed) {
   }
   for (const transport of ["MCP", "AGENT", "CLI"]) {
     const names = observed[transport];
-    if (names)
-      assertSameSet(`${transport} discovery`, expectedToolNames(manifest.operations, transport), names);
+    if (names) {
+      assertSameSet(`${transport} discovery`, expectedToolNames(manifest, transport, null), names);
+    }
+  }
+  for (const projection of observed.toolSurfaces ?? []) {
+    assertSameSet(`${projection.transport} surface "${projection.surface ?? "(default)"}" discovery`, expectedToolNames(manifest, projection.transport, projection.surface ?? null), projection.names);
+  }
+  for (const [contract, topology] of Object.entries(observed.realtime ?? {})) {
+    if (!manifest.realtimeContracts.includes(contract)) {
+      throw new Error(`REALTIME contract "${contract}" is not declared in the manifest`);
+    }
+    for (const direction of ["serverToClient", "clientToServer"]) {
+      assertSameSet(`REALTIME ${contract}.${direction} discovery`, manifest.realtime.filter((entry) => entry.contract === contract && entry.direction === direction).map((entry) => entry.event), topology[direction]);
+    }
   }
   if (observed.cliOnly) {
     assertSameSet("CLI-only discovery", manifest.cliOnly.map((command) => command.name), observed.cliOnly);
   }
-  for (const transport of ["HTTP", "MCP", "AGENT", "CLI"]) {
+  for (const transport of [
+    "HTTP",
+    "MCP",
+    "AGENT",
+    "CLI",
+    "REALTIME"
+  ]) {
     const names = observed.extensions?.[transport];
     if (!names)
       continue;
@@ -303,8 +619,13 @@ function boundedObservation(observation, maxDiagnosticBytes) {
     diagnostic: new TextDecoder().decode(bytes.slice(0, maxDiagnosticBytes))
   };
 }
-async function invokeBounded(driver, fixture, signal) {
-  signal.throwIfAborted();
+async function runBounded(run, signal) {
+  if (signal.aborted) {
+    Promise.resolve().then(run).catch(() => {
+      return;
+    });
+    throw signal.reason;
+  }
   let removeAbortListener = () => {
     return;
   };
@@ -314,7 +635,7 @@ async function invokeBounded(driver, fixture, signal) {
     removeAbortListener = () => signal.removeEventListener("abort", onAbort);
   });
   try {
-    return await Promise.race([driver.invoke(fixture, signal), aborted]);
+    return await Promise.race([Promise.resolve().then(run), aborted]);
   } finally {
     removeAbortListener();
   }
@@ -326,22 +647,28 @@ async function runSurfaceProbes({
   timeoutMs = 1e4,
   maxDiagnosticBytes = 4096
 }) {
-  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-    throw new TypeError("Surface probe timeoutMs must be a finite positive number");
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new TypeError("Surface probe timeoutMs must be a positive integer");
   }
   if (!Number.isInteger(maxDiagnosticBytes) || maxDiagnosticBytes <= 0) {
     throw new TypeError("Surface probe maxDiagnosticBytes must be a positive integer");
   }
   for (const probe of probes) {
-    await probe.setup?.();
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const probeSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+    let failed = false;
+    let failure;
     try {
+      probeSignal.throwIfAborted();
+      if (probe.setup)
+        await runBounded(() => probe.setup?.(probeSignal), probeSignal);
       for (const transport of probe.transports) {
+        probeSignal.throwIfAborted();
         const driver = drivers[transport];
-        if (!driver)
+        if (!driver) {
           throw new Error(`Surface probe "${probe.name}" has no ${transport} driver`);
-        const timeoutSignal = AbortSignal.timeout(timeoutMs);
-        const invokeSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
-        const actual = boundedObservation(await invokeBounded(driver, probe.fixture, invokeSignal), maxDiagnosticBytes);
+        }
+        const actual = boundedObservation(await runBounded(() => driver.invoke(probe.fixture, probeSignal), probeSignal), maxDiagnosticBytes);
         const expected = probe.expected[transport];
         if (!expected) {
           throw new Error(`Surface probe "${probe.name}" has no ${transport} expectation`);
@@ -352,9 +679,22 @@ expected: ${serializeSurfaceValue(expected)}
 actual: ${serializeSurfaceValue(actual)}`);
         }
       }
-    } finally {
-      await probe.teardown?.();
+    } catch (error) {
+      failed = true;
+      failure = error;
+    }
+    if (probe.teardown) {
+      try {
+        await runBounded(() => probe.teardown?.(probeSignal), probeSignal);
+      } catch (error) {
+        if (!failed) {
+          failed = true;
+          failure = error;
+        }
+      }
     }
+    if (failed)
+      throw failure;
   }
 }
 
@@ -384,9 +724,15 @@ function createHandlerTestClients(config) {
   return createClients(config.contracts, createTestClientConfig(config), config.contractConfig);
 }
 export {
+  RealtimeDisconnectObservationSchema,
+  RealtimeRejectionObservationSchema,
   SurfaceManifestExtensionSchema,
   SurfaceManifestOperationSchema,
+  SurfaceManifestRealtimeEventSchema,
   SurfaceManifestSchema,
+  SurfaceManifestToolSchema,
+  SurfaceManifestToolSurfaceSchema,
+  SurfaceRealtimeSchemaPairSchema,
   SurfaceSchemaDigestsSchema,
   TransportObservationSchema,
   assertSurfaceDiscovery,
@@ -394,6 +740,8 @@ export {
   buildSurfaceManifest,
   createHandlerTestClient,
   createHandlerTestClients,
+  createRealtimeProbeDriver,
+  defineRealtimeProbe,
   runSurfaceProbes,
   serializeSurfaceValue
 };