stitchkit 0.53.2 → 0.55.0

package/dist/testing/surface-manifest.d.ts

@@ -0,0 +1,156 @@
+import { type ZodObject, type ZodType, z } from 'zod';
+import type { EndpointToolAnnotations, HttpMethod } from '../contract';
+import type { RouteGroup, ServiceDef } from '../server/types';
+import type { CliCommandDefinition } from '../tools/cli-command';
+export declare const SurfaceSchemaDigestsSchema: ZodObject<{
+    params: z.ZodNullable<z.ZodString>;
+    input: z.ZodNullable<z.ZodString>;
+    output: z.ZodNullable<z.ZodString>;
+    multipart: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const SurfaceManifestOperationSchema: ZodObject<{
+    kind: z.ZodEnum<{
+        contract: "contract";
+        runtime: "runtime";
+    }>;
+    service: z.ZodString;
+    action: z.ZodString;
+    method: z.ZodEnum<{
+        DELETE: "DELETE";
+        GET: "GET";
+        HEAD: "HEAD";
+        PATCH: "PATCH";
+        POST: "POST";
+        PUT: "PUT";
+    }>;
+    scope: z.ZodNullable<z.ZodString>;
+    description: z.ZodString;
+    schemas: ZodObject<{
+        params: z.ZodNullable<z.ZodString>;
+        input: z.ZodNullable<z.ZodString>;
+        output: z.ZodNullable<z.ZodString>;
+        multipart: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    http: z.ZodArray<ZodObject<{
+        method: z.ZodEnum<{
+            DELETE: "DELETE";
+            GET: "GET";
+            HEAD: "HEAD";
+            PATCH: "PATCH";
+            POST: "POST";
+            PUT: "PUT";
+        }>;
+        path: z.ZodString;
+    }, z.core.$strip>>;
+    tools: z.ZodRecord<z.ZodEnum<{
+        AGENT: "AGENT";
+        CLI: "CLI";
+        MCP: "MCP";
+    }> & z.core.$partial, z.ZodString>;
+}, z.core.$strip>;
+export declare const SurfaceManifestCliCommandSchema: ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    input: z.ZodString;
+    output: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const SurfaceManifestExtensionSchema: ZodObject<{
+    name: z.ZodString;
+    transport: z.ZodEnum<{
+        AGENT: "AGENT";
+        CLI: "CLI";
+        HTTP: "HTTP";
+        MCP: "MCP";
+    }>;
+}, z.core.$strip>;
+export declare const SurfaceManifestSchema: ZodObject<{
+    manifestVersion: z.ZodLiteral<1>;
+    digestVersion: z.ZodLiteral<1>;
+    operations: z.ZodArray<ZodObject<{
+        kind: z.ZodEnum<{
+            contract: "contract";
+            runtime: "runtime";
+        }>;
+        service: z.ZodString;
+        action: z.ZodString;
+        method: z.ZodEnum<{
+            DELETE: "DELETE";
+            GET: "GET";
+            HEAD: "HEAD";
+            PATCH: "PATCH";
+            POST: "POST";
+            PUT: "PUT";
+        }>;
+        scope: z.ZodNullable<z.ZodString>;
+        description: z.ZodString;
+        schemas: ZodObject<{
+            params: z.ZodNullable<z.ZodString>;
+            input: z.ZodNullable<z.ZodString>;
+            output: z.ZodNullable<z.ZodString>;
+            multipart: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        http: z.ZodArray<ZodObject<{
+            method: z.ZodEnum<{
+                DELETE: "DELETE";
+                GET: "GET";
+                HEAD: "HEAD";
+                PATCH: "PATCH";
+                POST: "POST";
+                PUT: "PUT";
+            }>;
+            path: z.ZodString;
+        }, z.core.$strip>>;
+        tools: z.ZodRecord<z.ZodEnum<{
+            AGENT: "AGENT";
+            CLI: "CLI";
+            MCP: "MCP";
+        }> & z.core.$partial, z.ZodString>;
+    }, z.core.$strip>>;
+    cliOnly: z.ZodArray<ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        input: z.ZodString;
+        output: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    extensions: z.ZodArray<ZodObject<{
+        name: z.ZodString;
+        transport: z.ZodEnum<{
+            AGENT: "AGENT";
+            CLI: "CLI";
+            HTTP: "HTTP";
+            MCP: "MCP";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SurfaceManifest = z.infer<typeof SurfaceManifestSchema>;
+export type SurfaceManifestOperation = z.infer<typeof SurfaceManifestOperationSchema>;
+export type SurfaceManifestExtension = z.infer<typeof SurfaceManifestExtensionSchema>;
+/** Peer-free structural subset needed to describe a pathless runtime operation. */
+export interface SurfaceRuntimeToolDefinition {
+    name: string;
+    description: string;
+    identity: {
+        serviceName: string;
+        action: string;
+        method: HttpMethod;
+        scope?: string;
+    };
+    input: ZodObject;
+    output?: ZodType;
+    transports?: readonly ('MCP' | 'AGENT' | 'CLI')[];
+    annotations?: EndpointToolAnnotations;
+}
+export interface SurfaceManifestConfig {
+    services?: readonly ServiceDef[];
+    groups?: readonly Pick<RouteGroup, 'pathPrefix' | 'services'>[];
+    scopePrefixes?: Readonly<Record<string, string>>;
+    runtimeTools?: readonly SurfaceRuntimeToolDefinition[];
+    cliCommands?: readonly CliCommandDefinition[];
+    extensions?: readonly SurfaceManifestExtension[];
+}
+/** Canonical bytes used by snapshots and schema digests. Arrays retain order. */
+export declare function serializeSurfaceValue(value: unknown): string;
+/** Build one versioned snapshot of the declared HTTP/tool/CLI surface. */
+export declare function buildSurfaceManifest(config: SurfaceManifestConfig): SurfaceManifest;
+export declare function assertSurfaceManifestSnapshot(manifest: SurfaceManifest, snapshot: SurfaceManifest): void;
+//# sourceMappingURL=surface-manifest.d.ts.map

package/dist/testing/surface-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-manifest.d.ts","sourceRoot":"","sources":["../../src/testing/surface-manifest.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtD,OAAO,KAAK,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEvE,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAOjE,eAAO,MAAM,0BAA0B;;;;;iBAKrC,CAAC;AAEH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAUzC,CAAC;AAEH,eAAO,MAAM,+BAA+B;;;;;iBAK1C,CAAC;AAEH,eAAO,MAAM,8BAA8B;;;;;;;;iBAGzC,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAMhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AACtF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,mFAAmF;AACnF,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE;QACR,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,UAAU,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,SAAS,CAAC,KAAK,GAAG,OAAO,GAAG,KAAK,CAAC,EAAE,CAAC;IAClD,WAAW,CAAC,EAAE,uBAAuB,CAAC;CACvC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACjC,MAAM,CAAC,EAAE,SAAS,IAAI,CAAC,UAAU,EAAE,YAAY,GAAG,UAAU,CAAC,EAAE,CAAC;IAChE,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,YAAY,CAAC,EAAE,SAAS,4BAA4B,EAAE,CAAC;IACvD,WAAW,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC9C,UAAU,CAAC,EAAE,SAAS,wBAAwB,EAAE,CAAC;CAClD;AAkBD,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE5D;AAoDD,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CA0InF;AAED,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,eAAe,GACxB,IAAI,CAQN"}

package/dist/testing.d.ts

@@ -31,4 +31,6 @@ export declare function createHandlerTestClient<T extends Record<string, Endpoin
 export declare function createHandlerTestClients<T extends Record<string, ContractDef<Record<string, EndpointDef>, string>>, TServer = unknown, const K extends string = never>(config: HandlerTestClientsConfig<T, TServer, K>): {
     [P in keyof T]: ScopedHttpClient<T[P]['endpoints'], ScopedKeys<K>>;
 };
+export { assertSurfaceDiscovery, type ConformanceTransport, type RunSurfaceProbesConfig, runSurfaceProbes, type SurfaceDiscoveryObservation, type SurfaceProbe, type SurfaceProbeDriver, type TransportObservation, TransportObservationSchema, } from './testing/surface-conformance';
+export { assertSurfaceManifestSnapshot, buildSurfaceManifest, type SurfaceManifest, type SurfaceManifestConfig, type SurfaceManifestExtension, SurfaceManifestExtensionSchema, type SurfaceManifestOperation, SurfaceManifestOperationSchema, SurfaceManifestSchema, type SurfaceRuntimeToolDefinition, SurfaceSchemaDigestsSchema, serializeSurfaceValue, } from './testing/surface-manifest';
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,KAAK,YAAY,EAEjB,KAAK,oBAAoB,EAGzB,KAAK,UAAU,EAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,OAAO,CAAC,CAAC;AAEhF,MAAM,WAAW,0BAA0B,CAAC,OAAO;IACjD,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;IAC/B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,yBAAyB,CAAC;IACnC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB,CACtC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACrC,OAAO,GAAG,OAAO,EACjB,CAAC,SAAS,MAAM,GAAG,KAAK,CACxB,SAAQ,0BAA0B,CAAC,OAAO,CAAC;IAC3C,QAAQ,EAAE,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACjC,cAAc,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,wBAAwB,CACvC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC,EAC1E,OAAO,GAAG,OAAO,EACjB,CAAC,SAAS,MAAM,GAAG,KAAK,CACxB,SAAQ,0BAA0B,CAAC,OAAO,CAAC;IAC3C,SAAS,EAAE,CAAC,CAAC;IACb,cAAc,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC;CAC1C;AA+BD,gGAAgG;AAChG,wBAAgB,uBAAuB,CACrC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACrC,OAAO,GAAG,OAAO,EACjB,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,KAAK,EAC9B,MAAM,EAAE,uBAAuB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAEpF;AAED,2FAA2F;AAC3F,wBAAgB,wBAAwB,CACtC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC,EAC1E,OAAO,GAAG,OAAO,EACjB,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,KAAK,EAE9B,MAAM,EAAE,wBAAwB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,GAC9C;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;CAAE,CAMxE"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/dist/testing.js

@@ -1,9 +1,362 @@
+import {
+  assertToolName,
+  assertUniqueToolName,
+  toToolName
+} from "./index-k4dftwf7.js";
+import {
+  toJsonSchema
+} from "./index-cby4ar3v.js";
 import {
   createClient,
   createClients
-} from "./index-e1es808r.js";
+} from "./index-qh4xevf5.js";
 import"./index-48ffdxgk.js";
-import"./index-bmnhqtya.js";
+import {
+  isRecord
+} from "./index-7eq9va6e.js";
+import"./index-1bx83sw4.js";
+
+// src/testing/surface-conformance.ts
+import { z as z2 } from "zod";
+
+// src/testing/surface-manifest.ts
+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 SurfaceSchemaDigestsSchema = z.object({
+  params: z.string().nullable(),
+  input: z.string().nullable(),
+  output: z.string().nullable(),
+  multipart: z.string().nullable()
+});
+var SurfaceManifestOperationSchema = z.object({
+  kind: z.enum(["contract", "runtime"]),
+  service: z.string(),
+  action: z.string(),
+  method: HttpMethodSchema,
+  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())
+});
+var SurfaceManifestCliCommandSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  input: z.string(),
+  output: z.string().nullable()
+});
+var SurfaceManifestExtensionSchema = z.object({
+  name: z.string(),
+  transport: z.enum(["HTTP", "MCP", "AGENT", "CLI"])
+});
+var SurfaceManifestSchema = z.object({
+  manifestVersion: z.literal(1),
+  digestVersion: z.literal(1),
+  operations: z.array(SurfaceManifestOperationSchema),
+  cliOnly: z.array(SurfaceManifestCliCommandSchema),
+  extensions: z.array(SurfaceManifestExtensionSchema)
+});
+function compareCodepoints(left, right) {
+  if (left < right)
+    return -1;
+  if (left > right)
+    return 1;
+  return 0;
+}
+function canonicalValue(value) {
+  if (Array.isArray(value))
+    return value.map(canonicalValue);
+  if (!isRecord(value))
+    return value;
+  const result = {};
+  for (const key of Object.keys(value).sort(compareCodepoints)) {
+    result[key] = canonicalValue(value[key]);
+  }
+  return result;
+}
+function serializeSurfaceValue(value) {
+  return JSON.stringify(canonicalValue(value));
+}
+function digestValue(value) {
+  return createHash("sha256").update(serializeSurfaceValue(value)).digest("hex").slice(0, 16);
+}
+function canonicalSchemaValue(value, parentKey) {
+  if (Array.isArray(value)) {
+    const entries = value.map((entry) => canonicalSchemaValue(entry));
+    return parentKey === "required" && entries.every((entry) => typeof entry === "string") ? entries.sort((left, right) => compareCodepoints(String(left), String(right))) : entries;
+  }
+  if (!isRecord(value))
+    return value;
+  const result = {};
+  for (const key of Object.keys(value).sort(compareCodepoints)) {
+    result[key] = canonicalSchemaValue(value[key], key);
+  }
+  return result;
+}
+function schemaDigest(schema, io) {
+  if (!schema)
+    return null;
+  return digestValue(canonicalSchemaValue(toJsonSchema(schema, io, "any")));
+}
+function multipartDigest(value) {
+  return value === undefined ? null : digestValue(value);
+}
+function joinPath(...parts) {
+  const joined = parts.filter((part) => Boolean(part)).map((part) => part.replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
+  return `/${joined}`;
+}
+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 buildSurfaceManifest(config) {
+  const operations = new Map;
+  const addContract = (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);
+        continue;
+      }
+      operations.set(key, {
+        kind: "contract",
+        service: service.name,
+        action: method.key,
+        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: {}
+      });
+    }
+  };
+  for (const service of config.services ?? []) {
+    addContract(service, config.scopePrefixes?.[service.scope] ?? "");
+  }
+  for (const group of config.groups ?? []) {
+    for (const service of group.services)
+      addContract(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}`);
+    }
+    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
+  };
+  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;
+  };
+  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");
+    }
+  }
+  for (const definition of config.runtimeTools ?? []) {
+    const operation = operations.get(operationKey("runtime", definition.identity.serviceName, definition.identity.action));
+    if (!operation)
+      continue;
+    const transports = definition.transports ?? [
+      "MCP",
+      "AGENT"
+    ];
+    for (const transport of transports)
+      addTool(operation, definition.name, transport);
+  }
+  const cliOnly = (config.cliCommands ?? []).map((command) => ({
+    name: command.name,
+    description: command.description,
+    input: schemaDigest(command.input, "input") ?? digestValue({}),
+    output: schemaDigest(command.output, "output")
+  })).sort((left, right) => compareCodepoints(left.name, right.name));
+  return SurfaceManifestSchema.parse({
+    manifestVersion: 1,
+    digestVersion: 1,
+    operations: [...operations.values()].sort((left, right) => compareCodepoints(left.service, right.service) || compareCodepoints(left.action, right.action) || compareCodepoints(left.kind, right.kind)),
+    cliOnly,
+    extensions: [...config.extensions ?? []].sort((left, right) => compareCodepoints(left.transport, right.transport) || compareCodepoints(left.name, right.name))
+  });
+}
+function assertSurfaceManifestSnapshot(manifest, snapshot) {
+  const actual = serializeSurfaceValue(SurfaceManifestSchema.parse(manifest));
+  const expected = serializeSurfaceValue(SurfaceManifestSchema.parse(snapshot));
+  if (actual !== expected) {
+    throw new Error(`Surface manifest diverged from its committed snapshot
+expected: ${expected}
+actual: ${actual}`);
+  }
+}
+
+// src/testing/surface-conformance.ts
+var ProbeOutcomeSchema = z2.enum(["success", "validation_error", "domain_error", "aborted"]);
+var TransportObservationSchema = z2.object({
+  outcome: ProbeOutcomeSchema,
+  code: z2.string().optional(),
+  data: z2.unknown().optional(),
+  diagnostic: z2.string().optional()
+});
+function sorted(values) {
+  return [...values].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+}
+function assertSameSet(label, expectedValues, actualValues) {
+  const expected = sorted(expectedValues);
+  const actual = sorted(actualValues);
+  if (serializeSurfaceValue(expected) === serializeSurfaceValue(actual))
+    return;
+  throw new Error(`${label} mismatch
+expected: ${expected.join(", ") || "(empty)"}
+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 assertSurfaceDiscovery(manifest, observed) {
+  if (observed.openApi) {
+    assertSameSet("HTTP/OpenAPI", manifest.operations.flatMap((operation) => operation.http.map((entry) => `${entry.method}:${entry.path.replace(/:([^/]+)/g, "{$1}")}`)), openApiOperations(observed.openApi));
+  }
+  for (const transport of ["MCP", "AGENT", "CLI"]) {
+    const names = observed[transport];
+    if (names)
+      assertSameSet(`${transport} discovery`, expectedToolNames(manifest.operations, transport), names);
+  }
+  if (observed.cliOnly) {
+    assertSameSet("CLI-only discovery", manifest.cliOnly.map((command) => command.name), observed.cliOnly);
+  }
+  for (const transport of ["HTTP", "MCP", "AGENT", "CLI"]) {
+    const names = observed.extensions?.[transport];
+    if (!names)
+      continue;
+    assertSameSet(`${transport} extension discovery`, manifest.extensions.filter((extension) => extension.transport === transport).map((extension) => extension.name), names);
+  }
+}
+function boundedObservation(observation, maxDiagnosticBytes) {
+  const parsed = TransportObservationSchema.parse(observation);
+  if (!parsed.diagnostic)
+    return parsed;
+  const bytes = new TextEncoder().encode(parsed.diagnostic);
+  if (bytes.byteLength <= maxDiagnosticBytes)
+    return parsed;
+  return {
+    ...parsed,
+    diagnostic: new TextDecoder().decode(bytes.slice(0, maxDiagnosticBytes))
+  };
+}
+async function invokeBounded(driver, fixture, signal) {
+  signal.throwIfAborted();
+  let removeAbortListener = () => {
+    return;
+  };
+  const aborted = new Promise((_resolve, reject) => {
+    const onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+    removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+  });
+  try {
+    return await Promise.race([driver.invoke(fixture, signal), aborted]);
+  } finally {
+    removeAbortListener();
+  }
+}
+async function runSurfaceProbes({
+  probes,
+  drivers,
+  signal,
+  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(maxDiagnosticBytes) || maxDiagnosticBytes <= 0) {
+    throw new TypeError("Surface probe maxDiagnosticBytes must be a positive integer");
+  }
+  for (const probe of probes) {
+    await probe.setup?.();
+    try {
+      for (const transport of probe.transports) {
+        const driver = drivers[transport];
+        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 expected = probe.expected[transport];
+        if (!expected) {
+          throw new Error(`Surface probe "${probe.name}" has no ${transport} expectation`);
+        }
+        if (serializeSurfaceValue(actual) !== serializeSurfaceValue(expected)) {
+          throw new Error(`Surface probe "${probe.name}" ${transport} mismatch
+expected: ${serializeSurfaceValue(expected)}
+actual: ${serializeSurfaceValue(actual)}`);
+        }
+      }
+    } finally {
+      await probe.teardown?.();
+    }
+  }
+}
 
 // src/testing.ts
 function resolveTestBaseUrl(origin, pathPrefix) {
@@ -31,6 +384,16 @@ function createHandlerTestClients(config) {
   return createClients(config.contracts, createTestClientConfig(config), config.contractConfig);
 }
 export {
+  SurfaceManifestExtensionSchema,
+  SurfaceManifestOperationSchema,
+  SurfaceManifestSchema,
+  SurfaceSchemaDigestsSchema,
+  TransportObservationSchema,
+  assertSurfaceDiscovery,
+  assertSurfaceManifestSnapshot,
+  buildSurfaceManifest,
+  createHandlerTestClient,
   createHandlerTestClients,
-  createHandlerTestClient
+  runSurfaceProbes,
+  serializeSurfaceValue
 };

package/dist/tools/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/tools/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAGlC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EAEnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAG5D,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACjD;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAwET"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/tools/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,OAAO,EAAE,MAAM,IAAI,CAAC;AAGxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EAEnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAG5D,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACjD;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAwET"}