@ggui-ai/mcp-server 0.3.0-rc.0 → 0.5.0-rc.0

package/dist/build-mcp.d.ts

@@ -10,7 +10,7 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type ZodRawShape } from 'zod';
-import type { HandlerContext, SharedHandler } from '@ggui-ai/mcp-server-handlers';
+import { type HandlerContext, type SharedHandler } from '@ggui-ai/mcp-server-handlers';
 import type { Logger } from './logger.js';
 import { type GguiRenderResourceTemplateOptions } from './mcp-apps-outbound.js';
 export interface ServerInfo {

package/dist/build-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-mcp.d.ts","sourceRoot":"","sources":["../src/build-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAK,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAC1C,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACd,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAEL,KAAK,iCAAiC,EACvC,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,iCAAiC,CAAC;IAC3D;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IAElE;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC,CAAC;CACtE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,EAChE,UAAU,EAAE,MAAM,cAAc,EAChC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,qBAA0B,GAC/B,SAAS,CAyJX"}
+{"version":3,"file":"build-mcp.d.ts","sourceRoot":"","sources":["../src/build-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAK,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAC1C,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAEL,KAAK,iCAAiC,EACvC,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,iCAAiC,CAAC;IAC3D;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IAElE;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC,CAAC;CACtE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,EAChE,UAAU,EAAE,MAAM,cAAc,EAChC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,qBAA0B,GAC/B,SAAS,CAiLX"}

package/dist/build-mcp.js

@@ -12,6 +12,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
 import { isRecord } from '@ggui-ai/protocol';
 import { z } from 'zod';
+import { isHandlerFailure, } from '@ggui-ai/mcp-server-handlers';
 import { installMcpAppsOutbound, } from './mcp-apps-outbound.js';
 /**
  * Build a fresh MCP server with every handler registered.
@@ -87,6 +88,30 @@ export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
             const start = Date.now();
             try {
                 const data = await handler.handler(input, ctx);
+                // First-class in-result failure channel. A handler that
+                // returns the `HandlerFailure` marker gets an `isError: true`
+                // TOOL RESULT (never a thrown/JSON-RPC error): the marker's
+                // `errorText` is the model-visible content, and its `data` is
+                // validated against the SAME outputSchema as a success — MCP
+                // SDK clients validate structuredContent against outputSchema
+                // even when isError is set, so the envelope stays
+                // schema-conformant. NO `_meta` on failures: `resultMeta` is
+                // not invoked, so no mount affordance / bootstrap slice is
+                // emitted for a failed call.
+                if (isHandlerFailure(data)) {
+                    const validated = z.object(handler.outputSchema).parse(data.data);
+                    logger.warn('tool_invoked', {
+                        tool: handler.name,
+                        appId: ctx.appId,
+                        outcome: 'tool_error',
+                        elapsedMs: Date.now() - start,
+                    });
+                    return {
+                        isError: true,
+                        structuredContent: validated,
+                        content: [{ type: 'text', text: data.errorText }],
+                    };
+                }
                 const validated = z.object(handler.outputSchema).parse(data);
                 // Per-result `_meta` — NOT merged into structuredContent, so
                 // agents that typecheck against the tool signature never see

package/dist/console-chat-routes.d.ts

@@ -43,7 +43,7 @@
  * the exact Lane-1 chat-page spec assertion (`/OSS agent
  * generation/`) without a copy change.
  */
-import type { SharedHandler } from "@ggui-ai/mcp-server-handlers";
+import { type SharedHandler } from "@ggui-ai/mcp-server-handlers";
 import type { Express } from "express";
 import type { ZodRawShape } from "zod";
 import type { Logger } from "./logger.js";

package/dist/console-chat-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"console-chat-routes.d.ts","sourceRoot":"","sources":["../src/console-chat-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAIvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACjE,+DAA+D;IAC/D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACpE;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE;QACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;KAC1B,CAAC;IACF,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAsJ/D"}
+{"version":3,"file":"console-chat-routes.d.ts","sourceRoot":"","sources":["../src/console-chat-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAIvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACjE,+DAA+D;IAC/D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACpE;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE;QACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;KAC1B,CAAC;IACF,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA2K/D"}

package/dist/console-chat-routes.js

@@ -43,6 +43,7 @@
  * the exact Lane-1 chat-page spec assertion (`/OSS agent
  * generation/`) without a copy change.
  */
+import { isHandlerFailure, } from "@ggui-ai/mcp-server-handlers";
 import { randomUUID } from "node:crypto";
 import { DEFAULT_BUILDER_APP_ID } from "./auth.js";
 import { mintDevtoolCookie } from "./console-auth.js";
@@ -101,6 +102,27 @@ export function mountConsoleChatRoutes(opts) {
                 });
                 const handshakeId = hsRaw.handshakeId;
                 const raw = await renderHandler.handler({ handshakeId, contract: {} }, { appId: DEFAULT_BUILDER_APP_ID, requestId });
+                if (isHandlerFailure(raw)) {
+                    // In-result failure envelope (generation failed / rejected).
+                    // The marker's errorText is the honest self-correction
+                    // surface — reuse it verbatim; no ui payload (nothing
+                    // mountable landed for this turn).
+                    logger.warn?.("console_chat_render_failed", {
+                        threadId,
+                        error: raw.errorText,
+                    });
+                    res.status(200).json({
+                        threadId,
+                        userMessage,
+                        agentMessage: {
+                            id: `msg-${randomUUID()}`,
+                            role: "agent",
+                            text: raw.errorText,
+                            createdAt: now + 1,
+                        },
+                    });
+                    return;
+                }
                 const result = raw;
                 ui = {
                     sessionId: result.sessionId,

package/dist/control-service.d.ts

@@ -0,0 +1,160 @@
+/**
+ * `/control` — the control plane.
+ *
+ * ggui serves exactly TWO MCP surfaces:
+ *
+ *   - **Data plane** — the agent routes (`universalMcpPath`, plus the
+ *     per-tenant `${pathPrefix}/:appId` variant when configured). Carries
+ *     the `agent` + `runtime` audiences: the tools an agent calls while a
+ *     session is running.
+ *   - **Control plane** — this service. Carries the `protocol` + `ops`
+ *     audiences: design-time spec/discovery (anonymous) and operator-class
+ *     account management (authenticated, state-changing calls
+ *     confirm-gated).
+ *
+ * Audience TAGS stay normative — `audience` on a handler still declares
+ * its caller class, and the `ggui_protocol_*` / `ggui_ops_*` wire-name
+ * prefixes still encode it. What this module retires is one-HTTP-route-
+ * per-audience MOUNTING: `protocol` and `ops` land on the same path.
+ *
+ * WHY one route for two audiences: an HTTP route carries ONE auth
+ * posture. Design-time spec tools must answer bearer-less (an agent
+ * authoring a blueprint has no account yet); operator tools must not.
+ * Two routes forced a deployment to choose per route, which is why the
+ * two surfaces could never be pointed at by a single client config. A
+ * service mount is the seam that mixes both: the route is anonymous-
+ * capable, and each ops handler re-imposes auth for itself.
+ *
+ * The per-tool wrappers, in application order (innermost first):
+ *
+ *   1. {@link withConfirmGate} — state-changing ops only. Turns one
+ *      call into a deliberate two-call sequence so an agent cannot
+ *      silently mint credentials, spend credits, or delete resources.
+ *   2. {@link withAuthGate} — every ops tool. Rejects callers the auth
+ *      adapter never authenticated (the anonymous synthetic), so an ops
+ *      handler never runs against a phantom identity.
+ *   3. {@link stripAudience} — every tool. Service handlers MUST NOT
+ *      carry an `audience` tag (the mount path IS the audience); the tag
+ *      is consumed by the data-plane route filter and is meaningless
+ *      inside a service, so dropping it is lossless.
+ *
+ * Ordering matters: the auth gate sits OUTSIDE the confirm gate, so an
+ * unauthenticated caller gets an auth error rather than a confirmation
+ * preview that leaks which operations exist against which account.
+ */
+import { type SharedHandler } from "@ggui-ai/mcp-server-handlers";
+import { type ZodRawShape } from "zod";
+import type { McpService } from "./mcp-mounts.js";
+type AnyHandler = SharedHandler<ZodRawShape, ZodRawShape>;
+/** Every audience tag a handler may declare. */
+export type AudienceTag = "agent" | "runtime" | "protocol" | "ops";
+/** HTTP path the control plane mounts at. */
+export declare const CONTROL_PATH = "/control";
+/** Service name the control plane reports in validation errors + telemetry. */
+export declare const CONTROL_SERVICE_NAME = "control";
+/** Audiences the data plane (agent routes) serves. */
+export declare const DATA_PLANE_AUDIENCES: ReadonlyArray<AudienceTag>;
+/** Audiences the control plane serves. */
+export declare const CONTROL_PLANE_AUDIENCES: ReadonlyArray<AudienceTag>;
+/**
+ * Return the subset of `set` whose `audience` tag intersects `allowed`.
+ * The single projection from audience tags to mount surfaces — both
+ * planes read it, so a handler can never land on both or on neither.
+ *
+ * Handlers with `audience: undefined` default to `['agent']`: an
+ * untagged handler is agent-callable, which keeps zero-config OSS
+ * deployments (whose handlers rarely tag anything) on the data plane.
+ */
+export declare function filterHandlersByAudience(set: ReadonlyArray<AnyHandler>, allowed: ReadonlyArray<AudienceTag>): ReadonlyArray<AnyHandler>;
+/**
+ * Ops tools that answer in ONE call — reads, lists, and card-openers
+ * that change no state. Every other `ops`-tagged tool is treated as
+ * state-changing and confirm-gated.
+ *
+ * The classification is default-DENY on purpose. A curated
+ * "these ones are mutating" list has a silent failure mode: land a new
+ * state-changing ops tool, forget the list, and it ships un-gated with
+ * nothing to notice. Inverting it makes the forgotten case a visible
+ * annoyance (an extra confirmation round-trip on a read) instead of an
+ * invisible hole, which is the trade the Protocol and Contract Bar asks
+ * for — an unflagged gap is a failure in disguise.
+ *
+ * Deployments that register their own read-only ops tools extend this
+ * via `CreateGguiServerOptions.control.singleCallOps` rather than
+ * patching this set.
+ *
+ * `ggui_ops_setup_byok` is a deliberate entry: it LISTS provider-key
+ * status and returns the BYOK card — the set/remove tools are the real
+ * mutations. Confirm-gating it would break the card's inline render on
+ * the first call, because the confirmation preview does not carry the
+ * card's discriminant.
+ */
+export declare const SINGLE_CALL_OPS: ReadonlySet<string>;
+/**
+ * Return a copy of the handler with the `audience` tag removed.
+ * `validateMcpServices` rejects service handlers that carry one.
+ */
+export declare function stripAudience<I extends ZodRawShape, O extends ZodRawShape, D>(h: SharedHandler<I, O, D>): SharedHandler<I, O, D>;
+/**
+ * Require an authenticated caller.
+ *
+ * The control plane is anonymous-CAPABLE so design-time spec tools
+ * answer bearer-less. In that mode the transport synthesizes a builder
+ * identity (`authSource: 'anonymous'`) for requests that presented no
+ * credential — or presented one the adapter rejected. An un-gated ops
+ * handler would then run against that synthetic rather than refusing,
+ * which is how a caller with no account would read and write a phantom
+ * shared tenant.
+ *
+ * The gate is on `ctx.authSource`, not on which identity FIELDS are
+ * populated: every deployment tier proves identity differently
+ * (single-user builder, per-app key, per-user key, OIDC), and only the
+ * source distinguishes "the adapter authenticated this request" from
+ * "the transport let it through". Transports map
+ * {@link AuthRequiredError} to 401 so clients can prompt for sign-in.
+ */
+export declare function withAuthGate<I extends ZodRawShape, O extends ZodRawShape, D>(h: SharedHandler<I, O, D>): SharedHandler<I, O, D>;
+/**
+ * Wrap a state-changing handler in a stateless two-call confirmation
+ * gate. The first call (no `confirm: true`) returns a preview and runs
+ * nothing; a second call carrying `confirm: true` delegates to the
+ * inner handler.
+ *
+ * The `confirm` input field and the confirmation output fields live
+ * only on this wrapper — the underlying shared handler is untouched, so
+ * neither the field nor its `.describe()` text reaches any other
+ * caller of the same handler.
+ *
+ * The declared output schema is the inner schema with every field made
+ * optional, PLUS the confirmation fields, so both the preview (only
+ * confirmation fields) and a real commit response (inner fields)
+ * validate against it.
+ */
+export declare function withConfirmGate<I extends ZodRawShape, O extends ZodRawShape, D>(h: SharedHandler<I, O, D>): SharedHandler<ZodRawShape, ZodRawShape>;
+export interface BuildControlServiceArgs {
+    /**
+     * The server's fully composed handler list. The control plane filters
+     * it by audience itself, so callers hand over the same array the data
+     * plane reads — membership can never drift between the two.
+     */
+    readonly handlers: ReadonlyArray<AnyHandler>;
+    /**
+     * Additional ops tool names that answer in one call. Merged with
+     * {@link SINGLE_CALL_OPS}; use it for deployment-registered read-only
+     * ops tools that would otherwise be confirm-gated by the default-deny
+     * rule.
+     */
+    readonly singleCallOps?: ReadonlyArray<string>;
+}
+/**
+ * Assemble the control plane: every `protocol`-tagged handler served
+ * as-is (anonymous), every `ops`-tagged handler auth-gated and — unless
+ * it is a known single-call read — confirm-gated.
+ *
+ * Always `anonymous: true`: the route must answer bearer-less for the
+ * design-time tools, and the per-handler auth gate is what keeps the
+ * ops half closed.
+ */
+export declare function buildControlService(args: BuildControlServiceArgs): McpService;
+export {};
+//# sourceMappingURL=control-service.d.ts.map

package/dist/control-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-service.d.ts","sourceRoot":"","sources":["../src/control-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAK,KAAK,WAAW,EAAmB,MAAM,KAAK,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,KAAK,UAAU,GAAG,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;AAE1D,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,KAAK,CAAC;AAEnE,6CAA6C;AAC7C,eAAO,MAAM,YAAY,aAAa,CAAC;AAEvC,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAE9C,sDAAsD;AACtD,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,WAAW,CAAwB,CAAC;AAErF,0CAA0C;AAC1C,eAAO,MAAM,uBAAuB,EAAE,aAAa,CAAC,WAAW,CAAuB,CAAC;AAEvF;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,aAAa,CAAC,UAAU,CAAC,EAC9B,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,GAClC,aAAa,CAAC,UAAU,CAAC,CAK3B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAa9C,CAAC;AAEH;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,WAAW,EAAE,CAAC,EAC3E,CAAC,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACxB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAGxB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,WAAW,EAAE,CAAC,EAC1E,CAAC,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACxB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAYxB;AASD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,WAAW,EAAE,CAAC,EAC7E,CAAC,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACxB,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CA+BzC;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAChD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,UAAU,CAmB7E"}

package/dist/control-service.js

@@ -0,0 +1,220 @@
+/**
+ * `/control` — the control plane.
+ *
+ * ggui serves exactly TWO MCP surfaces:
+ *
+ *   - **Data plane** — the agent routes (`universalMcpPath`, plus the
+ *     per-tenant `${pathPrefix}/:appId` variant when configured). Carries
+ *     the `agent` + `runtime` audiences: the tools an agent calls while a
+ *     session is running.
+ *   - **Control plane** — this service. Carries the `protocol` + `ops`
+ *     audiences: design-time spec/discovery (anonymous) and operator-class
+ *     account management (authenticated, state-changing calls
+ *     confirm-gated).
+ *
+ * Audience TAGS stay normative — `audience` on a handler still declares
+ * its caller class, and the `ggui_protocol_*` / `ggui_ops_*` wire-name
+ * prefixes still encode it. What this module retires is one-HTTP-route-
+ * per-audience MOUNTING: `protocol` and `ops` land on the same path.
+ *
+ * WHY one route for two audiences: an HTTP route carries ONE auth
+ * posture. Design-time spec tools must answer bearer-less (an agent
+ * authoring a blueprint has no account yet); operator tools must not.
+ * Two routes forced a deployment to choose per route, which is why the
+ * two surfaces could never be pointed at by a single client config. A
+ * service mount is the seam that mixes both: the route is anonymous-
+ * capable, and each ops handler re-imposes auth for itself.
+ *
+ * The per-tool wrappers, in application order (innermost first):
+ *
+ *   1. {@link withConfirmGate} — state-changing ops only. Turns one
+ *      call into a deliberate two-call sequence so an agent cannot
+ *      silently mint credentials, spend credits, or delete resources.
+ *   2. {@link withAuthGate} — every ops tool. Rejects callers the auth
+ *      adapter never authenticated (the anonymous synthetic), so an ops
+ *      handler never runs against a phantom identity.
+ *   3. {@link stripAudience} — every tool. Service handlers MUST NOT
+ *      carry an `audience` tag (the mount path IS the audience); the tag
+ *      is consumed by the data-plane route filter and is meaningless
+ *      inside a service, so dropping it is lossless.
+ *
+ * Ordering matters: the auth gate sits OUTSIDE the confirm gate, so an
+ * unauthenticated caller gets an auth error rather than a confirmation
+ * preview that leaks which operations exist against which account.
+ */
+import { AuthRequiredError, } from "@ggui-ai/mcp-server-handlers";
+import { z } from "zod";
+/** HTTP path the control plane mounts at. */
+export const CONTROL_PATH = "/control";
+/** Service name the control plane reports in validation errors + telemetry. */
+export const CONTROL_SERVICE_NAME = "control";
+/** Audiences the data plane (agent routes) serves. */
+export const DATA_PLANE_AUDIENCES = ["agent", "runtime"];
+/** Audiences the control plane serves. */
+export const CONTROL_PLANE_AUDIENCES = ["protocol", "ops"];
+/**
+ * Return the subset of `set` whose `audience` tag intersects `allowed`.
+ * The single projection from audience tags to mount surfaces — both
+ * planes read it, so a handler can never land on both or on neither.
+ *
+ * Handlers with `audience: undefined` default to `['agent']`: an
+ * untagged handler is agent-callable, which keeps zero-config OSS
+ * deployments (whose handlers rarely tag anything) on the data plane.
+ */
+export function filterHandlersByAudience(set, allowed) {
+    return set.filter((h) => {
+        const tags = h.audience ?? ["agent"];
+        return tags.some((t) => allowed.includes(t));
+    });
+}
+/**
+ * Ops tools that answer in ONE call — reads, lists, and card-openers
+ * that change no state. Every other `ops`-tagged tool is treated as
+ * state-changing and confirm-gated.
+ *
+ * The classification is default-DENY on purpose. A curated
+ * "these ones are mutating" list has a silent failure mode: land a new
+ * state-changing ops tool, forget the list, and it ships un-gated with
+ * nothing to notice. Inverting it makes the forgotten case a visible
+ * annoyance (an extra confirmation round-trip on a read) instead of an
+ * invisible hole, which is the trade the Protocol and Contract Bar asks
+ * for — an unflagged gap is a failure in disguise.
+ *
+ * Deployments that register their own read-only ops tools extend this
+ * via `CreateGguiServerOptions.control.singleCallOps` rather than
+ * patching this set.
+ *
+ * `ggui_ops_setup_byok` is a deliberate entry: it LISTS provider-key
+ * status and returns the BYOK card — the set/remove tools are the real
+ * mutations. Confirm-gating it would break the card's inline render on
+ * the first call, because the confirmation preview does not carry the
+ * card's discriminant.
+ */
+export const SINGLE_CALL_OPS = new Set([
+    "ggui_ops_get_credit_balance",
+    "ggui_ops_get_my_blueprint_source",
+    "ggui_ops_get_org_balance",
+    "ggui_ops_list_apps",
+    "ggui_ops_list_blueprints",
+    "ggui_ops_list_connector_keys",
+    "ggui_ops_list_credit_transactions",
+    "ggui_ops_list_my_apps",
+    "ggui_ops_list_my_blueprints",
+    "ggui_ops_list_orgs",
+    "ggui_ops_list_provider_keys",
+    "ggui_ops_setup_byok",
+]);
+/**
+ * Return a copy of the handler with the `audience` tag removed.
+ * `validateMcpServices` rejects service handlers that carry one.
+ */
+export function stripAudience(h) {
+    const { audience: _omit, ...rest } = h;
+    return rest;
+}
+/**
+ * Require an authenticated caller.
+ *
+ * The control plane is anonymous-CAPABLE so design-time spec tools
+ * answer bearer-less. In that mode the transport synthesizes a builder
+ * identity (`authSource: 'anonymous'`) for requests that presented no
+ * credential — or presented one the adapter rejected. An un-gated ops
+ * handler would then run against that synthetic rather than refusing,
+ * which is how a caller with no account would read and write a phantom
+ * shared tenant.
+ *
+ * The gate is on `ctx.authSource`, not on which identity FIELDS are
+ * populated: every deployment tier proves identity differently
+ * (single-user builder, per-app key, per-user key, OIDC), and only the
+ * source distinguishes "the adapter authenticated this request" from
+ * "the transport let it through". Transports map
+ * {@link AuthRequiredError} to 401 so clients can prompt for sign-in.
+ */
+export function withAuthGate(h) {
+    return {
+        ...h,
+        async handler(input, ctx) {
+            if (ctx.authSource === undefined || ctx.authSource === "anonymous") {
+                throw new AuthRequiredError(`${h.name} is an operator tool and needs an authenticated caller. Present a bearer token this deployment accepts.`);
+            }
+            return h.handler(input, ctx);
+        },
+    };
+}
+/** Map every field of a Zod raw-shape to its `.optional()` form. */
+function optionalize(shape) {
+    return Object.fromEntries(Object.entries(shape).map(([key, value]) => [key, value.optional()]));
+}
+/**
+ * Wrap a state-changing handler in a stateless two-call confirmation
+ * gate. The first call (no `confirm: true`) returns a preview and runs
+ * nothing; a second call carrying `confirm: true` delegates to the
+ * inner handler.
+ *
+ * The `confirm` input field and the confirmation output fields live
+ * only on this wrapper — the underlying shared handler is untouched, so
+ * neither the field nor its `.describe()` text reaches any other
+ * caller of the same handler.
+ *
+ * The declared output schema is the inner schema with every field made
+ * optional, PLUS the confirmation fields, so both the preview (only
+ * confirmation fields) and a real commit response (inner fields)
+ * validate against it.
+ */
+export function withConfirmGate(h) {
+    const inputSchema = {
+        ...h.inputSchema,
+        confirm: z
+            .boolean()
+            .optional()
+            .describe("Set true to actually perform this state-changing operation. Omitted/false returns a confirmation preview instead."),
+    };
+    const outputSchema = {
+        ...optionalize(h.outputSchema),
+        confirmationRequired: z.boolean().optional(),
+        confirmationPrompt: z.string().optional(),
+    };
+    return {
+        ...h,
+        description: `${h.description} (State-changing: the first call returns a confirmation prompt; re-call with confirm:true to proceed.)`,
+        inputSchema,
+        outputSchema,
+        async handler(input, ctx) {
+            if (input.confirm !== true) {
+                return {
+                    confirmationRequired: true,
+                    confirmationPrompt: `Calling ${h.name} will change account state. Show the human exactly what will happen and, only with their explicit approval, call ${h.name} again with confirm:true.`,
+                };
+            }
+            const { confirm: _confirm, ...rest } = input;
+            return h.handler(rest, ctx);
+        },
+    };
+}
+/**
+ * Assemble the control plane: every `protocol`-tagged handler served
+ * as-is (anonymous), every `ops`-tagged handler auth-gated and — unless
+ * it is a known single-call read — confirm-gated.
+ *
+ * Always `anonymous: true`: the route must answer bearer-less for the
+ * design-time tools, and the per-handler auth gate is what keeps the
+ * ops half closed.
+ */
+export function buildControlService(args) {
+    const singleCall = new Set([...SINGLE_CALL_OPS, ...(args.singleCallOps ?? [])]);
+    const protocolTools = filterHandlersByAudience(args.handlers, ["protocol"]);
+    const opsTools = filterHandlersByAudience(args.handlers, ["ops"]);
+    const handlers = [
+        ...protocolTools.map((h) => stripAudience(h)),
+        ...opsTools.map((h) => {
+            const confirmed = singleCall.has(h.name) ? h : withConfirmGate(h);
+            return stripAudience(withAuthGate(confirmed));
+        }),
+    ];
+    return {
+        name: CONTROL_SERVICE_NAME,
+        path: CONTROL_PATH,
+        handlers,
+        anonymous: true,
+    };
+}

package/dist/index.d.ts

@@ -29,13 +29,15 @@ export type { HandlerContext, SharedHandler } from '@ggui-ai/mcp-server-handlers
 export type { GadgetDescriptor, McpUiDisplayMode, GguiSession, SystemGguiSession, } from '@ggui-ai/protocol';
 export type { GenerationDeps } from '@ggui-ai/mcp-server-handlers';
 export { buildNoCredentialsGguiSession } from '@ggui-ai/mcp-server-handlers';
-export { createGguiServer, defaultHandlers } from './server.js';
-export type { CreateGguiServerOptions, GguiServer, } from './server.js';
+export { buildOpsBundleHandlers, createGguiServer, defaultHandlers } from './server.js';
+export type { CreateGguiServerOptions, GguiServer, OpsBundleDeps, } from './server.js';
+export { buildControlService, CONTROL_PATH, filterHandlersByAudience, SINGLE_CALL_OPS, } from './control-service.js';
+export type { AudienceTag, BuildControlServiceArgs } from './control-service.js';
 export { FileSystemCodeStore } from './code-store-fs.js';
 export type { FileSystemCodeStoreOptions } from './code-store-fs.js';
 export type { McpServerMount } from './mcp-mounts.js';
 export type { McpService, ServicePath } from './mcp-mounts.js';
-export { validateMcpServices, validateServicePath } from './mcp-mounts.js';
+export { validateMcpServices, validateServiceHandlers, validateServicePath, } from './mcp-mounts.js';
 export { composePreviewReservedValidator, mergeReservedValidators, } from './reserved-validators.js';
 export { checkRenderSchemaCompat, DEFAULT_SCHEMA_COMPAT_MODE, hasErrorFinding, SchemaCompatError, } from './schema-compat.js';
 export type { SchemaCompatFinding, SchemaCompatMode, SchemaCompatReport, GguiSessionContractShape, ToolSchemaRef, } from './schema-compat.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -30,12 +30,18 @@
 // `/settings` URL) without taking a direct `@ggui-ai/mcp-server-handlers`
 // dependency.
 export { buildNoCredentialsGguiSession } from '@ggui-ai/mcp-server-handlers';
-export { createGguiServer, defaultHandlers } from './server.js';
+export { buildOpsBundleHandlers, createGguiServer, defaultHandlers } from './server.js';
+// Control plane (`/control`) — the composition that projects every
+// `protocol`- and `ops`-tagged handler onto one anonymous-capable
+// route with per-tool auth + confirmation gates. `createGguiServer`
+// mounts it automatically; the pieces are exported so deployments can
+// assert their own control surface at boot.
+export { buildControlService, CONTROL_PATH, filterHandlersByAudience, SINGLE_CALL_OPS, } from './control-service.js';
 // Content-addressable code delivery (2026-05-03). FileSystemCodeStore
 // is the OSS dev default; in-memory variant ships in
 // `@ggui-ai/mcp-server-core/in-memory` for tests + ephemeral runs.
 export { FileSystemCodeStore } from './code-store-fs.js';
-export { validateMcpServices, validateServicePath } from './mcp-mounts.js';
+export { validateMcpServices, validateServiceHandlers, validateServicePath, } from './mcp-mounts.js';
 // Reserved-channel payload validator composition.
 // `composePreviewReservedValidator` binds the A2UI adapter
 // for `_ggui:preview`; `mergeReservedValidators` layers caller-provided

package/dist/mcp-endpoint-routes.d.ts

@@ -1,11 +1,13 @@
 /**
- * MCP wire endpoints — the audience-routed JSON-RPC surfaces.
+ * MCP wire endpoints — the JSON-RPC surfaces.
  *
- *   POST <universalMcpPath>            — agent+runtime tools (default `/mcp`)
- *   POST <pathPrefix>/:appId           — per-tenant variant (opt-in via
- *                                        `perAppRouting`)
- *   POST /protocol                     — design-time spec/discovery tools
- *   POST /ops                          — operator-class management tools
+ *   POST <universalMcpPath>            — DATA PLANE: agent+runtime tools
+ *                                        (default `/mcp`)
+ *   POST <pathPrefix>/:appId           — data plane, per-tenant variant
+ *                                        (opt-in via `perAppRouting`)
+ *   POST /control                      — CONTROL PLANE: design-time
+ *                                        spec/discovery (anonymous) +
+ *                                        operator management (authed)
  *   POST <service.path>                — isolated MCP services (path IS
  *                                        the audience)
  *   GET/DELETE on each                 — 405 (stateless server; no
@@ -13,13 +15,18 @@
  *                                        session-terminate verbs)
  *
  * Every route shares ONE request pipeline (`makeMcpHandler`): resolve
- * identity via the AuthAdapter (anonymous services synthesize a
+ * identity via the AuthAdapter (anonymous surfaces synthesize a
  * builder identity on missing/invalid bearers), apply the per-app
  * authorize hook, build a fresh `McpServer` + Streamable HTTP
  * transport per request (stateless), and dispatch under the
  * AsyncLocalStorage-scoped `HandlerContext`. The difference between
  * routes is ONLY the handler set each exposes.
  *
+ * Audience TAGS remain the normative caller-class declaration; what
+ * they no longer do is mint one HTTP route each. `protocol` and `ops`
+ * both mount on `/control` — see `./control-service.ts` for why (one
+ * route carries one auth posture; the control plane needs two).
+ *
  * See `docs/development/audience-routes.md` for the audience taxonomy
  * (`agent` / `runtime` / `protocol` / `ops`) and the wire-name prefix
  * rules.
@@ -48,8 +55,15 @@ interface MountOptions {
     readonly auth: AuthAdapter;
     /** Server identity forwarded to every per-request `buildMcpServer`. */
     readonly info: ServerInfo;
-    /** Full composed handler list (audience filtering happens here). */
+    /** Full composed handler list (data-plane audience filtering happens here). */
     readonly handlers: ReadonlyArray<SharedHandler<ZodRawShape, ZodRawShape>>;
+    /**
+     * Control-plane handler set — already projected + wrapped by
+     * `buildControlService`. Passed pre-built rather than filtered here
+     * because the per-tool auth/confirm wrappers are composition, not
+     * transport.
+     */
+    readonly controlHandlers: ReadonlyArray<SharedHandler<ZodRawShape, ZodRawShape>>;
     /** Validated isolated-service list (`validateMcpServices` output). */
     readonly mcpServices: ReadonlyArray<McpService>;
     /** Request-scoped HandlerContext storage shared with the handlers. */
@@ -79,9 +93,9 @@ interface MountOptions {
     readonly buildMcpOptions: BuildMcpServerOptions;
 }
 /**
- * Mount the universal / per-app / protocol / ops / service MCP
- * endpoints onto the express app. Returns nothing — the routes
- * self-register.
+ * Mount the data-plane (universal / per-app), control-plane, and
+ * service MCP endpoints onto the express app. Returns nothing — the
+ * routes self-register.
  */
 export declare function mountMcpEndpoints(opts: MountOptions): void;
 export {};

package/dist/mcp-endpoint-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-endpoint-routes.d.ts","sourceRoot":"","sources":["../src/mcp-endpoint-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElF,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAEvC,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC7F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,sFAAsF;AACtF,UAAU,aAAa;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1E,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAChD,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAChD,qDAAqD;IACrD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,CAAC;IAC3D,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,CACrB,GAAG,EAAE,OAAO,KACT;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC9F;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;CACjD;AAyBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA4V1D"}
+{"version":3,"file":"mcp-endpoint-routes.d.ts","sourceRoot":"","sources":["../src/mcp-endpoint-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElF,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAEvC,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAM7F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,sFAAsF;AACtF,UAAU,aAAa;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1E;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IACjF,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAChD,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAChD,qDAAqD;IACrD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,CAAC;IAC3D,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,CACrB,GAAG,EAAE,OAAO,KACT;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC9F;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;CACjD;AAyBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA4U1D"}