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

package/dist/renders/props-mutation-core.js

@@ -0,0 +1,339 @@
+/**
+ * PROPS-MUTATION CORE — the single flow behind BOTH mutation tools
+ * (#483 tool split): `ggui_update` (advances the history epoch,
+ * mints a new record) and `ggui_amend` (in-place, epoch untouched).
+ * Extracted verbatim from the pre-split ggui_update handler; the
+ * per-tool deltas are parameterized on `tool`, everything else is
+ * byte-identical behavior.
+ */
+import { z } from 'zod';
+import { ContractViolationError, } from '@ggui-ai/protocol';
+import { GGUI_RENDER_UI_META } from '@ggui-ai/protocol/integrations/mcp-apps';
+import { refreshRenderIdentity } from './render-identity.js';
+import { applyGguiSessionPatch, } from './apply-ggui-session-patch.js';
+import { GguiSessionNotFoundError } from './errors.js';
+import { emitPayloadTraceEvent } from './payload-trace-sink.js';
+/**
+ * Input raw-shape shared by BOTH mutation tools — discriminated on
+ * `kind` (`'replace'` + `props` | `'merge'` + `patch`); identical wire
+ * grammar for `ggui_update` and `ggui_amend` (#483). Both validate the
+ * FINAL props (post-merge for `merge`) against the render's
+ * `propsSpec`.
+ */
+export const mutationInputSchema = {
+    /**
+     * Globally-unique render id. Optional on the wire so an in-process
+     * dispatcher (live-channel dispatch / threaded mount) can populate it
+     * via `HandlerContext.sessionId` instead. Required at the core
+     * level — see the resolve step inside `runPropsMutation`.
+     */
+    sessionId: z.string().optional(),
+    /**
+     * Mode discriminator. `'replace'` requires `props`; `'merge'`
+     * requires `patch`. The narrowing step inside the core enforces
+     * both presence + mutual exclusion.
+     */
+    kind: z.enum(['replace', 'merge']),
+    /**
+     * Full new props map. Required when `kind === 'replace'`; rejected
+     * otherwise. Validated against the GguiSession's `propsSpec` after
+     * applying.
+     */
+    props: z.record(z.string(), z.unknown()).optional(),
+    /**
+     * RFC 7396 JSON Merge Patch. Required when `kind === 'merge'`;
+     * rejected otherwise. The core applies the patch to the existing
+     * props, then validates the merged result against `propsSpec`.
+     * `null` values in the patch DELETE the corresponding key.
+     */
+    patch: z.record(z.string(), z.unknown()).optional(),
+};
+const inputSchema = mutationInputSchema;
+/**
+ * Canonical JSON stringify — object keys sorted recursively so two
+ * semantically-equal JsonObjects compare equal regardless of key
+ * insertion order. Arrays keep positional order (order is meaning
+ * there). Used by the no-op gate; props are validated JsonObjects, so
+ * no cycles by construction.
+ */
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+export async function runPropsMutation(deps, tool, input, ctx) {
+    // Strict: in-process dispatchers face exactly the protocol
+    // contract (unknown keys reject, as `updateInputSchema` does). On
+    // the MCP wire path this is a no-op by construction — the SDK's
+    // own arg validation strips unknown keys before the handler runs.
+    const parsed = z.object(inputSchema).strict().parse(input);
+    // Narrow on kind FIRST. Each branch enforces required-field +
+    // mutual-exclusion semantics that the flat raw-shape can't
+    // express. Runs before the billing gate and before any store
+    // read, so a malformed call costs nothing: no gate evaluation,
+    // no DynamoDB read, no trace emission — and the caller gets the
+    // contract error rather than whatever the gate would have said.
+    const kind = parsed.kind;
+    let patchInput;
+    if (kind === 'replace') {
+        if (parsed.props === undefined) {
+            throw new ContractViolationError({
+                tool,
+                violations: [
+                    {
+                        code: 'CTR_UPDATE_MISSING_PROPS',
+                        field: 'props',
+                        message: 'kind:"replace" requires `props` — the full new props map.',
+                    },
+                ],
+            });
+        }
+        if (parsed.patch !== undefined) {
+            throw new ContractViolationError({
+                tool,
+                violations: [
+                    {
+                        code: 'CTR_UPDATE_MIXED_FIELDS',
+                        field: 'patch',
+                        message: 'kind:"replace" must not include `patch`. Pick one mode per call.',
+                    },
+                ],
+            });
+        }
+        patchInput = { mode: 'replace', props: parsed.props };
+    }
+    else {
+        // kind === 'merge'
+        if (parsed.patch === undefined) {
+            throw new ContractViolationError({
+                tool,
+                violations: [
+                    {
+                        code: 'CTR_UPDATE_MISSING_PATCH',
+                        field: 'patch',
+                        message: 'kind:"merge" requires `patch` — the RFC 7396 JSON Merge Patch delta.',
+                    },
+                ],
+            });
+        }
+        if (parsed.props !== undefined) {
+            throw new ContractViolationError({
+                tool,
+                violations: [
+                    {
+                        code: 'CTR_UPDATE_MIXED_FIELDS',
+                        field: 'props',
+                        message: 'kind:"merge" must not include `props`. Pick one mode per call.',
+                    },
+                ],
+            });
+        }
+        patchInput = { mode: 'merge', patch: parsed.patch };
+    }
+    // Pre-mutation gate. Throws to abort BEFORE any state change.
+    // OSS default: no gate bound, no-op. Cloud binds a traffic-class
+    // gate here.
+    if (deps.billingGate) {
+        await deps.billingGate.preCheck({ ctx, tool });
+    }
+    // Resolve sessionId from wire OR threaded HandlerContext.
+    const sessionId = parsed.sessionId ?? ctx.sessionId;
+    if (!sessionId) {
+        throw new GguiSessionNotFoundError('', `${tool}: sessionId is required on the wire (or threaded via HandlerContext for in-process dispatchers).`);
+    }
+    // Tenancy gate. Cross-tenant + missing surface uniformly as
+    // GguiSessionNotFoundError so cross-tenant existence is not leaked.
+    const stored = await deps.renderStore.get(sessionId);
+    if (!stored || stored.appId !== ctx.appId) {
+        throw new GguiSessionNotFoundError(sessionId);
+    }
+    // Mount-URI identity (#471 round-4 live finding): `ggui_render`
+    // stamped `.../<sessionId>/<contractKey>` as the mounted iframe's
+    // resource URI. Hosts that key result→iframe routing on URI
+    // equality only deliver this update's result to the live card
+    // when the update reproduces that EXACT URI — a bare
+    // `.../<sessionId>` routes fine on OUR server but is a different
+    // string to the host, so the forwarded result misses the mount
+    // and the card never repaints. The contract key cannot be
+    // recomputed from the render row (it hashes the handshake-agreed
+    // contract — see render-identity.ts); read it from the durable
+    // identity record. Absent store/record ⇒ bare session URI
+    // (pre-identity renders keep the old shape).
+    let contractSegment = '';
+    if (deps.renderIdentityStore) {
+        try {
+            const identity = await deps.renderIdentityStore.get(sessionId);
+            if (identity?.contractKey) {
+                contractSegment = `/${identity.contractKey}`;
+            }
+        }
+        catch {
+            // Best-effort, matching every identity-store touch in this
+            // handler: a failed read must not fail the tool call, and the
+            // bare URI below stays routable on our server.
+        }
+    }
+    const mountResourceUri = `${GGUI_RENDER_UI_META.resourceUri}/${sessionId}${contractSegment}`;
+    // Devtools payload trace. No-op when no sink is registered.
+    // Fires AFTER the tenancy gate so cross-tenant probes never leak
+    // into the trace. Payload is the validated wire shape.
+    emitPayloadTraceEvent({
+        direction: 'outbound-update',
+        sessionId,
+        appId: ctx.appId,
+        tool,
+        payload: parsed,
+    });
+    // applyGguiSessionPatch throws ContractViolationError{tool:'ggui_update'}
+    // on propsSpec fail (validated against the FINAL props — post-merge
+    // for `merge` mode). Propagates verbatim — transport layer maps.
+    //
+    // Pull renderTarget from `stored.render` — both ComponentGguiSession and
+    // SystemGguiSession satisfy `GguiSessionTarget` (id + optional propsSpec +
+    // optional props). McpAppsGguiSession has no propsSpec — the helper's
+    // assertPropsContract no-ops on absent spec, so MCP Apps renders
+    // accept any patch shape (the iframe owns its own validation).
+    const renderTarget = stored.render;
+    const { updatedSession, finalProps } = applyGguiSessionPatch({
+        render: renderTarget,
+        tool,
+        ...patchInput,
+    });
+    // No-op gate (#471 round-3 live finding): a CONFORMING patch that
+    // leaves the final props semantically identical to the current
+    // state is almost always an agent error — the live failure mode
+    // was an LLM echoing the card's existing props back (believing it
+    // had "switched" the UI) and telling the user the card changed
+    // while nothing on screen could. The contract validated it, the
+    // commit would apply it, and no signal existed anywhere. Make the
+    // non-change OBSERVABLE instead of silently committing: skip the
+    // write + fan-out (there is nothing to deliver) and return an
+    // honest `updated: false` with a model-visible warning telling
+    // the agent what to do instead.
+    const priorProps = 'props' in renderTarget && renderTarget.props !== undefined
+        ? renderTarget.props
+        : {};
+    if (stableStringify(finalProps) === stableStringify(priorProps)) {
+        return {
+            sessionId,
+            updated: false,
+            mountResourceUri,
+            // No record minted on a no-op — the head epoch is untouched.
+            epoch: stored.render.epoch ?? 0,
+            warning: 'NO-OP: this patch left the props identical to the current state — nothing changed on screen. If you meant to refresh the UI, send values that actually differ; if the user’s gesture asks for a DIFFERENT surface (menu selection, navigation), run ggui_handshake + ggui_render for the next UI instead of updating this one.',
+        };
+    }
+    // Epoch (#483): the row is the AUTHORITY, advanced in the SAME
+    // commit as the props write — update mints a new history record
+    // (epoch + 1); amend leaves the head untouched. The reminted
+    // ledger event below is the wire SIGNAL frames latch on, not the
+    // counter (the event ring is horizon-bounded).
+    const priorEpoch = stored.render.epoch ?? 0;
+    const nextEpoch = tool === 'ggui_update' ? priorEpoch + 1 : priorEpoch;
+    const sessionToCommit = tool === 'ggui_update'
+        ? { ...updatedSession, epoch: nextEpoch }
+        : updatedSession;
+    // Persist via the commit seam — first-write mints, re-write
+    // replaces visible-bits in place. Lifecycle fields owned by the
+    // store (createdAt, eventSequence, hostSession) preserved across
+    // the upsert.
+    const committed = await deps.renderStore.commit({
+        render: sessionToCommit,
+        appId: stored.appId,
+        ...(stored.userId !== undefined ? { userId: stored.userId } : {}),
+        ...(stored.endUserIdentity !== undefined
+            ? { endUserIdentity: stored.endUserIdentity }
+            : {}),
+        ...(stored.themeId !== undefined ? { themeId: stored.themeId } : {}),
+        ...(stored.hostSession !== undefined
+            ? { hostSession: stored.hostSession }
+            : {}),
+    });
+    // Ledger append — the delivery substrate for the PULL rungs of
+    // the failover ladder (HTTP `/events` polling and the
+    // `ggui_runtime_pull` bridge rung read ONLY the event ledger).
+    // Without this append a props update is invisible to every
+    // cursor-based reader: live evidence (#471 round-3 forensics)
+    // showed eventSequence stuck at 0 across real updates — pull
+    // clients would poll politely forever and receive nothing.
+    // Best-effort: persistence already succeeded, and the push
+    // planes (WS/SSE fan-out, forwarded tool-result slice) deliver
+    // independently of the ledger.
+    let committedForIdentity = committed;
+    try {
+        // `'ui.updated'` is the canonical LEDGER taxonomy name; the
+        // live-channel FRAME namespace calls the same thing
+        // `props_update`. The translation lives at the client parse
+        // core (events-polling), never here — the ledger speaks only
+        // taxonomy types.
+        // The props event carries the epoch it belongs to (#483) so
+        // frames can ignore props from a NEWER epoch than their own
+        // instead of flashing the new state before the freeze lands.
+        const seq = await deps.renderStore.appendEvent({
+            sessionId,
+            type: 'ui.updated',
+            data: { sessionId, props: finalProps, epoch: nextEpoch },
+        });
+        // The append advanced the row's high-water mark past the
+        // commit-time snapshot — thread the returned seq so the
+        // identity refresh records the ledger state INCLUDING this
+        // update's own event (record.seqAtLastCommit tracks the row).
+        committedForIdentity = { ...committed, eventSequence: seq };
+        // Epoch boundary AFTER the props event (#483): pinned #N
+        // reconstruction replays props UP TO AND INCLUDING the N-th
+        // remint boundary, so the boundary must follow its own props.
+        // This is also the freeze signal older-epoch frames latch on.
+        if (tool === 'ggui_update') {
+            const remintSeq = await deps.renderStore.appendEvent({
+                sessionId,
+                type: 'ui.reminted',
+                data: { epoch: nextEpoch },
+            });
+            committedForIdentity = {
+                ...committedForIdentity,
+                eventSequence: remintSeq,
+            };
+        }
+    }
+    catch {
+        // Silent — a ledger hiccup must not fail the tool call; the
+        // pull rungs degrade to the ack/mount snapshot on next
+        // (re)subscribe, same recovery every reader already has.
+    }
+    // Keep the durable identity record's view of this row current.
+    // Reads the row the commit RETURNED (seq-adjusted above) so the
+    // record can't disagree with what was persisted.
+    await refreshRenderIdentity(deps.renderIdentityStore, committedForIdentity);
+    // Best-effort live delivery. Persistence is the source of truth;
+    // the live-channel fan-out is a latency optimization. Errors are
+    // swallowed — a failed notify must not fail the tool call (the
+    // renderer reads canonical state via `ack.render` on next
+    // (re)subscribe).
+    if (deps.propsUpdateNotifier) {
+        try {
+            await deps.propsUpdateNotifier.sendPropsUpdate(sessionId, finalProps, nextEpoch);
+        }
+        catch {
+            // Silent: stay aligned with `safelyNotifyGguiSessionCommit`'s
+            // posture in render.ts. A throwing notifier is a host-side
+            // bug, not a tool-call failure.
+        }
+    }
+    // Callers own presentation: ggui_update composes the pinned
+    // `#epoch` form from this bare mount URI; ggui_amend returns it
+    // bare (the live head).
+    return {
+        sessionId,
+        updated: true,
+        mountResourceUri,
+        epoch: nextEpoch,
+    };
+}

package/dist/renders/render.d.ts

@@ -704,6 +704,7 @@ declare const outputSchema: {
             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>>;
@@ -713,6 +714,7 @@ declare const outputSchema: {
         example: z.ZodString;
         args: z.ZodObject<{
             sessionId: z.ZodString;
+            timeout: z.ZodNumber;
         }, z.core.$strip>;
     }, z.core.$strip>>;
 };

package/dist/renders/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/renders/render.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/renders/render.ts"],"names":[],"mappings":"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"}

package/dist/renders/render.js

@@ -64,7 +64,7 @@ import { validatePropsData, ContractViolationError, validateContract, renderInpu
 import { emitCacheTraceEvent, newCacheTraceId, truncateCacheTraceIntent, } from './cache-trace-sink.js';
 import { emitPayloadTraceEvent } from './payload-trace-sink.js';
 import { isVisibleToCaller } from './tenancy.js';
-import { assembleRenderSliceBase, deriveRenderMeta, derivePublicEnvProjection, deriveContractBundle, rewritePrivateBundleUrls, } from './slice-meta-derivation.js';
+import { assembleRenderSliceBase, deriveRenderMeta, derivePublicEnvProjection, deriveContractBundle, rewritePrivateBundleUrls, spreadRenderMetaViewOntoSlice, } from './slice-meta-derivation.js';
 /**
  * Input raw-shape.
  *
@@ -122,6 +122,7 @@ const RENDER_FAILURE_GUIDANCE = {
     VALIDATION_ERROR: 'Fix the configuration or input named in the message',
     NO_PLATFORM_KEY: 'Have the operator set a provider key for this app, or switch the app to a model whose key is configured',
     NO_CREDENTIALS: 'Have the operator configure provider credentials on the server (environment variable or credentials file)',
+    GENERATION_QUEUE_OVERLOADED: 'No attempt was made — this is safe to retry immediately, or after a short backoff if it recurs',
 };
 /**
  * Model-visible content text for the failure envelope. Pinned format:
@@ -138,7 +139,7 @@ function buildRenderFailureText(failure) {
  * Project a generator-result {@link GenerationError} code onto the
  * canonical render-failure enum. `COMPILATION_ERROR` is a
  * finer-grained production failure, not a distinct wire class — it
- * folds into `PRODUCTION_FAILED`; the other four members map 1:1.
+ * folds into `PRODUCTION_FAILED`; the other five members map 1:1.
  */
 function toCanonicalRenderErrorCode(code) {
     switch (code) {
@@ -148,6 +149,8 @@ function toCanonicalRenderErrorCode(code) {
             return 'NO_PLATFORM_KEY';
         case 'NO_CREDENTIALS':
             return 'NO_CREDENTIALS';
+        case 'GENERATION_QUEUE_OVERLOADED':
+            return 'GENERATION_QUEUE_OVERLOADED';
         case 'PRODUCTION_FAILED':
         case 'COMPILATION_ERROR':
             return 'PRODUCTION_FAILED';
@@ -210,10 +213,15 @@ export function createGguiRenderHandler(deps) {
         inputSchema,
         outputSchema,
         _meta: {
-            // §2.4.1 entry-point lock: `_meta.ui.resourceUri` +
-            // `_meta.ui.visibility` per the MCP Apps spec. Exactly one ggui
-            // tool carries these; expanding this set without revisiting the
-            // design lock is a boundary violation.
+            // §2.4.1 entry-point lock, REVISED 2026-08-11: `_meta.ui.resourceUri`
+            // + `_meta.ui.visibility` per the MCP Apps spec. Exactly TWO ggui
+            // tools carry these — ggui_render (the entry point) and
+            // ggui_update (same template). The lock originally said one, but
+            // live claude.ai evidence (#471 round-2 retest) showed hosts
+            // forward a tool's RESULTS to the mounted iframe only when the
+            // tool's declaration carries the binding — without it every
+            // ggui_update landed server-side and the iframe never repainted.
+            // Expanding beyond these two still requires revisiting this note.
             //
             // Legacy flat-key (`_meta["ui/resourceUri"]`) is stamped
             // automatically by `registerAppTool` in `build-mcp.ts` — we
@@ -1225,9 +1233,15 @@ export function createGguiRenderHandler(deps) {
             const nextStep = hasActions
                 ? {
                     tool: 'ggui_consume',
-                    description: 'Drain the action pipe for this render — long-polls until a user gesture arrives or 15s timeout.',
-                    example: `ggui_consume({ sessionId: "${sessionId}" })`,
-                    args: { sessionId },
+                    // Imperative + honest: `timeout` MUST ride the hint —
+                    // consume's own default is 0 (single non-blocking drain),
+                    // so an agent copying a timeout-less example gets an
+                    // instant empty result and reasonably ends its turn (the
+                    // first live claude.ai test died exactly this way). 25 is
+                    // the server-enforced per-call cap (SPEC §7.3).
+                    description: "The UI has interactive actions. After this turn's other tool calls, you may long-poll once (waits up to 25s) to catch an immediate gesture; if `events` comes back empty, end your turn — later gestures arrive as new user messages carrying their own consume directive.",
+                    example: `ggui_consume({ sessionId: "${sessionId}", timeout: 25 })`,
+                    args: { sessionId, timeout: 25 },
                 }
                 : undefined;
             // Render response architecture (2026-05-13):
@@ -1385,7 +1399,7 @@ export function createGguiRenderHandler(deps) {
             // resolution (operator-debug-wins: live console pick beats the
             // per-render `ggui_render.themeId` beats static deps) all live
             // in ONE helper shared with `ggui_update`.
-            const { runtimeUrl, authFields, themeId: resolvedThemeId, themeMode: resolvedThemeMode, } = assembleRenderSliceBase(deps, {
+            const { runtimeUrl, authFields, channelUrls, themeId: resolvedThemeId, themeMode: resolvedThemeMode, } = assembleRenderSliceBase(deps, {
                 sessionId: output.sessionId,
                 appId: ctx.appId,
                 renderThemeId,
@@ -1436,17 +1450,14 @@ export function createGguiRenderHandler(deps) {
                 appId: ctx.appId,
                 runtimeUrl,
                 ...authFields,
+                // Token-bearing HTTP fallback rungs (pollingUrl + sseUrl),
+                // composed by the ONE shared helper — present exactly when
+                // the live trio above was minted and a session-API base
+                // resolved. See `assembleRenderSliceBase`.
+                ...channelUrls,
                 ...(streamWebSocketLocalTools !== undefined
                     ? { streamWebSocketLocalTools }
                     : {}),
-                // Operator-registered wrappers ride the render slice so the
-                // runtime can dynamic-import each before mounting. Projected
-                // by `deriveRenderMeta` from the (enriched) render contract;
-                // only emitted when wrappers are actually declared so
-                // pure-STDLIB apps stay byte-identical.
-                ...(view.gadgets !== undefined && view.gadgets.length > 0
-                    ? { gadgets: view.gadgets }
-                    : {}),
                 // Minimum-disclosure subset of App.publicEnv (union of
                 // declared wrappers' `requires`). Filtered above by
                 // `derivePublicEnvProjection`.
@@ -1460,19 +1471,13 @@ export function createGguiRenderHandler(deps) {
                 ...(resolvedThemeMode !== undefined
                     ? { themeMode: resolvedThemeMode }
                     : {}),
-                // Resolved per-app theme overlay (mode + `--ggui-*` variable map)
-                // projected by `deriveRenderMeta` from the render's `theme`
-                // sidecar. Only emitted when the App declared a theme so
-                // theme-less apps stay byte-identical.
-                ...(view.theme !== undefined ? { theme: view.theme } : {}),
-                ...(view.permissionsPolicy !== undefined
-                    ? { permissionsPolicy: [...view.permissionsPolicy] }
-                    : {}),
                 ...(lastSequence !== undefined ? { lastSequence } : {}),
-                ...(view.propsJson !== undefined ? { propsJson: view.propsJson } : {}),
-                ...(view.contextSlots !== undefined
-                    ? { contextSlots: [...view.contextSlots] }
-                    : {}),
+                // State + policy view fields (gadgets, theme overlay,
+                // permissionsPolicy, propsJson, contextSlots, and the #483
+                // freeze-latch self-epoch — a fresh render is epoch 0) — ONE
+                // shared spread so this emitter cannot drift from ggui_update /
+                // the shell / the /state route.
+                ...spreadRenderMetaViewOntoSlice(view),
                 // Content-addressable contract validators. Both fields present
                 // together or absent together — iframe-runtime treats absence
                 // as "no validators".

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"}