@ggui-ai/protocol 0.1.0-rc.1

package/dist/schemas/invoke.js

@@ -0,0 +1,169 @@
+/**
+ * Streamable Invoke Protocol v1 — Zod schemas.
+ *
+ * Single source of truth for the client→agent invoke turn. Mirrors Anthropic's
+ * Messages streaming format exactly (message_start / content_block_{start,delta,stop}
+ * / message_delta / message_stop / ping / error). UI rendering is expressed as
+ * plain `tool_use` blocks calling the `ggui_render` / `ggui_render_blueprint`
+ * client tools — no ggui-specific block type.
+ *
+ * TS types in types/invoke.ts are derived from these via z.infer. Consumers
+ * (@ggui-ai/server, @ggui-ai/react) import schemas for runtime validation
+ * and types for authoring.
+ */
+import { z } from 'zod';
+import { interfaceContextSchema } from './mcp.js';
+// ── Content blocks ────────────────────────────────────────────────────
+/** Plain text content — streamed via `text_delta` events. */
+export const textBlockSchema = z.object({
+    type: z.literal('text'),
+    text: z.string(),
+});
+/** Tool call initiated by the agent. Input may arrive via `input_json_delta`. */
+export const toolUseBlockSchema = z.object({
+    type: z.literal('tool_use'),
+    id: z.string(),
+    name: z.string(),
+    input: z.record(z.string(), z.unknown()),
+});
+/**
+ * Tool execution result (Protocol v1.1).
+ *
+ * Emitted inline on the assistant turn when the server executed a tool on
+ * the agent's behalf (e.g. `ggui_push`, `ggui_handshake`). Clients pair this
+ * with the matching `tool_use` by `tool_use_id` and render — no second
+ * round-trip through a `ggui_render` client tool is needed.
+ *
+ * This extends Anthropic's shape: Anthropic puts `tool_result` in the next
+ * user message, we also allow it on the assistant turn because the server
+ * already has the result. The `content` shape depends on the tool.
+ */
+export const toolResultBlockSchema = z.object({
+    type: z.literal('tool_result'),
+    tool_use_id: z.string(),
+    content: z.unknown(),
+    is_error: z.boolean().optional(),
+});
+/** Discriminated union of every legal content block type. */
+export const contentBlockSchema = z.discriminatedUnion('type', [
+    textBlockSchema,
+    toolUseBlockSchema,
+    toolResultBlockSchema,
+]);
+// ── Deltas ────────────────────────────────────────────────────────────
+export const textDeltaSchema = z.object({
+    type: z.literal('text_delta'),
+    text: z.string(),
+});
+export const inputJsonDeltaSchema = z.object({
+    type: z.literal('input_json_delta'),
+    partial_json: z.string(),
+});
+export const contentBlockDeltaPayloadSchema = z.discriminatedUnion('type', [
+    textDeltaSchema,
+    inputJsonDeltaSchema,
+]);
+// ── Events ────────────────────────────────────────────────────────────
+/** First event of a turn. */
+export const messageStartEventSchema = z.object({
+    type: z.literal('message_start'),
+    message: z.object({
+        id: z.string(),
+        role: z.literal('assistant'),
+        model: z.string().optional(),
+    }),
+});
+/** A new content block begins. */
+export const contentBlockStartEventSchema = z.object({
+    type: z.literal('content_block_start'),
+    index: z.number().int().nonnegative(),
+    content_block: contentBlockSchema,
+});
+/** Incremental update to the block at `index`. */
+export const contentBlockDeltaEventSchema = z.object({
+    type: z.literal('content_block_delta'),
+    index: z.number().int().nonnegative(),
+    delta: contentBlockDeltaPayloadSchema,
+});
+/** The block at `index` is complete. */
+export const contentBlockStopEventSchema = z.object({
+    type: z.literal('content_block_stop'),
+    index: z.number().int().nonnegative(),
+});
+/** Final metadata just before the turn ends. */
+export const messageDeltaEventSchema = z.object({
+    type: z.literal('message_delta'),
+    delta: z.object({
+        stop_reason: z.enum(['end_turn', 'max_tokens', 'tool_use', 'error']),
+        stop_sequence: z.string().nullable().optional(),
+    }),
+    usage: z.object({
+        input_tokens: z.number().int().nonnegative(),
+        output_tokens: z.number().int().nonnegative(),
+    }),
+});
+/** Turn is done. No events may follow. */
+export const messageStopEventSchema = z.object({
+    type: z.literal('message_stop'),
+});
+/** Keep-alive frame. */
+export const pingEventSchema = z.object({
+    type: z.literal('ping'),
+});
+/** Terminal error. No `message_stop` follows. */
+export const invokeErrorCodeSchema = z.enum([
+    'invalid_request',
+    'unauthorized',
+    'rate_limited',
+    'invoke_in_progress',
+    'upstream_error',
+    'tool_error',
+    'internal',
+]);
+export const errorEventSchema = z.object({
+    type: z.literal('error'),
+    error: z.object({
+        code: invokeErrorCodeSchema,
+        message: z.string(),
+        retryAfterMs: z.number().int().nonnegative().optional(),
+    }),
+});
+/**
+ * Discriminated union over every event the agent may emit.
+ *
+ * Parsing an incoming SSE frame:
+ *   const event = invokeEventSchema.parse(JSON.parse(frame.data));
+ *   switch (event.type) { ... }
+ */
+export const invokeEventSchema = z.discriminatedUnion('type', [
+    messageStartEventSchema,
+    contentBlockStartEventSchema,
+    contentBlockDeltaEventSchema,
+    contentBlockStopEventSchema,
+    messageDeltaEventSchema,
+    messageStopEventSchema,
+    pingEventSchema,
+    errorEventSchema,
+]);
+// ── Request ───────────────────────────────────────────────────────────
+/**
+ * A prior conversation turn. Content is either a plain text shortcut or a
+ * structured content block sequence (mirrors Anthropic's `messages[].content`).
+ */
+export const invokeTurnSchema = z.object({
+    role: z.enum(['user', 'assistant']),
+    content: z.union([z.string(), z.array(contentBlockSchema)]),
+});
+/**
+ * POST body shape for `{endpointUrl}/invoke`.
+ *
+ * Stateless by default — client holds history, sends full `history[]` every
+ * turn. Agents that need server-side memory layer their own keyed on
+ * `X-Ggui-Session-Id`.
+ */
+export const invokeRequestSchema = z.object({
+    message: z.string(),
+    history: z.array(invokeTurnSchema).optional(),
+    interfaceContext: interfaceContextSchema.optional(),
+    requestId: z.string().optional(),
+});

package/dist/schemas/mcp.d.ts

@@ -0,0 +1,301 @@
+/**
+ * MCP Tool Zod Schemas — Single Source of Truth
+ *
+ * These schemas define the validation rules for MCP tool inputs.
+ * TypeScript types in types/mcp.ts are derived from these via z.infer.
+ * The server handler imports these for runtime validation.
+ */
+import { z } from 'zod';
+export declare const viewportSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+export declare const interfaceContextSchema: z.ZodObject<{
+    viewport: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+    platform: z.ZodEnum<{
+        web: "web";
+        desktop: "desktop";
+        mobile: "mobile";
+    }>;
+    deviceType: z.ZodEnum<{
+        desktop: "desktop";
+        phone: "phone";
+        tablet: "tablet";
+    }>;
+    orientation: z.ZodEnum<{
+        portrait: "portrait";
+        landscape: "landscape";
+    }>;
+    devicePixelRatio: z.ZodOptional<z.ZodNumber>;
+    touchPrimary: z.ZodOptional<z.ZodBoolean>;
+    shellType: z.ZodOptional<z.ZodEnum<{
+        fullscreen: "fullscreen";
+        chat: "chat";
+        spatial: "spatial";
+    }>>;
+    colorScheme: z.ZodOptional<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+    }>>;
+    reducedMotion: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+export declare const popInputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+}, z.core.$strict>;
+export declare const consumeInputSchema: z.ZodObject<{
+    stackItemId: z.ZodString;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/**
+ * Input schema for `ggui_emit` — emit a stamped delivery on a declared
+ * `streamSpec[channel]`.
+ */
+export declare const emitInputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    channel: z.ZodString;
+    payload: z.ZodUnknown;
+    complete: z.ZodOptional<z.ZodBoolean>;
+    stackItemId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const getSessionInputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+}, z.core.$strict>;
+export declare const getStackInputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+}, z.core.$strict>;
+export declare const closeInputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+}, z.core.$strict>;
+export declare const listFeaturedBlueprintsInputSchema: z.ZodObject<{
+    level: z.ZodOptional<z.ZodEnum<{
+        component: "component";
+        primitive: "primitive";
+        composite: "composite";
+        template: "template";
+    }>>;
+    category: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const searchBlueprintsInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const renderBlueprintInputSchema: z.ZodObject<{
+    blueprintId: z.ZodString;
+    props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const discoverInputSchema: z.ZodObject<{}, z.core.$strict>;
+export declare const requestCredentialInputSchema: z.ZodObject<{
+    serviceId: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * `ggui_new_session` — mint or resolve a chat-scoped session handle.
+ *
+ * Server-mints, agent-threads. SEP-2567 aligned ("Sessionless MCP",
+ * Final 2026-03-11): the MCP spec deliberately removes Mcp-Session-Id
+ * because hosts can't agree on what a session means; the recommended
+ * pattern is exactly this — server returns explicit handles, agent
+ * threads them through subsequent calls.
+ *
+ * No inputs — every call mints a fresh random sessionId. (A prior
+ * optional `seed` for deterministic derivation was retired because
+ * LLMs were passing the same seed across user turns and getting back
+ * the same sessionId, defeating the "new" in the tool name.)
+ */
+export declare const newSessionInputSchema: z.ZodObject<{}, z.core.$strict>;
+export declare const newSessionOutputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    appId: z.ZodString;
+    createdAt: z.ZodString;
+    nextStep: z.ZodObject<{
+        tool: z.ZodLiteral<"ggui_handshake">;
+        description: z.ZodString;
+        example: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * `ggui_handshake` — three-step suggestion protocol.
+ *
+ * Step 1 (this input): the agent posts a draft — its idea: contract +
+ * optional variance + optional generator hint.
+ *
+ * Step 2 (server-side, see `handshakeOutputSchema`): the server runs
+ * `BlueprintSearch` and contract-validation in parallel and returns a
+ * `HandshakeSuggestion` routed by `origin: cache | agent | synth`.
+ *
+ * Step 3 (paired `ggui_push`): the agent accepts (reuses the
+ * provisional `blueprintId` minted in step-2) OR overrides (mints a
+ * fresh `blueprintId` against a NEW draft).
+ *
+ * Locked decisions:
+ *
+ *   - `blueprintDraft` is the single-field input wrapping contract +
+ *     variance + generator hint.
+ *   - The agent is the contract authority; synth amends only when
+ *     validation fails.
+ */
+export declare const handshakeInputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    intent: z.ZodString;
+    blueprintDraft: z.ZodType<import("..").BlueprintDraft, unknown, z.core.$ZodTypeInternals<import("..").BlueprintDraft, unknown>>;
+    forceCreate: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/**
+ * Three-step handshake output. Single `suggestion` carries
+ * `origin: cache | agent | synth`, `blueprintMeta` (always present),
+ * and optional `amendments` (synth-only) / `validationFindings`
+ * (soft on cache).
+ *
+ * The agent reads `suggestion.origin` to branch the paired push:
+ *
+ *   - `cache`  → push `{decision: {kind: 'accept'}}` for cache delivery.
+ *   - `agent`  → push `{decision: {kind: 'accept'}}` to gen against the draft.
+ *   - `synth`  → push `{decision: {kind: 'accept'}}` to gen against the amended contract.
+ *
+ * Any origin → push `{decision: {kind: 'override', blueprintDraft: {...}}}` to
+ * discard the suggestion and gen against a fresh draft (mints a new
+ * `blueprintId` server-side).
+ *
+ * Wire-output is intentionally lean. The handler carries `reason`,
+ * `target`, `alternatives`, `contractHash`, `serverCapabilities` on
+ * its internal `HandshakeOutput` TS shape for telemetry / post-classify
+ * tracing — zod strips them before structuredContent serialization.
+ *
+ * `serverCapabilities` reaches the iframe via `_meta.ggui.bootstrap`
+ * (see `bootstrap-meta-derivation.ts`), not via this response.
+ */
+export declare const handshakeOutputSchema: z.ZodObject<{
+    handshakeId: z.ZodString;
+    action: z.ZodEnum<{
+        replace: "replace";
+        create: "create";
+        reuse: "reuse";
+        update: "update";
+        compose: "compose";
+        declined: "declined";
+    }>;
+    suggestion: z.ZodType<import("..").HandshakeSuggestion, unknown, z.core.$ZodTypeInternals<import("..").HandshakeSuggestion, unknown>>;
+    reason: z.ZodOptional<z.ZodString>;
+    nextStep: z.ZodOptional<z.ZodObject<{
+        tool: z.ZodLiteral<"ggui_push">;
+        description: z.ZodString;
+        example: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * `ggui_push` — materialises a UI emission. Step 3 of the three-step
+ * handshake protocol.
+ *
+ * The agent commits its decision relative to the prior handshake's
+ * suggestion: ACCEPT (use the provisional `blueprintMeta` from
+ * step-2 verbatim) or OVERRIDE (mint a fresh blueprintId with a NEW
+ * `blueprintDraft`).
+ *
+ * Locked decisions:
+ *
+ *   - `decision` discriminator: `{kind: 'accept'} |
+ *     {kind: 'override', blueprintDraft: {...}}`.
+ *   - `accept` reuses `handshake.suggestion.blueprintMeta.blueprintId`
+ *     exactly; `override` discards the provisional id and mints fresh.
+ *
+ * There is no separate `ggui_commit` — push absorbs that responsibility.
+ */
+export declare const pushInputSchema: z.ZodObject<{
+    handshakeId: z.ZodString;
+    props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    decision: z.ZodType<import("..").PushDecision, unknown, z.core.$ZodTypeInternals<import("..").PushDecision, unknown>>;
+}, z.core.$strict>;
+/**
+ * Wire-output shape — intentionally lean: `{stackItemId, nextStep?,
+ * url, action}`. The handler carries `sessionId`, `shortCode`,
+ * `codeReady`, `handshakeId`, `decision`, `contract`, `contractHash`,
+ * `cache`, `codeUrl`, `codeHash` on its internal `PushOutput` TS shape
+ * for telemetry / post-classify tracing — zod strips them before
+ * structuredContent serialization.
+ *
+ * The iframe receives bootstrap credentials (`wsUrl`, `token`,
+ * `expiresAt`) via `_meta.ggui.bootstrap`, not via this response.
+ */
+export declare const pushOutputSchema: z.ZodObject<{
+    stackItemId: z.ZodString;
+    url: z.ZodString;
+    action: z.ZodEnum<{
+        replace: "replace";
+        create: "create";
+        reuse: "reuse";
+        update: "update";
+        compose: "compose";
+        declined: "declined";
+    }>;
+    nextStep: z.ZodOptional<z.ZodObject<{
+        tool: z.ZodLiteral<"ggui_consume">;
+        description: z.ZodString;
+        example: z.ZodString;
+        args: z.ZodObject<{
+            stackItemId: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * `ggui_update` — refresh the rendered UI with new state.
+ *
+ * Discriminated on `kind`:
+ *
+ *   - `kind: 'replace'` + `props` — full props replacement. The new
+ *     map IS the new state. Use when most props change OR when you
+ *     want deterministic state restoration (no merge ambiguity).
+ *
+ *   - `kind: 'merge'` + `patch` — RFC 7396 JSON Merge Patch semantics.
+ *     Top-level keys merge shallow; nested objects merge recursively;
+ *     a `null` value DELETES the key; arrays fully replace (NOT element-
+ *     wise). Use when most props stay the same and the agent only
+ *     needs to send a small delta — common after a single domain-tool
+ *     mutation. RFC 7396 chosen because it has a published spec and
+ *     wide library support (GitHub API, Kubernetes strategic-merge).
+ *
+ * Anti-patterns (the discriminated union rejects these structurally,
+ * but they're a common author mistake when copy-pasting):
+ *
+ *   - Do NOT send `props` on `kind: 'merge'` — use `patch`.
+ *   - Do NOT send `patch` on `kind: 'replace'` — use `props`.
+ *
+ * Both modes validate the FINAL props state (post-merge for `merge`)
+ * against the stack item's `propsSpec` and reject on violation —
+ * partial patches that would break required fields, type-mismatch
+ * values, etc. all reject pre-persist.
+ *
+ * `stackItemId` is globally unique; the server resolves the owning
+ * session via its secondary index and tenancy-checks via `ctx.appId`.
+ * NO `sessionId` on the wire.
+ */
+export declare const updateInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    stackItemId: z.ZodString;
+    kind: z.ZodLiteral<"replace">;
+    props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>, z.ZodObject<{
+    stackItemId: z.ZodString;
+    kind: z.ZodLiteral<"merge">;
+    patch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>], "kind">;
+/**
+ * Wire-output shape — minimal acknowledgement. The handler carries
+ * `sessionId`, `decision`, `contract`, `contractHash` on its internal
+ * `UpdateOutput` TS shape — zod strips them before structuredContent
+ * serialization.
+ *
+ * Post-update the iframe receives the new props via the live-channel
+ * `props_update` WS frame; the cross-host fallback path receives them
+ * via `_meta.ggui.bootstrap.propsJson` (see `update.resultMeta`). The
+ * wire response itself is just acknowledgement.
+ */
+export declare const updateOutputSchema: z.ZodObject<{
+    stackItemId: z.ZodString;
+    updated: z.ZodBoolean;
+}, z.core.$strip>;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/schemas/mcp.d.ts.map

@@ -0,0 +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;AASjB,eAAO,MAAM,cAAc;;kBAEhB,CAAC;AAEZ,eAAO,MAAM,kBAAkB;;;kBAIpB,CAAC;AAEZ;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;kBASjB,CAAC;AAEZ,eAAO,MAAM,qBAAqB;;kBAEvB,CAAC;AAEZ,eAAO,MAAM,mBAAmB;;kBAErB,CAAC;AAEZ,eAAO,MAAM,gBAAgB;;kBAElB,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;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,iCAAwB,CAAC;AAE3D,eAAO,MAAM,sBAAsB;;;;;;;;;iBAWjC,CAAC;AAMH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,oBAAoB;;;;;kBAmCtB,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;iBAgChC,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe;;;;kBA4BjB,CAAC;AAEZ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;iBA0B3B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;4BAa5B,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB;;;iBAG7B,CAAC"}