@ggui-ai/protocol 0.2.0-alpha.4 → 0.4.0-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (200) hide show
  1. package/README.md +16 -16
  2. package/dist/envelope-adapters.d.ts +6 -5
  3. package/dist/envelope-adapters.d.ts.map +1 -1
  4. package/dist/envelope-adapters.js +3 -3
  5. package/dist/envelopes/builders.d.ts +6 -32
  6. package/dist/envelopes/builders.d.ts.map +1 -1
  7. package/dist/envelopes/builders.js +3 -25
  8. package/dist/errors/version-mismatch.d.ts +1 -1
  9. package/dist/errors/version-mismatch.js +1 -1
  10. package/dist/gadgets/resolve-app-gadgets.d.ts +10 -0
  11. package/dist/gadgets/resolve-app-gadgets.d.ts.map +1 -0
  12. package/dist/gadgets/resolve-app-gadgets.js +19 -0
  13. package/dist/gadgets/resolve-contract-gadgets.d.ts +6 -6
  14. package/dist/gadgets/resolve-contract-gadgets.js +5 -5
  15. package/dist/gadgets/stdlib-gadgets.d.ts +1 -1
  16. package/dist/gadgets/stdlib-gadgets.d.ts.map +1 -1
  17. package/dist/gadgets/stdlib-gadgets.js +43 -22
  18. package/dist/iframe-bridge.d.ts +4 -43
  19. package/dist/iframe-bridge.d.ts.map +1 -1
  20. package/dist/iframe-bridge.js +4 -141
  21. package/dist/index.d.ts +60 -62
  22. package/dist/index.d.ts.map +1 -1
  23. package/dist/index.js +66 -61
  24. package/dist/integrations/mcp-apps.d.ts +83 -38
  25. package/dist/integrations/mcp-apps.d.ts.map +1 -1
  26. package/dist/integrations/mcp-apps.js +98 -52
  27. package/dist/recommended-prompts.d.ts +1 -1
  28. package/dist/recommended-prompts.js +1 -1
  29. package/dist/registry/blueprint-key.d.ts +3 -0
  30. package/dist/registry/blueprint-key.d.ts.map +1 -1
  31. package/dist/registry/blueprint-key.js +9 -0
  32. package/dist/registry/blueprint-stamp.d.ts +12 -0
  33. package/dist/registry/blueprint-stamp.d.ts.map +1 -0
  34. package/dist/registry/blueprint-stamp.js +12 -0
  35. package/dist/registry/canonicalize-contract.d.ts +31 -2
  36. package/dist/registry/canonicalize-contract.d.ts.map +1 -1
  37. package/dist/registry/canonicalize-contract.js +125 -13
  38. package/dist/registry/portable-blueprint.d.ts +71 -0
  39. package/dist/registry/portable-blueprint.d.ts.map +1 -0
  40. package/dist/registry/portable-blueprint.js +111 -0
  41. package/dist/registry/summarize-contract.d.ts +7 -2
  42. package/dist/registry/summarize-contract.d.ts.map +1 -1
  43. package/dist/registry/summarize-contract.js +12 -3
  44. package/dist/registry/variant-key.d.ts +17 -0
  45. package/dist/registry/variant-key.d.ts.map +1 -0
  46. package/dist/registry/variant-key.js +22 -0
  47. package/dist/schema-learning/derive-contract.d.ts +2 -2
  48. package/dist/schema-learning/derive-contract.js +2 -2
  49. package/dist/schema-learning/merge.d.ts.map +1 -1
  50. package/dist/schema-learning/merge.js +3 -2
  51. package/dist/schemas/app-theme.d.ts +38 -0
  52. package/dist/schemas/app-theme.d.ts.map +1 -0
  53. package/dist/schemas/app-theme.js +43 -0
  54. package/dist/schemas/blueprint.d.ts +30 -11
  55. package/dist/schemas/blueprint.d.ts.map +1 -1
  56. package/dist/schemas/blueprint.js +62 -26
  57. package/dist/schemas/data-contract.d.ts +28 -30
  58. package/dist/schemas/data-contract.d.ts.map +1 -1
  59. package/dist/schemas/data-contract.js +26 -26
  60. package/dist/schemas/handshake-suggestion.d.ts +2 -4
  61. package/dist/schemas/handshake-suggestion.d.ts.map +1 -1
  62. package/dist/schemas/handshake-suggestion.js +5 -14
  63. package/dist/schemas/mcp.d.ts +294 -59
  64. package/dist/schemas/mcp.d.ts.map +1 -1
  65. package/dist/schemas/mcp.js +350 -94
  66. package/dist/schemas/ops-blueprint.d.ts +12 -12
  67. package/dist/schemas/ops-blueprint.d.ts.map +1 -1
  68. package/dist/schemas/ops-blueprint.js +14 -24
  69. package/dist/screen-blueprints/define.d.ts +2 -2
  70. package/dist/screen-blueprints/match.d.ts +12 -7
  71. package/dist/screen-blueprints/match.d.ts.map +1 -1
  72. package/dist/screen-blueprints/match.js +7 -5
  73. package/dist/screen-blueprints/types.d.ts +14 -18
  74. package/dist/screen-blueprints/types.d.ts.map +1 -1
  75. package/dist/transport/websocket.d.ts +5 -26
  76. package/dist/transport/websocket.d.ts.map +1 -1
  77. package/dist/types/app-config.d.ts +0 -1
  78. package/dist/types/app-config.d.ts.map +1 -1
  79. package/dist/types/auth.d.ts +1 -46
  80. package/dist/types/auth.d.ts.map +1 -1
  81. package/dist/types/blueprint-source.d.ts +123 -0
  82. package/dist/types/blueprint-source.d.ts.map +1 -0
  83. package/dist/types/blueprint-source.js +126 -0
  84. package/dist/types/blueprint.d.ts +25 -18
  85. package/dist/types/blueprint.d.ts.map +1 -1
  86. package/dist/types/contract-inference.d.ts +2 -43
  87. package/dist/types/contract-inference.d.ts.map +1 -1
  88. package/dist/types/data-contract.d.ts +59 -344
  89. package/dist/types/data-contract.d.ts.map +1 -1
  90. package/dist/types/data-contract.js +5 -12
  91. package/dist/types/events.d.ts +31 -69
  92. package/dist/types/events.d.ts.map +1 -1
  93. package/dist/types/{render-event.d.ts → ggui-session-event.d.ts} +15 -15
  94. package/dist/types/ggui-session-event.d.ts.map +1 -0
  95. package/dist/types/{render-event.js → ggui-session-event.js} +5 -5
  96. package/dist/types/handshake-suggestion.d.ts +49 -35
  97. package/dist/types/handshake-suggestion.d.ts.map +1 -1
  98. package/dist/types/host-context.d.ts +8 -8
  99. package/dist/types/host-context.d.ts.map +1 -1
  100. package/dist/types/host-context.js +5 -5
  101. package/dist/types/invoke.d.ts +1 -13
  102. package/dist/types/invoke.d.ts.map +1 -1
  103. package/dist/types/{canvas-lifecycle.d.ts → lifecycle.d.ts} +35 -37
  104. package/dist/types/lifecycle.d.ts.map +1 -0
  105. package/dist/types/{canvas-lifecycle.js → lifecycle.js} +12 -14
  106. package/dist/types/live-channel.d.ts +48 -104
  107. package/dist/types/live-channel.d.ts.map +1 -1
  108. package/dist/types/llm-route.d.ts +4 -4
  109. package/dist/types/llm-route.d.ts.map +1 -1
  110. package/dist/types/llm-route.js +24 -2
  111. package/dist/types/llm.d.ts +13 -24
  112. package/dist/types/llm.d.ts.map +1 -1
  113. package/dist/types/llm.js +23 -53
  114. package/dist/types/mcp.d.ts +74 -177
  115. package/dist/types/mcp.d.ts.map +1 -1
  116. package/dist/types/mcp.js +11 -4
  117. package/dist/types/oauth-user-id.d.ts +12 -0
  118. package/dist/types/oauth-user-id.d.ts.map +1 -0
  119. package/dist/types/oauth-user-id.js +10 -0
  120. package/dist/types/portable-blueprint.d.ts +61 -0
  121. package/dist/types/portable-blueprint.d.ts.map +1 -0
  122. package/dist/types/portable-blueprint.js +8 -0
  123. package/dist/types/{session.d.ts → render.d.ts} +51 -53
  124. package/dist/types/render.d.ts.map +1 -0
  125. package/dist/types/thread.d.ts.map +1 -1
  126. package/dist/types/thread.js +3 -3
  127. package/dist/types/ui-generator.d.ts +24 -47
  128. package/dist/types/ui-generator.d.ts.map +1 -1
  129. package/dist/types/ui-generator.js +1 -53
  130. package/dist/validation/ajv-runtime.d.ts +3 -3
  131. package/dist/validation/ajv-runtime.d.ts.map +1 -1
  132. package/dist/validation/ajv-runtime.js +6 -5
  133. package/dist/validation/contract-validator.d.ts +23 -22
  134. package/dist/validation/contract-validator.d.ts.map +1 -1
  135. package/dist/validation/contract-validator.js +28 -26
  136. package/dist/validation/cross-references.d.ts +3 -3
  137. package/dist/validation/cross-references.js +3 -3
  138. package/dist/validation/hygiene-rules.d.ts +9 -9
  139. package/dist/validation/hygiene-rules.js +13 -13
  140. package/dist/validation/is-record.d.ts +17 -0
  141. package/dist/validation/is-record.d.ts.map +1 -0
  142. package/dist/validation/is-record.js +18 -0
  143. package/dist/validation/lint-contract.d.ts +1 -1
  144. package/dist/validation/lint-contract.js +3 -3
  145. package/dist/validation/name-invariants.d.ts +4 -4
  146. package/dist/validation/name-invariants.js +4 -4
  147. package/dist/validation/reserved-channels.d.ts +43 -46
  148. package/dist/validation/reserved-channels.d.ts.map +1 -1
  149. package/dist/validation/reserved-channels.js +14 -177
  150. package/dist/validation/resolve-stream-channel.d.ts +3 -9
  151. package/dist/validation/resolve-stream-channel.d.ts.map +1 -1
  152. package/dist/validation/resolve-stream-channel.js +3 -4
  153. package/dist/validation/sanitize-error.d.ts +10 -9
  154. package/dist/validation/sanitize-error.d.ts.map +1 -1
  155. package/dist/validation/sanitize-error.js +19 -18
  156. package/dist/validation/schema-compat-invariants.d.ts +1 -1
  157. package/dist/validation/schema-compat-invariants.js +3 -3
  158. package/dist/validation/schema-meta-validation.d.ts +4 -4
  159. package/dist/validation/schema-meta-validation.d.ts.map +1 -1
  160. package/dist/validation/schema-meta-validation.js +7 -9
  161. package/dist/validation/schema-subset.d.ts +9 -8
  162. package/dist/validation/schema-subset.d.ts.map +1 -1
  163. package/dist/validation/ui-security.d.ts +0 -17
  164. package/dist/validation/ui-security.d.ts.map +1 -1
  165. package/dist/validation/ui-security.js +17 -22
  166. package/dist/validation/zod-to-json-schema.d.ts +1 -1
  167. package/dist/validation/zod-to-json-schema.d.ts.map +1 -1
  168. package/dist/validation/zod-to-json-schema.js +4 -3
  169. package/dist/version.d.ts +818 -9
  170. package/dist/version.d.ts.map +1 -1
  171. package/dist/version.js +817 -8
  172. package/package.json +3 -3
  173. package/dist/bridge/invoke-agent.d.ts +0 -65
  174. package/dist/bridge/invoke-agent.d.ts.map +0 -1
  175. package/dist/bridge/invoke-agent.js +0 -113
  176. package/dist/stream/stream-parser.d.ts +0 -62
  177. package/dist/stream/stream-parser.d.ts.map +0 -1
  178. package/dist/stream/stream-parser.js +0 -199
  179. package/dist/types/canvas-lifecycle.d.ts.map +0 -1
  180. package/dist/types/credential.d.ts +0 -41
  181. package/dist/types/credential.d.ts.map +0 -1
  182. package/dist/types/credential.js +0 -32
  183. package/dist/types/data-bindings.d.ts +0 -322
  184. package/dist/types/data-bindings.d.ts.map +0 -1
  185. package/dist/types/data-bindings.js +0 -29
  186. package/dist/types/feedback.d.ts +0 -22
  187. package/dist/types/feedback.d.ts.map +0 -1
  188. package/dist/types/feedback.js +0 -7
  189. package/dist/types/mcp-proxy.d.ts +0 -67
  190. package/dist/types/mcp-proxy.d.ts.map +0 -1
  191. package/dist/types/mcp-proxy.js +0 -46
  192. package/dist/types/openrouter-models.d.ts +0 -23
  193. package/dist/types/openrouter-models.d.ts.map +0 -1
  194. package/dist/types/openrouter-models.js +0 -4843
  195. package/dist/types/region.d.ts +0 -26
  196. package/dist/types/region.d.ts.map +0 -1
  197. package/dist/types/region.js +0 -36
  198. package/dist/types/render-event.d.ts.map +0 -1
  199. package/dist/types/session.d.ts.map +0 -1
  200. /package/dist/types/{session.js → render.js} +0 -0
@@ -3,7 +3,25 @@
3
3
  *
4
4
  * These schemas define the validation rules for MCP tool inputs.
5
5
  * TypeScript types in types/mcp.ts are derived from these via z.infer.
6
- * The server handler imports these for runtime validation.
6
+ *
7
+ * Two consumption patterns, both anchored here:
8
+ *
9
+ * - **Wired raw shapes** (`*InputShape`): handlers in
10
+ * `@ggui-ai/mcp-server-handlers` (and the hosted pod's
11
+ * discover / request-credential tools) import the SHAPE directly as
12
+ * their `inputSchema` and validate with `z.object(shape)` — unknown
13
+ * keys are STRIPPED. The shape is the one authored copy of the
14
+ * validation rules AND the agent-facing `.describe()` strings that
15
+ * ship via `tools/list`.
16
+ *
17
+ * - **Lifecycle triad** (`ggui_handshake` / `ggui_update`): the
18
+ * handlers carry deliberate input divergences (handshake's
19
+ * blueprintDraft contract is loose ON PURPOSE so the negotiator can
20
+ * repair malformations; update's sessionId is optional for
21
+ * in-process dispatch), so they author their own raw shapes. The
22
+ * schemas here remain the canonical strict wire contract + the
23
+ * `z.infer` source for the published types. `ggui_render` is wired:
24
+ * its handler imports {@link renderInputShape}.
7
25
  */
8
26
  import { z } from 'zod';
9
27
  export declare const viewportSchema: z.ZodObject<{
@@ -42,48 +60,76 @@ export declare const interfaceContextSchema: z.ZodObject<{
42
60
  }>>;
43
61
  reducedMotion: z.ZodOptional<z.ZodBoolean>;
44
62
  }, z.core.$loose>;
63
+ /**
64
+ * `ggui_consume` input. The long-poll bound is SPEC §7.3: integer
65
+ * seconds in `[0, 25]` — the cap dodges infrastructure kill windows
66
+ * (API-gateway 30s HTTP limits, host MCP clients that abort long tool
67
+ * calls). Longer waits are the agent's loop, not a server knob.
68
+ */
69
+ export declare const consumeInputShape: {
70
+ readonly sessionId: z.ZodString;
71
+ readonly timeout: z.ZodOptional<z.ZodNumber>;
72
+ };
45
73
  export declare const consumeInputSchema: z.ZodObject<{
46
- renderId: z.ZodString;
74
+ sessionId: z.ZodString;
47
75
  timeout: z.ZodOptional<z.ZodNumber>;
48
- }, z.core.$strict>;
76
+ }, z.core.$strip>;
49
77
  /**
50
- * Input schema for `ggui_emit` — emit a stamped delivery on a declared
78
+ * `ggui_emit` input — emit a stamped delivery on a declared
51
79
  * `streamSpec[channel]`.
52
80
  */
81
+ export declare const emitInputShape: {
82
+ readonly sessionId: z.ZodString;
83
+ readonly channel: z.ZodString;
84
+ readonly payload: z.ZodUnknown;
85
+ readonly complete: z.ZodOptional<z.ZodBoolean>;
86
+ };
53
87
  export declare const emitInputSchema: z.ZodObject<{
54
- renderId: z.ZodString;
88
+ sessionId: z.ZodString;
55
89
  channel: z.ZodString;
56
90
  payload: z.ZodUnknown;
57
91
  complete: z.ZodOptional<z.ZodBoolean>;
58
- }, z.core.$strict>;
59
- export declare const getRenderInputSchema: z.ZodObject<{
60
- renderId: z.ZodString;
61
- }, z.core.$strict>;
62
- export declare const listFeaturedBlueprintsInputSchema: z.ZodObject<{
63
- level: z.ZodOptional<z.ZodEnum<{
64
- component: "component";
65
- primitive: "primitive";
66
- composite: "composite";
67
- template: "template";
68
- }>>;
69
- category: z.ZodOptional<z.ZodString>;
70
- tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
71
- limit: z.ZodOptional<z.ZodNumber>;
72
- }, z.core.$strict>;
92
+ }, z.core.$strip>;
93
+ export declare const getSessionInputShape: {
94
+ readonly sessionId: z.ZodString;
95
+ };
96
+ export declare const getSessionInputSchema: z.ZodObject<{
97
+ sessionId: z.ZodString;
98
+ }, z.core.$strip>;
99
+ /**
100
+ * `ggui_list_featured_blueprints` input — intentionally EMPTY. The
101
+ * pre-launch No-Backcompat scrub deleted the level/category/tags/limit
102
+ * filters (delete-until-wired); filters re-enter here when a real
103
+ * consumer passes them.
104
+ */
105
+ export declare const listFeaturedBlueprintsInputShape: {};
106
+ export declare const listFeaturedBlueprintsInputSchema: z.ZodObject<{}, z.core.$strip>;
107
+ export declare const searchBlueprintsInputShape: {
108
+ readonly query: z.ZodString;
109
+ readonly limit: z.ZodOptional<z.ZodNumber>;
110
+ };
73
111
  export declare const searchBlueprintsInputSchema: z.ZodObject<{
74
112
  query: z.ZodString;
75
113
  limit: z.ZodOptional<z.ZodNumber>;
76
- }, z.core.$strict>;
114
+ }, z.core.$strip>;
115
+ export declare const renderBlueprintInputShape: {
116
+ readonly blueprintId: z.ZodString;
117
+ };
77
118
  export declare const renderBlueprintInputSchema: z.ZodObject<{
78
119
  blueprintId: z.ZodString;
79
- props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
80
- }, z.core.$strict>;
81
- export declare const discoverInputSchema: z.ZodObject<{}, z.core.$strict>;
120
+ }, z.core.$strip>;
121
+ export declare const discoverInputShape: {};
122
+ export declare const discoverInputSchema: z.ZodObject<{}, z.core.$strip>;
123
+ export declare const requestCredentialInputShape: {
124
+ readonly serviceId: z.ZodString;
125
+ readonly reason: z.ZodOptional<z.ZodString>;
126
+ readonly sessionId: z.ZodOptional<z.ZodString>;
127
+ };
82
128
  export declare const requestCredentialInputSchema: z.ZodObject<{
83
129
  serviceId: z.ZodString;
84
130
  reason: z.ZodOptional<z.ZodString>;
85
- renderId: z.ZodOptional<z.ZodString>;
86
- }, z.core.$strict>;
131
+ sessionId: z.ZodOptional<z.ZodString>;
132
+ }, z.core.$strip>;
87
133
  /**
88
134
  * `ggui_handshake` — three-step suggestion protocol.
89
135
  *
@@ -105,10 +151,10 @@ export declare const requestCredentialInputSchema: z.ZodObject<{
105
151
  * - The agent is the contract authority; synth amends only when
106
152
  * validation fails.
107
153
  * - Post-Phase-B the handshake input carries NO `sessionId`. The
108
- * server mints `renderId` on the paired `ggui_render`; host
154
+ * server mints `sessionId` on the paired `ggui_render`; host
109
155
  * conversation grouping flows via the host-supplied
110
156
  * `_meta["ai.ggui/host-session"]` envelope captured at render
111
- * creation (see {@link RenderBase.hostSession}).
157
+ * creation (see {@link GguiSessionBase.hostSession}).
112
158
  */
113
159
  export declare const handshakeInputSchema: z.ZodObject<{
114
160
  intent: z.ZodString;
@@ -123,18 +169,19 @@ export declare const handshakeInputSchema: z.ZodObject<{
123
169
  *
124
170
  * The agent reads `suggestion.origin` to branch the paired render call:
125
171
  *
126
- * - `cache` → render `{decision: {kind: 'accept'}}` for cache delivery.
127
- * - `agent` → render `{decision: {kind: 'accept'}}` to gen against the draft.
128
- * - `synth` → render `{decision: {kind: 'accept'}}` to gen against the amended contract.
172
+ * - `cache` → render `{handshakeId, props}` (omit `override`) for cache delivery.
173
+ * - `agent` → render `{handshakeId, props}` (omit `override`) to gen against the draft.
174
+ * - `synth` → render `{handshakeId, props}` (omit `override`) to gen against the amended contract.
129
175
  *
130
- * Any origin → render `{decision: {kind: 'override', blueprintDraft: {...}}}` to
131
- * discard the suggestion and gen against a fresh draft (mints a new
132
- * `blueprintId` server-side).
176
+ * Any origin → render `{handshakeId, props, override: {contract?, variance?}}`
177
+ * to re-aim the suggestion — `override.contract` gens against a fresh
178
+ * contract; `override.variance` re-aims the variant axis.
133
179
  *
134
- * Wire-output is intentionally lean. The handler carries `reason`,
135
- * `target`, `alternatives`, `contractHash`, `serverCapabilities` on
136
- * its internal `HandshakeOutput` TS shape for telemetry / post-classify
137
- * tracing — zod strips them before structuredContent serialization.
180
+ * Wire-output is intentionally lean. The handler carries `target`,
181
+ * `alternatives`, `contractHash`, `serverCapabilities` on its internal
182
+ * `HandshakeOutput` TS shape for telemetry / post-classify tracing —
183
+ * zod strips them before structuredContent serialization. `reason` IS
184
+ * a wire field (optional, ≤280 chars — see below).
138
185
  *
139
186
  * `serverCapabilities` reaches the iframe via the `ai.ggui/render`
140
187
  * slice meta (see `slice-meta-derivation.ts`), not via this response.
@@ -164,33 +211,157 @@ export declare const handshakeOutputSchema: z.ZodObject<{
164
211
  * `ggui_render` — materialises a UI emission. Step 3 of the three-step
165
212
  * handshake protocol.
166
213
  *
167
- * The agent commits its decision relative to the prior handshake's
168
- * suggestion: ACCEPT (use the provisional `blueprintMeta` from
169
- * step-2 verbatim) or OVERRIDE (mint a fresh blueprintId with a NEW
170
- * `blueprintDraft`).
214
+ * The agent commits relative to the prior handshake's suggestion by
215
+ * PRESENCE of `override` (no discriminated union): omit `override` to
216
+ * ACCEPT the proposal as-is, or provide `override: {contract?, variance?}`
217
+ * to re-aim the contract and/or the variant axis (PATCH semantics).
171
218
  *
172
219
  * Locked decisions:
173
220
  *
174
- * - `decision` discriminator: `{kind: 'accept'} |
175
- * {kind: 'override', blueprintDraft: {...}}`.
176
- * - `accept` reuses `handshake.suggestion.blueprintMeta.blueprintId`
177
- * exactly; `override` discards the provisional id and mints fresh.
221
+ * - ACCEPT (omit `override`) reuses the agreed contract + the proposed
222
+ * variance, resolving the proposed `(contractKey, variantKey)`.
223
+ * - `override.contract` re-drafts the contract (STRICT — must already
224
+ * conform; the server does not repair it) and cold-gens against it.
225
+ * - `override.variance` re-aims the variant axis while keeping the
226
+ * agreed contract, re-resolving the effective
227
+ * `(contractKey, variantKey(newVariance))`.
228
+ * - `props` is REQUIRED (pass `{}` when the effective contract declares
229
+ * no propsSpec).
178
230
  *
179
231
  * There is no separate `ggui_commit` — render absorbs that responsibility.
180
232
  *
181
233
  * Post-Phase-B rename from `ggui_push` — the tool materialises a single
182
234
  * render (no stack of N to push onto); the new name reflects what the
183
235
  * tool does at the protocol surface.
236
+ *
237
+ * WIRED shape — `@ggui-ai/mcp-server-handlers`'s `ggui_render` registers
238
+ * {@link renderInputShape} as its `inputSchema` and validates with
239
+ * `z.object(shape)` (unknown top-level keys strip; `infra` / `override`
240
+ * sub-objects stay `.strict()` so typos inside them surface as clear zod
241
+ * paths).
184
242
  */
243
+ export declare const renderInputShape: {
244
+ readonly handshakeId: z.ZodString;
245
+ /**
246
+ * Runtime prop values for THIS render. Validated against the
247
+ * effective contract's `propsSpec` — required-field checks + type
248
+ * checks per spec entry. Validation failures fail the render with a
249
+ * recoverable `ContractViolationError`.
250
+ *
251
+ * REQUIRED — pass `{}` when the effective contract declares no
252
+ * propsSpec (the field is required, the value may be empty).
253
+ */
254
+ readonly props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
255
+ /**
256
+ * Per-render theme override. When set, lands on the committed
257
+ * render and takes priority over `App.defaultThemeId` at
258
+ * bootstrap-projection time. Use sparingly — most renders should
259
+ * inherit the app default.
260
+ */
261
+ readonly themeId: z.ZodOptional<z.ZodString>;
262
+ /**
263
+ * Typed `infra` envelope. Today carries one field (`model`); future
264
+ * expansion (temperature, max_tokens, provider hints) lands here
265
+ * additively. `model` MUST be a provider-prefixed id
266
+ * (`provider/model-name`); a bound generator may also accept
267
+ * generator-specific prefixes for alternate transports.
268
+ *
269
+ * Strict — extra keys at `infra.*` are not silently dropped, so a
270
+ * typo (`infra.modelId`) surfaces as a clear zod path instead of a
271
+ * silent default-model fallback.
272
+ */
273
+ readonly infra: z.ZodOptional<z.ZodObject<{
274
+ model: z.ZodOptional<z.ZodString>;
275
+ }, z.core.$strict>>;
276
+ /**
277
+ * Re-aim the handshake proposal (PATCH semantics). Omit to ACCEPT the
278
+ * proposal as-is; provide to re-draft the contract and/or re-aim the
279
+ * variant axis. At least one of `contract` / `variance` MUST be set —
280
+ * an empty `override: {}` is rejected.
281
+ *
282
+ * - `contract` — STRICT full re-draft of the contract. The server
283
+ * does NOT repair it; it must already conform.
284
+ * - `variance` — re-aim the variant axis (persona / aesthetic /
285
+ * context / seedPrompt) while keeping the agreed contract. A
286
+ * different variance resolves a distinct cached component.
287
+ */
288
+ readonly override: z.ZodOptional<z.ZodObject<{
289
+ contract: z.ZodOptional<z.ZodType<import("..").DataContract, unknown, z.core.$ZodTypeInternals<import("..").DataContract, unknown>>>;
290
+ variance: z.ZodOptional<z.ZodType<import("..").BlueprintVariance, unknown, z.core.$ZodTypeInternals<import("..").BlueprintVariance, unknown>>>;
291
+ }, z.core.$strict>>;
292
+ };
185
293
  export declare const renderInputSchema: z.ZodObject<{
186
294
  handshakeId: z.ZodString;
187
- props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
188
- decision: z.ZodType<import("..").PushDecision, unknown, z.core.$ZodTypeInternals<import("..").PushDecision, unknown>>;
189
- }, z.core.$strict>;
295
+ props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
296
+ themeId: z.ZodOptional<z.ZodString>;
297
+ infra: z.ZodOptional<z.ZodObject<{
298
+ model: z.ZodOptional<z.ZodString>;
299
+ }, z.core.$strict>>;
300
+ override: z.ZodOptional<z.ZodObject<{
301
+ contract: z.ZodOptional<z.ZodType<import("..").DataContract, unknown, z.core.$ZodTypeInternals<import("..").DataContract, unknown>>>;
302
+ variance: z.ZodOptional<z.ZodType<import("..").BlueprintVariance, unknown, z.core.$ZodTypeInternals<import("..").BlueprintVariance, unknown>>>;
303
+ }, z.core.$strict>>;
304
+ }, z.core.$strip>;
190
305
  /**
191
- * Wire-output shape — intentionally lean: `{renderId, nextStep?, action}`.
306
+ * Reuse outcome for a single `ggui_render` — surfaced on the wire so an
307
+ * agent or operator can tell whether a stored component was served or a
308
+ * new one was generated. Counts generation calls only; it carries no
309
+ * cost or tier semantics.
310
+ */
311
+ export declare const renderCacheMarkerSchema: z.ZodObject<{
312
+ hit: z.ZodBoolean;
313
+ similarity: z.ZodOptional<z.ZodNumber>;
314
+ cachedBlueprintId: z.ZodOptional<z.ZodString>;
315
+ llmCallsAvoided: z.ZodNumber;
316
+ kind: z.ZodOptional<z.ZodEnum<{
317
+ "full-template": "full-template";
318
+ cold: "cold";
319
+ }>>;
320
+ reason: z.ZodOptional<z.ZodString>;
321
+ }, z.core.$strip>;
322
+ /**
323
+ * Canonical failure codes for the in-result `ggui_render` failure
324
+ * envelope (SPEC §7.9 Plane 3). Closed enum — a failed render's
325
+ * `error.code` is always one of these four; finer-grained diagnostics
326
+ * ride on `error.message`.
327
+ *
328
+ * - `PRODUCTION_FAILED` — generation ran but did not produce a
329
+ * component (LLM/compile/commit failure).
330
+ * - `VALIDATION_ERROR` — a server-side precondition rejected the
331
+ * render before generation could run (misconfigured generation
332
+ * route, unusable stored config).
333
+ * - `NO_PLATFORM_KEY` — the server's managed provider-key
334
+ * configuration has no key for the resolved route.
335
+ * - `NO_CREDENTIALS` — no generation credentials are configured on
336
+ * the server at all.
337
+ */
338
+ export declare const renderErrorCodeSchema: z.ZodEnum<{
339
+ PRODUCTION_FAILED: "PRODUCTION_FAILED";
340
+ VALIDATION_ERROR: "VALIDATION_ERROR";
341
+ NO_PLATFORM_KEY: "NO_PLATFORM_KEY";
342
+ NO_CREDENTIALS: "NO_CREDENTIALS";
343
+ }>;
344
+ /**
345
+ * In-result failure marker for `ggui_render`. Present on the wire
346
+ * output iff the tool result is `isError: true` — the structuredContent
347
+ * stays schema-conformant on failures, and this field carries the
348
+ * canonical failure classification.
349
+ */
350
+ export declare const renderErrorSchema: z.ZodObject<{
351
+ code: z.ZodEnum<{
352
+ PRODUCTION_FAILED: "PRODUCTION_FAILED";
353
+ VALIDATION_ERROR: "VALIDATION_ERROR";
354
+ NO_PLATFORM_KEY: "NO_PLATFORM_KEY";
355
+ NO_CREDENTIALS: "NO_CREDENTIALS";
356
+ }>;
357
+ message: z.ZodString;
358
+ }, z.core.$strip>;
359
+ /**
360
+ * Wire-output shape — `{sessionId, resourceUri?, action, contractHash,
361
+ * cache, error?, nextStep?}`. `contractHash` (data-contract identity)
362
+ * and `cache` (reuse outcome) are required wire fields on this schema.
192
363
  * The handler carries `shortCode`, `codeReady`, `handshakeId`,
193
- * `decision`, `contract`, `contractHash`, `cache`, `codeUrl`, `codeHash`
364
+ * `decision`, `contract`, `codeUrl`, `codeHash`
194
365
  * on its internal `RenderOutput` TS shape for telemetry / post-classify
195
366
  * tracing — zod strips them before structuredContent serialization.
196
367
  *
@@ -198,16 +369,22 @@ export declare const renderInputSchema: z.ZodObject<{
198
369
  * `expiresAt`) via the single `ai.ggui/render` slice meta, not via this
199
370
  * response. There is no clickable `url` field — post-R5 the `/r/`
200
371
  * shortCode route was deleted (every host either resolves the
201
- * `_meta.ui.resourceUri` iframe or reads `{renderId}` via
372
+ * `_meta.ui.resourceUri` iframe or reads `{sessionId}` via
202
373
  * `render-resource/...`). Leaving a dead URL on the wire had the model
203
374
  * hallucinating links that resolve nowhere.
204
375
  *
376
+ * Failure envelope (SPEC §7.1): a failed/rejected generation returns
377
+ * this same schema-conformant shape on an `isError: true` tool result —
378
+ * `error` present, `resourceUri` absent (nothing mountable), no
379
+ * `_meta` on the result. The error GguiSession is still committed, so
380
+ * `sessionId` remains a live handle into the session channel.
381
+ *
205
382
  * Post-Phase-B the `'compose'` action enum value is gone — there is no
206
383
  * stack of N renders to compose against.
207
384
  */
208
385
  export declare const renderOutputSchema: z.ZodObject<{
209
- renderId: z.ZodString;
210
- resourceUri: z.ZodString;
386
+ sessionId: z.ZodString;
387
+ resourceUri: z.ZodOptional<z.ZodString>;
211
388
  action: z.ZodEnum<{
212
389
  replace: "replace";
213
390
  create: "create";
@@ -215,12 +392,35 @@ export declare const renderOutputSchema: z.ZodObject<{
215
392
  update: "update";
216
393
  declined: "declined";
217
394
  }>;
395
+ contractHash: z.ZodString;
396
+ blueprintId: z.ZodString;
397
+ variantKey: z.ZodString;
398
+ cache: z.ZodObject<{
399
+ hit: z.ZodBoolean;
400
+ similarity: z.ZodOptional<z.ZodNumber>;
401
+ cachedBlueprintId: z.ZodOptional<z.ZodString>;
402
+ llmCallsAvoided: z.ZodNumber;
403
+ kind: z.ZodOptional<z.ZodEnum<{
404
+ "full-template": "full-template";
405
+ cold: "cold";
406
+ }>>;
407
+ reason: z.ZodOptional<z.ZodString>;
408
+ }, z.core.$strip>;
409
+ error: z.ZodOptional<z.ZodObject<{
410
+ code: z.ZodEnum<{
411
+ PRODUCTION_FAILED: "PRODUCTION_FAILED";
412
+ VALIDATION_ERROR: "VALIDATION_ERROR";
413
+ NO_PLATFORM_KEY: "NO_PLATFORM_KEY";
414
+ NO_CREDENTIALS: "NO_CREDENTIALS";
415
+ }>;
416
+ message: z.ZodString;
417
+ }, z.core.$strip>>;
218
418
  nextStep: z.ZodOptional<z.ZodObject<{
219
419
  tool: z.ZodLiteral<"ggui_consume">;
220
420
  description: z.ZodString;
221
421
  example: z.ZodString;
222
422
  args: z.ZodObject<{
223
- renderId: z.ZodString;
423
+ sessionId: z.ZodString;
224
424
  }, z.core.$strip>;
225
425
  }, z.core.$strip>>;
226
426
  }, z.core.$strip>;
@@ -252,15 +452,15 @@ export declare const renderOutputSchema: z.ZodObject<{
252
452
  * partial patches that would break required fields, type-mismatch
253
453
  * values, etc. all reject pre-persist.
254
454
  *
255
- * `renderId` is globally unique; the server tenancy-checks via
455
+ * `sessionId` is globally unique; the server tenancy-checks via
256
456
  * `ctx.appId`.
257
457
  */
258
458
  export declare const updateInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
259
- renderId: z.ZodString;
459
+ sessionId: z.ZodString;
260
460
  kind: z.ZodLiteral<"replace">;
261
461
  props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
262
462
  }, z.core.$strict>, z.ZodObject<{
263
- renderId: z.ZodString;
463
+ sessionId: z.ZodString;
264
464
  kind: z.ZodLiteral<"merge">;
265
465
  patch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
266
466
  }, z.core.$strict>], "kind">;
@@ -276,7 +476,42 @@ export declare const updateInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
276
476
  * acknowledgement.
277
477
  */
278
478
  export declare const updateOutputSchema: z.ZodObject<{
279
- renderId: z.ZodString;
479
+ sessionId: z.ZodString;
280
480
  updated: z.ZodBoolean;
481
+ resourceUri: z.ZodString;
281
482
  }, z.core.$strip>;
483
+ /**
484
+ * `ggui_runtime_declare_tool_catalog` — the host runtime declares its
485
+ * per-app canonical tool-identity catalog (one row per app).
486
+ *
487
+ * The map is `bare tool name → the canonical serverInfo` that the tool's
488
+ * MCP server announced in its `initialize` reply. ggui folds this into
489
+ * the handshake step (`canonicalizeToolIdentity`) so a reused blueprint's
490
+ * `agentCapabilities.tools[*].serverInfo` is rewritten to the canonical
491
+ * value regardless of whether the inbound contract authored a config-key
492
+ * name, fabricated one, or omitted it. That makes blueprint reuse
493
+ * identity-stable across runtimes.
494
+ *
495
+ * Keyed by the BARE tool name — the same key the canonicalization step
496
+ * matches on. `version` is OPTIONAL: it rides along as metadata; tool
497
+ * identity is `(name)` matched by bare name, never `(name, version)`.
498
+ *
499
+ * `appId` is NOT on the input — the handler reads it off `ctx.appId`
500
+ * resolved by the upstream auth adapter, so a declaration can only ever
501
+ * write its own app's row. The output echoes the resolved `appId` so the
502
+ * caller can confirm which app row it wrote.
503
+ *
504
+ * REPLACE semantics: each declaration overwrites the app's prior catalog
505
+ * wholesale (the host re-declares its full current toolset on connect).
506
+ */
507
+ export declare const declareToolCatalogInputSchema: z.ZodObject<{
508
+ toolCatalog: z.ZodRecord<z.ZodString, z.ZodObject<{
509
+ name: z.ZodString;
510
+ version: z.ZodOptional<z.ZodString>;
511
+ }, z.core.$strict>>;
512
+ }, z.core.$strict>;
513
+ export declare const declareToolCatalogOutputSchema: z.ZodObject<{
514
+ saved: z.ZodBoolean;
515
+ appId: z.ZodString;
516
+ }, z.core.$strict>;
282
517
  //# sourceMappingURL=mcp.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/schemas/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,eAAO,MAAM,cAAc;;;iBAGzB,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAUnB,CAAC;AAUjB,eAAO,MAAM,kBAAkB;;;kBAIpB,CAAC;AAEZ;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;kBAOjB,CAAC;AAEZ,eAAO,MAAM,oBAAoB;;kBAEtB,CAAC;AAEZ,eAAO,MAAM,iCAAiC;;;;;;;;;;kBAKnC,CAAC;AAEZ,eAAO,MAAM,2BAA2B;;;kBAG7B,CAAC;AAEZ,eAAO,MAAM,0BAA0B;;;kBAG5B,CAAC;AAEZ,eAAO,MAAM,mBAAmB,iCAAwB,CAAC;AAEzD,eAAO,MAAM,4BAA4B;;;;kBAI9B,CAAC;AAaZ;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,oBAAoB;;;;kBA0BtB,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;iBAgChC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,iBAAiB;;;;kBA4BnB,CAAC;AAEZ;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;iBAkC7B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;4BAa5B,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB;;;iBAG7B,CAAC"}
1
+ {"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/schemas/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,eAAO,MAAM,cAAc;;;iBAGzB,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAUnB,CAAC;AAYjB;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;CAgBpB,CAAC;AAEX,eAAO,MAAM,kBAAkB;;;iBAA8B,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC;AAEX,eAAO,MAAM,eAAe;;;;;iBAA2B,CAAC;AAExD,eAAO,MAAM,oBAAoB;;CAKvB,CAAC;AAEX,eAAO,MAAM,qBAAqB;;iBAAiC,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,IAAc,CAAC;AAE5D,eAAO,MAAM,iCAAiC,gCAE7C,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;CAM7B,CAAC;AAEX,eAAO,MAAM,2BAA2B;;;iBAAuC,CAAC;AAEhF,eAAO,MAAM,yBAAyB;;CAO5B,CAAC;AAEX,eAAO,MAAM,0BAA0B;;iBAAsC,CAAC;AAE9E,eAAO,MAAM,kBAAkB,IAAc,CAAC;AAE9C,eAAO,MAAM,mBAAmB,gCAA+B,CAAC;AAEhE,eAAO,MAAM,2BAA2B;;;;CAI9B,CAAC;AAEX,eAAO,MAAM,4BAA4B;;;;iBAAwC,CAAC;AAalF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,oBAAoB;;;;kBA0BtB,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;iBAgChC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,gBAAgB;;IAO3B;;;;;;;;OAQG;;IAEH;;;;;OAKG;;IAQH;;;;;;;;;;OAUG;;;;IAaH;;;;;;;;;;;OAWG;;;;;CAuBK,CAAC;AAEX,eAAO,MAAM,iBAAiB;;;;;;;;;;;iBAA6B,CAAC;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;iBAyBlC,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,qBAAqB;;;;;EAKhC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;iBAS5B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwE7B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;4BAa5B,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB;;;;iBAW7B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,6BAA6B;;;;;kBAW/B,CAAC;AAEZ,eAAO,MAAM,8BAA8B;;;kBAKhC,CAAC"}