@ggui-ai/protocol 0.6.2 → 0.7.0

package/dist/errors/resource-read.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Projection from a typed `resources/read` failure onto a JSON-RPC
+ * error (SPEC §7.9 Plane 1).
+ *
+ * A read of a render locator (`ui://ggui/render/{sessionId}/{blueprintKey}`)
+ * returns either a live mount or an error — never a successful result
+ * carrying a shell that will never come alive. Routing every failure
+ * branch through this one function is what makes that host-checkable:
+ * "any successful `contents` result IS a live mount" holds because the
+ * only other exit is a JSON-RPC error.
+ *
+ * # Numeric codes
+ *
+ * `NOT_FOUND` maps to `-32002`. That is the number MCP itself uses for
+ * a resource that does not exist, and the number this protocol already
+ * assigns to a missing session — for a locator keyed by `sessionId`
+ * those are one condition, not two.
+ *
+ * The other three map to `MOUNT_UNAVAILABLE` (`-32006`), a canonical
+ * code claimed from the range the protocol reserves for new ones. They
+ * are deliberately NOT `INTERNAL_ERROR`: a purged component, a server
+ * that keeps no durable record, and a render with no delivery channel
+ * are all deterministic outcomes of a correctly functioning server.
+ * `-32603` would report them as a malfunction and invite hosts to retry
+ * a read that cannot ever succeed. The fine-grained classification
+ * rides on `error.data.code`, so a host that only understands the
+ * number still routes correctly, and one that reads `data.code` can
+ * distinguish "come back never" from "come back with a fresh render".
+ *
+ * # Why `NOT_FOUND` loses its message
+ *
+ * A caller reading a locator it is not allowed to see and a caller
+ * reading a locator that never existed MUST receive byte-identical
+ * errors. Anything that varies between the two — a message naming a
+ * session, a `detail` mentioning a refusal — turns the read into an
+ * oracle for the existence of other callers' renders. Rather than
+ * leaving that to the discipline of every call site, this function
+ * substitutes a constant message and drops `detail` whenever the code
+ * is `NOT_FOUND`. Diagnostics for the refused case belong in the
+ * server's own logs, which the caller cannot read.
+ *
+ * # What this function CANNOT enforce — a server obligation
+ *
+ * Substituting the message closes only the message half of the problem.
+ * The code half stays with the caller: a server that runs its
+ * authorization check late can hand this function a `NOT_MOUNTABLE` or
+ * `BLUEPRINT_UNRESOLVABLE` for a locator the caller was never entitled
+ * to read, and the resulting `-32006` reveals that the locator exists —
+ * the same oracle, reached by a different route, with a mapper behaving
+ * perfectly.
+ *
+ * So the ordering is normative, scoped to the branches that can leak:
+ * a server using this projection MUST route a refusal through its
+ * TERMINAL failure — the single answer it gives for every locator it
+ * will not resolve — and MUST NOT run a branch whose outcome VARIES
+ * WITH THE LOCATOR before the access check. Reaching one of those is
+ * itself the disclosure. Resolution work is exactly such a branch, so
+ * it happens only after the check has passed.
+ *
+ * Naming the TERMINAL rather than a specific code is deliberate. Which
+ * code the terminal carries is a property of the deployment: a server
+ * keeping durable records answers `NOT_FOUND`, one keeping none answers
+ * `NOT_SUPPORTED`, and each answers it for a refused locator and a
+ * missing one alike. Pinning this rule to `NOT_FOUND` would declare the
+ * second server non-conformant for behaving correctly. What the rule
+ * protects is that refusal and absence are the SAME answer — never
+ * which answer it is.
+ *
+ * A deployment-global answer is not a locator-varying branch.
+ * `NOT_SUPPORTED` describes the server and is identical for every
+ * locator on a server that emits it, so answering it before any
+ * per-locator work — the access check included — reveals nothing and is
+ * permitted.
+ */
+import { MCP_ERROR_CODES, type ResourceReadError, type ResourceReadErrorCode } from '../types/mcp.js';
+/**
+ * The single message every `NOT_FOUND` read returns, whatever the
+ * underlying reason. Names no session, app, or caller.
+ */
+export declare const RESOURCE_NOT_FOUND_MESSAGE = "Resource not found.";
+/**
+ * JSON-RPC error body for a failed `resources/read`. `data.code` is the
+ * closed classification; `data.detail` is optional operator context and
+ * is absent whenever `data.code` is `NOT_FOUND`.
+ */
+export interface ResourceReadJsonRpcError {
+    /**
+     * Narrowed to the two numbers this projection can emit, so a consumer
+     * switching on it gets exhaustiveness rather than an open `number`.
+     */
+    readonly code: typeof MCP_ERROR_CODES.SESSION_NOT_FOUND | typeof MCP_ERROR_CODES.MOUNT_UNAVAILABLE;
+    readonly message: string;
+    readonly data: {
+        readonly code: ResourceReadErrorCode;
+        readonly detail?: string;
+    };
+}
+/**
+ * Switch rather than an `if` with a fallthrough on purpose: every member
+ * of the enum is named, so adding a fifth code fails to compile here
+ * until someone decides which number it carries. A default branch would
+ * have swallowed it into `MOUNT_UNAVAILABLE` silently.
+ */
+export declare function resourceReadErrorToJsonRpc(err: ResourceReadError): ResourceReadJsonRpcError;
+//# sourceMappingURL=resource-read.d.ts.map

package/dist/errors/resource-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-read.d.ts","sourceRoot":"","sources":["../../src/errors/resource-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,OAAO,EACL,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AAEzB;;;GAGG;AACH,eAAO,MAAM,0BAA0B,wBAAwB,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EACT,OAAO,eAAe,CAAC,iBAAiB,GACxC,OAAO,eAAe,CAAC,iBAAiB,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;QACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,iBAAiB,GACrB,wBAAwB,CAqB1B"}

package/dist/errors/resource-read.js

@@ -0,0 +1,107 @@
+/**
+ * Projection from a typed `resources/read` failure onto a JSON-RPC
+ * error (SPEC §7.9 Plane 1).
+ *
+ * A read of a render locator (`ui://ggui/render/{sessionId}/{blueprintKey}`)
+ * returns either a live mount or an error — never a successful result
+ * carrying a shell that will never come alive. Routing every failure
+ * branch through this one function is what makes that host-checkable:
+ * "any successful `contents` result IS a live mount" holds because the
+ * only other exit is a JSON-RPC error.
+ *
+ * # Numeric codes
+ *
+ * `NOT_FOUND` maps to `-32002`. That is the number MCP itself uses for
+ * a resource that does not exist, and the number this protocol already
+ * assigns to a missing session — for a locator keyed by `sessionId`
+ * those are one condition, not two.
+ *
+ * The other three map to `MOUNT_UNAVAILABLE` (`-32006`), a canonical
+ * code claimed from the range the protocol reserves for new ones. They
+ * are deliberately NOT `INTERNAL_ERROR`: a purged component, a server
+ * that keeps no durable record, and a render with no delivery channel
+ * are all deterministic outcomes of a correctly functioning server.
+ * `-32603` would report them as a malfunction and invite hosts to retry
+ * a read that cannot ever succeed. The fine-grained classification
+ * rides on `error.data.code`, so a host that only understands the
+ * number still routes correctly, and one that reads `data.code` can
+ * distinguish "come back never" from "come back with a fresh render".
+ *
+ * # Why `NOT_FOUND` loses its message
+ *
+ * A caller reading a locator it is not allowed to see and a caller
+ * reading a locator that never existed MUST receive byte-identical
+ * errors. Anything that varies between the two — a message naming a
+ * session, a `detail` mentioning a refusal — turns the read into an
+ * oracle for the existence of other callers' renders. Rather than
+ * leaving that to the discipline of every call site, this function
+ * substitutes a constant message and drops `detail` whenever the code
+ * is `NOT_FOUND`. Diagnostics for the refused case belong in the
+ * server's own logs, which the caller cannot read.
+ *
+ * # What this function CANNOT enforce — a server obligation
+ *
+ * Substituting the message closes only the message half of the problem.
+ * The code half stays with the caller: a server that runs its
+ * authorization check late can hand this function a `NOT_MOUNTABLE` or
+ * `BLUEPRINT_UNRESOLVABLE` for a locator the caller was never entitled
+ * to read, and the resulting `-32006` reveals that the locator exists —
+ * the same oracle, reached by a different route, with a mapper behaving
+ * perfectly.
+ *
+ * So the ordering is normative, scoped to the branches that can leak:
+ * a server using this projection MUST route a refusal through its
+ * TERMINAL failure — the single answer it gives for every locator it
+ * will not resolve — and MUST NOT run a branch whose outcome VARIES
+ * WITH THE LOCATOR before the access check. Reaching one of those is
+ * itself the disclosure. Resolution work is exactly such a branch, so
+ * it happens only after the check has passed.
+ *
+ * Naming the TERMINAL rather than a specific code is deliberate. Which
+ * code the terminal carries is a property of the deployment: a server
+ * keeping durable records answers `NOT_FOUND`, one keeping none answers
+ * `NOT_SUPPORTED`, and each answers it for a refused locator and a
+ * missing one alike. Pinning this rule to `NOT_FOUND` would declare the
+ * second server non-conformant for behaving correctly. What the rule
+ * protects is that refusal and absence are the SAME answer — never
+ * which answer it is.
+ *
+ * A deployment-global answer is not a locator-varying branch.
+ * `NOT_SUPPORTED` describes the server and is identical for every
+ * locator on a server that emits it, so answering it before any
+ * per-locator work — the access check included — reveals nothing and is
+ * permitted.
+ */
+import { MCP_ERROR_CODES, } from '../types/mcp.js';
+/**
+ * The single message every `NOT_FOUND` read returns, whatever the
+ * underlying reason. Names no session, app, or caller.
+ */
+export const RESOURCE_NOT_FOUND_MESSAGE = 'Resource not found.';
+/**
+ * Switch rather than an `if` with a fallthrough on purpose: every member
+ * of the enum is named, so adding a fifth code fails to compile here
+ * until someone decides which number it carries. A default branch would
+ * have swallowed it into `MOUNT_UNAVAILABLE` silently.
+ */
+export function resourceReadErrorToJsonRpc(err) {
+    switch (err.code) {
+        case 'NOT_FOUND':
+            // Constant body — see "Why NOT_FOUND loses its message" above.
+            return {
+                code: MCP_ERROR_CODES.SESSION_NOT_FOUND,
+                message: RESOURCE_NOT_FOUND_MESSAGE,
+                data: { code: 'NOT_FOUND' },
+            };
+        case 'BLUEPRINT_UNRESOLVABLE':
+        case 'NOT_SUPPORTED':
+        case 'NOT_MOUNTABLE':
+            return {
+                code: MCP_ERROR_CODES.MOUNT_UNAVAILABLE,
+                message: err.message,
+                data: err.detail === undefined
+                    ? { code: err.code }
+                    : { code: err.code, detail: err.detail },
+            };
+    }
+}

package/dist/gadgets/resolve-app-gadgets.d.ts

@@ -1,10 +1,16 @@
 import type { GadgetDescriptor } from '../types/data-contract';
 /**
- * Resolve an app's effective gadget set: the first-party stdlib package is the
- * structural FLOOR, and `declared` (app-declared extensions) layers on top.
- * Replaces the legacy fallback-when-absent resolution that dropped the stdlib
- * package the moment an app declared any extension. `declared` wins on a
- * `package` collision; absent/empty ⇒ exactly the stdlib set; idempotent.
+ * Resolve an app's effective gadget set from its three sources, in
+ * ascending precedence: the first-party stdlib package is the
+ * structural FLOOR, `installed` (rows added through the host's install
+ * surface) layers on top of it, and `declared` (app-declared extensions
+ * from the app's own config) wins over both. Later wins on a `package`
+ * collision — declared beats installed beats floor, because the app's
+ * own config is the operator's explicit source of truth and must not be
+ * silently shadowed by an install performed elsewhere.
+ *
+ * Absent/empty sources ⇒ exactly the stdlib set; idempotent over
+ * already-resolved input.
  */
-export declare function resolveAppGadgets(declared?: readonly GadgetDescriptor[] | null): readonly GadgetDescriptor[];
+export declare function resolveAppGadgets(declared?: readonly GadgetDescriptor[] | null, installed?: readonly GadgetDescriptor[] | null): readonly GadgetDescriptor[];
 //# sourceMappingURL=resolve-app-gadgets.d.ts.map

package/dist/gadgets/resolve-app-gadgets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-app-gadgets.d.ts","sourceRoot":"","sources":["../../src/gadgets/resolve-app-gadgets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAO/D;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,CAAC,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,GAC5C,SAAS,gBAAgB,EAAE,CAG7B"}
+{"version":3,"file":"resolve-app-gadgets.d.ts","sourceRoot":"","sources":["../../src/gadgets/resolve-app-gadgets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAO/D;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,CAAC,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,EAC7C,SAAS,CAAC,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,GAC7C,SAAS,gBAAgB,EAAE,CAS7B"}

package/dist/gadgets/resolve-app-gadgets.js

@@ -6,14 +6,25 @@ function dedupeByPackage(list) {
     return [...m.values()];
 }
 /**
- * Resolve an app's effective gadget set: the first-party stdlib package is the
- * structural FLOOR, and `declared` (app-declared extensions) layers on top.
- * Replaces the legacy fallback-when-absent resolution that dropped the stdlib
- * package the moment an app declared any extension. `declared` wins on a
- * `package` collision; absent/empty ⇒ exactly the stdlib set; idempotent.
+ * Resolve an app's effective gadget set from its three sources, in
+ * ascending precedence: the first-party stdlib package is the
+ * structural FLOOR, `installed` (rows added through the host's install
+ * surface) layers on top of it, and `declared` (app-declared extensions
+ * from the app's own config) wins over both. Later wins on a `package`
+ * collision — declared beats installed beats floor, because the app's
+ * own config is the operator's explicit source of truth and must not be
+ * silently shadowed by an install performed elsewhere.
+ *
+ * Absent/empty sources ⇒ exactly the stdlib set; idempotent over
+ * already-resolved input.
  */
-export function resolveAppGadgets(declared) {
-    if (!declared || declared.length === 0)
+export function resolveAppGadgets(declared, installed) {
+    if ((!declared || declared.length === 0) && (!installed || installed.length === 0)) {
         return STDLIB_GADGETS;
-    return dedupeByPackage([...STDLIB_GADGETS, ...declared]);
+    }
+    return dedupeByPackage([
+        ...STDLIB_GADGETS,
+        ...(installed ?? []),
+        ...(declared ?? []),
+    ]);
 }

package/dist/gadgets/stdlib-gadgets.d.ts

@@ -12,7 +12,7 @@ export declare const STDLIB_GADGETS_PACKAGE = "@ggui-ai/gadgets";
  * in `@ggui-ai/gadgets` asserts the two stay in sync, so a release-time
  * bump to the runtime package without updating this constant fails CI.
  */
-export declare const STDLIB_GADGETS_VERSION = "0.6.2";
+export declare const STDLIB_GADGETS_VERSION = "0.7.0";
 /**
  * v1 catalog of stdlib gadget descriptors. Every entry's
  * `package` defaults to {@link STDLIB_GADGETS_PACKAGE}; the

package/dist/gadgets/stdlib-gadgets.js

@@ -39,7 +39,7 @@ export const STDLIB_GADGETS_PACKAGE = '@ggui-ai/gadgets';
  * in `@ggui-ai/gadgets` asserts the two stay in sync, so a release-time
  * bump to the runtime package without updating this constant fails CI.
  */
-export const STDLIB_GADGETS_VERSION = '0.6.2';
+export const STDLIB_GADGETS_VERSION = '0.7.0';
 /**
  * v1 catalog of stdlib gadget descriptors. Every entry's
  * `package` defaults to {@link STDLIB_GADGETS_PACKAGE}; the

package/dist/index.d.ts

@@ -36,6 +36,7 @@ export * from "./envelope-adapters";
 export * from "./envelopes/builders";
 export * from "./errors/version-mismatch";
 export * from "./errors/unknown-permission-name";
+export * from "./errors/resource-read";
 export * from "./validation/contract-validator";
 export * from "./validation/cross-references";
 export * from "./validation/is-record";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gBAAgB,CAAC;AAI/B,cAAc,sBAAsB,CAAC;AAOrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AAIxC,cAAc,qBAAqB,CAAC;AAIpC,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAK5F,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAMlE,YAAY,EAEV,SAAS,EACT,YAAY,EACZ,eAAe,EACf,YAAY,EAEZ,WAAW,EACX,eAAe,EAEf,UAAU,GACX,MAAM,gBAAgB,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAI/C,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AAKnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mCAAmC,CAAC;AAClD,cAAc,2BAA2B,CAAC;AAC1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EACL,2BAA2B,EAC3B,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,oCAAoC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gBAAgB,CAAC;AAI/B,cAAc,sBAAsB,CAAC;AAOrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AAIxC,cAAc,qBAAqB,CAAC;AAIpC,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAK5F,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAMlE,YAAY,EAEV,SAAS,EACT,YAAY,EACZ,eAAe,EACf,YAAY,EAEZ,WAAW,EACX,eAAe,EAEf,UAAU,GACX,MAAM,gBAAgB,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAI/C,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AAKnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kCAAkC,CAAC;AAGjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mCAAmC,CAAC;AAClD,cAAc,2BAA2B,CAAC;AAC1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EACL,2BAA2B,EAC3B,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,oCAAoC,CAAC"}

package/dist/index.js

@@ -61,6 +61,9 @@ export * from "./envelope-adapters.js";
 export * from "./envelopes/builders.js";
 export * from "./errors/version-mismatch.js";
 export * from "./errors/unknown-permission-name.js";
+// Typed `resources/read` failures → JSON-RPC. The single exit for every
+// non-mount outcome of a render-locator read.
+export * from "./errors/resource-read.js";
 export * from "./validation/contract-validator.js";
 export * from "./validation/cross-references.js";
 export * from "./validation/is-record.js";

package/dist/schemas/data-contract.d.ts

@@ -492,7 +492,7 @@ export declare const gadgetDescriptorSchema: z.ZodObject<{
  * Used by:
  *   - `createGguiGadget` SDK factory (validates wrapper specs).
  *   - `App.gadgets` registration handlers (ggui.json seed,
- *     ops_register_gadget, etc.).
+ *     `ggui gadget install`, config push).
  *
  * Same TS interface as the wire schema — the strictness lives in zod
  * refinements, not the type system.
@@ -559,27 +559,33 @@ export declare const strictGadgetDescriptorSchema: z.ZodObject<{
     typesSri: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /**
- * Registration-ready descriptor validator.
- * {@link strictGadgetDescriptorSchema} plus the refinement that
- * every non-stdlib package MUST carry a `typesUrl`.
- *
- * Two boundaries, two schemas:
- *
- *   - `strictGadgetDescriptorSchema` — **author time**. The
- *     `createGguiGadget` SDK factory validates a wrapper spec at
- *     module load, BEFORE the build emits a `.d.ts` — `typesUrl`
- *     doesn't exist yet, so it can't be required here.
- *   - `registeredGadgetDescriptorSchema` — **registration time**.
- *     The build helper (`writeDescriptorJson`) and the `App.gadgets`
- *     registration handlers validate here, AFTER the build has
- *     emitted the `.d.ts`, computed its SRI, and stamped
- *     `typesUrl` + `typesSri` on the descriptor.
- *
- * The code-gen sandbox loads the `.d.ts` the URL points at to
+ * Types-pipeline descriptor validator — PARKED (2026-08-09 gadget
+ * catalog foundations): no catalog-serving boundary consumes it.
+ * {@link strictGadgetDescriptorSchema} plus the refinement that every
+ * non-stdlib package MUST carry a `typesUrl`.
+ *
+ * Every live catalog boundary — descriptor writes, catalog reads, and
+ * the generation-time catalog adapter — validates with
+ * `strictGadgetDescriptorSchema`, where `typesUrl` is optional:
+ * nothing in the publish→install chain stamps `typesUrl` yet, and the
+ * types fetcher already skips descriptors without one, so generation
+ * degrades gracefully to no-types codegen.
+ *
+ * The one surviving consumer is the wrapper-author build helper
+ * (`writeDescriptorJson` in `@ggui-ai/gadgets/codegen`) — the
+ * authoring-side front half of the types pipeline, where the wrapper
+ * build HAS just emitted a `.d.ts` and stamped `typesUrl` +
+ * `typesSri`, so requiring them is coherent there.
+ *
+ * The export stays because it is the already-written contract for the
+ * types-pipeline follow-up: publish stamps `typesUrl` + `typesSri` on
+ * the descriptor after the build emits the `.d.ts`, descriptor
+ * projections carry both fields through, and the generation-time
+ * catalog adapter adopts this schema as its posture again — the
+ * code-gen sandbox then loads the `.d.ts` the URL points at to
  * typecheck generated component code against the package's real
  * export signatures. Stdlib (`@ggui-ai/gadgets`) is exempt — the
- * sandbox loads its types directly. No permissive fallback:
- * pre-launch posture forces strict typing across the board.
+ * sandbox loads its types directly.
  */
 export declare const registeredGadgetDescriptorSchema: z.ZodObject<{
     exports: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{

package/dist/schemas/data-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-contract.d.ts","sourceRoot":"","sources":["../../src/schemas/data-contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"data-contract.d.ts","sourceRoot":"","sources":["../../src/schemas/data-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,UAAU,EACX,MAAM,wBAAwB,CAAC;AAEhC;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAYhD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CA2BlD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;;;;;kBASjB,CAAC;AAEZ,sFAAsF;AACtF,eAAO,MAAM,eAAe;;;;;;;;;;kBAKjB,CAAC;AAEZ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;kBAUnB,CAAC;AAEZ,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB;;;;;;;;mBAA0C,CAAC;AAExE,iFAAiF;AACjF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;kBAgB1B,CAAC;AAEZ,uEAAuE;AACvE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;mBAAiD,CAAC;AAE/E,yEAAyE;AACzE,eAAO,MAAM,kBAAkB;;;;;;kBAQpB,CAAC;AAEZ,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB;;;;;;mBAA2C,CAAC;AAE1E,sFAAsF;AACtF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;kBAiBtB,CAAC;AAEZ,qEAAqE;AACrE,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;iBAIxB,CAAC;AAEjB;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,qBAAqB,QAAiC,CAAC;AAEpE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,wCAEpB,CAAC;AAEd;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,QAA8B,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,mBAAmB,QACsB,CAAC;AAEvD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,QAAyC,CAAC;AAEpE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,cAAc,QAAyB,CAAC;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,qBAAqB,CAAC;AAEtD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,QAAiD,CAAC;AAE/E;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;;;;GAQG;AACH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAwExE;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;oBAa7B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAanC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;kBAKxB,CAAC;AAEZ;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAK9B,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAU1C,CAAC;AAQJ;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB;;;kBAKvB,CAAC;AAEZ;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB;;;mBAa/B,CAAC;AAEL;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B;;;;;kBAO9B,CAAC;AAEZ;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,sDAElB,CAAC;AAEd;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,kBAAkB,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CASZ,CAAC"}

package/dist/schemas/data-contract.js

@@ -498,7 +498,7 @@ export const gadgetDescriptorSchema = z
  * Used by:
  *   - `createGguiGadget` SDK factory (validates wrapper specs).
  *   - `App.gadgets` registration handlers (ggui.json seed,
- *     ops_register_gadget, etc.).
+ *     `ggui gadget install`, config push).
  *
  * Same TS interface as the wire schema — the strictness lives in zod
  * refinements, not the type system.
@@ -510,37 +510,44 @@ export const strictGadgetDescriptorSchema = z
 })
     .strict();
 /**
- * Registration-ready descriptor validator.
- * {@link strictGadgetDescriptorSchema} plus the refinement that
- * every non-stdlib package MUST carry a `typesUrl`.
- *
- * Two boundaries, two schemas:
- *
- *   - `strictGadgetDescriptorSchema` — **author time**. The
- *     `createGguiGadget` SDK factory validates a wrapper spec at
- *     module load, BEFORE the build emits a `.d.ts` — `typesUrl`
- *     doesn't exist yet, so it can't be required here.
- *   - `registeredGadgetDescriptorSchema` — **registration time**.
- *     The build helper (`writeDescriptorJson`) and the `App.gadgets`
- *     registration handlers validate here, AFTER the build has
- *     emitted the `.d.ts`, computed its SRI, and stamped
- *     `typesUrl` + `typesSri` on the descriptor.
- *
- * The code-gen sandbox loads the `.d.ts` the URL points at to
+ * Types-pipeline descriptor validator — PARKED (2026-08-09 gadget
+ * catalog foundations): no catalog-serving boundary consumes it.
+ * {@link strictGadgetDescriptorSchema} plus the refinement that every
+ * non-stdlib package MUST carry a `typesUrl`.
+ *
+ * Every live catalog boundary — descriptor writes, catalog reads, and
+ * the generation-time catalog adapter — validates with
+ * `strictGadgetDescriptorSchema`, where `typesUrl` is optional:
+ * nothing in the publish→install chain stamps `typesUrl` yet, and the
+ * types fetcher already skips descriptors without one, so generation
+ * degrades gracefully to no-types codegen.
+ *
+ * The one surviving consumer is the wrapper-author build helper
+ * (`writeDescriptorJson` in `@ggui-ai/gadgets/codegen`) — the
+ * authoring-side front half of the types pipeline, where the wrapper
+ * build HAS just emitted a `.d.ts` and stamped `typesUrl` +
+ * `typesSri`, so requiring them is coherent there.
+ *
+ * The export stays because it is the already-written contract for the
+ * types-pipeline follow-up: publish stamps `typesUrl` + `typesSri` on
+ * the descriptor after the build emits the `.d.ts`, descriptor
+ * projections carry both fields through, and the generation-time
+ * catalog adapter adopts this schema as its posture again — the
+ * code-gen sandbox then loads the `.d.ts` the URL points at to
  * typecheck generated component code against the package's real
  * export signatures. Stdlib (`@ggui-ai/gadgets`) is exempt — the
- * sandbox loads its types directly. No permissive fallback:
- * pre-launch posture forces strict typing across the board.
+ * sandbox loads its types directly.
  */
 export const registeredGadgetDescriptorSchema = strictGadgetDescriptorSchema.refine((entry) => entry.package === STDLIB_GADGETS_PACKAGE ||
     typeof entry.typesUrl === 'string', {
     message: 'registered GadgetDescriptor MUST declare a `typesUrl` (HTTPS URL to the package\'s .d.ts) — the code-gen sandbox loads it to typecheck generated component code against the export signatures. Run `tsup --dts` (or `tsc --declaration`) in the wrapper build and publish the emitted .d.ts. Only the first-party `@ggui-ai/gadgets` stdlib is exempt.',
     path: ['typesUrl'],
 });
-// `package` + `version` are required on every descriptor (mirroring
-// the wire's `(hook, package, version)` identity tuple), so there is
-// no "at least one of package / bundleUrl / bundleHost" refinement
-// and no "bundleHost requires package + version" refinement.
+// `package` + `version` are required on every descriptor —
+// `(package, version)` is the registry's frozen identity tuple; the
+// wire references packages by name only — so there is no "at least
+// one of package / bundleUrl / bundleHost" refinement and no
+// "bundleHost requires package + version" refinement.
 /**
  * Wire-side per-export USE entry on `clientCapabilities.gadgets`.
  *

package/dist/schemas/mcp.d.ts

@@ -7,12 +7,12 @@
  * Two consumption patterns, both anchored here:
  *
  *   - **Wired raw shapes** (`*InputShape`): handlers in
- *     `@ggui-ai/mcp-server-handlers` (and the hosted pod's
- *     discover / request-credential tools) import the SHAPE directly as
- *     their `inputSchema` and validate with `z.object(shape)` — unknown
- *     keys are STRIPPED. The shape is the one authored copy of the
- *     validation rules AND the agent-facing `.describe()` strings that
- *     ship via `tools/list`.
+ *     `@ggui-ai/mcp-server-handlers` (and the hosted pod's discover
+ *     tool) import the SHAPE directly as their `inputSchema` and
+ *     validate with `z.object(shape)` — unknown keys are STRIPPED.
+ *     The shape is the one authored copy of the validation rules AND
+ *     the agent-facing `.describe()` strings that ship via
+ *     `tools/list`.
  *
  *   - **Lifecycle triad** (`ggui_handshake` / `ggui_update`): the
  *     handlers carry deliberate input divergences (handshake's
@@ -120,16 +120,6 @@ export declare const renderBlueprintInputSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const discoverInputShape: {};
 export declare const discoverInputSchema: z.ZodObject<{}, z.core.$strip>;
-export declare const requestCredentialInputShape: {
-    readonly serviceId: z.ZodString;
-    readonly reason: z.ZodOptional<z.ZodString>;
-    readonly sessionId: z.ZodOptional<z.ZodString>;
-};
-export declare const requestCredentialInputSchema: z.ZodObject<{
-    serviceId: z.ZodString;
-    reason: z.ZodOptional<z.ZodString>;
-    sessionId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
 /**
  * `ggui_handshake` — three-step suggestion protocol.
  *
@@ -356,6 +346,58 @@ export declare const renderErrorSchema: z.ZodObject<{
     }>;
     message: z.ZodString;
 }, z.core.$strip>;
+/**
+ * Canonical failure codes for a `resources/read` on a render locator
+ * (`ui://ggui/render/{sessionId}/{blueprintKey}`). Closed enum.
+ *
+ * This is a DIFFERENT surface from {@link renderErrorCodeSchema}: that
+ * one classifies a `ggui_render` tool call that ran and failed, and
+ * rides in the tool result. This one classifies a resource read that
+ * cannot return a mount, and rides on a JSON-RPC error — a read either
+ * yields a live mount or fails, never a successful result wrapping a
+ * dead shell. That is what makes the contract host-checkable.
+ *
+ *   - `NOT_FOUND` — no live render and no restorable record. The
+ *     locator never existed, aged out, was erased, or the caller may
+ *     not read it. Denial is deliberately reported as absence: a
+ *     distinguishable "denied" would turn the read into an oracle for
+ *     the existence of other callers' renders.
+ *   - `BLUEPRINT_UNRESOLVABLE` — a record exists, but the component
+ *     behind it cannot be resolved: removed, taken down, or the record
+ *     carries no component reference at all.
+ *   - `NOT_SUPPORTED` — this deployment keeps no durable record, so an
+ *     evicted locator can never be restored. A property of the server,
+ *     identical for every caller and every locator.
+ *   - `NOT_MOUNTABLE` — the render resolved, but no delivery channel is
+ *     available to mount it.
+ */
+export declare const resourceReadErrorCodeSchema: z.ZodEnum<{
+    NOT_FOUND: "NOT_FOUND";
+    BLUEPRINT_UNRESOLVABLE: "BLUEPRINT_UNRESOLVABLE";
+    NOT_SUPPORTED: "NOT_SUPPORTED";
+    NOT_MOUNTABLE: "NOT_MOUNTABLE";
+}>;
+/**
+ * Failure shape for a `resources/read` that cannot return a mount.
+ * Projected onto a JSON-RPC error by `resourceReadErrorToJsonRpc` —
+ * `code` lands on `error.data.code`, so hosts can branch on the
+ * classification without parsing prose.
+ *
+ * `message` is caller-facing and `detail` is operator-facing. NEITHER
+ * is preserved on `NOT_FOUND`: the mapper substitutes a constant there
+ * so a denied read and a genuine miss are byte-identical on the wire.
+ * Put diagnostics for that case in the server's own logs.
+ */
+export declare const resourceReadErrorSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        NOT_FOUND: "NOT_FOUND";
+        BLUEPRINT_UNRESOLVABLE: "BLUEPRINT_UNRESOLVABLE";
+        NOT_SUPPORTED: "NOT_SUPPORTED";
+        NOT_MOUNTABLE: "NOT_MOUNTABLE";
+    }>;
+    message: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 /**
  * Wire-output shape — `{sessionId, resourceUri?, action, contractHash,
  * cache, error?, nextStep?}`. `contractHash` (data-contract identity)

package/dist/schemas/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/schemas/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,eAAO,MAAM,cAAc;;;iBAGzB,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAUnB,CAAC;AAYjB;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;CAgBpB,CAAC;AAEX,eAAO,MAAM,kBAAkB;;;iBAA8B,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC;AAEX,eAAO,MAAM,eAAe;;;;;iBAA2B,CAAC;AAExD,eAAO,MAAM,oBAAoB;;CAKvB,CAAC;AAEX,eAAO,MAAM,qBAAqB;;iBAAiC,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,IAAc,CAAC;AAE5D,eAAO,MAAM,iCAAiC,gCAE7C,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;CAM7B,CAAC;AAEX,eAAO,MAAM,2BAA2B;;;iBAAuC,CAAC;AAEhF,eAAO,MAAM,yBAAyB;;CAO5B,CAAC;AAEX,eAAO,MAAM,0BAA0B;;iBAAsC,CAAC;AAE9E,eAAO,MAAM,kBAAkB,IAAc,CAAC;AAE9C,eAAO,MAAM,mBAAmB,gCAA+B,CAAC;AAEhE,eAAO,MAAM,2BAA2B;;;;CAI9B,CAAC;AAEX,eAAO,MAAM,4BAA4B;;;;iBAAwC,CAAC;AAalF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,oBAAoB;;;;kBA0BtB,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;iBAgChC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,gBAAgB;;IAO3B;;;;;;;;OAQG;;IAEH;;;;;OAKG;;IAQH;;;;;;;;;;OAUG;;;;IAaH;;;;;;;;;;;OAWG;;;;;CAuBK,CAAC;AAEX,eAAO,MAAM,iBAAiB;;;;;;;;;;;iBAA6B,CAAC;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;iBAyBlC,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,qBAAqB;;;;;EAKhC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;iBAS5B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwE7B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;4BAa5B,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB;;;;iBAW7B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,6BAA6B;;;;;kBAW/B,CAAC;AAEZ,eAAO,MAAM,8BAA8B;;;kBAKhC,CAAC"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/schemas/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,eAAO,MAAM,cAAc;;;iBAGzB,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAUnB,CAAC;AAYjB;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;CAgBpB,CAAC;AAEX,eAAO,MAAM,kBAAkB;;;iBAA8B,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC;AAEX,eAAO,MAAM,eAAe;;;;;iBAA2B,CAAC;AAExD,eAAO,MAAM,oBAAoB;;CAKvB,CAAC;AAEX,eAAO,MAAM,qBAAqB;;iBAAiC,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,IAAc,CAAC;AAE5D,eAAO,MAAM,iCAAiC,gCAE7C,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;CAM7B,CAAC;AAEX,eAAO,MAAM,2BAA2B;;;iBAAuC,CAAC;AAEhF,eAAO,MAAM,yBAAyB;;CAO5B,CAAC;AAEX,eAAO,MAAM,0BAA0B;;iBAAsC,CAAC;AAE9E,eAAO,MAAM,kBAAkB,IAAc,CAAC;AAE9C,eAAO,MAAM,mBAAmB,gCAA+B,CAAC;AAahE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,oBAAoB;;;;kBA0BtB,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;iBAgChC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,gBAAgB;;IAO3B;;;;;;;;OAQG;;IAEH;;;;;OAKG;;IAQH;;;;;;;;;;OAUG;;;;IAaH;;;;;;;;;;;OAWG;;;;;CAuBK,CAAC;AAEX,eAAO,MAAM,iBAAiB;;;;;;;;;;;iBAA6B,CAAC;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;iBAyBlC,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,qBAAqB;;;;;EAKhC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;iBAS5B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,2BAA2B;;;;;EAKtC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;iBAalC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwE7B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;4BAa5B,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB;;;;iBAW7B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,6BAA6B;;;;;kBAW/B,CAAC;AAEZ,eAAO,MAAM,8BAA8B;;;kBAKhC,CAAC"}