@ggui-ai/protocol 0.22.0 → 0.24.0

package/dist/version.js

@@ -6,6 +6,106 @@
  * schema change; the most recent change anchors {@link PROTOCOL_VERSION}.
  *
  * --------------------------------------------------------------------
+ * The consume result declares its next-call hint (2026-09-26, additive,
+ * ggui#1399: MINOR, same draft stamp). `gguiConsumeOutputSchema` gains an
+ * optional `nextStep: { tool: 'ggui_amend', description, example, args:
+ * { sessionId } }` — the render → consume chain's shape, closing the loop
+ * from the drained gesture back to the card: present iff `events` is
+ * non-empty, absent on an empty drain, the decision the agent's. SPEC §7.3
+ * names it. DECLARED here, EMITTED one release later: the handler returns
+ * no hint yet, and the tool's output reaches `tools/list` closed
+ * (ggui#1333), so a host must cache a schema naming the member before any
+ * server answers with it. No `PROTOCOL_VERSION` move.
+ *
+ * --------------------------------------------------------------------
+ * The relay declares its contract-violation answer (2026-09-25,
+ * additive, ggui#1358: MINOR, same draft stamp). `contractViolationSchema`
+ * is the zod mirror of `ContractViolation`; `ggui_runtime_submit_action`'s
+ * output `code` enum gains `CONTRACT_VIOLATION` and the output gains an
+ * optional `violations: ContractViolation[]`. SPEC §4.7's handler contract
+ * and §2.4's failure modes name the relay's answer beside the live
+ * channel's frame. DECLARED here, ENFORCED one release later: the relay
+ * does not yet run the `actionSpec` gate, and the tool's output reaches
+ * `tools/list` closed (ggui#1333), so a host must cache a schema naming the
+ * code before any server answers with it. No `PROTOCOL_VERSION` move.
+ *
+ * --------------------------------------------------------------------
+ * The handshake suggestion names the card a judged hit proposes
+ * (2026-09-25, additive, ggui#1336: MINOR, same draft stamp).
+ * `BlueprintMeta.matchedIntent?` carries the stored intent the reuse judge
+ * compared with the request, capped at `MATCHED_INTENT_MAX_CHARS` (280,
+ * the judge's own truncation), so the agent (which holds the
+ * conversation) can decline a proposal it reads as the wrong card. Present
+ * only on a judged hit from the requesting app's own pool, never from a
+ * pool shared across apps. DECLARED in this change, EMITTED one release
+ * later: every output object reaches `tools/list` closed
+ * (`additionalProperties: false`, ggui#1333), so a host that cached the
+ * previous release's schema would refuse a member it did not name. The
+ * member carries a `.describe()` naming its meaning and the decline path
+ * (`forceCreate`), so the agent that receives it knows what it is for. The
+ * `intent` input's description now says it is stored and shown to later
+ * requests of the same app, and names the task, never the end user.
+ * Kit: the `n1-compat` catalog gains the `handshake-suggestion` wire and
+ * tag 9.1's cache-hit suggestion as a BACKWARD case. No
+ * `PROTOCOL_VERSION` move.
+ *
+ * --------------------------------------------------------------------
+ * The read-plane-only posture is normative, and graded (2026-09-24,
+ * additive, ggui#1304: MINOR, same draft stamp). SPEC §7.10.6 states the
+ * posture the reference server has run since ggui#537: a result publishes
+ * the render locator on `structuredContent.resourceUri` and the same
+ * value on `_meta.ui.resourceUri`, and carries neither the
+ * `ai.ggui/render` slice nor a live-channel token; the locator's read
+ * then mounts. A host that mounts the declaration-level shell against
+ * such a server MUST answer that read, and a host that advertises
+ * `serverResources` MUST answer `resources/read`. Kit: the new
+ * `read-plane-only-conformance` catalog grades the server; the
+ * host-helper catalog's H2 probe map gains `serverResources` →
+ * `resources/read`. Kit, same row: the `bootstrap-protocol` fixtures
+ * describe the live delivery paths (the inline global, the forwarded
+ * tool result's top-level `_meta`), a new `tool-result-override` setup
+ * directive drives the missing-slice failure, and that fixture expects
+ * `MISSING_META_GGUI_BOOTSTRAP`, the spelling emitters send (§5.5.2 now
+ * says so; `BOOTSTRAP_META_MISSING` names the same condition). No wire
+ * shape moves. No `PROTOCOL_VERSION` move.
+ *
+ * --------------------------------------------------------------------
+ * Host-declared gesture delivery (2026-09-24, additive, ggui#1309: MINOR,
+ * same draft stamp). New exports: `GGUI_HOST_CAPABILITIES_HEADER`
+ * (`ggui-host-capabilities`), `HOST_CAPABILITY_UI_MESSAGE_TURN`
+ * (`ui-message-turn`), `parseHostCapabilitiesHeader`. A host's own code
+ * declares the token on its MCP connection's header; `ggui_render` then
+ * omits its `nextStep: ggui_consume` hint, so the agent ends its turn at
+ * paint. Unknown tokens are ignored. No `PROTOCOL_VERSION` move.
+ *
+ * --------------------------------------------------------------------
+ * A member-level clear on a theme write (2026-09-23, additive, ggui#1308:
+ * MINOR, same draft stamp). New exports: `APP_THEME_CLEARABLE_MEMBERS`
+ * (`mode`, `name`, `frameless`, `fonts`, `imagery` — the optional members
+ * outside the attestation), `AppThemeClearableMember`,
+ * `appThemeWriteSchema` / `AppThemeWrite` (the write form, where those
+ * members also accept `null`), and `splitAppThemeWrite`. `appThemeSchema`
+ * and `AppTheme` are unchanged and null-free. The #1124 refusal text names
+ * the member-level clear for each clearable dropped member. The shared
+ * writer's half (storing the split document, naming the cleared members)
+ * lands WITH this (cloud). No `PROTOCOL_VERSION` move.
+ *
+ * --------------------------------------------------------------------
+ * The card's spent `oneShot` names on the render slice (2026-09-23,
+ * additive, ggui#1223: MINOR, same draft stamp).
+ * `McpAppAiGguiRenderMeta.spentOneShots?: readonly string[]`, projected only
+ * by `deriveRenderMeta` from the stored `ComponentGguiSession.spentOneShots`
+ * record (`SpentOneShotsRecord` = `{ epoch, actions }`) — only when the
+ * record's epoch is the projected card's, filtered to the names that card
+ * declares `oneShot`. A consumed action re-served after a reload rendered
+ * live again; the runtime now seeds its guard from the slice. New exports:
+ * `spentOneShotsSchema`, `SpentOneShotsRecord`; the parser options gain
+ * `onInvalidSpentOneShots` (a malformed value is dropped and named, never
+ * fatal). Kit: the `render-meta` forward case carries the member. The store
+ * write (ggui#1305) and the runtime seed land separately. No
+ * `PROTOCOL_VERSION` move.
+ *
+ * --------------------------------------------------------------------
  * `actionSpec` on the static render slice (2026-09-23, additive, ggui#1178:
  * MINOR, same draft stamp). `McpAppAiGguiRenderMeta.actionSpec?: ActionSpec`,
  * projected only by `deriveRenderMeta` (component renders) and WHOLE, the
@@ -3777,7 +3877,7 @@ export const PROTOCOL_VERSION = "draft-2026-09-10";
  *     PATCH under §1.3); it cannot be cut from main, whose delta since
  *     0.14.0 is minor-class.
  */
-export const GGUI_WAVE_VERSION = "0.22.0";
+export const GGUI_WAVE_VERSION = "0.24.0";
 /**
  * Schema version stamped onto wire envelopes that opt into the
  * `schemaVersion` forward-compat field (see {@link ActionEnvelope},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/protocol",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "sideEffects": [
     "./dist/schemas/sync-check.js",
     "./dist/validation/ajv-runtime.js"