@ggui-ai/protocol 0.14.0 → 0.15.0

package/dist/version.js

@@ -6,6 +6,75 @@
  * schema change; the most recent change anchors {@link PROTOCOL_VERSION}.
  *
  * --------------------------------------------------------------------
+ * SPEC §7.1's refused arm is ONE primitive (2026-09-05, additive,
+ * pre-launch, ggui#803 leg 9). The tool result a render gate answers a
+ * pre-generation refusal with was built by hand in
+ * `@ggui-ai/mcp-server-handlers` (`buildRenderRefusalText` + an inline
+ * `{ outcome: 'refused', refusal }`), the conformance kit carried its
+ * own reference, and the reference server could not project it at all
+ * — so the reference server was not a reference for the refused
+ * envelope, and a third hand-built copy there would only have re-graded
+ * the kit's reference.
+ *
+ *   rr1. **`projectRenderRefusal(refusal): RenderRefusalResult`** (new
+ *      export, `envelopes/render-refusal.ts`) — `isError: true`,
+ *      `content[0].text` = `<code>: <message> <fix>`, `structuredContent`
+ *      = `{ outcome: 'refused', refusal }` typed as **`RefusedRenderOutput`**
+ *      (`z.infer<typeof refusedOutputSchema>`, new export), no `_meta`.
+ *      Pure and synchronous. The four facts have one source.
+ *
+ *   rr2. **Consumers**: `mcp-server-handlers`' `ggui_render` builds the
+ *      refused result here (its local builder, inline object and
+ *      `RenderRefusedOutput` alias are deleted — no shim); the
+ *      reference server supplies the kit's `refusalProjector` from the
+ *      same primitive at the kit's stringly boundary (a code off
+ *      `RENDER_GATE_REFUSAL_CODES` → `null`; anything else parsed by
+ *      `renderRefusalSchema`), so its six `refusal-envelope/*` rows are
+ *      GRADED, not skipped. The kit's own hand-built reference stays as
+ *      the second source that catches the primitive drifting.
+ *
+ * Conformance-kit verdict: no new kit entry — the six `refusal-envelope`
+ * cases already grade exactly these four facts; what changed is that
+ * two implementations now answer them through one function, and the
+ * reference server's exact-set assertion moved the rows from SKIPPED to
+ * PASSING. Bytes on the wire: unchanged.
+ *
+ * Package version — classification MADE here: MINOR for
+ * `@ggui-ai/protocol` (two new exports, additive) and for
+ * `@ggui-ai/mcp-server-handlers` (same result, one source), pre-1.0 and
+ * pre-launch. PROTOCOL_VERSION unchanged — no WS envelope moved.
+ *
+ * --------------------------------------------------------------------
+ * Authorization refusals carry JSON-RPC `data` (2026-09-05, additive,
+ * pre-launch, ggui#825). `@ggui-ai/mcp-server`'s per-app `authorize`
+ * hook refuses by throwing, and the route answered every throw with a
+ * bare `403 {code: -32000, message: "Forbidden"}` — correct in effect,
+ * illegible to a client that needs to tell "this app is no longer served" from
+ * "your credential is wrong".
+ *
+ *   ar1. **`ErrorMapperResult.data?: JsonValue`** — a deployment's
+ *      `errorMapper` may attach JSON-RPC 2.0 error `data` (any JSON
+ *      value) to a mapped result; serialized verbatim on `error.data`,
+ *      omitted when absent. Applies to every mapped error, not only
+ *      authorization refusals.
+ *
+ *   ar2. **The per-app authorization refusal consults the mapper**,
+ *      bounded to 401 / 403: a mapper answering any other status, or
+ *      throwing, is ignored and logged (`per_app_authorize_mapper_out_
+ *      of_bounds` / `error_mapper_failed` on the route logger) and the
+ *      default-deny 403 stands byte-identical to a deployment with no
+ *      mapper. The allow path never consults the mapper.
+ *
+ * Conformance-kit verdict: no kit entry required — an optional field on
+ * an operator-side hook result, no MCP tool name/shape touched; the
+ * shape of any `data.refusal` a deployment chooses to attach is that
+ * deployment's declaration, not this package's.
+ *
+ * Package version — classification MADE here: MINOR for
+ * `@ggui-ai/mcp-server` (new optional field on `ErrorMapperResult` +
+ * the authorization refusal path consults `errorMapper`), pre-1.0 and
+ * pre-launch. PROTOCOL_VERSION unchanged — no WS envelope moved.
+ * --------------------------------------------------------------------
  * Authored source rides blueprint reuse (2026-08-14, additive,
  * pre-launch). Cache-reuse renders (a repeated prompt semantic-matches
  * a cached blueprint) previously committed without authored
@@ -3121,15 +3190,6 @@
  *      reference and against the shipping projector in
  *      `@ggui-ai/mcp-server-handlers`) and `registry-completeness`
  *      (the registry's structural pins, bound to the LIVE registry).
- *
- * FOLLOWER — moves in the SAME commit as this constant, pinned by a
- * gate that fails loud when it lags: the `protocol` field of every
- * shipped `samples/gguis/<name>/ggui.json` (the `@ggui-ai/project-config`
- * samples test). That pin is a HOUSE rule — shipped samples declare the
- * CURRENT stamp, because a new project starts from them. The CONTRACT
- * for any `ggui.json#protocol` is membership in
- * `CLIENT_SUPPORTED_VERSIONS`, enforced by the loader (`UPGRADE_REQUIRED`
- * on a non-member); the two coincide only while the set is a singleton.
  *   r7. **Tool output shapes are protocol-owned (ggui#817 part C):**
  *      seven schemas — search / featured / validate / consume's
  *      host-context projection / list_sessions' summary / runtime_pull's
@@ -3146,6 +3206,44 @@
  *      grammar and nothing else, so `{}` still reaches the gate per r5); the
  *      full envelope (`renderInputEnvelopeSchema`) parses after the gate.
  *      Bare model ids are out.
+ *   r9. **Endpoint-level refusal (ggui#825):** registry surface
+ *      `mcp-endpoint` (v11) and the transport envelope — a per-app MCP
+ *      endpoint that refuses a request for a registry state answers HTTP
+ *      403 with `{ code: -32000, message: 'Forbidden', data: { refusal } }`
+ *      (`transportRefusalErrorSchema`; `refusal` = the projection without
+ *      the render-only fields, `MCP_ENDPOINT_REFUSAL_CODES` derived — today
+ *      `app_deprovisioned`). Untyped authorization failures keep the bare
+ *      403 by contract. Additive.
+ *   r10. **Consume / list_sessions / emit own their wire shapes (ggui#817
+ *      part C2):** `consumeEventEntrySchema` (the drained row, closed),
+ *      `gguiSessionStatusSchema` (`active` | `expired`), `gguiConsumeOutputSchema`,
+ *      `gguiListSessionsOutputSchema`, `gguiEmitOutputSchema`; the types
+ *      derive (`ConsumeEventEntry`, `GguiConsumeOutput`, `GguiEmitOutput`,
+ *      `GguiListSessionsOutput`, `GguiSessionStatus`). `tools/list` now
+ *      advertises the entry vocabulary and the status enum for
+ *      `ggui_consume`; `parsePendingEnvelope` parses a drained row instead
+ *      of casting it, so a malformed pipe entry refuses at the seam. The
+ *      wire bytes of a well-formed row are unchanged. Additive.
+ *   r11. **Endpoint refusal codes (ggui#836):** the per-app endpoint speaks
+ *      §7.9 Plane-1 rows — the typed deprovisioned arm is `-32003`
+ *      (`APP_NOT_FOUND`, `App not found`) with `data.refusal`; untyped
+ *      authorization failures are `-32001` (`UNAUTHORIZED`) with no
+ *      `data`; HTTP 403 on both. `-32000` (the SDK client's
+ *      `ConnectionClosed`) is never a code a first-party server chooses.
+ *      Supersedes r9's literals; pre-launch, no compatibility arm.
+ *   r12. **`GENERATION_OVERLOADED: -32014`** joins `PLATFORM_ERROR_CODES` —
+ *      the generation queue is saturated (HTTP 503 + `Retry-After`; the
+ *      server is the limit, unlike `-32013`). Additive; the four complete
+ *      mirrors carry it under `check-error-code-mirrors`.
+ *
+ * FOLLOWER — moves in the SAME commit as this constant, pinned by a
+ * gate that fails loud when it lags: the `protocol` field of every
+ * shipped `samples/gguis/<name>/ggui.json` (the `@ggui-ai/project-config`
+ * samples test). That pin is a HOUSE rule — shipped samples declare the
+ * CURRENT stamp, because a new project starts from them. The CONTRACT
+ * for any `ggui.json#protocol` is membership in
+ * `CLIENT_SUPPORTED_VERSIONS`, enforced by the loader (`UPGRADE_REQUIRED`
+ * on a non-member); the two coincide only while the set is a singleton.
  */
 export const PROTOCOL_VERSION = "draft-2026-09-04";
 /**
@@ -3163,8 +3261,32 @@ export const PROTOCOL_VERSION = "draft-2026-09-04";
  * `package.json#version` (the same parity pattern as
  * `STDLIB_GADGETS_VERSION` and `agent-server`'s `CLIENT_INFO`), and the
  * `/release:cut` straggler list names it so the bump is mechanical.
+ *
+ * Wave classifications (protocol seat; the kit is the arbiter,
+ * docs/protocol/VERSION-POLICY.md §1–2):
+ *
+ *   - **0.15.0 — MINOR** (ruled 2026-09-05). Every `@ggui-ai/protocol`
+ *     landing since the 0.14.0 cut (`f3cf6c906`) is additive under
+ *     §1.2: the `@ggui-ai/protocol/wire` browser entry (ggui#819), the
+ *     `GENERATION_OVERLOADED: -32014` canonical code and SPEC §7.9's
+ *     Plane 0 (ggui#840), `ErrorMapperResult.data` (ggui#825), the
+ *     endpoint-level refusal — `403 {code: -32003, data.refusal}` for
+ *     `app_deprovisioned` (ggui#836), the `ggui_consume` /
+ *     `ggui_list_sessions` / `ggui_emit` output schemas (ggui#817 C2),
+ *     and the `.readonly()` removal from the gadget wire schema
+ *     (ggui#824). The one non-additive-looking line — the untyped
+ *     authorization refusal moving from `-32000` to `-32001
+ *     UNAUTHORIZED` (ggui#836) — is not a fixture regression: no
+ *     fixture on 0.14.0 pinned `-32000` (it was the SDK's default
+ *     courtesy code, never a first-party choice; ggui#840's Plane-0
+ *     ruling), and the transport-refusal catalog now states `-32001`.
+ *     §1.4 (`draft-`: semver describes intent) applies on top. A
+ *     0.14.1 is legitimate ONLY as a founder-ruled hotfix branch off
+ *     `f3cf6c906` carrying ggui#846 alone (a declaration-emit fix —
+ *     PATCH under §1.3); it cannot be cut from main, whose delta since
+ *     0.14.0 is minor-class.
  */
-export const GGUI_WAVE_VERSION = "0.14.0";
+export const GGUI_WAVE_VERSION = "0.15.0";
 /**
  * Schema version stamped onto wire envelopes that opt into the
  * `schemaVersion` forward-compat field (see {@link ActionEnvelope},

package/dist/wire.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `@ggui-ai/protocol/wire` — the browser entry (ggui#819).
+ *
+ * What a renderer running inside an iframe validates and types against:
+ * the contract's shapes and their inference, the live-channel frames, the
+ * action envelope, the host-context projection, the reserved-channel
+ * guard, the interface-context snapshot, the invoke event, the permission
+ * grammar and the two limits the runtime shares with the server. Nothing
+ * a SERVER registers or validates — no tool input/output schema, no ops
+ * tool, no LLM route table, no contract zod schema — is reachable from
+ * here at runtime: a bundler cannot drop a module whose top level builds
+ * zod schemas, so the iframe pays for every module its entry reaches
+ * (`wire.test.ts` walks the graph and pins that). The root barrel keeps
+ * every name; this entry is the same names, fewer modules.
+ */
+export * from './types/contract-inference.js';
+export * from './types/data-contract.js';
+export * from './types/live-channel.js';
+export * from './types/render.js';
+export * from './types/invoke.js';
+export * from './types/events.js';
+export * from './types/ggui-session-event.js';
+export * from './types/host-context.js';
+export * from './types/interface-context.js';
+export * from './validation/contract-validator.js';
+export * from './validation/reserved-channels.js';
+export * from './validation/hygiene-rules.js';
+export * from './errors/unknown-permission-name.js';
+export * from './envelopes/builders.js';
+export * from './schemas/invoke.js';
+export * from './schemas/interface-context.js';
+export * from './schemas/runtime-telemetry-limits.js';
+export * from './schemas/public-env-key.js';
+export * from './version.js';
+export * from './schemas/data-contract.js';
+export * from './types/gadget.js';
+export * from './gadgets/stdlib-gadgets.js';
+export * from './gadgets/resolve-contract-gadgets.js';
+export * from './iframe-bridge.js';
+export type { ValidateFunction } from './validation/ajv-runtime.js';
+export type { AppTheme } from './schemas/app-theme.js';
+export type { AppDisplayConfig } from './types/app-config.js';
+export type { EndUserIdentity } from './types/auth.js';
+export type { GguiRuntimePullInput, GguiConsumeOutput, ConsumeEventEntry, GguiEmitOutput, GguiSessionStatus, } from './types/mcp.js';
+//# sourceMappingURL=wire.d.ts.map

package/dist/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../src/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kCAAkC,CAAC;AACjD,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,0BAA0B,CAAC;AACzC,cAAc,WAAW,CAAC;AAI1B,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,oCAAoC,CAAC;AAGnD,cAAc,iBAAiB,CAAC;AAChC,YAAY,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,aAAa,CAAC"}

package/dist/wire.js

@@ -0,0 +1,44 @@
+/**
+ * `@ggui-ai/protocol/wire` — the browser entry (ggui#819).
+ *
+ * What a renderer running inside an iframe validates and types against:
+ * the contract's shapes and their inference, the live-channel frames, the
+ * action envelope, the host-context projection, the reserved-channel
+ * guard, the interface-context snapshot, the invoke event, the permission
+ * grammar and the two limits the runtime shares with the server. Nothing
+ * a SERVER registers or validates — no tool input/output schema, no ops
+ * tool, no LLM route table, no contract zod schema — is reachable from
+ * here at runtime: a bundler cannot drop a module whose top level builds
+ * zod schemas, so the iframe pays for every module its entry reaches
+ * (`wire.test.ts` walks the graph and pins that). The root barrel keeps
+ * every name; this entry is the same names, fewer modules.
+ */
+export * from './types/contract-inference.js';
+export * from './types/data-contract.js';
+export * from './types/live-channel.js';
+export * from './types/render.js';
+export * from './types/invoke.js';
+export * from './types/events.js';
+export * from './types/ggui-session-event.js';
+export * from './types/host-context.js';
+export * from './types/interface-context.js';
+export * from './validation/contract-validator.js';
+export * from './validation/reserved-channels.js';
+export * from './validation/hygiene-rules.js';
+export * from './errors/unknown-permission-name.js';
+export * from './envelopes/builders.js';
+export * from './schemas/invoke.js';
+export * from './schemas/interface-context.js';
+export * from './schemas/runtime-telemetry-limits.js';
+export * from './schemas/public-env-key.js';
+export * from './version.js';
+// The gadget family: the stdlib hooks bundled into the iframe validate a
+// descriptor draft at runtime (`createGguiGadget`), so the contract-schema
+// module comes along — it is what the browser validates there.
+export * from './schemas/data-contract.js';
+export * from './types/gadget.js';
+export * from './gadgets/stdlib-gadgets.js';
+export * from './gadgets/resolve-contract-gadgets.js';
+// The iframe bridge vocabulary (`BRIDGE_EVENTS`) — what the RN WebView bridge
+// and the web runtime agree on; browser data, not a tool schema.
+export * from './iframe-bridge.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/protocol",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "sideEffects": [
     "./dist/schemas/sync-check.js",
     "./dist/validation/ajv-runtime.js"
@@ -78,6 +78,12 @@
       "require": "./dist/integrations/theme-binding.js",
       "default": "./dist/integrations/theme-binding.js"
     },
+    "./wire": {
+      "types": "./dist/wire.d.ts",
+      "import": "./dist/wire.js",
+      "require": "./dist/wire.js",
+      "default": "./dist/wire.js"
+    },
     "./version": {
       "types": "./dist/version.d.ts",
       "import": "./dist/version.js",