@ggui-ai/protocol 0.13.0 → 0.15.0

package/dist/schemas/mcp.js

@@ -25,24 +25,10 @@
  */
 import { z } from 'zod';
 import { blueprintDraftSchema, handshakeSuggestionSchema, } from './handshake-suggestion.js';
-import { dataContractSchema } from './data-contract.js';
-import { blueprintVarianceSchema } from './blueprint.js';
-// ── Shared Sub-Schemas ──
-export const viewportSchema = z.object({
-    width: z.number(),
-    height: z.number(),
-});
-export const interfaceContextSchema = z.object({
-    viewport: viewportSchema,
-    platform: z.enum(['web', 'mobile', 'desktop']),
-    deviceType: z.enum(['phone', 'tablet', 'desktop']),
-    orientation: z.enum(['portrait', 'landscape']),
-    devicePixelRatio: z.number().optional(),
-    touchPrimary: z.boolean().optional(),
-    shellType: z.enum(['chat', 'fullscreen', 'spatial']).optional(),
-    colorScheme: z.enum(['light', 'dark']).optional(),
-    reducedMotion: z.boolean().optional(),
-}).passthrough();
+import { dataContractSchema, jsonObjectSchema, jsonValueSchema } from './data-contract.js';
+import { blueprintVarianceSchema, blueprintSourceSchema } from './blueprint.js';
+import { MCP_ENDPOINT_REFUSAL_CODES, REFUSAL_RETRIES, RENDER_GATE_REFUSAL_CODES, } from '../types/refusal-codes.js';
+import { RUNTIME_TELEMETRY_MAX_EVENTS } from './runtime-telemetry-limits.js';
 // ── Wired Tool Input Shapes ──
 //
 // Raw zod shapes for the non-lifecycle tools. The SHAPE is the canonical
@@ -325,9 +311,14 @@ export const renderInputShape = {
     /**
      * Typed `infra` envelope. Today carries one field (`model`); future
      * expansion (temperature, max_tokens, provider hints) lands here
-     * additively. `model` MUST be a provider-prefixed id
-     * (`provider/model-name`); a bound generator may also accept
-     * generator-specific prefixes for alternate transports.
+     * additively. `model` MUST parse as a model route in either wire form —
+     * canonical `provider:model` or LiteLLM `provider/model` (aliases resolve
+     * in both). The mechanism is `renderInputEnvelopeSchema`
+     * (`schemas/render-input-envelope.ts`), which the render handler parses
+     * BEFORE its pre-generation gate; this registered shape stays
+     * parser-free by design so a browser bundle never carries the route
+     * tables (ggui#818). A bound generator may also accept generator-specific
+     * prefixes for alternate transports.
      *
      * Strict — extra keys at `infra.*` are not silently dropped, so a
      * typo (`infra.modelId`) surfaces as a clear zod path instead of a
@@ -339,7 +330,7 @@ export const renderInputShape = {
             .string()
             .min(1)
             .optional()
-            .describe('Provider-prefixed model id (e.g., `anthropic/claude-haiku-4-5`, `openai/gpt-5`). Generator-specific prefixes (e.g., `bedrock/...` for AWS Bedrock routing) supported when the bound generator handles them.'),
+            .describe('Model route in either wire form — canonical `anthropic:claude-haiku-4-5-20251001` or LiteLLM `anthropic/claude-haiku-4-5` (aliases resolve in both); generator-specific prefixes (e.g. `bedrock/...`) route to that transport. A value that parses in neither form fails the handler input parse at `infra.model`, before any pre-generation gate; `model_not_in_tier` is only ever a well-formed route with no rate row on the effective tier.'),
     })
         .strict()
         .optional(),
@@ -445,6 +436,177 @@ export const renderErrorSchema = z.object({
         .string()
         .describe('Human-readable failure detail — fold into the next attempt or surface to the operator.'),
 });
+/**
+ * The three outcomes a `ggui_render` result can report (SPEC §7.1,
+ * ggui#786). A reader branches on this rather than guessing from which
+ * fields happen to be present:
+ *
+ *   - `rendered` — the render ran and produced an interface. The
+ *     identity fields (`sessionId`, `action`, `contractHash`,
+ *     `blueprintId`, `variantKey`, `cache`) are all present.
+ *   - `failed` — generation RAN and did not produce a component. The
+ *     error session IS committed, so the identity fields are present
+ *     and `error` carries the classification. The handshake is
+ *     consumed.
+ *   - `refused` — the deployment declined the call BEFORE it did any
+ *     work: no state read, nothing committed, no spend. (The SDK has
+ *     already checked the call against the declared `inputSchema` —
+ *     the claim is nothing READ, not nothing validated.) The identity
+ *     fields are structurally ABSENT and `refusal` carries the whole
+ *     story; the handshake is INTACT, so the same id is valid on a
+ *     retry.
+ *
+ * Declared HERE rather than in `types/mcp.ts` (which re-exports the
+ * inferred type) so `types/render.ts` can reference it without a
+ * type-only import cycle through `types/mcp.ts` — same convention as
+ * {@link renderErrorCodeSchema}.
+ */
+export const renderOutcomeSchema = z.enum(['rendered', 'failed', 'refused']);
+/**
+ * In-result PRE-GENERATION REFUSAL marker (SPEC §7.1's refused arm,
+ * ggui#786). Present iff `outcome: 'refused'`.
+ *
+ * `code` draws from the closed render-gate subset of
+ * `PRE_GENERATION_REFUSAL_CODES` — a code that is not registered fails
+ * this enum at the transport, loudly. It is a bug, never a wire state.
+ *
+ * An agent MUST NOT auto-retry an `after-fix` refusal whose registry
+ * row names a `fixBy` other than `caller`: the fix belongs to the app's
+ * owner, the tenant, or the operator, and retrying does not perform it.
+ */
+/**
+ * The refusal projection every surface shares — what a client acts on:
+ * the diagnostic, the one recovery step, and how the call becomes
+ * possible again. Defined ONCE and spread into each surface's envelope
+ * (the render gate's {@link renderRefusalSchema}, the per-app endpoint's
+ * {@link transportRefusalSchema}); the `code` enum is per surface,
+ * derived from the registry. `fixBy` never travels — it is a registry
+ * attribute a client reads by `code`.
+ */
+const refusalProjectionFields = {
+    message: z
+        .string()
+        .describe('Precise diagnostic — what was checked, and against what. Surface it to the operator; do not parse it.'),
+    fix: z
+        .string()
+        .describe('The one recovery step, addressed to the party that can take it. Retry the same call only when that party is the caller.'),
+    retry: z
+        .enum(REFUSAL_RETRIES)
+        .describe("How the call becomes possible again. 'after-fix': a named party acts and the same call then succeeds. 'next-period': time restores it at the next period boundary. 'later': transient — retry after a short delay. 'never': no caller action restores it under this identity."),
+};
+export const renderRefusalSchema = z.object({
+    code: z
+        .enum(RENDER_GATE_REFUSAL_CODES)
+        .describe("Registered refusal state. Look the code up in the protocol's refusal registry for its retry class and which party can act; the accompanying `fix` names the one recovery step."),
+    ...refusalProjectionFields,
+    handshake: z
+        .literal('intact')
+        .describe('The handshake was NOT consumed — nothing was read. The same handshakeId is valid on a retry.'),
+    balanceCentsAtCheck: z
+        .number()
+        .int()
+        .optional()
+        .describe('Present only when the refusing check read a balance: its value at the moment of the check.'),
+});
+/**
+ * A refusal typed on the per-app MCP endpoint's authorization
+ * (ggui#825) — the registry projection WITHOUT the render-only fields:
+ * no `handshake` (nothing was handed), no `balanceCentsAtCheck`. Strict:
+ * a render-only field here is a bug, never a wire state. `code` draws
+ * from {@link MCP_ENDPOINT_REFUSAL_CODES} — today exactly
+ * `app_deprovisioned`, the one refusal with a tenant-side fix and
+ * therefore the one that MUST be legible where a deleted app and a bad
+ * credential would otherwise look alike.
+ */
+export const transportRefusalSchema = z.strictObject({
+    code: z
+        .enum(MCP_ENDPOINT_REFUSAL_CODES)
+        .describe("Registered refusal state on the per-app endpoint. Look the code up in the protocol's refusal registry for its retry class and which party can act."),
+    ...refusalProjectionFields,
+});
+/**
+ * The JSON-RPC error object a per-app MCP endpoint answers with when it
+ * refuses a request for a typed reason (ggui#825, codes ruled in
+ * ggui#836): HTTP 403, `code` `-32003` (`APP_NOT_FOUND` — the endpoint
+ * no longer serves this app, the same reading ggui's embed host gives a
+ * proxy 403) and `message` `App not found`, plus `data.refusal`, which
+ * makes it legible. `data` is strict: it carries the refusal and nothing
+ * else. An authorization failure that is not a registry state answers
+ * HTTP 403 with `-32001` (`UNAUTHORIZED`) and NO `data` — the three
+ * untyped arms stay indistinguishable among themselves by contract:
+ * naming any of them would say which is true. A first-party server
+ * never chooses `-32000`: it is the SDK client's `ConnectionClosed`, so
+ * a bare 403 and a dropped socket would share a number.
+ */
+export const transportRefusalErrorSchema = z.strictObject({
+    code: z.literal(-32003),
+    message: z.literal('App not found'),
+    data: z.strictObject({ refusal: transportRefusalSchema }),
+});
+/**
+ * The COMPLETE structuredContent of a refused tool result — the whole
+ * payload, not a slice of it. Strict on purpose: a refusal commits
+ * nothing, so ANY other key (a `sessionId`, a `resourceUri`, an
+ * `error`) means the projection leaked state that does not exist.
+ *
+ * Today `ggui_render` is the only tool that carries a refusing gate;
+ * {@link renderOutputSchema} delegates its refused arm here rather than
+ * restating the rules, so there is exactly ONE declaration of them.
+ *
+ * NOT reusable verbatim by a second refusing tool, despite the strict
+ * shape reading as generic: {@link renderRefusalSchema} REQUIRES
+ * `handshake: 'intact'`, and that field is render-only by
+ * construction — a mutation consumes no handshake, so it has nothing
+ * to report intact. A mutation arm therefore lands WITH its first
+ * emitter, sharing the facts this envelope carries (`code`, `message`,
+ * `fix`, `retry`, one closed registry) and carrying no `handshake`
+ * field at all (ggui#798).
+ */
+export const refusedOutputSchema = z.strictObject({
+    outcome: z.literal('refused'),
+    refusal: renderRefusalSchema,
+});
+/**
+ * The refused arm's presence rule: the WHOLE payload must be
+ * {@link refusedOutputSchema}. Delegating here rather than restating
+ * the rule inline keeps one declaration of the RENDER refused
+ * envelope. A mutation arm cannot delegate to it — that schema
+ * REQUIRES `handshake: 'intact'` — so it mints its own with its first
+ * emitter, sharing the facts and carrying no `handshake` (ggui#798).
+ */
+function refineRefusedArm(value, ctx) {
+    if (refusedOutputSchema.safeParse(value).success)
+        return;
+    ctx.addIssue({
+        code: 'custom',
+        message: "outcome 'refused' MUST carry a registered `refusal` and nothing else — a refusal commits nothing, so no identity field and no `error` may appear beside it.",
+    });
+}
+/**
+ * Report a field the committed arms (`rendered` / `failed`) require but
+ * the payload omits. The fields are optional at the schema level only
+ * to make room for the refused arm; demoting them must not weaken the
+ * committed arms, which is what this restores.
+ */
+function requireOnCommittedArm(present, field, outcome, ctx) {
+    if (present)
+        return;
+    ctx.addIssue({
+        code: 'custom',
+        path: [field],
+        message: `outcome '${outcome}' MUST carry \`${field}\` — a committed render reports its full identity.`,
+    });
+}
+/** `refusal` rides the refused arm only. */
+function rejectRefusalOnCommittedArm(refusal, outcome, ctx) {
+    if (refusal === undefined)
+        return;
+    ctx.addIssue({
+        code: 'custom',
+        path: ['refusal'],
+        message: `\`refusal\` is present only on outcome 'refused', not '${outcome}'.`,
+    });
+}
 /**
  * Canonical failure codes for a `resources/read` on a render locator
  * (`ui://ggui/render/{sessionId}/{blueprintKey}`). Closed enum.
@@ -498,9 +660,10 @@ export const resourceReadErrorSchema = z.object({
         .describe('Extra diagnostic context for operators. Dropped on NOT_FOUND so a denied read cannot be told apart from a miss.'),
 });
 /**
- * Wire-output shape — `{sessionId, resourceUri?, action, contractHash,
- * cache, error?, nextStep?}`. `contractHash` (data-contract identity)
- * and `cache` (reuse outcome) are required wire fields on this schema.
+ * Wire-output shape. `outcome` is the discriminant and the only
+ * unconditionally required field; which of the others exist follows
+ * from it, per the THREE OUTCOMES section below — that section is the
+ * single summary of this shape, so do not restate it here.
  * The handler carries `shortCode`, `codeReady`, `handshakeId`,
  * `decision`, `contract`, `codeUrl`, `codeHash`
  * on its internal `RenderOutput` TS shape for telemetry / post-classify
@@ -514,17 +677,38 @@ export const resourceReadErrorSchema = z.object({
  * `render-resource/...`). Leaving a dead URL on the wire had the model
  * hallucinating links that resolve nowhere.
  *
- * Failure envelope (SPEC §7.1): a failed/rejected generation returns
- * this same schema-conformant shape on an `isError: true` tool result —
- * `error` present, `resourceUri` absent (nothing mountable), no
- * `_meta` on the result. The error GguiSession is still committed, so
- * `sessionId` remains a live handle into the session channel.
+ * THREE OUTCOMES (SPEC §7.1, ggui#786). Every result carries
+ * {@link renderOutcomeSchema} on `outcome`, and the identity fields are
+ * present IFF something was committed — which is why they are optional
+ * at the schema level and pinned by the presence refinement below:
+ *
+ *   - `rendered` — identity fields present; `resourceUri` present iff
+ *     mountable; no `error`, no `refusal`.
+ *   - `failed` — generation ran and produced nothing. Identity fields
+ *     present (the error GguiSession IS committed, so `sessionId`
+ *     remains a live handle into the session channel), `error`
+ *     present, `resourceUri` absent, no `_meta` on the result. The
+ *     handshake is consumed.
+ *   - `refused` — the deployment declined before doing any work.
+ *     Identity fields ABSENT, `refusal` present, no `error`, no
+ *     `nextStep`, no `_meta`. Nothing was committed and the handshake
+ *     is intact. The refused arm's whole envelope is
+ *     {@link refusedOutputSchema}.
+ *
+ * The root stays ONE object with a discriminant field rather than a
+ * discriminated union: the MCP spec's `Tool.outputSchema` root MUST be
+ * a JSON Schema of type `object`, and the SDK registers zod raw shapes.
+ * TypeScript narrowing is via the guards at the bottom of this file
+ * ({@link isRenderedOutput} / {@link isFailedRenderOutput} /
+ * {@link isRefusedRenderOutput}), never a parallel union type.
  *
  * Post-Phase-B the `'compose'` action enum value is gone — there is no
  * stack of N renders to compose against.
  */
 export const renderOutputSchema = z.object({
-    sessionId: z.string(),
+    outcome: renderOutcomeSchema.describe("Which of the three outcomes this result reports. 'rendered': an interface was produced. 'failed': generation ran and produced none — the session is committed and `error` classifies it. 'refused': the deployment declined before doing any work — `refusal` carries the state, nothing was committed, and the handshake is still valid."),
+    /** Present iff something was committed — absent on a refusal. */
+    sessionId: z.string().optional(),
     /**
      * Spec-canonical MCP-Apps entry-point — same `ui://ggui/render/{id}`
      * URI surfaced on `_meta.ui.resourceUri`. Surfacing it on the LLM-
@@ -541,17 +725,24 @@ export const renderOutputSchema = z.object({
         .string()
         .optional()
         .describe('MCP-Apps mount URI (ui://ggui/render/{id}). Present iff the render is mountable; absent on a failed render.'),
-    action: z.enum(['create', 'reuse', 'update', 'replace', 'declined']),
+    action: z
+        .enum(['create', 'reuse', 'update', 'replace', 'declined'])
+        .optional(),
     contractHash: z
         .string()
+        .optional()
         .describe('Canonical hash of the rendered data contract (shape only — fields, types, specs). Same hash ⟺ same data flow.'),
     blueprintId: z
         .string()
+        .optional()
         .describe('Opaque id of the materialised component for this render. On the handshake-decided reuse paths (accept a cache-origin proposal, or a variance re-aim that resolves to an existing variant) it is the stored id — equal ids across renders mean the same stored component. override.contract always generates cold and mints a fresh id, even for an identical contract.'),
     variantKey: z
         .string()
+        .optional()
         .describe('Canonical hash of the design-time variance (persona, aesthetic, seed prompt, context). With contractHash it forms the reuse key: the same pair reuses one component; a different variant of the same contract gets its own.'),
-    cache: renderCacheMarkerSchema.describe('Reuse outcome for this render: whether a stored component was served, its similarity, the matched component id, and how many generation calls that avoided.'),
+    cache: renderCacheMarkerSchema
+        .optional()
+        .describe('Reuse outcome for this render: whether a stored component was served, its similarity, the matched component id, and how many generation calls that avoided.'),
     /**
      * In-result failure marker — present iff the tool result is
      * `isError: true`. The structuredContent stays schema-conformant on
@@ -561,6 +752,14 @@ export const renderOutputSchema = z.object({
     error: renderErrorSchema
         .optional()
         .describe('Present iff the tool result is isError — canonical {code, message} for a failed/rejected generation. Absent on success.'),
+    /**
+     * In-result PRE-GENERATION REFUSAL marker — present iff
+     * `outcome: 'refused'`, and then it is the ONLY field besides
+     * `outcome` (see {@link refusedOutputSchema}).
+     */
+    refusal: renderRefusalSchema
+        .optional()
+        .describe('Present iff outcome is refused — the registered state the deployment declined on, plus the one recovery step. Nothing was committed and the handshake is still valid.'),
     /**
      * Wire-shape recovery hint for the next call. Emitted ONLY when the
      * rendered contract has a non-empty `actionSpec` — i.e. the agent will
@@ -586,6 +785,56 @@ export const renderOutputSchema = z.object({
             timeout: z.number(),
         }),
     }).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.'),
+}).superRefine((value, ctx) => {
+    // Present-iff-committed. NOTE for implementors: this refinement is
+    // attached to the COMPOSED schema. A consumer that decomposes the
+    // schema to its raw shape and rebuilds it (`z.object(schema.shape)`,
+    // which is how the MCP SDK registers a tool's outputSchema) loses
+    // these rules — which is why the transport validates a refused
+    // payload against `refusedOutputSchema` directly. See SPEC §7.1.
+    if (value.outcome === 'refused') {
+        refineRefusedArm(value, ctx);
+        return;
+    }
+    requireOnCommittedArm(value.sessionId !== undefined, 'sessionId', value.outcome, ctx);
+    requireOnCommittedArm(value.action !== undefined, 'action', value.outcome, ctx);
+    requireOnCommittedArm(value.contractHash !== undefined, 'contractHash', value.outcome, ctx);
+    requireOnCommittedArm(value.blueprintId !== undefined, 'blueprintId', value.outcome, ctx);
+    requireOnCommittedArm(value.variantKey !== undefined, 'variantKey', value.outcome, ctx);
+    requireOnCommittedArm(value.cache !== undefined, 'cache', value.outcome, ctx);
+    rejectRefusalOnCommittedArm(value.refusal, value.outcome, ctx);
+    // `resourceUri` present IFF `rendered` — the mountability rule, the
+    // one presence rule the six identity fields do not cover. A `failed`
+    // render commits an error GguiSession but exposes no mount, so a URI
+    // beside it points a host at a render that does not exist.
+    if (value.outcome === 'rendered' && value.resourceUri === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['resourceUri'],
+            message: "outcome 'rendered' MUST carry `resourceUri` — a rendered result is mountable, and the URI is how a host mounts it.",
+        });
+    }
+    if (value.outcome === 'failed' && value.resourceUri !== undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['resourceUri'],
+            message: "`resourceUri` is present only on outcome 'rendered' — a failed render exposes no mount affordance.",
+        });
+    }
+    if (value.outcome === 'failed' && value.error === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['error'],
+            message: "outcome 'failed' MUST carry `error` — the classification is what distinguishes it from a render that succeeded.",
+        });
+    }
+    if (value.outcome === 'rendered' && value.error !== undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['error'],
+            message: "`error` is present only on outcome 'failed', not 'rendered'.",
+        });
+    }
 });
 /**
  * `ggui_update` — refresh the rendered UI with new state.
@@ -654,9 +903,22 @@ export const amendInputSchema = z.discriminatedUnion('kind', [
     }).strict(),
 ]);
 /**
- * Wire-output shape — minimal acknowledgement. The handler carries
- * `decision`, `contract`, `contractHash` on its internal `UpdateOutput`
- * TS shape — zod strips them before structuredContent serialization.
+ * Agent-facing description of the schema-attestation hash, shared by
+ * both mutation tools (ggui#560). It is not a comment: `.describe()`
+ * ships as JSON-Schema `description` in the tool declaration, so this
+ * string is what an agent reads out of `tools/list` when it has to
+ * decide whether a hash mismatch means the contract moved under it.
+ * Declared once so the two tools cannot say different things about the
+ * same field.
+ */
+const PROPS_SCHEMA_HASH_DESCRIPTION = 'sha256 (lowercase hex) over the RFC 8785 canonical form of the enforced props schema this mutation was validated against — the same schema the paired handshake disclosed. Present when the session declares a propsSpec. Equal to the handshake propsSchemaHash by the session-continuity guarantee; a mismatch means the contract changed under you.';
+/** Agent-facing description of the grammar-profile classifier. Same rationale as {@link PROPS_SCHEMA_HASH_DESCRIPTION}. */
+const PROPS_SCHEMA_PROFILE_DESCRIPTION = "Grammar profile of the enforced props schema: 'grammar-safe' or 'full'. Present with propsSchemaHash; treat unrecognized values as 'full'.";
+/**
+ * Wire-output shape — minimal acknowledgement. This schema IS the
+ * handler's declared output: `ggui_update` registers `.shape` and its
+ * return type is `GguiUpdateOutput` (`z.infer` of this schema), so
+ * there is no second declaration to keep in step (ggui#798).
  *
  * Every REAL update (`updated: true`) mints a new history record and
  * its result carries the `ai.ggui/render` slice as a FULL bootable
@@ -666,6 +928,15 @@ export const amendInputSchema = z.discriminatedUnion('kind', [
  * 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.
+ *
+ * NO refusal arm (ggui#786): the pre-generation refusal envelope rides
+ * `ggui_render` only. There is no pre-state POLICY gate on the
+ * mutation tools today — nothing on this path can decline a call for
+ * deployment-policy reasons (a contract error still rejects a
+ * malformed mutation before any store read; that is a parse result,
+ * not a refusal) — and `handshake: 'intact'` would assert something
+ * meaningless on a tool that consumes no handshake. The arm lands with its first
+ * emitter (ggui#798), not as a mechanical port of the render one.
  */
 export const updateOutputSchema = z.object({
     sessionId: z.string(),
@@ -676,8 +947,7 @@ export const updateOutputSchema = z.object({
      * 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.
+     * mount URI.
      */
     resourceUri: z.string(),
     /**
@@ -707,9 +977,15 @@ export const updateOutputSchema = z.object({
      * session-continuity guarantee, so a mismatch is the observable form
      * of a contract changing mid-session.
      */
-    propsSchemaHash: z.string().optional(),
+    propsSchemaHash: z
+        .string()
+        .optional()
+        .describe(PROPS_SCHEMA_HASH_DESCRIPTION),
     /** Present with `propsSchemaHash`; same profile classifier as the handshake's. */
-    propsSchemaProfile: z.string().optional(),
+    propsSchemaProfile: z
+        .string()
+        .optional()
+        .describe(PROPS_SCHEMA_PROFILE_DESCRIPTION),
 });
 /**
  * `ggui_amend` wire output (#483) — acknowledgement only. `resourceUri`
@@ -717,17 +993,49 @@ export const updateOutputSchema = z.object({
  * 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.
+ *
+ * As with {@link updateOutputSchema}, this schema IS the handler's
+ * declared output — `ggui_amend` registers `.shape` and returns
+ * `GguiAmendOutput` (ggui#798).
  */
 export const amendOutputSchema = z.object({
     sessionId: z.string(),
     updated: z.boolean(),
+    /**
+     * The BARE live-head URI — amend targets the mounted card and never
+     * mints a record, so there is no pinned URI to return and no epoch
+     * field (the history number is untouched by construction).
+     *
+     * NORMATIVE re-anchor reference (SPEC §7.1.2.1, ggui#652 /
+     * guuey#535): together with `sessionId` this is the durable record
+     * that an in-place repaint touched this session at this turn. A
+     * host's persistence layer MAY consume it as a locator-only
+     * re-anchor — `resources/read`-resolvable, stable for the session's
+     * lifetime — so a restored transcript re-positions the card at its
+     * latest referencing turn and rehydrates CURRENT state instead of a
+     * stale earlier snapshot. It rides `structuredContent` (LLM-visible,
+     * same rationale as ggui_update's resourceUri: consumers that strip
+     * `_meta` still reach it) and MUST NOT move to a result `_meta`
+     * slice — any result `_meta` on this tool makes view-minting hosts
+     * break the in-place semantics.
+     *
+     * Both this field and `sessionId` are REQUIRED, which is what makes
+     * SPEC §7.1.2.1's "structurally guaranteed" true rather than a
+     * convention.
+     */
     resourceUri: z.string(),
     /** Same no-op feedback channel as ggui_update's `warning`. */
     warning: z.string().optional(),
     /** Schema attestation (ggui#560) — same semantics as ggui_update's. */
-    propsSchemaHash: z.string().optional(),
+    propsSchemaHash: z
+        .string()
+        .optional()
+        .describe(PROPS_SCHEMA_HASH_DESCRIPTION),
     /** Present with `propsSchemaHash`. */
-    propsSchemaProfile: z.string().optional(),
+    propsSchemaProfile: z
+        .string()
+        .optional()
+        .describe(PROPS_SCHEMA_PROFILE_DESCRIPTION),
 });
 /**
  * `ggui_runtime_declare_tool_catalog` — the host runtime declares its
@@ -898,11 +1206,6 @@ 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).
@@ -951,3 +1254,207 @@ export const runtimeTelemetryInputShape = {
 export const runtimeTelemetryInputSchema = z.object(runtimeTelemetryInputShape);
 /** `ggui_runtime_telemetry` output — bare acknowledgement. */
 export const runtimeTelemetryOutputSchema = z.object({ ok: z.literal(true) });
+/** A render that produced an interface — identity fields present. */
+export function isRenderedOutput(output) {
+    return output.outcome === 'rendered';
+}
+/**
+ * A generation that RAN and produced nothing. The error session is
+ * committed, so `sessionId` is a live handle and `error` classifies it.
+ */
+export function isFailedRenderOutput(output) {
+    return output.outcome === 'failed';
+}
+/**
+ * A PRE-GENERATION refusal — nothing read and nothing committed, so
+ * every identity field is absent and `refusal` carries the state. (Not
+ * "nothing parsed": the SDK has already checked the call against the
+ * tool's declared `inputSchema` by the time a gate can refuse it.)
+ */
+export function isRefusedRenderOutput(output) {
+    return output.outcome === 'refused';
+}
+// ============================================================================
+// Tool output schemas the protocol owns (#817 part C). A handler registers
+// `<schema>.shape` as its MCP `outputSchema` and derives its output type from
+// the schema — never a parallel interface. No `.readonly()` here: zod 4
+// projects it as `readOnly` into the advertised JSON Schema, and the wire is
+// mutable JSON; readonly is applied at the seam (`DeepReadonly` on the
+// derived types). Every shape is closed: the transport strip-parses against
+// `.shape`, so the shape IS the wire.
+// ============================================================================
+/** Display modes an MCP Apps host can render a view in (ext-apps vocabulary). */
+export const mcpUiDisplayModeSchema = z.enum(['inline', 'fullscreen', 'pip']);
+/**
+ * The host-context projection the iframe-runtime observes and `ggui_consume`
+ * echoes (`client.hostContext`). Every field optional: a host that never
+ * reports one leaves it absent — absent ⇒ the documented default.
+ */
+export const hostContextProjectionSchema = z.object({
+    availableDisplayModes: z.array(mcpUiDisplayModeSchema).optional(),
+    currentDisplayMode: mcpUiDisplayModeSchema.optional(),
+    containerDimensions: z
+        .object({
+        width: z.number().optional(),
+        maxWidth: z.number().optional(),
+        height: z.number().optional(),
+        maxHeight: z.number().optional(),
+    })
+        .optional(),
+    platform: z.enum(['web', 'desktop', 'mobile']).optional(),
+    deviceCapabilities: z
+        .object({ touch: z.boolean().optional(), hover: z.boolean().optional() })
+        .optional(),
+    locale: z.string().optional(),
+    timeZone: z.string().optional(),
+});
+/** `ggui_consume`'s `client` slice — what the runtime observed about its host. */
+export const clientObservationsSchema = z.object({
+    hostContext: hostContextProjectionSchema.optional(),
+});
+/** One row of `ggui_list_sessions` — eight closed keys; nothing passes through. */
+export const gguiSessionSummaryWireSchema = z.object({
+    sessionId: z.string(),
+    hostName: z.string().optional(),
+    hostSessionId: z.string().optional(),
+    createdAt: z.string(),
+    lastActivityAt: z.string(),
+    status: z.string(),
+    wsToken: z.string().optional(),
+    wsTokenExpiresAt: z.string().optional(),
+});
+/**
+ * The two states a GguiSession is in on the wire — the pair the consume
+ * loop exits on (`expired`). Owned here (ggui#817 part C2); the type is
+ * derived, never a second list.
+ */
+export const gguiSessionStatusSchema = z.enum(['active', 'expired']);
+/**
+ * One drained row of `ggui_consume` — a user action that reached the
+ * pipe (ggui#817 part C2). Closed on the wire: an unknown key is
+ * stripped at the transport, a missing key refuses the row at the seam
+ * (`parsePendingEnvelope`), so a malformed pipe entry never ships to an
+ * agent typed as a good one.
+ */
+export const consumeEventEntrySchema = z.object({
+    type: z.literal('action'),
+    sessionId: z.string().min(1),
+    intent: z.string(),
+    actionData: jsonValueSchema.nullable(),
+    uiContext: jsonObjectSchema,
+    actionId: z.string(),
+    firedAt: z.string(),
+});
+/**
+ * `ggui_consume`'s output — the drained rows, the session's state, and the
+ * client's observations when the host sent any (ggui#817 part C2). The
+ * handler registers `.shape`; `tools/list` therefore advertises the entry
+ * vocabulary and the status enum instead of a free-form record and a free
+ * string.
+ */
+export const gguiConsumeOutputSchema = z.object({
+    events: z.array(consumeEventEntrySchema),
+    status: gguiSessionStatusSchema,
+    client: clientObservationsSchema.optional(),
+});
+/** `ggui_list_sessions`' output — the closed summary rows (ggui#817 part C2). */
+export const gguiListSessionsOutputSchema = z.object({
+    sessions: z.array(gguiSessionSummaryWireSchema),
+});
+/**
+ * `ggui_emit`'s output (ggui#817 part C2): `accepted` at the boundary, and
+ * `seq` when the server keeps a stream buffer — seq-aware implementations
+ * stamp and return it so replay cursors can be built from the ack.
+ */
+export const gguiEmitOutputSchema = z.object({
+    accepted: z.boolean(),
+    seq: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe('Session-scoped monotonic outbound sequence assigned to this delivery. Present when the server keeps a stream buffer.'),
+});
+/**
+ * `ggui_get_session`'s wire: the store row's six base fields plus the mount
+ * variant — for EVERY session. An MCP-Apps mount is locator-only on the
+ * render object, but its store row carries the base fields, so the
+ * projection reads them from the row and the wire never fails on that
+ * variant. The locator itself is not on this wire (MCP-Apps resources have
+ * their own paths).
+ * `contextSnapshot` rides when a component (`render`) mount's row has one —
+ * never on an mcpApps mount.
+ */
+export const gguiGetSessionOutputSchema = z.object({
+    variant: z.enum(['render', 'mcpApps']),
+    id: z.string(),
+    appId: z.string(),
+    eventSequence: z.number().int().nonnegative(),
+    createdAt: z.number().int().nonnegative(),
+    lastActivityAt: z.number().int().nonnegative(),
+    expiresAt: z.number().int().nonnegative(),
+    /**
+     * The last-known value of every declared contextSpec slot, as
+     * `ggui_runtime_sync_context` wrote it onto the row — the read path a
+     * raw MCP client (no widget-context mirror) has for contextSpec values.
+     * Present iff the row carries one — component (`render`) mounts only; an
+     * mcpApps mount never carries one; never an empty placeholder.
+     */
+    contextSnapshot: jsonObjectSchema.optional(),
+});
+/** The three sequential gates of `ggui_protocol_validate_blueprint`. */
+export const blueprintValidationTierSchema = z.enum(['compile', 'selfCheck', 'runtime']);
+export const blueprintValidationIssueSchema = z.object({
+    tier: blueprintValidationTierSchema,
+    code: z.string(),
+    message: z.string(),
+    fix: z.string().optional(),
+});
+/** `ggui_protocol_validate_blueprint`'s result envelope: `failedAt` names the tier that stopped, or null. */
+export const blueprintValidationResultSchema = z.object({
+    valid: z.boolean(),
+    failedAt: blueprintValidationTierSchema.nullable(),
+    errors: z.array(blueprintValidationIssueSchema),
+    warnings: z.array(blueprintValidationIssueSchema),
+});
+/** A provider row — what `ggui_list_featured_blueprints` returns per blueprint. */
+export const blueprintEntryWireSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().optional(),
+    source: blueprintSourceSchema,
+    updatedAt: z.string(),
+    tags: z.array(z.string()).optional(),
+});
+export const gguiListFeaturedBlueprintsOutputSchema = z.object({
+    blueprints: z.array(blueprintEntryWireSchema),
+    total: z.number().int().nonnegative(),
+});
+/** One `ggui_search_blueprints` hit — a scored row plus the registry-only keys. */
+export const gguiSearchBlueprintsResultSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string(),
+    category: z.string(),
+    props: z.array(z.object({ name: z.string(), type: z.string(), required: z.boolean(), description: z.string() })),
+    callbacks: z.array(z.string()),
+    featured: z.boolean(),
+    relevance: z.literal('match'),
+    score: z.number(),
+    origin: z.literal('registry').optional(),
+    artifactId: z.string().optional(),
+    version: z.string().optional(),
+    mcpTools: z.array(z.object({ server: z.string().optional(), tool: z.string() })).optional(),
+    scopeVerification: z.enum(['verified', 'unverified']).optional(),
+});
+export const gguiSearchBlueprintsOutputSchema = z.object({
+    results: z.array(gguiSearchBlueprintsResultSchema),
+    total: z.number(),
+    query: z.string(),
+    degradedSources: z
+        .array(z.object({
+        source: z.literal('registry'),
+        reason: z.enum(['unreachable', 'timeout', 'invalid_response']),
+    }))
+        .optional(),
+});