@ggui-ai/mcp-server 0.2.0-alpha.4 → 0.4.0-rc.0

package/dist/pairing-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pairing-transport.d.ts","sourceRoot":"","sources":["../src/pairing-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,mEAAmE;AACnE,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,qBAAqB,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,kCACb,CAAC;AAElC,MAAM,WAAW,uBAAuB;IACtC,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,uBAAuB,GAC5B,IAAI,CAmNN"}
+{"version":3,"file":"pairing-transport.d.ts","sourceRoot":"","sources":["../src/pairing-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,mEAAmE;AACnE,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,qBAAqB,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,kCACb,CAAC;AAElC,MAAM,WAAW,uBAAuB;IACtC,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,uBAAuB,GAC5B,IAAI,CAmNN"}

package/dist/pairing-transport.js

@@ -1,3 +1,4 @@
+import { isRecord } from '@ggui-ai/protocol';
 import { resolveIdentity, UnauthenticatedError } from './auth.js';
 /** Default URL path the pairing-completion route is mounted at. */
 export const DEFAULT_PAIRING_PATH = '/pair';
@@ -36,7 +37,7 @@ export function mountPairingTransport(app, opts) {
     // stores verbatim.
     app.post(path, async (req, res) => {
         const reqLogger = opts.logger.child({ route: 'POST ' + path });
-        const body = (req.body ?? {});
+        const body = isRecord(req.body) ? req.body : {};
         const code = typeof body['code'] === 'string' ? body['code'] : undefined;
         const deviceName = typeof body['deviceName'] === 'string' ? body['deviceName'] : undefined;
         const remoteAddress = req.socket.remoteAddress ?? undefined;

package/dist/request-context.d.ts

@@ -2,7 +2,7 @@
  * Per-request context plumbing — AsyncLocalStorage backed.
  *
  * The capability-URL routes (`/r/<code>`, `/api/bootstrap/<code>`) and
- * the push/update tool result-meta builders all want to know the
+ * the render/update tool result-meta builders all want to know the
  * absolute public base URL of THIS server as seen by THIS client.
  * That can't come from a static config in two common dev/OSS scenarios:
  *
@@ -30,7 +30,7 @@
  *
  * Auto-derive applies ONLY to data the relevant route really should
  * derive from the request:
- *   - runtimeUrl on push/update bootstrap meta (this slice).
+ *   - runtimeUrl on render/update bootstrap meta (this slice).
  *
  * Auto-derive MUST NOT apply to:
  *   - OAuth callback URLs (operator-config'd one-time per provider;

package/dist/request-context.js

@@ -2,7 +2,7 @@
  * Per-request context plumbing — AsyncLocalStorage backed.
  *
  * The capability-URL routes (`/r/<code>`, `/api/bootstrap/<code>`) and
- * the push/update tool result-meta builders all want to know the
+ * the render/update tool result-meta builders all want to know the
  * absolute public base URL of THIS server as seen by THIS client.
  * That can't come from a static config in two common dev/OSS scenarios:
  *
@@ -30,7 +30,7 @@
  *
  * Auto-derive applies ONLY to data the relevant route really should
  * derive from the request:
- *   - runtimeUrl on push/update bootstrap meta (this slice).
+ *   - runtimeUrl on render/update bootstrap meta (this slice).
  *
  * Auto-derive MUST NOT apply to:
  *   - OAuth callback URLs (operator-config'd one-time per provider;

package/dist/reserved-validators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reserved-validators.d.ts","sourceRoot":"","sources":["../src/reserved-validators.ts"],"names":[],"mappings":"AA6BA,OAAO,EAGL,KAAK,wBAAwB,EAE9B,MAAM,mBAAmB,CAAC;AA0C3B;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,IAAI,WAAW,CAC5D,MAAM,EACN,wBAAwB,CACzB,CAEA;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,SAAS,EAC/D,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,SAAS,GAClE,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,SAAS,CAS3D"}
+{"version":3,"file":"reserved-validators.d.ts","sourceRoot":"","sources":["../src/reserved-validators.ts"],"names":[],"mappings":"AAqCA,OAAO,EAGL,KAAK,wBAAwB,EAE9B,MAAM,mBAAmB,CAAC;AA0C3B;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,IAAI,WAAW,CAC5D,MAAM,EACN,wBAAwB,CACzB,CAEA;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,SAAS,EAC/D,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,SAAS,GAClE,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,SAAS,CAS3D"}

package/dist/reserved-validators.js

@@ -13,7 +13,7 @@
  *   - {@link composePreviewReservedValidator} — returns a single-entry
  *     map binding `_ggui:preview` to the A2UI adapter. Call at server
  *     construction and feed into `extraReservedValidators` on
- *     `SessionChannelOptions` / `CreateGguiServerOptions`.
+ *     `GguiSessionChannelOptions` / `CreateGguiServerOptions`.
  *   - {@link mergeReservedValidators} — combine multiple validator maps
  *     when a caller provides their own extras AND the server wants to
  *     layer A2UI on top. Caller-provided entries win on key conflict.
@@ -22,6 +22,14 @@
  * catalog filtering, no surface-id checking — those live in the A2UI
  * runtime consumer. The adapter enforces only what `parseServerMessage`
  * enforces: message-shape conformance to the V1 write-path union.
+ *
+ * The three copies (mcp-server / react / react-native) are documented
+ * structural mirrors: docstrings may differ per package, but the
+ * EXECUTABLE CODE must stay identical — guarded by the
+ * comment-stripped mirror gate in the SDK twin-parity suites
+ * (`ggui-react{,-native}/src/twin-parity.test.ts`,
+ * `CODE_IDENTICAL_MIRRORS`). Apply code changes to all three copies
+ * in the same slice.
  */
 import { parseServerMessage, } from '@ggui-ai/preview-a2ui';
 import { PREVIEW_CHANNEL, } from '@ggui-ai/protocol';

package/dist/route-param.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A single (non-splat) route param / query value is a string at runtime, but
+ * @types/express@5 widens `req.params[name]` to `string | string[]` (path-to-
+ * regexp v8 supports repeatable params). Narrow to the single-string case;
+ * an array (multi-value) collapses to undefined so callers' existing
+ * missing-param guards handle it.
+ */
+export declare function singleParam(v: string | string[] | undefined): string | undefined;
+//# sourceMappingURL=route-param.d.ts.map

package/dist/route-param.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-param.d.ts","sourceRoot":"","sources":["../src/route-param.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAEhF"}

package/dist/route-param.js

@@ -0,0 +1,10 @@
+/**
+ * A single (non-splat) route param / query value is a string at runtime, but
+ * @types/express@5 widens `req.params[name]` to `string | string[]` (path-to-
+ * regexp v8 supports repeatable params). Narrow to the single-string case;
+ * an array (multi-value) collapses to undefined so callers' existing
+ * missing-param guards handle it.
+ */
+export function singleParam(v) {
+    return typeof v === 'string' ? v : undefined;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Iframe-runtime bundle static mount (C8 — plan §C8 Deliverable 2).
+ *
+ * Serves the `@ggui-ai/iframe-runtime` iframe runtime bundle from
+ * `runtimePath` (default `/_ggui/iframe-runtime.js`). The thin-shell
+ * HTML served from `ui://ggui/render` dynamic-script-loads this
+ * URL on boot — the rendering runtime is OUT of the shell and IN
+ * this separately-served file (C8 pivot, shrinking the shell from
+ * ~175 LOC inline JS to ~30 LOC wrapper).
+ *
+ * Routing discipline: registered BEFORE the console block because
+ * console's default `path` is `/` and its `express.static`
+ * + SPA-fallback would otherwise match `/_ggui/iframe-runtime.js` first
+ * (Express route table is order-sensitive). Registering early keeps
+ * the runtime path from leaking into the console's `index.html`
+ * fallback on a missing-bundle day.
+ *
+ * Missing-bundle posture mirrors the console mount: 503 with a
+ * `pnpm --filter @ggui-ai/iframe-runtime build` remediation hint. Silent
+ * 404 would be mistaken for "renderer is broken" instead of
+ * "renderer bundle wasn't built" — same debugging trap console
+ * avoids.
+ */
+import type { Express } from "express";
+import type { Logger } from "./logger.js";
+interface MountOptions {
+    /** Express app to mount onto. */
+    readonly app: Express;
+    /** HTTP route under which the bundle is mounted. */
+    readonly runtimePath: string;
+    /** Absolute path of the built bundle file on disk. */
+    readonly runtimeBundleFile: string;
+    /** Structured logger for the missing-bundle boot warning. */
+    readonly logger: Logger;
+}
+/**
+ * Mount `GET <runtimePath>` onto the express app. Returns nothing —
+ * the route self-registers. When the bundle file is missing on disk
+ * the mount degrades to a 503 with a build hint.
+ */
+export declare function mountRuntimeBundleRoute(opts: MountOptions): void;
+export {};
+//# sourceMappingURL=runtime-bundle-route.d.ts.map

package/dist/runtime-bundle-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-bundle-route.d.ts","sourceRoot":"","sources":["../src/runtime-bundle-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAiDhE"}

package/dist/runtime-bundle-route.js

@@ -0,0 +1,80 @@
+/**
+ * Iframe-runtime bundle static mount (C8 — plan §C8 Deliverable 2).
+ *
+ * Serves the `@ggui-ai/iframe-runtime` iframe runtime bundle from
+ * `runtimePath` (default `/_ggui/iframe-runtime.js`). The thin-shell
+ * HTML served from `ui://ggui/render` dynamic-script-loads this
+ * URL on boot — the rendering runtime is OUT of the shell and IN
+ * this separately-served file (C8 pivot, shrinking the shell from
+ * ~175 LOC inline JS to ~30 LOC wrapper).
+ *
+ * Routing discipline: registered BEFORE the console block because
+ * console's default `path` is `/` and its `express.static`
+ * + SPA-fallback would otherwise match `/_ggui/iframe-runtime.js` first
+ * (Express route table is order-sensitive). Registering early keeps
+ * the runtime path from leaking into the console's `index.html`
+ * fallback on a missing-bundle day.
+ *
+ * Missing-bundle posture mirrors the console mount: 503 with a
+ * `pnpm --filter @ggui-ai/iframe-runtime build` remediation hint. Silent
+ * 404 would be mistaken for "renderer is broken" instead of
+ * "renderer bundle wasn't built" — same debugging trap console
+ * avoids.
+ */
+import { existsSync } from "node:fs";
+/**
+ * Mount `GET <runtimePath>` onto the express app. Returns nothing —
+ * the route self-registers. When the bundle file is missing on disk
+ * the mount degrades to a 503 with a build hint.
+ */
+export function mountRuntimeBundleRoute(opts) {
+    const { app, runtimePath, runtimeBundleFile, logger } = opts;
+    if (existsSync(runtimeBundleFile)) {
+        app.get(runtimePath, (_req, res) => {
+            res.setHeader("Content-Type", "application/javascript; charset=utf-8");
+            // Short cache — operators iterating on the renderer want
+            // fresh copies after rebuild. Production hardening (etag,
+            // long-term caching with hashed filenames) is a follow-on
+            // concern; same posture console takes.
+            res.setHeader("Cache-Control", "no-cache");
+            // CORS: the bundle MUST be loadable from `<script type="module"
+            // src=...>` inside a sandboxed `srcdoc` iframe (the
+            // `<McpAppIframe>` mount path — see `packages/ggui-react/src/
+            // McpAppIframe/dispatch.ts::deriveResourceMountSource`). Such an
+            // iframe has the `null` origin and module-script fetches always
+            // run in CORS mode; without a permissive header browsers reject
+            // the response and the renderer never executes (Lane 1 specs
+            // pinning `data-ggui-mcp-app-iframe-lifecycle="code-ready"`
+            // hang to timeout). The bundle is public — it ships unmodified
+            // to anyone who fetched the page, so `*` is the right shape;
+            // there's no auth state on the renderer route to protect via a
+            // narrower origin allowlist. This pairs with the production
+            // `/ui://ggui/render` shell HTML setting `s.type='module'`
+            // (`mcp-apps-outbound.ts::GGUI_RENDER_SHELL_SCRIPT_BODY`).
+            res.setHeader("Access-Control-Allow-Origin", "*");
+            // `dotfiles: 'allow'` — express@5's `res.sendFile` (send@1.x)
+            // splits the FULL absolute path into segments and applies its
+            // default `dotfiles: 'ignore'` policy, which 404s any file whose
+            // path crosses a dot-prefixed directory segment (e.g. a checkout
+            // under `~/.local/...` or a git worktree under `.../.git/...`).
+            // `runtimeBundleFile` is a fixed, server-controlled absolute path
+            // — never derived from the request — so there is no traversal
+            // surface to protect; allow the bundle to serve regardless of
+            // where the package install tree happens to live. express@4's
+            // `sendFile` did not subject the parent directories to this check.
+            res.sendFile(runtimeBundleFile, { dotfiles: "allow" });
+        });
+    }
+    else {
+        logger.warn("renderer_bundle_missing", {
+            bundleFile: runtimeBundleFile,
+            hint: "Run `pnpm --filter @ggui-ai/iframe-runtime build` to produce the bundle. Serving 503 from the mount point until it exists.",
+        });
+        app.get(runtimePath, (_req, res) => {
+            res
+                .status(503)
+                .type("text/plain")
+                .send("renderer bundle not built. Run:\n  pnpm --filter @ggui-ai/iframe-runtime build\n");
+        });
+    }
+}

package/dist/schema-compat.d.ts

@@ -1,59 +1,44 @@
 /**
- * Schema compatibility check — verifies that a Render's declared
- * `actionSpec` / `streamSpec` schemas line up with the input/output
- * schemas of the tools they reference. Wired at two canonical check
- * points: `ggui_render` validation (defensive, fires when the
- * generator eventually emits contract) and blueprint registration
- * (the console blueprint-try endpoint — the real-world site where a
- * Render with pre-declared `actionSpec` / `streamSpec` and tool
- * refs lands on the server).
+ * Schema compatibility check — verifies that a GguiSession's declared
+ * `actionSpec` schemas line up with the input schemas of the
+ * `nextStep` tools they hint at. Wired at two canonical check points:
+ * `ggui_render` validation (defensive, fires when the generator
+ * eventually emits contract) and blueprint registration (the console
+ * blueprint-try endpoint — the real-world site where a GguiSession
+ * with a pre-declared `actionSpec` and tool hints lands on the
+ * server).
  *
  * **Algorithmic primitive** lives in `@ggui-ai/protocol`:
  *
  *   - `isSchemaSubset(superset, subset)` answers "can every value
  *     subset accepts also pass superset?".
  *   - `zodToJsonSchema(...)` converts a tool's ZodRawShape
- *     `inputSchema` / `outputSchema` to the JsonSchema shape the
- *     subset algorithm consumes.
+ *     `inputSchema` to the JsonSchema shape the subset algorithm
+ *     consumes.
  *
- * **What this module adds.** A small layer that walks a Render's
- * `actionSpec` + `streamSpec`, resolves each declared `tool` ref
- * against a toolName → ZodRawShape registry, runs the appropriate
- * subset check, and reports a stable {@link SchemaCompatReport}. The
- * caller (console endpoint, push handler — later) decides whether
- * a non-empty report should throw, warn, or be ignored per the
- * {@link SchemaCompatMode} policy flag.
+ * **What this module adds.** A small layer that walks a GguiSession's
+ * `actionSpec`, resolves each declared `nextStep` hint against a
+ * toolName → ZodRawShape registry, runs the subset check, and reports
+ * a stable {@link SchemaCompatReport}. The caller (console endpoint,
+ * render handler) decides whether a non-empty report should throw,
+ * warn, or be ignored per the {@link SchemaCompatMode} policy flag.
  *
- * **Direction semantics (load-bearing).**
- *
- *   - For `actionSpec[name].schema` + `tool`: the action's payload
- *     is sent INTO the tool, so the action schema must be a subset
- *     of the tool's `inputSchema`. Compat relation:
- *     `isSchemaSubset(toolInputSchema, actionSchema)`.
- *   - For `streamSpec[channel].schema` + `tool`: the tool's return
- *     value is emitted OUT on the channel. Every value the tool
- *     returns MUST be accepted by the channel schema (otherwise a
- *     tool-fired refresh would emit a payload that subscribers
- *     reject). The channel schema is therefore the PERMISSIVE side
- *     and the tool's return is the restricted side. Compat relation:
- *     `isSchemaSubset(channelSchema, toolReturnSchema)` — i.e.
- *     "every toolReturn-accepted value is also channelSchema-
- *     accepted".
- *
- *     Note: the `StreamChannelEntry.schema` docstring phrases this
- *     as "the tool's returns MUST be a superset of channel schema".
- *     That historical phrasing is author-facing and slightly
- *     misleading if read literally as set-theoretic superset of
- *     accepted-values; the semantic intent is the one encoded here
- *     — EVERY tool return passes channel validation.
+ * **Direction semantics (load-bearing).** For `actionSpec[name]
+ * .schema` + `nextStep`: the action's payload is what the agent
+ * forwards INTO the hinted tool, so the action schema must be a
+ * subset of the tool's `inputSchema`. Compat relation:
+ * `isSchemaSubset(toolInputSchema, actionSchema)`. The check is
+ * advisory by nature — `nextStep` is a hint the agent owns — but a
+ * mismatch on a same-server tool is an author bug worth failing
+ * loudly at registration time.
  */
 import type { ZodRawShape } from 'zod';
-import { type SubsetViolation, type ActionSpec, type StreamSpec } from '@ggui-ai/protocol';
+import { type SubsetViolation, type ActionSpec } from '@ggui-ai/protocol';
 /**
  * Stance the host takes when a check surfaces violations.
  *
  *   - `'reject'` (default) — throw {@link SchemaCompatError} so the
- *     containing request fails before the stack item commits /
+ *     containing request fails before the render commits /
  *     before the blueprint registers. The canonical enforcement
  *     posture for launch.
  *   - `'warn'` — return the report without throwing. The caller is
@@ -77,25 +62,33 @@ export declare const DEFAULT_SCHEMA_COMPAT_MODE: SchemaCompatMode;
  */
 export interface SchemaCompatFinding {
     /**
-     * Which spec side produced this finding. `'action'` for an
-     * `actionSpec[name]` tool ref; `'stream'` for a
-     * `streamSpec[channel].tool` ref. Consumers can branch on this
-     * when rendering the cause.
+     * Which spec side produced this finding. Always `'action'` — the
+     * only spec side carrying a tool reference is `actionSpec[name]
+     * .nextStep`. Kept as a literal field so consumers that render the
+     * cause have a stable discriminator.
      */
-    readonly kind: 'action' | 'stream';
+    readonly kind: 'action';
     /** Action name or channel name. */
     readonly specName: string;
     /** Tool name the spec referenced. */
     readonly toolName: string;
     /** One of:
-     *   - `'tool-not-found'`  — the ref's tool is not registered on
-     *     the composed handler set. (Author bug — matching the
-     *     existing `TOOL_NOT_FOUND` contract semantics, but surfaced
-     *     before any envelope reaches the agentic loop.)
+     *   - `'tool-not-found'`  — the hinted tool is not registered on
+     *     the composed handler set (and not declared in the contract's
+     *     `agentCapabilities.tools` cross-MCP catalog).
      *   - `'schema-mismatch'` — the subset check failed with at least
      *     one violation. See {@link SchemaCompatFinding.violations}.
      */
     readonly reason: 'tool-not-found' | 'schema-mismatch';
+    /**
+     * Whether this finding blocks the render (`'error'`) or is purely
+     * advisory (`'warn'`). Defaults to error severity when omitted — the
+     * throw gate treats any finding lacking `severity: 'warn'` as a
+     * hard error. An action `nextStep` tool-not-found is tagged `'warn'`
+     * because `nextStep` is a documented HINT the agent owns and ggui
+     * never dispatches; an unresolved one must not block the render.
+     */
+    readonly severity?: 'error' | 'warn';
     /** Subset violations carried through for rich error rendering.
      *  Empty array when `reason: 'tool-not-found'`. */
     readonly violations: readonly SubsetViolation[];
@@ -111,18 +104,17 @@ export interface SchemaCompatReport {
 }
 /**
  * Narrow shape of what the check helper needs from each registered
- * tool. Satisfied by `SharedHandler<ZodRawShape, ZodRawShape>` — the
- * two schema fields are the only consumed inputs.
+ * tool. Satisfied by `SharedHandler<ZodRawShape, ZodRawShape>` —
+ * `name` + `inputSchema` are the only consumed inputs.
  */
 export interface ToolSchemaRef {
     readonly name: string;
     readonly inputSchema: ZodRawShape;
-    readonly outputSchema: ZodRawShape;
 }
 /**
- * Narrow shape of the Render subset the checker consumes — the
- * two spec fields PLUS the contract's own tool catalog. Accepts any
- * object carrying them, so both `@ggui-ai/protocol::Render` and
+ * Narrow shape of the GguiSession subset the checker consumes — the
+ * `actionSpec` PLUS the contract's own tool catalog. Accepts any
+ * object carrying them, so both `@ggui-ai/protocol::GguiSession` and
  * the console endpoint's manifest contract shape work without a cast.
  *
  * `agentCapabilities.tools` is the contract author's declared catalog
@@ -133,9 +125,8 @@ export interface ToolSchemaRef {
  * schema check (we can't validate a remote server's tool schema from
  * here; the agent owns the cross-MCP call).
  */
-export interface RenderContractShape {
+export interface GguiSessionContractShape {
     readonly actionSpec?: ActionSpec;
-    readonly streamSpec?: StreamSpec;
     readonly agentCapabilities?: {
         readonly tools?: Readonly<Record<string, unknown>>;
     };
@@ -150,9 +141,8 @@ export declare class SchemaCompatError extends Error {
     constructor(report: SchemaCompatReport, context: string);
 }
 /**
- * Check a Render's `actionSpec` / `streamSpec` entries against
- * the tool registry. See {@link SchemaCompatMode} for policy
- * semantics.
+ * Check a GguiSession's `actionSpec` entries against the tool
+ * registry. See {@link SchemaCompatMode} for policy semantics.
  *
  * Returns a {@link SchemaCompatReport}. When `mode === 'reject'`
  * AND findings exist, throws {@link SchemaCompatError} instead —
@@ -163,5 +153,17 @@ export declare class SchemaCompatError extends Error {
  * up in thrown error messages so an operator reading logs sees
  * which ingress surfaced the mismatch.
  */
-export declare function checkRenderSchemaCompat(render: RenderContractShape, tools: Iterable<ToolSchemaRef>, mode: SchemaCompatMode, context: string): SchemaCompatReport;
+export declare function checkRenderSchemaCompat(render: GguiSessionContractShape, tools: Iterable<ToolSchemaRef>, mode: SchemaCompatMode, context: string): SchemaCompatReport;
+/**
+ * Does this report carry at least one finding that should BLOCK the
+ * render? A finding blocks unless it is explicitly advisory
+ * (`severity: 'warn'`) — i.e. anything lacking `severity: 'warn'`
+ * counts as a hard error (default-error semantics). The single
+ * source of truth for the throw gate, shared by the internal
+ * `'reject'`-mode gate above AND any external host that runs the
+ * check in `'warn'` mode and owns its own `ggui_render` enforcement.
+ * Keeping ONE predicate guarantees the gates of every deployment of
+ * this server family can never silently diverge.
+ */
+export declare function hasErrorFinding(report: SchemaCompatReport): boolean;
 //# sourceMappingURL=schema-compat.d.ts.map

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,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,GAAG,QAAQ,CAAC;IACnC,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,iBAAiB,CAAC;IACtD;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;IAClC,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC;CACpC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,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;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC9B,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,GACd,kBAAkB,CA0HpB"}
+{"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"}

package/dist/schema-compat.js

@@ -18,9 +18,8 @@ export class SchemaCompatError extends Error {
     }
 }
 /**
- * Check a Render's `actionSpec` / `streamSpec` entries against
- * the tool registry. See {@link SchemaCompatMode} for policy
- * semantics.
+ * Check a GguiSession's `actionSpec` entries against the tool
+ * registry. See {@link SchemaCompatMode} for policy semantics.
  *
  * Returns a {@link SchemaCompatReport}. When `mode === 'reject'`
  * AND findings exist, throws {@link SchemaCompatError} instead —
@@ -77,6 +76,10 @@ export function checkRenderSchemaCompat(render, tools, mode, context) {
                 specName: actionName,
                 toolName,
                 reason: 'tool-not-found',
+                // Advisory: `nextStep` is a documented HINT the agent owns and
+                // ggui never dispatches, so an unresolved one must not block
+                // the render. Warn-only — the throw gate skips it.
+                severity: 'warn',
                 violations: [],
             });
             continue;
@@ -102,71 +105,40 @@ export function checkRenderSchemaCompat(render, tools, mode, context) {
             });
         }
     }
-    // streamSpec — each channel.tool's outputSchema must be a superset
-    // of channel.schema (inverted direction from actions).
-    const streamSpec = render.streamSpec ?? {};
-    for (const [channelName, entry] of Object.entries(streamSpec)) {
-        if (!entry || typeof entry !== 'object')
-            continue;
-        const toolName = entry.tool;
-        if (typeof toolName !== 'string' || toolName.length === 0)
-            continue;
-        const channelSchema = entry.schema;
-        if (!channelSchema)
-            continue;
-        const tool = byName.get(toolName);
-        if (!tool) {
-            // Cross-MCP escape hatch — symmetric with the actionSpec arm.
-            if (contractDeclaredTools.has(toolName))
-                continue;
-            findings.push({
-                kind: 'stream',
-                specName: channelName,
-                toolName,
-                reason: 'tool-not-found',
-                violations: [],
-            });
-            continue;
-        }
-        const toolOutput = zodToJsonSchema(tool.outputSchema);
-        // Direction: every tool-returned value must be accepted by the
-        // channel schema. Channel is the superset / permissive side,
-        // tool-return is the restricted side.
-        const result = isSchemaSubset(channelSchema, toolOutput);
-        if (!result.compatible) {
-            findings.push({
-                kind: 'stream',
-                specName: channelName,
-                toolName,
-                reason: 'schema-mismatch',
-                violations: result.violations,
-            });
-        }
-    }
     const report = {
         compatible: findings.length === 0,
         findings,
     };
-    if (mode === 'reject' && !report.compatible) {
+    if (mode === 'reject' && hasErrorFinding(report)) {
         throw new SchemaCompatError(report, context);
     }
     return report;
 }
+/**
+ * Does this report carry at least one finding that should BLOCK the
+ * render? A finding blocks unless it is explicitly advisory
+ * (`severity: 'warn'`) — i.e. anything lacking `severity: 'warn'`
+ * counts as a hard error (default-error semantics). The single
+ * source of truth for the throw gate, shared by the internal
+ * `'reject'`-mode gate above AND any external host that runs the
+ * check in `'warn'` mode and owns its own `ggui_render` enforcement.
+ * Keeping ONE predicate guarantees the gates of every deployment of
+ * this server family can never silently diverge.
+ */
+export function hasErrorFinding(report) {
+    return report.findings.some((f) => f.severity !== 'warn');
+}
 /**
  * Format a report into a human-readable message suitable for a
  * thrown error or a log line. Output is deterministic — sorted
- * by `kind` then `specName` — so tests can pattern-match on the
+ * by `specName` — so tests can pattern-match on the
  * exact string without ordering flakes.
  */
 function formatReport(report, context) {
     if (report.compatible) {
         return `${context}: SCHEMA_MISMATCH_ERROR (no findings — internal error)`;
     }
-    const sorted = [...report.findings].sort((a, b) => {
-        if (a.kind !== b.kind)
-            return a.kind < b.kind ? -1 : 1;
-        return a.specName < b.specName ? -1 : a.specName > b.specName ? 1 : 0;
-    });
+    const sorted = [...report.findings].sort((a, b) => a.specName < b.specName ? -1 : a.specName > b.specName ? 1 : 0);
     const lines = sorted.map((f) => {
         if (f.reason === 'tool-not-found') {
             return `- ${f.kind} "${f.specName}" references tool "${f.toolName}" which is not registered`;