@ggui-ai/protocol 0.8.0 → 0.9.0

package/dist/schemas/mcp.d.ts

@@ -316,7 +316,7 @@ export declare const renderCacheMarkerSchema: z.ZodObject<{
 /**
  * Canonical failure codes for the in-result `ggui_render` failure
  * envelope (SPEC §7.9 Plane 3). Closed enum — a failed render's
- * `error.code` is always one of these four; finer-grained diagnostics
+ * `error.code` is always one of these five; finer-grained diagnostics
  * ride on `error.message`.
  *
  *   - `PRODUCTION_FAILED` — generation ran but did not produce a
@@ -328,12 +328,21 @@ export declare const renderCacheMarkerSchema: z.ZodObject<{
  *     configuration has no key for the resolved route.
  *   - `NO_CREDENTIALS` — no generation credentials are configured on
  *     the server at all.
+ *   - `GENERATION_QUEUE_OVERLOADED` — the deployment's generation
+ *     admission gate rejected this request before any generation
+ *     attempt started (concurrent-request queue full, or wait for a
+ *     free slot exceeded the configured timeout). Distinct from
+ *     `PRODUCTION_FAILED` by design: generation never ran, so callers
+ *     MUST NOT bill or count it as a failed attempt. See
+ *     {@link GenerationError} in `types/ui-generator.ts` for the full
+ *     contract.
  */
 export declare const renderErrorCodeSchema: z.ZodEnum<{
     PRODUCTION_FAILED: "PRODUCTION_FAILED";
     VALIDATION_ERROR: "VALIDATION_ERROR";
     NO_PLATFORM_KEY: "NO_PLATFORM_KEY";
     NO_CREDENTIALS: "NO_CREDENTIALS";
+    GENERATION_QUEUE_OVERLOADED: "GENERATION_QUEUE_OVERLOADED";
 }>;
 /**
  * In-result failure marker for `ggui_render`. Present on the wire
@@ -347,6 +356,7 @@ export declare const renderErrorSchema: z.ZodObject<{
         VALIDATION_ERROR: "VALIDATION_ERROR";
         NO_PLATFORM_KEY: "NO_PLATFORM_KEY";
         NO_CREDENTIALS: "NO_CREDENTIALS";
+        GENERATION_QUEUE_OVERLOADED: "GENERATION_QUEUE_OVERLOADED";
     }>;
     message: z.ZodString;
 }, z.core.$strip>;
@@ -458,6 +468,7 @@ export declare const renderOutputSchema: z.ZodObject<{
             VALIDATION_ERROR: "VALIDATION_ERROR";
             NO_PLATFORM_KEY: "NO_PLATFORM_KEY";
             NO_CREDENTIALS: "NO_CREDENTIALS";
+            GENERATION_QUEUE_OVERLOADED: "GENERATION_QUEUE_OVERLOADED";
         }>;
         message: z.ZodString;
     }, z.core.$strip>>;
@@ -467,6 +478,7 @@ export declare const renderOutputSchema: z.ZodObject<{
         example: z.ZodString;
         args: z.ZodObject<{
             sessionId: z.ZodString;
+            timeout: z.ZodNumber;
         }, z.core.$strip>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -510,21 +522,55 @@ export declare const updateInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"merge">;
     patch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strict>], "kind">;
+/**
+ * `ggui_amend` wire input (#483) — same replace/merge mutation
+ * grammar as `ggui_update`, different mount identity: amend targets
+ * the ALREADY-MOUNTED card. No new card, no history entry, the
+ * history number does not advance. Git reading: `ggui_update` =
+ * commit; `ggui_amend` = commit --amend.
+ */
+export declare const amendInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    sessionId: z.ZodString;
+    kind: z.ZodLiteral<"replace">;
+    props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>, z.ZodObject<{
+    sessionId: z.ZodString;
+    kind: z.ZodLiteral<"merge">;
+    patch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>], "kind">;
 /**
  * Wire-output shape — minimal acknowledgement. The handler carries
  * `decision`, `contract`, `contractHash` on its internal `UpdateOutput`
  * TS shape — zod strips them before structuredContent serialization.
  *
- * Post-update the iframe receives the new props via the live-channel
- * `props_update` WS frame; the cross-host fallback path receives them
- * via the `ai.ggui/render.propsJson` slice field (see
- * `update.resultMeta`). The wire response itself is just
- * acknowledgement.
+ * Every REAL update (`updated: true`) mints a new history record and
+ * its result carries the `ai.ggui/render` slice as a FULL bootable
+ * mount package (#483 — hosts mint a per-result view for the new
+ * card); a no-op (`updated: false`) carries NO result `_meta`.
+ * Already-mounted frames are not repainted by update — they freeze as
+ * history when its higher-epoch `props_update` frame lands; the
+ * in-place repaint over the live-channel ladder (WS / SSE / polling /
+ * bridge-pull) is `ggui_amend`'s job.
  */
 export declare const updateOutputSchema: z.ZodObject<{
     sessionId: z.ZodString;
     updated: z.ZodBoolean;
     resourceUri: z.ZodString;
+    epoch: z.ZodNumber;
+    warning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * `ggui_amend` wire output (#483) — acknowledgement only. `resourceUri`
+ * is the BARE live-head URI (amend targets the mounted card; it never
+ * mints a record, so there is no pinned URI to return and no epoch
+ * field — the history number is untouched by construction). The
+ * mounted card receives the new props over the live channels.
+ */
+export declare const amendOutputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    updated: z.ZodBoolean;
+    resourceUri: z.ZodString;
+    warning: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /**
  * `ggui_runtime_declare_tool_catalog` — the host runtime declares its
@@ -560,4 +606,170 @@ export declare const declareToolCatalogOutputSchema: z.ZodObject<{
     saved: z.ZodBoolean;
     appId: z.ZodString;
 }, z.core.$strict>;
+/**
+ * Server-side page cap for `ggui_runtime_pull`. A `limit` above this is
+ * CLAMPED (not rejected) — the tool mirrors the cursor-walk posture of
+ * the `/events` HTTP route, where a too-eager page size is a tuning
+ * knob, not a caller bug. Shared so the pulling client and the serving
+ * handler agree on the effective page ceiling from one constant.
+ */
+export declare const RUNTIME_PULL_MAX_LIMIT = 100;
+/**
+ * Server-side ceiling on `ggui_runtime_pull`'s `wait` hold, in seconds.
+ * Chosen under `ggui_consume`'s proven 25-second host tolerance for
+ * held tool calls — the hold must resolve before any host-side
+ * `tools/call` timeout fires, or the transport counts a failure the
+ * server intended as a quiet success.
+ */
+export declare const RUNTIME_PULL_MAX_WAIT_SECONDS = 20;
+/**
+ * One `GguiSessionEvent` ledger row on the `ggui_runtime_pull` wire —
+ * the zod mirror of the canonical `GguiSessionEvent` interface in
+ * `types/ggui-session-event.ts` (which stays the type-level source of
+ * truth; `mcp.test.ts` pins the two together in both directions).
+ */
+export declare const gguiSessionEventSchema: z.ZodObject<{
+    seq: z.ZodNumber;
+    type: z.ZodString;
+    timestamp: z.ZodString;
+    data: z.ZodUnknown;
+}, z.core.$strip>;
+/**
+ * `ggui_runtime_pull` input — the terminal bridge-pull rung of the
+ * live-channel failover ladder (WS → SSE → HTTP polling → bridge-pull).
+ *
+ * Two named parties:
+ *
+ *   - **Puller** — the `@ggui-ai/iframe-runtime` bridge rung. In a
+ *     CSP-jailed MCP Apps host the iframe can reach no network origin
+ *     at all, so it pulls the event ledger by issuing `tools/call`
+ *     postMessages that the host's MCP client relays (the tool
+ *     registers `_meta.ui.visibility: ['app']` per MCP Apps spec §401
+ *     — hosts MUST route view-issued calls to it and MUST reject
+ *     view-issued calls to tools without it).
+ *   - **Server** — the MCP server hosting the render. It serves the
+ *     SAME `GguiSessionEvent` ledger `GET
+ *     /api/sessions/:sessionId/events` serves, through the same
+ *     `listEventsSince` read, and MUST answer with the same shapes
+ *     (see {@link runtimePullOutputSchema}) so one client parse core
+ *     handles both carriers.
+ *
+ * Divergences from the HTTP route, both deliberate: `sinceSequence` is
+ * OPTIONAL here (the bridge rung owns its cursor and seeds from 0; the
+ * route requires it because a bare browser GET has no cursor owner),
+ * and `limit` is clamped to {@link RUNTIME_PULL_MAX_LIMIT} instead of
+ * rejecting above it. Tenancy violations and unknown sessionIds
+ * surface uniformly as the `session_not_found` error — existence of
+ * other tenants' renders is never leaked.
+ */
+export declare const runtimePullInputShape: {
+    readonly sessionId: z.ZodString;
+    readonly sinceSequence: z.ZodOptional<z.ZodNumber>;
+    readonly limit: z.ZodOptional<z.ZodNumber>;
+    readonly wait: z.ZodOptional<z.ZodNumber>;
+};
+export declare const runtimePullInputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    sinceSequence: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    wait: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Normal-page arm — EXACT `EventsResponse` parity with
+ * `GET /api/sessions/:sessionId/events` (same keys, same semantics):
+ * `events` strictly ascending by seq, `lastSequence` = the render's
+ * current high-water mark (NOT the page's last seq — advances the
+ * cursor on empty pages), `hasMore` = the page was truncated by
+ * `limit`.
+ */
+export declare const runtimePullEventsPageSchema: z.ZodObject<{
+    events: z.ZodArray<z.ZodObject<{
+        seq: z.ZodNumber;
+        type: z.ZodString;
+        timestamp: z.ZodString;
+        data: z.ZodUnknown;
+    }, z.core.$strip>>;
+    lastSequence: z.ZodNumber;
+    hasMore: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * Replay-horizon arm — parity with the route's 410 body, but on this
+ * carrier it is a NORMAL result arm, not an error: the bridge rung is
+ * terminal and treats it as a re-sync instruction. Returned when the
+ * cursor fell out of the replayable window on EITHER side
+ * (`sinceSequence` above the server's `lastSequence` — a cursor from a
+ * different deployment/reset render — or below the retention horizon).
+ * Client recovery: re-mount state from a fresh snapshot and reset the
+ * cursor to `currentSequence`.
+ */
+export declare const runtimePullHorizonSchema: z.ZodObject<{
+    reason: z.ZodLiteral<"REPLAY_HORIZON_PASSED">;
+    currentSequence: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * `ggui_runtime_pull` output — the canonical strict wire contract, a
+ * two-arm union: {@link runtimePullEventsPageSchema} (normal page) |
+ * {@link runtimePullHorizonSchema} (cursor out of window). The handler
+ * registers a flat raw shape (MCP tool registration takes a
+ * `ZodRawShape`, which cannot express a top-level union) and its
+ * alignment test pins that shape to this union — same posture as
+ * `updateInputSchema`.
+ */
+export declare const runtimePullOutputSchema: z.ZodUnion<readonly [z.ZodObject<{
+    events: z.ZodArray<z.ZodObject<{
+        seq: z.ZodNumber;
+        type: z.ZodString;
+        timestamp: z.ZodString;
+        data: z.ZodUnknown;
+    }, z.core.$strip>>;
+    lastSequence: z.ZodNumber;
+    hasMore: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    reason: z.ZodLiteral<"REPLAY_HORIZON_PASSED">;
+    currentSequence: z.ZodNumber;
+}, z.core.$strip>]>;
+/**
+ * Per-batch event cap on `ggui_runtime_telemetry` — a bounded
+ * fire-and-forget diagnostic channel, never a data plane.
+ */
+export declare const RUNTIME_TELEMETRY_MAX_EVENTS = 40;
+/**
+ * `ggui_runtime_telemetry` input — the iframe runtime's transport
+ * self-report (`_meta.ui.visibility: ['app']`, view-callable only).
+ *
+ * Contract (both parties named): the IFRAME RUNTIME batches short
+ * `{at, kind, detail?}` events describing its delivery-ladder journey
+ * (boot-path decision, per-rung status transitions and failures —
+ * `channel_failover_swap`, `channel_polling_budget_exhausted`, … —
+ * and outbound doorbell rings) and flushes them over the host's
+ * `tools/call` postMessage bridge; the SERVER logs one structured
+ * line per batch for operator forensics and stores NOTHING. Sandboxed
+ * hosts (claude.ai's `claudemcpcontent.com` frames) expose no
+ * readable console and no network — this tool is the ONLY way the
+ * ladder's behavior on such hosts reaches an operator. `sessionId` is
+ * client-claimed (log-tagged, never trusted for reads); events are
+ * bounded (≤ {@link RUNTIME_TELEMETRY_MAX_EVENTS} per batch, `kind` ≤
+ * 64 chars, `detail` ≤ 512) so a hostile view cannot use the channel
+ * for bulk exfiltration or log flooding.
+ */
+export declare const runtimeTelemetryInputShape: {
+    readonly sessionId: z.ZodString;
+    readonly events: z.ZodArray<z.ZodObject<{
+        at: z.ZodNumber;
+        kind: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+};
+export declare const runtimeTelemetryInputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    events: z.ZodArray<z.ZodObject<{
+        at: z.ZodNumber;
+        kind: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** `ggui_runtime_telemetry` output — bare acknowledgement. */
+export declare const runtimeTelemetryOutputSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, z.core.$strip>;
 //# sourceMappingURL=mcp.d.ts.map

package/dist/schemas/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/schemas/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,eAAO,MAAM,cAAc;;;iBAGzB,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAUnB,CAAC;AAYjB;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;CAgBpB,CAAC;AAEX,eAAO,MAAM,kBAAkB;;;iBAA8B,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC;AAEX,eAAO,MAAM,eAAe;;;;;iBAA2B,CAAC;AAExD,eAAO,MAAM,oBAAoB;;CAKvB,CAAC;AAEX,eAAO,MAAM,qBAAqB;;iBAAiC,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,IAAc,CAAC;AAE5D,eAAO,MAAM,iCAAiC,gCAE7C,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;;;CAwB7B,CAAC;AAEX,eAAO,MAAM,2BAA2B;;;;;iBAAuC,CAAC;AAEhF,eAAO,MAAM,yBAAyB;;CAO5B,CAAC;AAEX,eAAO,MAAM,0BAA0B;;iBAAsC,CAAC;AAE9E,eAAO,MAAM,kBAAkB,IAAc,CAAC;AAE9C,eAAO,MAAM,mBAAmB,gCAA+B,CAAC;AAahE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,oBAAoB;;;;kBA0BtB,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;iBAgChC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,gBAAgB;;IAO3B;;;;;;;;OAQG;;IAEH;;;;;OAKG;;IAQH;;;;;;;;;;OAUG;;;;IAaH;;;;;;;;;;;OAWG;;;;;CAuBK,CAAC;AAEX,eAAO,MAAM,iBAAiB;;;;;;;;;;;iBAA6B,CAAC;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;iBAyBlC,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,qBAAqB;;;;;EAKhC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;iBAS5B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,2BAA2B;;;;;EAKtC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;iBAalC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwE7B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;4BAa5B,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB;;;;iBAW7B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,6BAA6B;;;;;kBAW/B,CAAC;AAEZ,eAAO,MAAM,8BAA8B;;;kBAKhC,CAAC"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/schemas/mcp.ts"],"names":[],"mappings":"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"}

package/dist/schemas/mcp.js

@@ -391,7 +391,7 @@ export const renderCacheMarkerSchema = z.object({
 /**
  * Canonical failure codes for the in-result `ggui_render` failure
  * envelope (SPEC §7.9 Plane 3). Closed enum — a failed render's
- * `error.code` is always one of these four; finer-grained diagnostics
+ * `error.code` is always one of these five; finer-grained diagnostics
  * ride on `error.message`.
  *
  *   - `PRODUCTION_FAILED` — generation ran but did not produce a
@@ -403,12 +403,21 @@ export const renderCacheMarkerSchema = z.object({
  *     configuration has no key for the resolved route.
  *   - `NO_CREDENTIALS` — no generation credentials are configured on
  *     the server at all.
+ *   - `GENERATION_QUEUE_OVERLOADED` — the deployment's generation
+ *     admission gate rejected this request before any generation
+ *     attempt started (concurrent-request queue full, or wait for a
+ *     free slot exceeded the configured timeout). Distinct from
+ *     `PRODUCTION_FAILED` by design: generation never ran, so callers
+ *     MUST NOT bill or count it as a failed attempt. See
+ *     {@link GenerationError} in `types/ui-generator.ts` for the full
+ *     contract.
  */
 export const renderErrorCodeSchema = z.enum([
     'PRODUCTION_FAILED',
     'VALIDATION_ERROR',
     'NO_PLATFORM_KEY',
     'NO_CREDENTIALS',
+    'GENERATION_QUEUE_OVERLOADED',
 ]);
 /**
  * In-result failure marker for `ggui_render`. Present on the wire
@@ -417,7 +426,7 @@ export const renderErrorCodeSchema = z.enum([
  * canonical failure classification.
  */
 export const renderErrorSchema = z.object({
-    code: renderErrorCodeSchema.describe('Canonical failure class. PRODUCTION_FAILED: generation did not produce a component. VALIDATION_ERROR: a server-side precondition rejected the render before generation. NO_PLATFORM_KEY: the server\'s managed provider-key configuration has no key for the resolved route. NO_CREDENTIALS: no generation credentials are configured on the server.'),
+    code: renderErrorCodeSchema.describe('Canonical failure class. PRODUCTION_FAILED: generation did not produce a component. VALIDATION_ERROR: a server-side precondition rejected the render before generation. NO_PLATFORM_KEY: the server\'s managed provider-key configuration has no key for the resolved route. NO_CREDENTIALS: no generation credentials are configured on the server. GENERATION_QUEUE_OVERLOADED: the deployment\'s admission gate rejected the request before generation started (queue full or wait timed out) — not a failed attempt; safe to retry immediately.'),
     message: z
         .string()
         .describe('Human-readable failure detail — fold into the next attempt or surface to the operator.'),
@@ -556,8 +565,13 @@ export const renderOutputSchema = z.object({
         example: z.string(),
         args: z.object({
             sessionId: z.string(),
+            // The per-call long-poll window in seconds. Carried on the hint
+            // because consume's own default is 0 (single non-blocking
+            // drain): an agent copying a timeout-less hint gets an instant
+            // empty result and stops looping.
+            timeout: z.number(),
         }),
-    }).optional().describe('Recovery hint — when the rendered contract has actions, points the agent at ggui_consume({sessionId}) for the inbound action loop. Absent for pure-display renders.'),
+    }).optional().describe('Required-next-call hint — when the rendered contract has actions, points the agent at ggui_consume({sessionId, timeout}) for the inbound action loop. Absent for pure-display renders.'),
 });
 /**
  * `ggui_update` — refresh the rendered UI with new state.
@@ -595,13 +609,34 @@ export const updateInputSchema = z.discriminatedUnion('kind', [
         sessionId: z.string().describe('GguiSession opaque id (UUID) — returned by ggui_render.'),
         kind: z.literal('replace'),
         props: z.record(z.string(), z.unknown())
-            .describe('Full replacement props map. New map IS the new state.'),
+            .describe('Full replacement props map. New map IS the new state, rendered as a NEW card (a new history entry). For an in-place repaint of the mounted card use ggui_amend.'),
     }).strict(),
     z.object({
         sessionId: z.string().describe('GguiSession opaque id (UUID) — returned by ggui_render.'),
         kind: z.literal('merge'),
         patch: z.record(z.string(), z.unknown())
-            .describe('RFC 7396 JSON Merge Patch — null deletes a key; arrays fully replace.'),
+            .describe('RFC 7396 JSON Merge Patch — null deletes a key; arrays fully replace. The merged state renders as a NEW card (a new history entry). For an in-place repaint of the mounted card use ggui_amend.'),
+    }).strict(),
+]);
+/**
+ * `ggui_amend` wire input (#483) — same replace/merge mutation
+ * grammar as `ggui_update`, different mount identity: amend targets
+ * the ALREADY-MOUNTED card. No new card, no history entry, the
+ * history number does not advance. Git reading: `ggui_update` =
+ * commit; `ggui_amend` = commit --amend.
+ */
+export const amendInputSchema = z.discriminatedUnion('kind', [
+    z.object({
+        sessionId: z.string().describe('GguiSession opaque id (UUID) — returned by ggui_render.'),
+        kind: z.literal('replace'),
+        props: z.record(z.string(), z.unknown())
+            .describe('Full replacement props map, applied to the currently mounted card in place.'),
+    }).strict(),
+    z.object({
+        sessionId: z.string().describe('GguiSession opaque id (UUID) — returned by ggui_render.'),
+        kind: z.literal('merge'),
+        patch: z.record(z.string(), z.unknown())
+            .describe('RFC 7396 JSON Merge Patch — null deletes a key; arrays fully replace. Applied to the currently mounted card in place.'),
     }).strict(),
 ]);
 /**
@@ -609,23 +644,61 @@ export const updateInputSchema = z.discriminatedUnion('kind', [
  * `decision`, `contract`, `contractHash` on its internal `UpdateOutput`
  * TS shape — zod strips them before structuredContent serialization.
  *
- * Post-update the iframe receives the new props via the live-channel
- * `props_update` WS frame; the cross-host fallback path receives them
- * via the `ai.ggui/render.propsJson` slice field (see
- * `update.resultMeta`). The wire response itself is just
- * acknowledgement.
+ * Every REAL update (`updated: true`) mints a new history record and
+ * its result carries the `ai.ggui/render` slice as a FULL bootable
+ * mount package (#483 — hosts mint a per-result view for the new
+ * card); a no-op (`updated: false`) carries NO result `_meta`.
+ * Already-mounted frames are not repainted by update — they freeze as
+ * history when its higher-epoch `props_update` frame lands; the
+ * in-place repaint over the live-channel ladder (WS / SSE / polling /
+ * bridge-pull) is `ggui_amend`'s job.
  */
 export const updateOutputSchema = z.object({
     sessionId: z.string(),
     updated: z.boolean(),
     /**
-     * Unchanged from the initial render — the same `ui://ggui/render/{id}`
-     * URI the mount stamped. Mirrored on the LLM-visible structuredContent
-     * so SDKs that strip `_meta` from tool_results can still reach the
+     * The epoch-pinned URI of the NEW history record this update minted
+     * (`ui://ggui/render/{id}[/{key}]#{epoch}` — see epoch-uri.ts). On a
+     * no-op (`updated: false`) no record is minted and this is the bare
+     * live-head URI. Mirrored on the LLM-visible structuredContent so
+     * SDKs that strip `_meta` from tool_results can still reach the
      * mount URI. Kept in sync with the update handler's wire shape —
      * this export and the handler's inline schema must not drift.
      */
     resourceUri: z.string(),
+    /**
+     * The session's head epoch after this call: advanced by one on a
+     * real update (`updated: true`), unchanged on a no-op. `ggui_render`
+     * mints epoch 0. The session ROW is the authority
+     * (`GguiSessionBase.epoch`, absent ⇒ 0); the ledger's `ui.reminted`
+     * events are the wire signal only — the ledger is horizon-bounded
+     * and must never be counted as the source of truth.
+     */
+    epoch: z.number().int().min(0),
+    /**
+     * Present ONLY on a no-op (`updated: false`): the patch conformed to
+     * the contract but left the final props semantically identical to
+     * the current state, so nothing was written, nothing changes on
+     * screen, and NO new history record was minted. Model-visible by
+     * design — the common producer of a no-op is an agent echoing
+     * existing props back believing it changed the UI, and this field is
+     * its feedback channel.
+     */
+    warning: z.string().optional(),
+});
+/**
+ * `ggui_amend` wire output (#483) — acknowledgement only. `resourceUri`
+ * is the BARE live-head URI (amend targets the mounted card; it never
+ * mints a record, so there is no pinned URI to return and no epoch
+ * field — the history number is untouched by construction). The
+ * mounted card receives the new props over the live channels.
+ */
+export const amendOutputSchema = z.object({
+    sessionId: z.string(),
+    updated: z.boolean(),
+    resourceUri: z.string(),
+    /** Same no-op feedback channel as ggui_update's `warning`. */
+    warning: z.string().optional(),
 });
 /**
  * `ggui_runtime_declare_tool_catalog` — the host runtime declares its
@@ -664,3 +737,188 @@ export const declareToolCatalogOutputSchema = z
     appId: z.string(),
 })
     .strict();
+// ── `ggui_runtime_pull` — bridge-pull rung of the live-channel ladder ──
+/**
+ * Server-side page cap for `ggui_runtime_pull`. A `limit` above this is
+ * CLAMPED (not rejected) — the tool mirrors the cursor-walk posture of
+ * the `/events` HTTP route, where a too-eager page size is a tuning
+ * knob, not a caller bug. Shared so the pulling client and the serving
+ * handler agree on the effective page ceiling from one constant.
+ */
+export const RUNTIME_PULL_MAX_LIMIT = 100;
+/**
+ * Server-side ceiling on `ggui_runtime_pull`'s `wait` hold, in seconds.
+ * Chosen under `ggui_consume`'s proven 25-second host tolerance for
+ * held tool calls — the hold must resolve before any host-side
+ * `tools/call` timeout fires, or the transport counts a failure the
+ * server intended as a quiet success.
+ */
+export const RUNTIME_PULL_MAX_WAIT_SECONDS = 20;
+/**
+ * One `GguiSessionEvent` ledger row on the `ggui_runtime_pull` wire —
+ * the zod mirror of the canonical `GguiSessionEvent` interface in
+ * `types/ggui-session-event.ts` (which stays the type-level source of
+ * truth; `mcp.test.ts` pins the two together in both directions).
+ */
+export const gguiSessionEventSchema = z.object({
+    seq: z
+        .number()
+        .int()
+        .min(1)
+        .describe('Monotonic, gap-free per render; starts at 1 (0 is the "no events yet" cursor sentinel, never an event).'),
+    type: z
+        .string()
+        .min(1)
+        .describe('Wire-frame type — see the canonical GguiSessionEventType taxonomy; plain string so servers can mint new types without a protocol bump.'),
+    timestamp: z
+        .string()
+        .describe('ISO 8601 UTC timestamp the server stamped on emission.'),
+    data: z
+        .unknown()
+        .describe('Type-specific payload — structurally identical to the matching live-channel frame payload.'),
+});
+/**
+ * `ggui_runtime_pull` input — the terminal bridge-pull rung of the
+ * live-channel failover ladder (WS → SSE → HTTP polling → bridge-pull).
+ *
+ * Two named parties:
+ *
+ *   - **Puller** — the `@ggui-ai/iframe-runtime` bridge rung. In a
+ *     CSP-jailed MCP Apps host the iframe can reach no network origin
+ *     at all, so it pulls the event ledger by issuing `tools/call`
+ *     postMessages that the host's MCP client relays (the tool
+ *     registers `_meta.ui.visibility: ['app']` per MCP Apps spec §401
+ *     — hosts MUST route view-issued calls to it and MUST reject
+ *     view-issued calls to tools without it).
+ *   - **Server** — the MCP server hosting the render. It serves the
+ *     SAME `GguiSessionEvent` ledger `GET
+ *     /api/sessions/:sessionId/events` serves, through the same
+ *     `listEventsSince` read, and MUST answer with the same shapes
+ *     (see {@link runtimePullOutputSchema}) so one client parse core
+ *     handles both carriers.
+ *
+ * Divergences from the HTTP route, both deliberate: `sinceSequence` is
+ * OPTIONAL here (the bridge rung owns its cursor and seeds from 0; the
+ * route requires it because a bare browser GET has no cursor owner),
+ * and `limit` is clamped to {@link RUNTIME_PULL_MAX_LIMIT} instead of
+ * rejecting above it. Tenancy violations and unknown sessionIds
+ * surface uniformly as the `session_not_found` error — existence of
+ * other tenants' renders is never leaked.
+ */
+export const runtimePullInputShape = {
+    sessionId: z
+        .string()
+        .min(1)
+        .describe('Active render id — sourced from `_meta["ai.ggui/render"].sessionId` on the iframe boot envelope. Unknown and cross-tenant ids surface uniformly as session_not_found.'),
+    sinceSequence: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe('Replay cursor — only events with seq > sinceSequence return. Omit (= 0) on first pull; advance to the last event\'s seq (or lastSequence on an empty page) on every subsequent pull.'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe(`Max events per page. Values above ${RUNTIME_PULL_MAX_LIMIT} are clamped to ${RUNTIME_PULL_MAX_LIMIT}; omit for the default ${RUNTIME_PULL_MAX_LIMIT}. When hasMore is true, immediately re-pull with the advanced cursor.`),
+    wait: z
+        .number()
+        .min(0)
+        .optional()
+        .describe(`Subscription-mode hold, in seconds. When set and the cursor page is empty, the server holds this call until an event lands or the hold elapses (values above ${RUNTIME_PULL_MAX_WAIT_SECONDS} are clamped to ${RUNTIME_PULL_MAX_WAIT_SECONDS}). An empty page after a full hold is a NORMAL result — immediately re-pull to stay subscribed, or back off to sparse un-held pulls after a few consecutive empties. Omit (= 0) for an immediate return.`),
+};
+export const runtimePullInputSchema = z.object(runtimePullInputShape);
+/**
+ * Normal-page arm — EXACT `EventsResponse` parity with
+ * `GET /api/sessions/:sessionId/events` (same keys, same semantics):
+ * `events` strictly ascending by seq, `lastSequence` = the render's
+ * current high-water mark (NOT the page's last seq — advances the
+ * cursor on empty pages), `hasMore` = the page was truncated by
+ * `limit`.
+ */
+export const runtimePullEventsPageSchema = z.object({
+    events: z.array(gguiSessionEventSchema),
+    lastSequence: z.number().int().min(0),
+    hasMore: z.boolean(),
+});
+/**
+ * Replay-horizon arm — parity with the route's 410 body, but on this
+ * carrier it is a NORMAL result arm, not an error: the bridge rung is
+ * terminal and treats it as a re-sync instruction. Returned when the
+ * cursor fell out of the replayable window on EITHER side
+ * (`sinceSequence` above the server's `lastSequence` — a cursor from a
+ * different deployment/reset render — or below the retention horizon).
+ * Client recovery: re-mount state from a fresh snapshot and reset the
+ * cursor to `currentSequence`.
+ */
+export const runtimePullHorizonSchema = z.object({
+    reason: z.literal('REPLAY_HORIZON_PASSED'),
+    currentSequence: z.number().int().min(0),
+});
+/**
+ * `ggui_runtime_pull` output — the canonical strict wire contract, a
+ * two-arm union: {@link runtimePullEventsPageSchema} (normal page) |
+ * {@link runtimePullHorizonSchema} (cursor out of window). The handler
+ * registers a flat raw shape (MCP tool registration takes a
+ * `ZodRawShape`, which cannot express a top-level union) and its
+ * alignment test pins that shape to this union — same posture as
+ * `updateInputSchema`.
+ */
+export const runtimePullOutputSchema = z.union([
+    runtimePullEventsPageSchema,
+    runtimePullHorizonSchema,
+]);
+/**
+ * Per-batch event cap on `ggui_runtime_telemetry` — a bounded
+ * fire-and-forget diagnostic channel, never a data plane.
+ */
+export const RUNTIME_TELEMETRY_MAX_EVENTS = 40;
+/**
+ * `ggui_runtime_telemetry` input — the iframe runtime's transport
+ * self-report (`_meta.ui.visibility: ['app']`, view-callable only).
+ *
+ * Contract (both parties named): the IFRAME RUNTIME batches short
+ * `{at, kind, detail?}` events describing its delivery-ladder journey
+ * (boot-path decision, per-rung status transitions and failures —
+ * `channel_failover_swap`, `channel_polling_budget_exhausted`, … —
+ * and outbound doorbell rings) and flushes them over the host's
+ * `tools/call` postMessage bridge; the SERVER logs one structured
+ * line per batch for operator forensics and stores NOTHING. Sandboxed
+ * hosts (claude.ai's `claudemcpcontent.com` frames) expose no
+ * readable console and no network — this tool is the ONLY way the
+ * ladder's behavior on such hosts reaches an operator. `sessionId` is
+ * client-claimed (log-tagged, never trusted for reads); events are
+ * bounded (≤ {@link RUNTIME_TELEMETRY_MAX_EVENTS} per batch, `kind` ≤
+ * 64 chars, `detail` ≤ 512) so a hostile view cannot use the channel
+ * for bulk exfiltration or log flooding.
+ */
+export const runtimeTelemetryInputShape = {
+    sessionId: z
+        .string()
+        .min(1)
+        .describe('Render id the report concerns — sourced from the boot envelope. Client-claimed: used as a log tag only.'),
+    events: z
+        .array(z.object({
+        at: z
+            .number()
+            .min(0)
+            .describe('Milliseconds since iframe boot (monotonic, client clock).'),
+        kind: z
+            .string()
+            .min(1)
+            .max(64)
+            .describe("Event name — e.g. 'boot.path', 'status.connected', 'channel_failover_swap', 'doorbell.ring'."),
+        detail: z
+            .string()
+            .max(512)
+            .optional()
+            .describe('Optional compact context (JSON fragment or message).'),
+    }))
+        .min(1)
+        .max(RUNTIME_TELEMETRY_MAX_EVENTS)
+        .describe('Batched ladder/doorbell events, oldest first.'),
+};
+export const runtimeTelemetryInputSchema = z.object(runtimeTelemetryInputShape);
+/** `ggui_runtime_telemetry` output — bare acknowledgement. */
+export const runtimeTelemetryOutputSchema = z.object({ ok: z.literal(true) });

package/dist/types/data-contract.d.ts

@@ -170,8 +170,8 @@ export interface StreamChannelEntry {
     /**
      * JSON Schema for the channel payload. This is the authoritative
      * shape guard for every delivery on this channel — live-channel
-     * enforcement points (hosted fan-out, OSS `/ws`, `@ggui-ai/react`
-     * data receipt, `@ggui-ai/react-native` data receipt) all validate
+     * enforcement points (hosted fan-out, OSS `/ws`, `@ggui-ai/mcp-apps-react`
+     * data receipt, `@ggui-ai/mcp-apps-react-native` data receipt) all validate
      * deliveries against it.
      *
      * When the channel declares a `source.tool` feed, the protocol-level