@ggui-ai/protocol 0.7.0 → 0.9.0

package/dist/version.js

@@ -6,6 +6,69 @@
  * 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
@@ -141,6 +204,188 @@
  * 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.
+ *
+ * SSE middle rung (2026-08-11): the failover-ladder stream surface — a
+ * MINOR for the `@ggui-ai/protocol` wave, deferred to the next cut
+ * (≥ 0.9.0) under the same one-wave-version rule as above. Two
+ * additive pieces, one motivation (hosts whose CSP blocks WebSocket
+ * but permits `EventSource`, giving the ladder a live middle rung
+ * between WS and cursor polling):
+ *
+ *   sm1. **`McpAppAiGguiRenderMeta.sseUrl`** — optional server-stamped
+ *      `/api/sessions/<sessionId>/stream?wsToken=<token>` URL beside
+ *      `pollingUrl`. Every envelope that parsed before parses
+ *      identically (tolerant scalar posture, no pairing invariant —
+ *      the URL is self-authorizing via its embedded token). Absent ⇒
+ *      no SSE rung; the ladder is WS → polling. The stream contract
+ *      the URL points at (ChannelFrame-per-`data:`-line byte-same as
+ *      the WS push, `id:` = ledger seq on replay frames only,
+ *      `: hb` comment heartbeat ≤ ~25s, `retry: 3000` first write,
+ *      `Last-Event-ID` over `?sinceSequence=`, 401/404/410 mirroring
+ *      `/events`) is pinned on the interface docstring.
+ *
+ *   sm2. **`composeSessionApiUrls` + `SessionApiUrls`** — the ONE
+ *      pure composer every stamping surface (render/update resultMeta,
+ *      self-contained shell, `/state` bootstrap) routes both URLs
+ *      through — the `deriveRenderMeta` move applied to channel URLs.
+ *      New exports only. This REPAIRS a confirmed drift: `/state` used
+ *      to stamp an unconditional token-less `/state`-shaped
+ *      pollingUrl that could only 401 through the events composer;
+ *      both URLs now stamp ONLY when the live trio is minted, and
+ *      omission is the honest no-HTTP-fallback signal.
+ *
+ * Conformance-kit verdict: same posture as if1 — no fixture pins the
+ * render slice's closed field set (verbatim-carry by design), so the
+ * additive field breaks nothing. Full SSE endpoint conformance cases
+ * are a FLAGGED follow-up (unit tests ride this slice; conformance
+ * ticket after launch — No Silent Block). PROTOCOL_VERSION unchanged —
+ * no WS envelope moved; the SSE `data:` line reuses the ChannelFrame
+ * shape byte for byte.
+ *
+ * --------------------------------------------------------------------
+ * Bridge-pull terminal rung (2026-08-11): `ggui_runtime_pull` — a
+ * MINOR for the `@ggui-ai/protocol` wave, riding the same next cut
+ * (≥ 0.9.0) as the SSE entry above. One motivation: hosts whose CSP
+ * blocks EVERY network API from the iframe (claude.ai's srcdoc
+ * sandbox) can still pull the event ledger over the host's
+ * `tools/call` postMessage bridge — the fourth and terminal rung of
+ * the failover ladder (WS → SSE → HTTP polling → bridge-pull).
+ *
+ *   bp1. **`runtimePullInput/OutputSchema` + `GguiRuntimePullInput/
+ *      Output`** — new tool contract, output byte-parity with the
+ *      `/events` route (`EventsResponse` page arm |
+ *      `REPLAY_HORIZON_PASSED` arm as a NORMAL result) so ONE client
+ *      parse core serves both carriers. `_meta.ui.visibility: ['app']`
+ *      restricts callers to MCP Apps views per spec §401.
+ *
+ *   bp2. **`wait` + `RUNTIME_PULL_MAX_WAIT_SECONDS`** — the
+ *      subscription-mode hold: an empty cursor page holds the call
+ *      server-side (≤ 20s, under `ggui_consume`'s proven 25s host
+ *      tolerance) until an event lands. Back-to-back held single-shots
+ *      emulate push through a request/response-only bridge; clients
+ *      demote to sparse un-held pulls after consecutive empty holds.
+ *
+ * Conformance-kit verdict: additive tool, no existing fixture touches
+ * it; bridge-carrier conformance cases join the SSE follow-up ticket
+ * (No Silent Block). PROTOCOL_VERSION unchanged — no WS envelope
+ * moved; the ledger event vocabulary gained active use of the
+ * existing `'ui.updated'` taxonomy member (`ggui_update` now appends
+ * it), not a new member.
+ *
+ * --------------------------------------------------------------------
+ * React/RN SDK-surface retirement (2026-08-13, owner ruling; rides
+ * the same next cut ≥ 0.9.0): `@ggui-ai/react` + `@ggui-ai/react-
+ * native` are MCP Apps HOST-HELPER libraries, not SDKs — embeds mount
+ * views via the spec path (`AppRenderer` / RN `McpAppIframe`) and get
+ * runtime semantics (freeze latch, crash card, epochs) from the
+ * mounted iframe itself. Deleted from `@ggui-ai/react`: `GguiRender`
+ * + its WS stack (`useWebSocket`, `WebSocketManager`, `EventBuffer`,
+ * reserved-validators), local `ThemeProvider`, `SelfRepairBoundary`
+ * family, `AgentBrowsePanel`, the dead wire-type re-exports, the
+ * public `useGguiContext`/`useAdapter`/`AdapterRegistry` barrel
+ * entries (impls stay internal), and `chat-thread/**` (both
+ * packages — third-party chat framework, zero consumers; guuey built
+ * `@guuey/threads` instead). RN's direct-render family was already
+ * deleted pre-ruling (#425, 7d5c6955b). Zero-consumer adversarially
+ * traced per export before deletion; guuey pins both packages at
+ * 0.6.3 (npm-immutable — installs unaffected; handoff note per the
+ * deletion discipline). Breaking TS-API shrink, 0.x MINOR carries it.
+ * SAME-DAY RENAME RULING: the packages republish at this cut as
+ * `@ggui-ai/mcp-apps-react` / `@ggui-ai/mcp-apps-react-native` —
+ * the names must say "MCP Apps bindings," not "SDK." Old names get
+ * `npm deprecate` + pointer at cut time (owner click, OTP; new names
+ * need Trusted Publishing setup — see release:cut).
+ *
+ * --------------------------------------------------------------------
+ * Mutation tool split + epoch history (2026-08-13, ggui#481→#483,
+ * SUPERSEDES the same-night renderAsNew param design, which never
+ * reached a cut): a MINOR for the `@ggui-ai/protocol` wave, riding
+ * the same next cut (≥ 0.9.0). One motivation arc: hosts mint
+ * per-result views from result shape, so mutation results must be
+ * either complete mount packages or carry nothing — and once every
+ * update result is a durable record, the records ARE a history.
+ *
+ *   ts1. **`ggui_amend`** — new tool: in-place mutation of the
+ *      mounted card. Same replace/merge grammar as update
+ *      (`amendInputSchema`/`amendOutputSchema` + inferred types); NOT
+ *      UI-bound, results carry NO `_meta` under any outcome; the
+ *      history epoch is untouched by construction. Additive.
+ *
+ *   ts2. **`ggui_update` semantics change, stated plainly:** every
+ *      real update now mints a NEW history record — output gains
+ *      mandatory `epoch` and its `resourceUri` is the epoch-PINNED
+ *      URI (`…#N`); the result `_meta` is unconditionally the full
+ *      bootable mount package (#481). `renderAsNew` is deleted from
+ *      both arms. A consumer that treated update results as in-place
+ *      acknowledgements sees new cards; the in-place path moved to
+ *      ggui_amend. Pre-launch no-compat; the kit is the arbiter and
+ *      update-family conformance cases ship IN THIS SLICE (epoch
+ *      immutability, head aliasing, amend-mints-nothing), closing the
+ *      previously flagged gap.
+ *
+ *   ts3. **Epoch surfaces:** `GguiSessionBase.epoch` +
+ *      `McpAppsGguiSession.epoch` (optional, absent ⇒ 0 — the row is
+ *      the authority; the ledger is horizon-bounded); `'ui.reminted'`
+ *      joins the ledger taxonomy with `UiRemintedEventData`;
+ *      `UiUpdatedEventData` types the props event (now epoch-stamped);
+ *      `composeEpochUri`/`parseEpochUri` (the ONE encoding seam —
+ *      fragment today, flippable post-host-probe);
+ *      `deriveEpochFromEvents` (in-horizon reconstruction only).
+ *      SPEC §7.1.2/§7.1.2.1/§7.1.2.2 are the normative text.
+ *
+ *   ts4. **Live-fan epoch obligation (2026-08-13 follow-up, same
+ *      wave):** `PropsUpdatePayload.epoch` (`@ggui-ai/protocol`
+ *      live-channel, optional on the wire) is the freeze-latch signal,
+ *      and servers MUST stamp live `props_update` frames with the
+ *      COMMIT-TIME epoch (SPEC §7.1.2.2). TS API surfaces moved with
+ *      it: `PropsUpdateNotifier.sendPropsUpdate` gains a required
+ *      `epoch` third param (`@ggui-ai/mcp-server-handlers`), as does
+ *      `GguiSessionChannelServer.sendPropsUpdate`
+ *      (`@ggui-ai/mcp-server`) — 2-arg callers break at compile time
+ *      (pre-launch no-compat; 0.x MINOR carries it). Motivating
+ *      incident: a second notifier impl (cloud pod) omitted the then-
+ *      optional field and shipped epoch-less frames — the latch
+ *      degraded to legacy-apply exactly as designed for skew, which
+ *      is also the compat story: old runtime × new server ignores the
+ *      extra field; new runtime × old server sees no epoch and
+ *      applies as before. Graceful both directions.
+ *
+ * PROTOCOL_VERSION unchanged — no WS frame changed shape; the
+ * `ai.ggui/render` slice's field set was never closed, and the
+ * `ui.updated` / `props_update` payloads gained an optional field on
+ * open payload surfaces.
+ *
  * --------------------------------------------------------------------
  * Credential-broker surface retired (2026-08-08, BREAKING, pre-launch,
  * ggui#436). The `system` frame's auth vocabulary and the

package/package.json

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