@ggui-ai/protocol 0.6.3 → 0.8.0

package/dist/version.js

@@ -6,6 +6,278 @@
  * schema change; the most recent change anchors {@link PROTOCOL_VERSION}.
  *
  * --------------------------------------------------------------------
+ * MCP tool bindings & discovery (2026-08-10, additive, pre-launch,
+ * ggui#259). Artifacts gain an optional MCP tool-binding list and
+ * registry search gains a tool dimension, connecting the two
+ * namespaces the registry serves: signed UI artifacts and the MCP
+ * tools they render. SPEC §7.7.4.1 is the normative home.
+ *
+ *   tb1. **`mcpTools` on both manifest kinds**
+ *      (`@ggui-ai/artifact-manifest`): 1–16 `{server?, tool}`
+ *      entries, charset `/^[A-Za-z0-9_.-]{1,128}$/`,
+ *      exact-duplicate `(server, tool)` pairs rejected with the
+ *      existing `manifest_invalid` code. Declared wins entirely;
+ *      a blueprint without the field derives bare `{tool}` entries
+ *      from the union of its contract's per-prop `sourceTool` and
+ *      `streamSpec` `source.tool` names (`resolveMcpToolBindings`,
+ *      marked `derived`). Bindings are search metadata only — they
+ *      never enter contract canonicalization or `blueprintKey`.
+ *      NOTE: manifest schemas are strict-rooted, so an OLDER
+ *      manifest parser REJECTS a manifest file carrying the field —
+ *      the optionality guarantee below is wire-response-scoped
+ *      (search/read), not manifest-file-scoped.
+ *
+ *   tb2. **Registry wire additions** (`@ggui-ai/registry-core`),
+ *      all optional: `SearchResultEntry` += `mcpTools?`,
+ *      `mcpToolsSource?: 'declared' | 'derived'`,
+ *      `scopeVerification?: 'verified' | 'unverified'`,
+ *      `verifiedDomain?`; the single-version read response += the
+ *      same two verification fields; search input += `tool?` /
+ *      `server?` exact filters (AND-composed with the existing
+ *      filters, `matchesMcpToolFilters` semantics; an invalid
+ *      charset value is the existing `invalid_request` 400).
+ *      Pre-existing consumers see `undefined` and behave as before.
+ *
+ *   tb3. **Agent surface** (`@ggui-ai/mcp-server-handlers`):
+ *      `ggui_search_blueprints` gains an opt-in `registry` source
+ *      merged after the local sources; unreachable / timeout /
+ *      unparseable-body answers degrade typed —
+ *      `degradedSources: [{source: 'registry', reason:
+ *      'unreachable' | 'timeout' | 'invalid_response'}]` — never a
+ *      tool failure, never a thrown error.
+ *
+ * Conformance-kit verdict: additive, minor-intent while `draft-`,
+ * so PROTOCOL_VERSION is unchanged — no WS envelope moved; the
+ * change is confined to the manifest, registry HTTP, and MCP
+ * tool-result surfaces. The new `binding-conformance` catalog in
+ * `@ggui-ai/protocol-conformance` (`runBindingResolutionCases` /
+ * `runBindingFilterCases`) arbitrates resolution precedence and
+ * filter semantics; search/read response optionality is pinned by
+ * registry-core unit tests, because the strict-rooted manifest
+ * schema makes a manifest-file optionality fixture false (tb1).
+ *
+ * Package version — the classification is MADE here, not deferred:
+ * MINOR for the `@ggui-ai/*` wave, additive under the version
+ * policy's minor rule (every fixture that passed against the
+ * current wave still passes; the delta is new surface), pre-1.0
+ * and pre-launch. FOUR packages carry minor-class changes into
+ * that wave — `@ggui-ai/artifact-manifest` (the field + resolver),
+ * `@ggui-ai/registry-core` (wire + filters),
+ * `@ggui-ai/mcp-server-handlers` (the registry source), and
+ * `@ggui-ai/protocol-conformance` (the catalog that decides them).
+ * Only the mechanical write is deferred: every `@ggui-ai/*`
+ * package carries ONE wave version, so the release owner takes all
+ * four bumps together at the next wave cut.
+ * --------------------------------------------------------------------
+ * Typed `resources/read` failures (2026-08-09, additive, pre-launch,
+ * ggui#430). A read of a render locator
+ * (`ui://ggui/render/{sessionId}/{blueprintKey}`) gains a closed failure
+ * union and a canonical JSON-RPC number, so the read has exactly two
+ * exits: a live mount, or a typed error. Before this, an unresolvable
+ * read returned a SUCCESS-shaped result carrying a loading shell that
+ * would never come alive — the same class of defect ruling B fixed for
+ * `ggui_render`, on the resource surface instead of the tool surface.
+ *
+ *   rr1. **New closed enum `ResourceReadErrorCode`** = NOT_FOUND |
+ *      BLUEPRINT_UNRESOLVABLE | NOT_SUPPORTED | NOT_MOUNTABLE, with
+ *      `resourceReadErrorSchema {code, message, detail?}`. Deliberately
+ *      NOT an extension of `renderErrorCodeSchema` (rb2): that enum
+ *      classifies a `ggui_render` tool call that ran and failed and
+ *      rides IN the tool result; this one classifies a resource read
+ *      and rides ON a JSON-RPC error. Two surfaces, two closed enums,
+ *      same UPPER_SNAKE house style.
+ *
+ *   rr2. **`-32006 MOUNT_UNAVAILABLE` claimed** — the first draw from
+ *      the `-32006` onwards range that rb4 reserved when it retired
+ *      `-32004`. The next free canonical slot is `-32007`. It covers
+ *      BLUEPRINT_UNRESOLVABLE / NOT_SUPPORTED / NOT_MOUNTABLE.
+ *      Deliberately NOT `INTERNAL_ERROR`: a component that is gone, a
+ *      server that keeps no durable record, and a render with no
+ *      delivery channel are all deterministic outcomes of a correctly
+ *      functioning server, and `-32603` would report a malfunction and
+ *      invite a retry that cannot succeed. The fine-grained class rides
+ *      on `error.data.code`.
+ *
+ *   rr3. **NOT_FOUND maps to `-32002`**, which MCP uses for a missing
+ *      resource and which this table already assigns to a missing
+ *      session — for a locator keyed by `sessionId` those are one
+ *      condition, not two.
+ *
+ *   rr4. **NOT_FOUND carries a CONSTANT body.** The mapper substitutes
+ *      a fixed message and drops `detail`, so a read refused by the
+ *      authorization check and a read of a locator that never existed
+ *      are byte-identical on the wire. Anything that varies between the
+ *      two makes the read an existence oracle for other callers'
+ *      renders. The mapper closes the message half; the ordering half
+ *      is a server obligation — a branch whose outcome VARIES WITH THE
+ *      LOCATOR MUST NOT run before the authorization check, because
+ *      reaching one tells the caller the locator resolved for somebody.
+ *      A deployment-global answer is not such a branch: NOT_SUPPORTED
+ *      is identical for every locator on the server that emits it, so
+ *      answering it early discloses nothing. (Scoped this way in the
+ *      same slice the conformance catalog landed, which grades the
+ *      indistinguishability the rule exists to produce and deliberately
+ *      does not grade ordering. The unscoped form would have declared
+ *      a correct substrate-less server non-conformant.)
+ *
+ *   rr5. **A read that cannot mount is now an ERROR, not a
+ *      success-shaped shell.** This is the observable wire change, and
+ *      it is what rr1–rr4 exist to give a shape to. Every failure
+ *      branch of the render-locator read used to return a result whose
+ *      `contents` carried a loading shell — a page that waited forever
+ *      for a render that was never coming. Those branches now throw,
+ *      and the transport serializes them as the JSON-RPC errors above;
+ *      the shell builder behind them is DELETED rather than left
+ *      unreferenced, so no branch can produce one. Reads that CAN
+ *      mount are unchanged byte for byte. A host that treated any
+ *      successful read as mountable was right only by accident and is
+ *      now right by construction; a host that never handled the error
+ *      exit at all now has one to handle. The invariant this buys is
+ *      the whole point: any successful `contents` result IS a live
+ *      mount.
+ *
+ * Conformance-kit verdict: additive, minor-intent while `draft-`, so
+ * PROTOCOL_VERSION is unchanged — no WS envelope moved, and the change
+ * is confined to the MCP resource surface (same reasoning as rb's stamp
+ * adjudication).
+ *
+ * The kit arbitrates this surface now. `resource-read-conformance` in
+ * `@ggui-ai/protocol-conformance` binds the `resources/read` method:
+ * `runResourceReadConformance()` drives an adopter-supplied scenario
+ * driver through a 12-case catalog and grades the two numbers (rr1–rr3),
+ * the closed classification on `error.data.code`, NOT_FOUND's absent
+ * `detail` and constant message (rr4), the refused-equals-missing byte
+ * identity across every server shape, and rr5's invariant on a live row
+ * and a re-minted one alike. What it does NOT arbitrate is `tools/call`:
+ * no driver is bound to that method, so the `ggui_consume` and
+ * `ggui_emit` obligations stay kit-invisible and this entry closes
+ * nothing for them.
+ *
+ * Because that catalog exists and ships, the package-version decision
+ * below is stated outright rather than made conditional on a driver
+ * that has yet to arrive.
+ *
+ * Five things stay ungraded on purpose and MUST NOT be read as
+ * obligations: the ORDER in which a substrate-less server answers
+ * NOT_SUPPORTED; `detail` wording on any code; the NOT_FOUND message
+ * literal (its constancy is the obligation, not its prose); `-32603`
+ * message text; and the NUMBER a URI naming no locator receives —
+ * including negatively, since MCP itself assigns the resource-missing
+ * number to a read of a URI a server does not serve, and banning it
+ * would make every framework that leans on that assignment
+ * non-conformant. On that last one the law is classification-only:
+ * such a URI MUST NOT carry one of the four codes on `error.data.code`.
+ *
+ * Package version — the classification is MADE here, not deferred.
+ * The resource-read surface and the new canonical code are a MINOR for
+ * the `@ggui-ai/*` wave: additive under the version policy's minor rule
+ * (every fixture that passed against the current wave still passes; the
+ * delta is new surface), pre-1.0 and pre-launch. TWO packages carry
+ * minor-class changes into that wave — `@ggui-ai/protocol` (the closed
+ * enum, the canonical number, the projection) and
+ * `@ggui-ai/protocol-conformance` (the catalog that decides them).
+ *
+ * What is deferred is only the mechanical write. Every `@ggui-ai/*`
+ * package carries ONE wave version, and a wave cut moves all of them to
+ * it in a single commit — no package's number can move on its own — so
+ * the release owner takes both bumps together at the next cut. One
+ * deferral, one owner, two named packages. Nothing about what the
+ * change IS remains open.
+ *
+ * #457 (2026-08-10): the substrate stores' `durability` declaration —
+ * a MINOR surface that SHIPPED IN 0.7.0 (the wave was published from
+ * main after it landed; an earlier revision of this note deferred it
+ * to the next cut, which the publish overtook). `@ggui-ai/mcp-server-core`
+ * adds a required member to three published ports (pre-launch
+ * no-compat: every in-tree impl moved in the same slice; out-of-tree
+ * implementors add one literal) and `@ggui-ai/protocol-conformance`
+ * adds the `all-ephemeral` wiring arm + its fusion case (additive —
+ * the catalog's public-API additive-only rule holds; the SPEC §7.10.4
+ * amendment defines "durable" as declared, which was previously
+ * undefined, not different).
+ *
+ * On the kit's half, one thing is worth saying plainly rather than
+ * calling its delta "purely additive": `parseCase` rejects unknown
+ * keys, so a case file with a typo'd key throws instead of being
+ * quietly ignored. That strictness is free on a sub-module with no
+ * prior published version — nothing can be built against it yet — but
+ * extending it over the existing fixture catalog would be a MAJOR, not
+ * a minor, and must be adjudicated as one.
+ *
+ * #471 (2026-08-10): the fetch-free delivery surface — a MINOR for the
+ * `@ggui-ai/protocol` wave, deferred to the next cut under the same
+ * one-wave-version rule as above. Three additive pieces, one shared
+ * motivation (hosts whose iframe CSP forbids every URL-scheme load
+ * while permitting inline scripts):
+ *
+ *   if1. **`McpAppAiGguiRenderMeta.codeB64`** — optional base64
+ *      compiled component source, the fetch-free twin of `codeUrl`
+ *      (coexists with it; exclusive with `kind`). Every envelope that
+ *      parsed before parses identically; the parser's new rejection
+ *      arm (`codeB64` + `kind` both set) rejects a shape no producer
+ *      ever emitted. `hasMountModeDiscriminator` widens PERMISSIVELY
+ *      (a codeB64-only slice becomes mountable — previously
+ *      undefined, not different).
+ *
+ *   if2. **`GguiShellHtmlOptions.runtimeInlineSource` +
+ *      `escapeInlineScript`** — host-helper additions; the default
+ *      (external `<script src>`) emission is byte-unchanged.
+ *
+ *   if3. Consumer-side: `@ggui-ai/design` gains the inline-exec
+ *      module (new exports only); `@ggui-ai/mcp-server` gains the
+ *      `mcpApps.inlineRuntimeShell` opt-in (default OFF — the served
+ *      static shell is byte-unchanged for every existing mount) and
+ *      `registerGguiRenderResource` gains a trailing optional
+ *      CSP-fallback parameter (existing positional calls unchanged).
+ *
+ * Conformance-kit verdict: no fixture pins the render slice's closed
+ * field set (the slice is verbatim-carry by design — the host-helper
+ * suite's "unknown future fields ride along" case is the governing
+ * posture), so the additive field breaks nothing. PROTOCOL_VERSION
+ * unchanged — no wire frame changed shape.
+ *
+ * --------------------------------------------------------------------
+ * Credential-broker surface retired (2026-08-08, BREAKING, pre-launch,
+ * ggui#436). The `system` frame's auth vocabulary and the
+ * `ggui_request_credential` tool leave the protocol entirely.
+ * Credential ceremony for an agent's own MCP tools is the AGENT HOST's
+ * responsibility — it owns the runtime, the user relationship, and the
+ * consent chrome. ggui's wire deliberately carries no auth frames.
+ *
+ *   rc1. **`SystemPayload` / `SystemAction` deleted**, and `'system'`
+ *      leaves `WebSocketMessageType` + the `WebSocketMessage` union.
+ *      The vocabulary was `auth_required` / `credential_ready` and
+ *      nothing else — with the broker gone there is no other action to
+ *      carry, so the frame class dies with it rather than surviving as
+ *      an empty discriminator.
+ *
+ *   rc2. **`requestCredentialInputSchema` /
+ *      `requestCredentialInputShape` / `GguiRequestCredentialInput` /
+ *      `GguiRequestCredentialOutput` deleted.** The only handler that
+ *      ever implemented the tool (the hosted pod's
+ *      `tools/request-credential.ts`) was deleted the day before in
+ *      the same issue: it pushed its consent overlay through an API
+ *      Gateway WebSocket leg the pod never had, so the tool could not
+ *      function. `ggui_request_credential` is appended to the
+ *      mcp-server RETIRED_TOOL_NAMES regression lock.
+ *
+ *   rc3. **Client lanes deleted, not stubbed.** `@ggui-ai/react`'s
+ *      `GguiRenderProps.onSystemMessage` (+ its dispatch arm),
+ *      `@ggui-ai/iframe-runtime`'s `channels/system.ts` handler and
+ *      its `auth-required` `ObservabilityEvent` arm
+ *      (`AuthRequiredEvent`), and both SDKs' `SystemPayload` /
+ *      `SystemAction` re-exports go. The observability event was a
+ *      projection of `SystemPayload` — with no payload to project it
+ *      has no producer.
+ *
+ * Conformance-kit verdict: no kit fixture asserted the `system` frame
+ * and no first-party server ever emitted one (the pod's broker was the
+ * only would-be emitter and it was pre-transport dead) — same posture
+ * as the 2026-07-27 dead-vocabulary entry. PROTOCOL_VERSION unchanged;
+ * rolling it would force a lockstep UPGRADE_REQUIRED break on every
+ * pinned client to version a frame class that never flew.
+ *
+ * --------------------------------------------------------------------
  * Ops-tool console-parity slice (2026-07-29, BREAKING on the ops
  * surface only, pre-launch, ggui#400). Rename ledger — same treatment
  * as the `ggui_ops_register_blueprint` → `ggui_ops_save_library_blueprint`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/protocol",
-  "version": "0.6.3",
+  "version": "0.8.0",
   "description": "ggui protocol types — events, renders, WebSocket, MCP, LLM models",
   "license": "Apache-2.0",
   "keywords": [