@ggui-ai/mcp-server-handlers 0.7.0 → 0.9.0

package/dist/renders/runtime-pull.d.ts

@@ -0,0 +1,122 @@
+/**
+ * `ggui_runtime_pull` — terminal bridge-pull rung of the live-channel
+ * failover ladder (WS → SSE → HTTP polling → bridge-pull).
+ *
+ * In a CSP-jailed MCP Apps host (claude.ai) the iframe can reach NO
+ * network origin — no WS, no SSE, no HTTP polling. The one channel it
+ * always has is the host's `tools/call` postMessage bridge. This tool
+ * serves the GguiSessionEvent ledger over that bridge: the
+ * `@ggui-ai/iframe-runtime` bridge rung pulls it on a flat interval,
+ * reusing the SAME cursor-walk algorithm (and the same parse core) as
+ * its HTTP `/events` polling rung, with `tools/call` as the carrier.
+ *
+ * **Wire shape** (what iframe-runtime postMessages via `tools/call`
+ * and the host relays to the MCP server):
+ *
+ * ```jsonc
+ * {
+ *   "method": "tools/call",
+ *   "params": {
+ *     "name": "ggui_runtime_pull",
+ *     "arguments": {
+ *       "sessionId":     "rnd_…",  // bootstrap.sessionId
+ *       "sinceSequence": 12,       // replay cursor; omit = 0
+ *       "limit":         100       // page size; clamped to 100
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * **Output = EXACT `EventsResponse` parity** with
+ * `GET /api/sessions/:sessionId/events` (`@ggui-ai/mcp-server`'s
+ * `api-renders-routes.ts`) — both read the ledger through the same
+ * `GguiSessionStore.listEventsSince` and answer with the same two
+ * shapes, so the client reuses one parse core across carriers:
+ *
+ *   - Normal page: `{events, lastSequence, hasMore}` — events strictly
+ *     ascending by seq with `seq > sinceSequence`, `lastSequence` = the
+ *     render's high-water mark (advances the cursor even on an empty
+ *     page), `hasMore` = the page was truncated by `limit` (client
+ *     SHOULD immediately re-pull with the advanced cursor).
+ *   - Horizon: `{reason: 'REPLAY_HORIZON_PASSED', currentSequence}` — a
+ *     NORMAL result arm, not an error (the bridge rung is terminal;
+ *     this is a re-sync instruction, mirroring the route's 410 body).
+ *     Returned when the cursor fell out of the replayable window on
+ *     EITHER side: `sinceSequence > lastSequence` (cursor from a
+ *     different deployment / reset render) or
+ *     `sinceSequence < horizonSeq` (events evicted from the bounded
+ *     retention window). Client recovery: re-mount from a fresh
+ *     snapshot and reset the cursor to `currentSequence`.
+ *
+ * **Failure modes:**
+ *   - Unknown sessionId, cross-tenant sessionId, and a render deleted
+ *     mid-read all surface uniformly as
+ *     {@link GguiSessionNotFoundError} — no cross-tenant existence
+ *     leak (tenancy gate: `renderStore.get` + `ctx.appId`).
+ *   - Malformed input (empty sessionId, negative cursor, `limit < 1`)
+ *     rejects at the zod boundary.
+ *
+ * **Visibility.** Registered with `_meta.ui.visibility: ['app']` so
+ * MCP Apps hosts route iframe-issued `tools/call` to this handler per
+ * spec §401 — REQUIRED: without it hosts reject view-issued calls, and
+ * the terminal rung goes dark exactly where it is the only channel
+ * left. Outer agents don't see the tool — ledger replay is a runtime
+ * concern, not an agent gesture.
+ *
+ * Deliberate divergences from the `/events` route, per the bridge-pull
+ * ruling: `sinceSequence` is optional (`?? 0` — the bridge rung owns
+ * its cursor), and `limit` above {@link RUNTIME_PULL_MAX_LIMIT} is
+ * CLAMPED, not rejected.
+ */
+import { z } from 'zod';
+import { type GguiRuntimePullOutput } from '@ggui-ai/protocol';
+import type { GguiSessionStore } from '@ggui-ai/mcp-server-core';
+import type { SharedHandler } from '../types.js';
+declare const inputSchema: {
+    readonly sessionId: z.ZodString;
+    readonly sinceSequence: z.ZodOptional<z.ZodNumber>;
+    readonly limit: z.ZodOptional<z.ZodNumber>;
+    readonly wait: z.ZodOptional<z.ZodNumber>;
+};
+declare const outputSchema: {
+    /** Normal page only — ledger rows with `seq > sinceSequence`, ascending. */
+    readonly events: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        seq: z.ZodNumber;
+        type: z.ZodString;
+        timestamp: z.ZodString;
+        data: z.ZodUnknown;
+    }, z.core.$strip>>>;
+    /** Normal page only — the render's current high-water mark (cursor floor on empty pages). */
+    readonly lastSequence: z.ZodOptional<z.ZodNumber>;
+    /** Normal page only — `true` when `limit` truncated the page; re-pull immediately. */
+    readonly hasMore: z.ZodOptional<z.ZodBoolean>;
+    /** Horizon arm only — the cursor fell out of the replayable window (normal result, not an error). */
+    readonly reason: z.ZodOptional<z.ZodLiteral<"REPLAY_HORIZON_PASSED">>;
+    /** Horizon arm only — reset the cursor here after re-mounting from a snapshot. */
+    readonly currentSequence: z.ZodOptional<z.ZodNumber>;
+};
+export interface GguiRuntimePullHandlerDeps {
+    /**
+     * The same store `ggui_render` commits to and the `/events` route
+     * reads from — one ledger, two carriers. The handler needs both
+     * `get` (tenancy gate) and `listEventsSince` (cursor read).
+     */
+    readonly renderStore: GguiSessionStore;
+    /**
+     * Subscription-mode hold probe cadence, in ms. During a `wait` hold
+     * the handler re-reads the ledger at this interval — deliberately a
+     * store poll rather than an in-process wake seam, because the
+     * update that ends the hold may land on a DIFFERENT pod (the store
+     * is the only cross-pod truth this package may assume). Defaults to
+     * 1000. Test hook: inject a small value for deterministic hold
+     * tests without fake timers.
+     */
+    readonly waitProbeIntervalMs?: number;
+}
+/**
+ * Build the `ggui_runtime_pull` handler. Registers as app-visible so
+ * MCP Apps hosts route iframe-issued `tools/call` to it per spec §401.
+ */
+export declare function createGguiRuntimePullHandler(deps: GguiRuntimePullHandlerDeps): SharedHandler<typeof inputSchema, typeof outputSchema, GguiRuntimePullOutput>;
+export {};
+//# sourceMappingURL=runtime-pull.d.ts.map

package/dist/renders/runtime-pull.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-pull.d.ts","sourceRoot":"","sources":["../../src/renders/runtime-pull.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAKL,KAAK,qBAAqB,EAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAkB,aAAa,EAAE,MAAM,aAAa,CAAC;AAKjE,QAAA,MAAM,WAAW;;;;;CAAwB,CAAC;AAQ1C,QAAA,MAAM,YAAY;IAChB,4EAA4E;;;;;;;IAE5E,6FAA6F;;IAE7F,sFAAsF;;IAEtF,qGAAqG;;IAErG,kFAAkF;;CAE1E,CAAC;AAEX,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC;;;;;;;;OAQG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,0BAA0B,GAC/B,aAAa,CAAC,OAAO,WAAW,EAAE,OAAO,YAAY,EAAE,qBAAqB,CAAC,CAkG/E"}

package/dist/renders/runtime-pull.js

@@ -0,0 +1,178 @@
+/**
+ * `ggui_runtime_pull` — terminal bridge-pull rung of the live-channel
+ * failover ladder (WS → SSE → HTTP polling → bridge-pull).
+ *
+ * In a CSP-jailed MCP Apps host (claude.ai) the iframe can reach NO
+ * network origin — no WS, no SSE, no HTTP polling. The one channel it
+ * always has is the host's `tools/call` postMessage bridge. This tool
+ * serves the GguiSessionEvent ledger over that bridge: the
+ * `@ggui-ai/iframe-runtime` bridge rung pulls it on a flat interval,
+ * reusing the SAME cursor-walk algorithm (and the same parse core) as
+ * its HTTP `/events` polling rung, with `tools/call` as the carrier.
+ *
+ * **Wire shape** (what iframe-runtime postMessages via `tools/call`
+ * and the host relays to the MCP server):
+ *
+ * ```jsonc
+ * {
+ *   "method": "tools/call",
+ *   "params": {
+ *     "name": "ggui_runtime_pull",
+ *     "arguments": {
+ *       "sessionId":     "rnd_…",  // bootstrap.sessionId
+ *       "sinceSequence": 12,       // replay cursor; omit = 0
+ *       "limit":         100       // page size; clamped to 100
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * **Output = EXACT `EventsResponse` parity** with
+ * `GET /api/sessions/:sessionId/events` (`@ggui-ai/mcp-server`'s
+ * `api-renders-routes.ts`) — both read the ledger through the same
+ * `GguiSessionStore.listEventsSince` and answer with the same two
+ * shapes, so the client reuses one parse core across carriers:
+ *
+ *   - Normal page: `{events, lastSequence, hasMore}` — events strictly
+ *     ascending by seq with `seq > sinceSequence`, `lastSequence` = the
+ *     render's high-water mark (advances the cursor even on an empty
+ *     page), `hasMore` = the page was truncated by `limit` (client
+ *     SHOULD immediately re-pull with the advanced cursor).
+ *   - Horizon: `{reason: 'REPLAY_HORIZON_PASSED', currentSequence}` — a
+ *     NORMAL result arm, not an error (the bridge rung is terminal;
+ *     this is a re-sync instruction, mirroring the route's 410 body).
+ *     Returned when the cursor fell out of the replayable window on
+ *     EITHER side: `sinceSequence > lastSequence` (cursor from a
+ *     different deployment / reset render) or
+ *     `sinceSequence < horizonSeq` (events evicted from the bounded
+ *     retention window). Client recovery: re-mount from a fresh
+ *     snapshot and reset the cursor to `currentSequence`.
+ *
+ * **Failure modes:**
+ *   - Unknown sessionId, cross-tenant sessionId, and a render deleted
+ *     mid-read all surface uniformly as
+ *     {@link GguiSessionNotFoundError} — no cross-tenant existence
+ *     leak (tenancy gate: `renderStore.get` + `ctx.appId`).
+ *   - Malformed input (empty sessionId, negative cursor, `limit < 1`)
+ *     rejects at the zod boundary.
+ *
+ * **Visibility.** Registered with `_meta.ui.visibility: ['app']` so
+ * MCP Apps hosts route iframe-issued `tools/call` to this handler per
+ * spec §401 — REQUIRED: without it hosts reject view-issued calls, and
+ * the terminal rung goes dark exactly where it is the only channel
+ * left. Outer agents don't see the tool — ledger replay is a runtime
+ * concern, not an agent gesture.
+ *
+ * Deliberate divergences from the `/events` route, per the bridge-pull
+ * ruling: `sinceSequence` is optional (`?? 0` — the bridge rung owns
+ * its cursor), and `limit` above {@link RUNTIME_PULL_MAX_LIMIT} is
+ * CLAMPED, not rejected.
+ */
+import { z } from 'zod';
+import { RUNTIME_PULL_MAX_LIMIT, RUNTIME_PULL_MAX_WAIT_SECONDS, gguiSessionEventSchema, runtimePullInputShape, } from '@ggui-ai/protocol';
+import { GguiSessionNotFoundError } from './errors.js';
+// Canonical SSoT shape — authored once in `@ggui-ai/protocol`
+// (`schemas/mcp.ts`), same wiring as `ggui_get_session`.
+const inputSchema = runtimePullInputShape;
+// Flat raw shape for MCP tool registration — a `ZodRawShape` cannot
+// express the top-level two-arm union, so every field of both arms is
+// optional here and the canonical strict contract stays
+// `runtimePullOutputSchema` (`@ggui-ai/protocol`). The alignment tests
+// in `runtime-pull.test.ts` pin this shape to the union key-for-key —
+// same posture as `ggui_update`'s input.
+const outputSchema = {
+    /** Normal page only — ledger rows with `seq > sinceSequence`, ascending. */
+    events: z.array(gguiSessionEventSchema).optional(),
+    /** Normal page only — the render's current high-water mark (cursor floor on empty pages). */
+    lastSequence: z.number().int().min(0).optional(),
+    /** Normal page only — `true` when `limit` truncated the page; re-pull immediately. */
+    hasMore: z.boolean().optional(),
+    /** Horizon arm only — the cursor fell out of the replayable window (normal result, not an error). */
+    reason: z.literal('REPLAY_HORIZON_PASSED').optional(),
+    /** Horizon arm only — reset the cursor here after re-mounting from a snapshot. */
+    currentSequence: z.number().int().min(0).optional(),
+};
+/**
+ * Build the `ggui_runtime_pull` handler. Registers as app-visible so
+ * MCP Apps hosts route iframe-issued `tools/call` to it per spec §401.
+ */
+export function createGguiRuntimePullHandler(deps) {
+    return {
+        name: 'ggui_runtime_pull',
+        title: '[runtime] Pull Events',
+        audience: ['runtime'],
+        description: 'Serves the GguiSessionEvent ledger over the host\'s tools/call postMessage bridge — the terminal failover rung for iframes whose CSP blocks every network channel. Cursor-replay semantics identical to the HTTP events endpoint: returns {events, lastSequence, hasMore} for a live cursor, or {reason: "REPLAY_HORIZON_PASSED", currentSequence} as a NORMAL result when the cursor fell out of the replayable window (client re-mounts from a snapshot and resets its cursor). Never invoked by the model directly — `_meta.ui.visibility: [\'app\']` restricts callers to MCP Apps views per spec §401; the iframe holds no auth credential so the host is the relay party.',
+        inputSchema,
+        outputSchema,
+        _meta: {
+            ui: {
+                // Spec §401: only an MCP Apps view (iframe) can call.
+                // Outer agent does NOT see this tool.
+                visibility: ['app'],
+            },
+        },
+        async handler(rawInput, ctx) {
+            const parsed = z.object(inputSchema).parse(rawInput);
+            const { sessionId } = parsed;
+            const sinceSequence = parsed.sinceSequence ?? 0;
+            const limit = Math.min(parsed.limit ?? RUNTIME_PULL_MAX_LIMIT, RUNTIME_PULL_MAX_LIMIT);
+            // Subscription-mode hold (transport-ladder ruling 20). Clamped
+            // like `limit` — a tolerant reader, and the ceiling is a hard
+            // safety line: the hold MUST resolve before host-side tools/call
+            // timeouts (ggui_consume's 25s holds prove ~20s is safe).
+            const waitMs = Math.min(parsed.wait ?? 0, RUNTIME_PULL_MAX_WAIT_SECONDS) * 1000;
+            const probeIntervalMs = deps.waitProbeIntervalMs ?? 1000;
+            // Tenancy gate — cross-tenant + missing surface uniformly so
+            // cross-tenant existence is not leaked (same posture as the
+            // /events route's wsToken appId check, with ctx.appId as the
+            // proved identity on this carrier).
+            const stored = await deps.renderStore.get(sessionId);
+            if (!stored || stored.appId !== ctx.appId) {
+                throw new GguiSessionNotFoundError(sessionId);
+            }
+            const deadline = Date.now() + waitMs;
+            // Hold loop: one immediate read, then — empty page + time left —
+            // probe the store at `probeIntervalMs` until an event lands or
+            // the hold elapses. The probe is a STORE read on purpose: the
+            // event that ends this hold may be committed by another pod, and
+            // the store is the only cross-pod truth available here. Horizon
+            // results and non-empty pages return immediately regardless of
+            // remaining hold budget.
+            for (;;) {
+                const result = await deps.renderStore.listEventsSince(sessionId, sinceSequence, limit);
+                if (result === null) {
+                    // Render deleted between reads — same uniform not-found as
+                    // never-existed (also ends a hold on a mid-hold delete).
+                    throw new GguiSessionNotFoundError(sessionId);
+                }
+                // Replay-horizon gate — mirrors the /events route verbatim.
+                // Two cases collapse to REPLAY_HORIZON_PASSED:
+                //   (a) sinceSequence > lastSequence — cursor from a different
+                //       deployment / reset render; the server cannot safely
+                //       advance it.
+                //   (b) sinceSequence < horizonSeq — events evicted from the
+                //       bounded retention window (cloud TTL; in-mem never).
+                if (sinceSequence > result.lastSequence ||
+                    sinceSequence < result.horizonSeq) {
+                    return {
+                        reason: 'REPLAY_HORIZON_PASSED',
+                        currentSequence: result.lastSequence,
+                    };
+                }
+                if (result.events.length > 0 || Date.now() >= deadline) {
+                    // Events to deliver, or the hold elapsed — an empty page
+                    // after a full hold is a NORMAL result (the client stays
+                    // subscribed by immediately re-pulling).
+                    return {
+                        events: result.events,
+                        lastSequence: result.lastSequence,
+                        hasMore: result.hasMore,
+                    };
+                }
+                await new Promise((resolve) => {
+                    setTimeout(resolve, probeIntervalMs);
+                });
+            }
+        },
+    };
+}

package/dist/renders/runtime-telemetry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `ggui_runtime_telemetry` — the iframe runtime's transport
+ * self-report, and the ONLY window an operator has into the delivery
+ * ladder's behavior on sandboxed MCP-Apps hosts.
+ *
+ * Why this tool exists (2026-08-12, transport-ladder debugging): on
+ * claude.ai the view runs in a `claudemcpcontent.com` sandbox frame
+ * whose console is unreadable from outside and whose CSP blocks every
+ * network channel — when the WS → SSE → polling → bridge-pull ladder
+ * misbehaves there, NOTHING reaches server logs and the failure is
+ * invisible by construction. The runtime therefore batches its own
+ * ladder events (boot-path decision, per-rung status transitions, the
+ * live-channel logger's `channel_*` diagnostics, doorbell rings) and
+ * flushes them over the host's `tools/call` postMessage bridge — the
+ * one carrier a CSP jail cannot block.
+ *
+ * Posture: fire-and-forget diagnostics, NEVER a data plane.
+ *   - Stores nothing; emits ONE structured log line per batch.
+ *   - `sessionId` is client-claimed — a log tag, never a read key, so
+ *     no tenancy gate and no store dependency (nothing to leak).
+ *   - Bounded by the protocol schema (≤ 40 events/batch, kind ≤ 64
+ *     chars, detail ≤ 512) against log flooding; `ctx.appId` (the
+ *     PROVED identity on this carrier) tags every line so abuse is
+ *     attributable.
+ */
+import { z } from 'zod';
+import { type GguiRuntimeTelemetryOutput } from '@ggui-ai/protocol';
+import type { SharedHandler } from '../types.js';
+declare const inputSchema: {
+    readonly sessionId: z.ZodString;
+    readonly events: z.ZodArray<z.ZodObject<{
+        at: z.ZodNumber;
+        kind: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+};
+declare const outputSchema: {
+    readonly ok: z.ZodLiteral<true>;
+};
+/**
+ * Structured-log sink. Matches the narrow slice of the pod/server
+ * logger this handler needs; OSS default falls back to a single-line
+ * `console.log` in the same shape the log pipeline already parses.
+ */
+export interface RuntimeTelemetryLogger {
+    info(event: string, fields: Record<string, unknown>): void;
+}
+export interface GguiRuntimeTelemetryHandlerDeps {
+    /** Optional structured logger; absent → single-line console JSON. */
+    readonly logger?: RuntimeTelemetryLogger;
+}
+/**
+ * Build the `ggui_runtime_telemetry` handler. Registers as
+ * app-visible (`_meta.ui.visibility: ['app']`) so MCP Apps hosts route
+ * iframe-issued `tools/call` to it per spec §401 — the same channel
+ * `ggui_runtime_submit_action` and `ggui_runtime_pull` ride.
+ */
+export declare function createGguiRuntimeTelemetryHandler(deps?: GguiRuntimeTelemetryHandlerDeps): SharedHandler<typeof inputSchema, typeof outputSchema, GguiRuntimeTelemetryOutput>;
+export {};
+//# sourceMappingURL=runtime-telemetry.d.ts.map

package/dist/renders/runtime-telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-telemetry.d.ts","sourceRoot":"","sources":["../../src/renders/runtime-telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAkB,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjE,QAAA,MAAM,WAAW;;;;;;;CAA6B,CAAC;AAE/C,QAAA,MAAM,YAAY;;CAER,CAAC;AAEX;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC5D;AAED,MAAM,WAAW,+BAA+B;IAC9C,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,IAAI,GAAE,+BAAoC,GACzC,aAAa,CAAC,OAAO,WAAW,EAAE,OAAO,YAAY,EAAE,0BAA0B,CAAC,CAyCpF"}

package/dist/renders/runtime-telemetry.js

@@ -0,0 +1,76 @@
+/**
+ * `ggui_runtime_telemetry` — the iframe runtime's transport
+ * self-report, and the ONLY window an operator has into the delivery
+ * ladder's behavior on sandboxed MCP-Apps hosts.
+ *
+ * Why this tool exists (2026-08-12, transport-ladder debugging): on
+ * claude.ai the view runs in a `claudemcpcontent.com` sandbox frame
+ * whose console is unreadable from outside and whose CSP blocks every
+ * network channel — when the WS → SSE → polling → bridge-pull ladder
+ * misbehaves there, NOTHING reaches server logs and the failure is
+ * invisible by construction. The runtime therefore batches its own
+ * ladder events (boot-path decision, per-rung status transitions, the
+ * live-channel logger's `channel_*` diagnostics, doorbell rings) and
+ * flushes them over the host's `tools/call` postMessage bridge — the
+ * one carrier a CSP jail cannot block.
+ *
+ * Posture: fire-and-forget diagnostics, NEVER a data plane.
+ *   - Stores nothing; emits ONE structured log line per batch.
+ *   - `sessionId` is client-claimed — a log tag, never a read key, so
+ *     no tenancy gate and no store dependency (nothing to leak).
+ *   - Bounded by the protocol schema (≤ 40 events/batch, kind ≤ 64
+ *     chars, detail ≤ 512) against log flooding; `ctx.appId` (the
+ *     PROVED identity on this carrier) tags every line so abuse is
+ *     attributable.
+ */
+import { z } from 'zod';
+import { runtimeTelemetryInputShape, } from '@ggui-ai/protocol';
+const inputSchema = runtimeTelemetryInputShape;
+const outputSchema = {
+    ok: z.literal(true),
+};
+/**
+ * Build the `ggui_runtime_telemetry` handler. Registers as
+ * app-visible (`_meta.ui.visibility: ['app']`) so MCP Apps hosts route
+ * iframe-issued `tools/call` to it per spec §401 — the same channel
+ * `ggui_runtime_submit_action` and `ggui_runtime_pull` ride.
+ */
+export function createGguiRuntimeTelemetryHandler(deps = {}) {
+    return {
+        name: 'ggui_runtime_telemetry',
+        title: '[runtime] Report Transport Telemetry',
+        audience: ['runtime'],
+        description: "Fire-and-forget transport diagnostics from the iframe runtime — batched delivery-ladder events (boot path, WS/SSE/polling/bridge rung transitions, doorbell rings) logged server-side for operator forensics. Stores nothing, returns {ok: true}. Never invoked by the model — `_meta.ui.visibility: ['app']` restricts callers to MCP Apps views; sandboxed hosts expose no console, so this tool is the only way ladder behavior there reaches an operator.",
+        inputSchema,
+        outputSchema,
+        _meta: {
+            ui: {
+                // Spec §401: only an MCP Apps view (iframe) can call. The
+                // outer agent does NOT see this tool.
+                visibility: ['app'],
+            },
+        },
+        // eslint-disable-next-line @typescript-eslint/require-await -- SharedHandler's handler contract is async; this one has no awaits (log-and-return)
+        async handler(rawInput, ctx) {
+            const parsed = z.object(inputSchema).parse(rawInput);
+            const line = {
+                sessionId: parsed.sessionId,
+                appId: ctx.appId,
+                eventCount: parsed.events.length,
+                events: parsed.events.map((e) => ({
+                    at: e.at,
+                    kind: e.kind,
+                    ...(e.detail !== undefined ? { detail: e.detail } : {}),
+                })),
+            };
+            if (deps.logger) {
+                deps.logger.info('runtime_telemetry', line);
+            }
+            else {
+                // eslint-disable-next-line no-console -- structured single-line event for log-pipeline pickup (same posture as render-identity's emitters)
+                console.log(JSON.stringify({ msg: 'runtime_telemetry', ...line }));
+            }
+            return { ok: true };
+        },
+    };
+}

package/dist/renders/slice-meta-derivation.d.ts

@@ -48,9 +48,13 @@ import { type CompiledContractValidators, type McpAppAiGguiRenderMeta } from '@g
  *      ships via a non-registry CDN (esm.sh, jsdelivr, …).
  *   2. `entry.bundleHost` + `entry.package` + `entry.version` —
  *      hostname resolution: server assembles
- *      `https://<bundleHost>/bundles/<scope>/<name>/<version>/bundle.js`
- *      (matches `@ggui-ai/registry-core`'s `bundleStorage.bundleUrl(…)`
- *      path layout — see `packages/registry-core/src/impls/memory-bundle-storage.ts`).
+ *      `https://<bundleHost>/bundles/public/<scope>/<name>/<version>/bundle.js`
+ *      — the PUBLIC prefix of `@ggui-ai/registry-core`'s
+ *      visibility-split `BundleStorage` layout (H1). Host composition
+ *      serves the anonymous render-time fetch, which only the public
+ *      prefix answers; private artifacts always arrive as explicit
+ *      `bundleUrl` values and are presign-rewritten at render-meta
+ *      time ({@link rewritePrivateBundleUrls}).
  *   3. Spec default `registry.ggui.ai` — applied when `entry.bundleHost`
  *      is absent but `package` + `version` are present (first-party
  *      hosted-registry default).
@@ -90,6 +94,48 @@ export declare function resolveGadgetUrls(entry: Partial<Pick<GadgetDescriptor,
     readonly bundleUrl?: string;
     readonly styleUrl?: string;
 };
+/**
+ * URL-path marker of the registry's PRIVATE bundle prefix (H1
+ * visibility split) — the substring {@link rewritePrivateBundleUrls}
+ * dispatches on.
+ */
+export declare const PRIVATE_BUNDLE_PREFIX = "/bundles/private/";
+/**
+ * H1 ruling 1b — rewrite a render item's PRIVATE gadget bundle URLs
+ * into fetchable equivalents at render-meta time.
+ *
+ * A private artifact's explicit `bundleUrl` / `styleUrl` / `typesUrl`
+ * point at the registry's `bundles/private/` prefix, which serves no
+ * anonymous request — the sandboxed iframe (which sends no
+ * credentials) could never load it. When a `presign` function is
+ * supplied, every descriptor URL containing
+ * {@link PRIVATE_BUNDLE_PREFIX} is replaced by `await presign(url)` —
+ * the hosted deployment presigns a short-lived object-storage URL via
+ * its pod task role. Everything else is untouched: public explicit
+ * URLs, bundleHost-composed URLs (which are public-prefix by
+ * construction, see {@link resolveGadgetUrls}), and descriptors with
+ * no URLs at all.
+ *
+ * **OSS default: passthrough.** Without `presign` the item is returned
+ * unchanged — the self-hosted story is same-origin: a self-hoster's
+ * iframe and registry share an origin, so its `/bundles/private/…`
+ * route can authenticate the fetch itself (cookie/session) or the
+ * operator simply publishes render-consumed gadgets public. No
+ * presigning infrastructure is required to run the OSS stack.
+ *
+ * MUST run BEFORE {@link deriveRenderMeta}: both the CSP origin
+ * allowlist (`deriveBundleOrigins`) and the iframe registrations
+ * (`deriveGadgetRegistrations`) read the descriptor URLs, so the
+ * rewritten (presigned) origin lands in `script-src`/`style-src`
+ * automatically and the iframe fetches exactly what the CSP allows.
+ * Zero iframe changes — the client sees an ordinary absolute URL.
+ *
+ * Purity note: `deriveRenderMeta` stays pure; this pre-pass is the
+ * ONLY projection stage that may perform I/O, and it returns a new
+ * item (never mutates) so the WeakMap-memoized URL resolution keys
+ * stay correct.
+ */
+export declare function rewritePrivateBundleUrls(item: GguiSession, presign?: (url: string) => Promise<string>): Promise<GguiSession>;
 /**
  * Per-slot contextSpec data for an active render, derived to a
  * wire-friendly array. Returns `undefined` when no slots are declared.
@@ -276,7 +322,22 @@ export declare function derivePropsJson(item: GguiSession): string | undefined;
  */
 export interface RenderMetaView {
     readonly kind?: string;
+    /** History head epoch (#483) — the mount's own epoch for the freeze latch. */
+    readonly epoch?: number;
     readonly propsJson?: string;
+    /**
+     * Base64-encoded compiled component source — the fetch-free static
+     * delivery channel for hosts whose iframe CSP forbids cross-origin
+     * fetches (no `connect-src`/`script-src` to this server). Distinct
+     * from the 2026-05-13-retired raw-ESM `componentCode` field: this is
+     * base64 (inline-embedding-safe), consumed by the iframe-runtime's
+     * seed builder which PREFERS it over `codeUrl` and never fetches.
+     * Omitted when the source exceeds {@link CODE_B64_MAX_CHARS}
+     * (over-cap renders keep the codeUrl / live channels) and for
+     * system-card renders. Each transport spreads it explicitly, like
+     * every other view field.
+     */
+    readonly codeB64?: string;
     readonly contextSlots?: ReadonlyArray<{
         name: string;
         contextName: string;
@@ -432,17 +493,44 @@ export declare function deriveContractBundle(item: GguiSession): Promise<{
     readonly bundleSource: string;
     readonly validators: CompiledContractValidators;
 } | undefined>;
+/**
+ * Ceiling on the base64 length {@link deriveRenderMeta} will inline as
+ * `codeB64` (256 KiB of base64 ≈ 192 KiB of source). Generated
+ * components run 5–50 KB; the cap exists so a pathological render
+ * cannot balloon every tool result and resource read it rides on.
+ * Over-cap renders keep their `codeUrl` / live-channel delivery.
+ */
+export declare const CODE_B64_MAX_CHARS = 262144;
 /**
  * Build the {@link RenderMetaView} for a render — the
  * single-entry-point projection function every bootstrap transport
  * SHOULD call. Composing transports take the view, spread it into
  * their own envelope alongside render/auth/runtime concerns. The
- * static-component code body itself is delivered via the render
- * handler's `codeUrl` channel (composed from `codeStore` + `codeBaseUrl`);
- * this projection only carries the wire-shape metadata.
+ * static-component code body is delivered via the render handler's
+ * `codeUrl` channel (composed from `codeStore` + `codeBaseUrl`) AND —
+ * for fetch-blocked hosts — inline via the size-capped `codeB64`
+ * field this projection carries.
  *
  * Pure. Same input → identical output, byte-for-byte.
  */
+/**
+ * Spread a {@link RenderMetaView}'s state + policy fields onto an
+ * `ai.ggui/render` slice literal — the ONE place the view→slice field
+ * list lives (#483 follow-up). Every slice emitter (ggui_render /
+ * ggui_update resultMeta, the resources/read shell, the /state route)
+ * MUST compose its envelope as `{ ...siteFields, ...spreadRenderMetaViewOntoSlice(view) }`
+ * instead of re-listing view fields: four emitters once re-spread the
+ * list by hand, and a field missing from one hand-copy is silently
+ * deleted for that transport (the `epoch` freeze-latch signal shipped
+ * exactly that way — probe 18). Mode discriminators (`kind`,
+ * `codeB64`/`codeUrl`) stay site-local on purpose: their mutual-
+ * exclusion logic differs per transport.
+ *
+ * Array fields are emitted only when non-empty (absent and `[]` are
+ * indistinguishable to every consumer's projection) and re-spread into
+ * fresh arrays so no emitter aliases the view's internals.
+ */
+export declare function spreadRenderMetaViewOntoSlice(view: RenderMetaView | undefined): Pick<McpAppAiGguiRenderMeta, 'epoch' | 'propsJson' | 'contextSlots' | 'permissionsPolicy' | 'theme' | 'gadgets'>;
 export declare function deriveRenderMeta(item: GguiSession): RenderMetaView;
 /**
  * Deps fields powering the `ai.ggui/render` slice envelope, shared by
@@ -520,7 +608,51 @@ export interface RenderSliceMetaDeps {
         readonly id?: string;
         readonly mode?: 'light' | 'dark';
     } | undefined;
+    /**
+     * H1 ruling 1b — presigner for PRIVATE gadget bundle URLs, applied
+     * via {@link rewritePrivateBundleUrls} before the render projection
+     * so a private artifact's `bundles/private/…` URLs become
+     * short-lived fetchable equivalents (and their origin lands in the
+     * CSP allowlist). Injected at the deployment boundary: the hosted
+     * pod supplies an object-storage presigner running on its task
+     * role; leaving it unset (the OSS default) passes URLs through
+     * unchanged — the self-hosted same-origin story needs no presigning.
+     *
+     * Consumed by the full-envelope projection (`ggui_render`); the
+     * `ggui_update` slice subset carries no gadget URLs or CSP, so it
+     * never presigns.
+     */
+    readonly presignPrivateBundleUrl?: (url: string) => Promise<string>;
+    /**
+     * Absolute public origin the wsToken-gated session API
+     * (`/api/sessions/:sessionId/{events,stream}`) is served on. Feeds
+     * `composeSessionApiUrls` so the `ai.ggui/render` slice stamps
+     * `pollingUrl` + `sseUrl` alongside the minted live trio.
+     *
+     * Function form (request-aware): mirrors {@link runtimeUrl}'s
+     * rationale — behind a tunnel or reverse proxy a static value can't
+     * know the public host, so the server passes a getter resolved
+     * lazily inside the request scope (X-Forwarded-Host honored for
+     * loopback peers). When unset (or the getter returns `undefined`),
+     * the assembly falls back to the ws→http origin flip of the minted
+     * trio's `wsUrl` — correct whenever the session API is served on
+     * the WS origin (OSS defaults, the cloud pod's single ingress).
+     * Operators splitting WS and HTTP across hosts MUST set this (or
+     * `publicBaseUrl` upstream), or both URLs will point at the
+     * WS-only host.
+     */
+    readonly sessionApiBaseUrl?: string | (() => string | undefined);
 }
+/**
+ * Flip a WebSocket URL's origin to its HTTP twin —
+ * `wss://host/ws` → `https://host`, `ws://host/ws` → `http://host`.
+ * The fallback base for {@link composeSessionApiUrls} when no
+ * explicit `sessionApiBaseUrl` is configured (same derivation the
+ * cloud pod uses for its oauth issuerUrl). Total: a malformed
+ * `wsUrl` returns `undefined` so slice assembly degrades to
+ * no-channel-URLs instead of throwing mid-resultMeta.
+ */
+export declare function wsOriginToHttpOrigin(wsUrl: string): string | undefined;
 /**
  * Envelope-base fields assembled from {@link RenderSliceMetaDeps} —
  * the per-call slice plumbing every emitting handler shares.
@@ -533,6 +665,14 @@ export interface RenderSliceBase {
      * the minter's legacy `token`). Empty object when no minter wired.
      */
     readonly authFields: Partial<Pick<McpAppAiGguiRenderMeta, 'wsUrl' | 'wsToken' | 'expiresAt'>>;
+    /**
+     * Token-bearing HTTP fallback URLs (`pollingUrl` + `sseUrl`),
+     * composed via `composeSessionApiUrls`. Stamped ONLY when the
+     * minter ran (both URLs embed the token) AND a session-API base
+     * resolved; empty object otherwise — the slice then honestly
+     * advertises no HTTP fallback.
+     */
+    readonly channelUrls: Partial<Pick<McpAppAiGguiRenderMeta, 'pollingUrl' | 'sseUrl'>>;
     /** Resolved theme preset id, when any layer produced one. */
     readonly themeId?: string;
     /** Resolved theme mode, when any layer produced one. */