@ggui-ai/mcp-server 0.14.0 → 0.16.0

package/dist/mcp-endpoint-routes.js

@@ -3,7 +3,7 @@
  *
  *   POST <universalMcpPath>            — DATA PLANE: agent+runtime tools
  *                                        (default `/mcp`)
- *   POST <pathPrefix>/:appId           — data plane, per-tenant variant
+ *   POST <pathPrefix>/:appId           — data plane, per-app variant
  *                                        (opt-in via `perAppRouting`)
  *   POST /control                      — CONTROL PLANE: design-time
  *                                        spec/discovery (anonymous) +
@@ -31,13 +31,50 @@
  * (`agent` / `runtime` / `protocol` / `ops`) and the wire-name prefix
  * rules.
  */
-import { isRecord } from "@ggui-ai/protocol";
+import { MCP_ERROR_CODES, isRecord } from "@ggui-ai/protocol";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { randomUUID } from "node:crypto";
 import { resolveIdentity, UnauthenticatedError } from "./auth.js";
 import { buildMcpServer } from "./build-mcp.js";
 import { CONTROL_PATH, DATA_PLANE_AUDIENCES, filterHandlersByAudience, } from "./control-service.js";
 import { buildWwwAuthenticate, resolveIssuerUrl } from "./oauth.js";
+/** The JSON-RPC error object a mapped result becomes on the wire. */
+function jsonRpcError(mapped) {
+    return {
+        code: mapped.code,
+        message: mapped.message,
+        ...(mapped.data !== undefined ? { data: mapped.data } : {}),
+    };
+}
+/** The two statuses an authorization refusal may carry — a mapper is bounded to them. */
+const AUTHORIZATION_REFUSAL_STATUSES = new Set([401, 403]);
+/**
+ * A deployment's error mapper may attach JSON-RPC `data` (and its own
+ * `code` / `message` / headers) to a per-app authorization refusal, so a
+ * client can read a structured reason instead of parsing prose. The
+ * refusal stays a 401 or a 403: a mapper answering any other status, or
+ * throwing, is ignored and logged, and the default-deny 403 stands
+ * byte-identical to a deployment with no mapper at all.
+ */
+function mapAuthorizationRefusal(err, errorMapper, log) {
+    if (!errorMapper)
+        return undefined;
+    let mapped;
+    try {
+        mapped = errorMapper(err);
+    }
+    catch (mapperErr) {
+        log.warn("error_mapper_failed", { error: String(mapperErr) });
+        return undefined;
+    }
+    if (mapped === undefined)
+        return undefined;
+    if (!AUTHORIZATION_REFUSAL_STATUSES.has(mapped.status)) {
+        log.warn("per_app_authorize_mapper_out_of_bounds", { status: mapped.status });
+        return undefined;
+    }
+    return mapped;
+}
 /**
  * Resolve the resource path that `WWW-Authenticate` should point at
  * for the current request. Per-app `/mcp` requests
@@ -113,7 +150,7 @@ export function mountMcpEndpoints(opts) {
                     identity = { identity: { kind: "builder" }, source: "anonymous" };
                 }
                 else {
-                    // Diagnostic: did a Bearer credential actually reach the pod on
+                    // Diagnostic: did a Bearer credential actually reach the server on
                     // this request? This splits "the client/transport never sent one"
                     // from "we received it but the adapter rejected it" — otherwise
                     // indistinguishable in `auth_failed`. Only a short, non-secret
@@ -145,7 +182,7 @@ export function mountMcpEndpoints(opts) {
                     }
                     res.status(401).json({
                         jsonrpc: "2.0",
-                        error: { code: -32000, message: err.message },
+                        error: { code: MCP_ERROR_CODES.UNAUTHORIZED, message: err.message },
                         id: null,
                     });
                     return;
@@ -171,7 +208,10 @@ export function mountMcpEndpoints(opts) {
             reqLogger.warn("federated_identity_rejected", { route: req.path });
             res.status(403).json({
                 jsonrpc: "2.0",
-                error: { code: -32000, message: "federated identities are not permitted on this route" },
+                error: {
+                    code: MCP_ERROR_CODES.UNAUTHORIZED,
+                    message: "federated identities are not permitted on this route",
+                },
                 id: null,
             });
             return;
@@ -196,7 +236,7 @@ export function mountMcpEndpoints(opts) {
                 res.status(401).json({
                     jsonrpc: "2.0",
                     error: {
-                        code: -32000,
+                        code: MCP_ERROR_CODES.UNAUTHORIZED,
                         message: `${opsToolName} is an operator tool and needs an authenticated caller. ` +
                             `Present a bearer token this deployment accepts, or complete the OAuth flow ` +
                             `advertised in WWW-Authenticate (universal connector keys come from the ` +
@@ -207,10 +247,10 @@ export function mountMcpEndpoints(opts) {
                 return;
             }
         }
-        // Per-tenant URL routing. When `perAppRouting`
+        // Per-app URL routing. When `perAppRouting`
         // is configured AND the request matched the per-app path
         // `/:${paramName}/mcp`, Express populates `req.params[paramName]`
-        // with the validated tenant id. Use it as `ctx.appId` for this
+        // with the validated app id. Use it as `ctx.appId` for this
         // request, overriding `appIdFromIdentity`. The universal `/mcp`
         // route doesn't have the param so it falls through to the
         // identity-based resolution.
@@ -218,11 +258,14 @@ export function mountMcpEndpoints(opts) {
         const hasUrlAppId = typeof urlAppId === "string" && urlAppId.length > 0;
         // Per-app authorize hook — when the deployment configured
         // `perAppRouting.authorize` AND the request matched the per-app
-        // path, invoke the callback. Throwing collapses to a 403 before
-        // the MCP handler ever sees the request, which is the boundary
-        // that prevents cross-user blueprint reads when pod tools bypass
+        // path, invoke the callback. Throwing refuses before the MCP
+        // handler ever sees the request, which is the boundary that
+        // prevents cross-user blueprint reads when a deployment's own tools bypass
         // AppSync owner-auth via raw DDB. Universal-endpoint requests
-        // skip this entirely (no urlAppId).
+        // skip this entirely (no urlAppId). The deployment's `errorMapper`
+        // may give the refusal a structured JSON-RPC `data` (bounded to
+        // 401 / 403, see `mapAuthorizationRefusal`); otherwise — and for
+        // every mapping outside those bounds — the default-deny 403 stands.
         if (hasUrlAppId && perAppRouting?.authorize) {
             try {
                 await perAppRouting.authorize(urlAppId, identity);
@@ -232,9 +275,17 @@ export function mountMcpEndpoints(opts) {
                     urlAppId,
                     reason: err instanceof Error ? err.message : String(err),
                 });
-                res.status(403).json({
+                const mapped = mapAuthorizationRefusal(err, errorMapper, reqLogger);
+                if (mapped?.headers)
+                    res.set(mapped.headers);
+                res.status(mapped?.status ?? 403).json({
                     jsonrpc: "2.0",
-                    error: { code: -32000, message: "Forbidden" },
+                    // #836: a first-party server never answers -32000 — that is the SDK
+                    // client's own ConnectionClosed number, so a refusal and a dropped
+                    // socket would read the same. An authorization refusal is UNAUTHORIZED.
+                    error: mapped
+                        ? jsonRpcError(mapped)
+                        : { code: MCP_ERROR_CODES.UNAUTHORIZED, message: "Unauthorized" },
                     id: null,
                 });
                 return;
@@ -248,11 +299,11 @@ export function mountMcpEndpoints(opts) {
             // handler should branch on the specific mechanism.
             authSource: identity.source,
             // Identity is the canonical source of two mutually-exclusive
-            // hosted fields: `apiKeyHash` for kind=app, `userId` for kind=user.
-            // Threading them onto HandlerContext here means hosted handlers
-            // (the K8s ggui-protocol pod's billing gate + per-user blueprint
-            // scoping) can read identity directly without a parallel pod-only
-            // context shape; OSS handlers continue to ignore both fields.
+            // fields: `apiKeyHash` for kind=app, `userId` for kind=user.
+            // Threading them onto HandlerContext here means a deployment's own
+            // handlers (per-key metering, per-user scoping) can read identity
+            // directly without a parallel context shape; the handlers this
+            // package ships ignore both fields.
             ...(identity.identity.kind === "app" ? { apiKeyHash: identity.identity.apiKeyHash } : {}),
             ...(identity.identity.kind === "user" ? { userId: identity.identity.userId } : {}),
             // What the credential itself may act on, when the adapter
@@ -301,7 +352,7 @@ export function mountMcpEndpoints(opts) {
                         res.set(mapped.headers);
                     res.status(mapped.status).json({
                         jsonrpc: "2.0",
-                        error: { code: mapped.code, message: mapped.message },
+                        error: jsonRpcError(mapped),
                         id: null,
                     });
                 }
@@ -316,7 +367,9 @@ export function mountMcpEndpoints(opts) {
         }
     };
     const methodNotAllowed = (_req, res) => {
-        res.status(405).json({
+        // A 405 names what IS allowed (RFC 9110 §15.5.6); every mount here is
+        // POST-only.
+        res.set("Allow", "POST").status(405).json({
             jsonrpc: "2.0",
             error: {
                 code: -32000,
@@ -341,24 +394,24 @@ export function mountMcpEndpoints(opts) {
         anonymousOpsChallenge: controlOpsToolNames,
     });
     // Universal endpoint — `appId` resolved from the auth identity via
-    // `appIdFromIdentity`. Cloud `mcp.ggui.ai` deployments resolve this
-    // to `User.defaultAppId` via the auth-adapter; OSS deployments fall
-    // through to userId / DEFAULT_BUILDER_APP_ID.
+    // `appIdFromIdentity`. A deployment's auth adapter may resolve it
+    // (e.g. to the user's default app); without one it falls through to
+    // userId / DEFAULT_BUILDER_APP_ID.
     //
-    // Path defaults to `/mcp` (Streamable HTTP convention). Cloud
-    // `mcp.ggui.ai` overrides to `/` so the bare-root URL is the
-    // universal endpoint — domain already says "mcp", no path repeat.
+    // Path defaults to `/mcp` (Streamable HTTP convention). A deployment
+    // whose hostname already says "mcp" may serve it at `/` so the
+    // bare-root URL is the universal endpoint — no path repeat.
     // Exposes audience tags ['agent', 'runtime'] — runtime tools stay
     // routable on the same endpoint but invisible to the agent's
     // `tools/list` via the `_meta.ui.visibility: ['app']` filter.
     app.post(universalMcpPath, agentMcpHandler);
-    // Per-tenant endpoint — only mounted when the deployment opts in
+    // Per-app endpoint — only mounted when the deployment opts in
     // via `perAppRouting`. The same handler reads `req.params[paramName]`
     // and uses it as `ctx.appId` for the request.
     //
     // When `pathPrefix` is set, the route mounts at
-    // `${pathPrefix}/:${paramName}` — cloud uses `/apps` so URLs are
-    // `mcp.ggui.ai/apps/<appId>`. The prefix segments per-tenant traffic
+    // `${pathPrefix}/:${paramName}` — e.g. `/apps`, so URLs read
+    // `<host>/apps/<appId>`. The prefix segments per-app traffic
     // from system routes (`/health`, `/oauth/*`, `/.well-known/*`,
     // `/r/*`) so an opaque appId can never shadow a future static path.
     //
@@ -386,6 +439,12 @@ export function mountMcpEndpoints(opts) {
         });
         const route = pathPrefix !== undefined ? `${pathPrefix}/:${paramName}` : `/:${paramName}`;
         app.post(route, agentMcpHandler);
+        // The per-app endpoint is POST-only like every other mount: GET (a
+        // client's optional SSE listener) and DELETE (session terminate) read
+        // the transport's 405, never Express's text/html 404 — a 404 says "no
+        // such resource" and a client retries it every turn (ggui#850).
+        app.get(route, methodNotAllowed);
+        app.delete(route, methodNotAllowed);
     }
     // /control — the control plane. Hosts every `audience: ['protocol']`
     // tool (design-time spec/discovery, anonymous) and every

package/dist/oauth-as-routes.d.ts

@@ -29,7 +29,7 @@ interface MountOptions {
     /** Universal MCP endpoint path — the default RFC 9728 resource. */
     readonly universalMcpPath: string;
     /**
-     * Per-tenant URL routing shape. When configured, a second
+     * Per-app URL routing shape. When configured, a second
      * well-known endpoint mounts under the same path prefix the
      * per-app `/mcp` handler lives on.
      */

package/dist/oauth.d.ts

@@ -51,13 +51,13 @@
  * Auth codes + DCR clients live in-memory ({@link InMemoryOAuthStorage}).
  * For multi-replica deployments (2+ processes behind one load
  * balancer), either:
- *   - Use nginx-ingress sticky sessions so the same pod handles both
- *     `/oauth/authorize` and `/oauth/token` (current sandbox posture).
+ *   - Use sticky sessions at your load balancer / reverse proxy so the
+ *     same replica handles both `/oauth/authorize` and `/oauth/token`.
  *   - Plug a Redis-backed {@link OAuthStorage} via the
  *     `oauth.storage` config option (production posture).
  *
  * DCR clients are short-lived in practice — Claude Desktop registers
- * once per install + caches the `client_id`. A pod restart drops all
+ * once per install + caches the `client_id`. A server restart drops all
  * registrations; clients re-register transparently on next failure.
  */
 import type { Request, Response } from 'express';

package/dist/oauth.js

@@ -51,13 +51,13 @@
  * Auth codes + DCR clients live in-memory ({@link InMemoryOAuthStorage}).
  * For multi-replica deployments (2+ processes behind one load
  * balancer), either:
- *   - Use nginx-ingress sticky sessions so the same pod handles both
- *     `/oauth/authorize` and `/oauth/token` (current sandbox posture).
+ *   - Use sticky sessions at your load balancer / reverse proxy so the
+ *     same replica handles both `/oauth/authorize` and `/oauth/token`.
  *   - Plug a Redis-backed {@link OAuthStorage} via the
  *     `oauth.storage` config option (production posture).
  *
  * DCR clients are short-lived in practice — Claude Desktop registers
- * once per install + caches the `client_id`. A pod restart drops all
+ * once per install + caches the `client_id`. A server restart drops all
  * registrations; clients re-register transparently on next failure.
  */
 import { createHash, randomBytes } from 'node:crypto';

package/dist/render-read-gate.d.ts

@@ -15,7 +15,7 @@ export interface RenderReadRowView {
      * first time.
      *
      * Absent stays a legitimate state: builder and anonymous
-     * single-tenant flows mint rows with no subject, and those still
+     * single-app flows mint rows with no subject, and those still
      * pass rung 4.
      */
     readonly userId?: string;
@@ -31,9 +31,9 @@ export interface RenderReadRowView {
  *     that subject. The row's subject is its `userId`, written at
  *     commit; see {@link RenderReadRowView.userId} for why this rung
  *     only starts binding now.
- *  4. Everything else same-app passes: app credentials (tenant trust —
+ *  4. Everything else same-app passes: app credentials (app trust —
  *     the app is obligated to enforce its own user-ownership before
- *     fetching on a user's behalf), builder/anonymous single-tenant
+ *     fetching on a user's behalf), builder/anonymous single-app
  *     flows, and rows with no subject.
  *
  * Deny is surfaced by the CALLER byte-identically to a missing row —

package/dist/render-read-gate.js

@@ -9,9 +9,9 @@
  *     that subject. The row's subject is its `userId`, written at
  *     commit; see {@link RenderReadRowView.userId} for why this rung
  *     only starts binding now.
- *  4. Everything else same-app passes: app credentials (tenant trust —
+ *  4. Everything else same-app passes: app credentials (app trust —
  *     the app is obligated to enforce its own user-ownership before
- *     fetching on a user's behalf), builder/anonymous single-tenant
+ *     fetching on a user's behalf), builder/anonymous single-app
  *     flows, and rows with no subject.
  *
  * Deny is surfaced by the CALLER byte-identically to a missing row —

package/dist/runtime-bundle-hash.d.ts

@@ -45,7 +45,7 @@ export declare function resolveHashedRuntimeBundleUrl(plainUrl: string, bundleFi
  * `bundleFile` (default: the workspace's built bundle — the same file
  * `createGguiServer` hashes, so both derive the same value), or
  * `undefined` when the bundle is unreadable. Deployments that compose
- * their own render handler (the cloud pod's `handlers: tools` shape)
+ * their own render handler (a production deployment's `handlers:` shape)
  * use this to build a `createCodeModuleUrlMinter` that stamps the SAME
  * `<rt>` the co-resident factory's variant route serves (ggui#522
  * slice 2) — re-deriving the scheme by hand is how the codeUrl binding

package/dist/runtime-bundle-hash.js

@@ -69,7 +69,7 @@ export function resolveHashedRuntimeBundleUrl(plainUrl, bundleFile = RUNTIME_BUN
  * `bundleFile` (default: the workspace's built bundle — the same file
  * `createGguiServer` hashes, so both derive the same value), or
  * `undefined` when the bundle is unreadable. Deployments that compose
- * their own render handler (the cloud pod's `handlers: tools` shape)
+ * their own render handler (a production deployment's `handlers:` shape)
  * use this to build a `createCodeModuleUrlMinter` that stamps the SAME
  * `<rt>` the co-resident factory's variant route serves (ggui#522
  * slice 2) — re-deriving the scheme by hand is how the codeUrl binding

package/dist/schema-compat.d.ts

@@ -33,6 +33,7 @@
  * loudly at registration time.
  */
 import type { ZodRawShape } from 'zod';
+import { DomainError } from '@ggui-ai/protocol';
 import { type SubsetViolation, type ActionSpec } from '@ggui-ai/protocol';
 /**
  * Stance the host takes when a check surfaces violations.
@@ -136,7 +137,7 @@ export interface GguiSessionContractShape {
  * finding. Carries the full {@link SchemaCompatReport} so callers
  * can log / surface the detail beyond the `message` string.
  */
-export declare class SchemaCompatError extends Error {
+export declare class SchemaCompatError extends DomainError<'schema_mismatch_error'> {
     readonly report: SchemaCompatReport;
     constructor(report: SchemaCompatReport, context: string);
 }

package/dist/schema-compat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,gBAA2B,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,iBAAiB,CAAC;IACtD;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACrC;uDACmD;IACnD,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACnD;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,iBAAiB,CAAC,EAAE;QAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;KACpD,CAAC;CACH;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;gBACxB,MAAM,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM;CAKxD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,wBAAwB,EAChC,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC9B,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,GACd,kBAAkB,CAuFpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAEnE"}
+{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,gBAA2B,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,iBAAiB,CAAC;IACtD;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACrC;uDACmD;IACnD,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACnD;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,iBAAiB,CAAC,EAAE;QAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;KACpD,CAAC;CACH;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,WAAW,CAAC,uBAAuB,CAAC;IACzE,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;gBACxB,MAAM,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM;CAIxD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,wBAAwB,EAChC,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC9B,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,GACd,kBAAkB,CAuFpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAEnE"}

package/dist/schema-compat.js

@@ -1,3 +1,4 @@
+import { DomainError } from '@ggui-ai/protocol';
 import { isSchemaSubset, zodToJsonSchema, } from '@ggui-ai/protocol';
 /**
  * Default mode applied when the host does not override. Matches the
@@ -9,11 +10,10 @@ export const DEFAULT_SCHEMA_COMPAT_MODE = 'reject';
  * finding. Carries the full {@link SchemaCompatReport} so callers
  * can log / surface the detail beyond the `message` string.
  */
-export class SchemaCompatError extends Error {
+export class SchemaCompatError extends DomainError {
     report;
     constructor(report, context) {
-        super(formatReport(report, context));
-        this.name = 'SchemaCompatError';
+        super('schema_mismatch_error', formatReport(report, context));
         this.report = report;
     }
 }
@@ -136,7 +136,7 @@ export function hasErrorFinding(report) {
  */
 function formatReport(report, context) {
     if (report.compatible) {
-        return `${context}: SCHEMA_MISMATCH_ERROR (no findings — internal error)`;
+        return `${context} — no findings (internal error)`;
     }
     const sorted = [...report.findings].sort((a, b) => a.specName < b.specName ? -1 : a.specName > b.specName ? 1 : 0);
     const lines = sorted.map((f) => {
@@ -153,7 +153,7 @@ function formatReport(report, context) {
         return `- ${f.kind} "${f.specName}" (tool "${f.toolName}") — schema mismatch${suffix}`;
     });
     return [
-        `${context}: SCHEMA_MISMATCH_ERROR — ${report.findings.length} finding${report.findings.length > 1 ? 's' : ''}`,
+        `${context} — ${report.findings.length} finding${report.findings.length > 1 ? 's' : ''}`,
         ...lines,
     ].join('\n');
 }