@ggui-ai/protocol 0.1.0-rc.1

package/dist/stream/stream-parser.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Universal stream parser for agent responses.
+ *
+ * Extracts text from any LLM provider's streaming format (Anthropic, OpenAI,
+ * Gemini, Cohere, Mistral, etc.) without hardcoding provider schemas.
+ * Uses depth-first search on well-known field names and container structures.
+ *
+ * Decoupled from any transport (WebSocket, HTTP, etc.) — callers provide
+ * callbacks for chunk delivery.
+ */
+/**
+ * Detect whether a response should be treated as a stream based on headers.
+ * Accepts raw header strings so callers aren't coupled to the fetch API.
+ */
+export declare function isStreamingContentType(contentType: string, transferEncoding?: string): boolean;
+/**
+ * Depth-first search for a text string in a JSON structure.
+ *
+ * Search strategy:
+ *   1. Check TEXT_FIELDS at current level (string values only)
+ *   2. Recurse into CONTAINER_FIELDS
+ *
+ * Works with any provider because it searches by field-name patterns,
+ * not by provider-specific schemas.
+ */
+export declare function deepFindText(obj: unknown, depth?: number): string;
+/**
+ * Detect if a streaming JSON event signals end-of-stream.
+ *
+ * Recognized signals:
+ *   - type: "done" / "message_stop"
+ *   - choices[0].finish_reason !== null
+ *   - (HTTP stream close is handled by the reader, not here)
+ */
+export declare function isStreamDone(data: Record<string, unknown>): boolean;
+/**
+ * Extract sessionId from a streaming event.
+ * Checks for a top-level `sessionId` string — no envelope format required.
+ */
+export declare function extractSessionId(data: Record<string, unknown>): string | undefined;
+/**
+ * Callbacks for stream consumers. Transport-agnostic — works with WebSocket,
+ * HTTP response streaming, file output, or anything else.
+ */
+export interface StreamCallbacks {
+    onChunk: (text: string) => Promise<void>;
+    onDone: () => Promise<void>;
+    onSessionId?: (sessionId: string) => Promise<void>;
+}
+/**
+ * Read a streaming HTTP response and invoke callbacks for each text chunk.
+ *
+ * Supports three wire formats:
+ *   1. text/event-stream (SSE) — parses `data:` lines
+ *   2. application/x-ndjson — one JSON object per line
+ *   3. Any other — forwards raw text chunks
+ *
+ * JSON events (SSE and NDJSON) are parsed with deepFindText for universal
+ * text extraction. Non-JSON content is forwarded as raw text.
+ */
+export declare function readStream(body: ReadableStream<Uint8Array>, contentType: string, callbacks: StreamCallbacks): Promise<void>;
+//# sourceMappingURL=stream-parser.d.ts.map

package/dist/stream/stream-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-parser.d.ts","sourceRoot":"","sources":["../../src/stream/stream-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAKT;AAUD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,MAAM,CA0B5D;AAID;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAUnE;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAKlF;AAID;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,eAAe,GACzB,OAAO,CAAC,IAAI,CAAC,CAkFf"}

package/dist/stream/stream-parser.js

@@ -0,0 +1,199 @@
+/**
+ * Universal stream parser for agent responses.
+ *
+ * Extracts text from any LLM provider's streaming format (Anthropic, OpenAI,
+ * Gemini, Cohere, Mistral, etc.) without hardcoding provider schemas.
+ * Uses depth-first search on well-known field names and container structures.
+ *
+ * Decoupled from any transport (WebSocket, HTTP, etc.) — callers provide
+ * callbacks for chunk delivery.
+ */
+// ── Detection ──
+/**
+ * Detect whether a response should be treated as a stream based on headers.
+ * Accepts raw header strings so callers aren't coupled to the fetch API.
+ */
+export function isStreamingContentType(contentType, transferEncoding) {
+    if (contentType.includes('text/event-stream'))
+        return true;
+    if (contentType.includes('application/x-ndjson'))
+        return true;
+    if (contentType.includes('text/plain') && transferEncoding?.includes('chunked'))
+        return true;
+    return false;
+}
+// ── Text extraction ──
+/** Well-known field names that carry streaming text across LLM providers. */
+const TEXT_FIELDS = ['text', 'content', 'chunk', 'message', 'output', 'response'];
+/** Well-known container fields that wrap text in nested structures. */
+const CONTAINER_FIELDS = ['delta', 'choices', 'candidates', 'parts', 'content_block', 'data', 'body'];
+/**
+ * Depth-first search for a text string in a JSON structure.
+ *
+ * Search strategy:
+ *   1. Check TEXT_FIELDS at current level (string values only)
+ *   2. Recurse into CONTAINER_FIELDS
+ *
+ * Works with any provider because it searches by field-name patterns,
+ * not by provider-specific schemas.
+ */
+export function deepFindText(obj, depth = 0) {
+    if (depth > 6)
+        return '';
+    if (!obj || typeof obj !== 'object')
+        return '';
+    const record = obj;
+    for (const key of TEXT_FIELDS) {
+        const val = record[key];
+        if (typeof val === 'string' && val.length > 0)
+            return val;
+    }
+    for (const key of CONTAINER_FIELDS) {
+        if (!(key in record))
+            continue;
+        const val = record[key];
+        if (Array.isArray(val)) {
+            for (const item of val) {
+                const found = deepFindText(item, depth + 1);
+                if (found)
+                    return found;
+            }
+        }
+        else {
+            const found = deepFindText(val, depth + 1);
+            if (found)
+                return found;
+        }
+    }
+    return '';
+}
+// ── Done detection ──
+/**
+ * Detect if a streaming JSON event signals end-of-stream.
+ *
+ * Recognized signals:
+ *   - type: "done" / "message_stop"
+ *   - choices[0].finish_reason !== null
+ *   - (HTTP stream close is handled by the reader, not here)
+ */
+export function isStreamDone(data) {
+    const t = data.type;
+    if (t === 'done' || t === 'message_stop')
+        return true;
+    if (Array.isArray(data.choices)) {
+        const first = data.choices[0];
+        if (first?.finish_reason != null)
+            return true;
+    }
+    return false;
+}
+// ── SessionId extraction ──
+/**
+ * Extract sessionId from a streaming event.
+ * Checks for a top-level `sessionId` string — no envelope format required.
+ */
+export function extractSessionId(data) {
+    if (typeof data.sessionId === 'string' && data.sessionId) {
+        return data.sessionId;
+    }
+    return undefined;
+}
+/**
+ * Read a streaming HTTP response and invoke callbacks for each text chunk.
+ *
+ * Supports three wire formats:
+ *   1. text/event-stream (SSE) — parses `data:` lines
+ *   2. application/x-ndjson — one JSON object per line
+ *   3. Any other — forwards raw text chunks
+ *
+ * JSON events (SSE and NDJSON) are parsed with deepFindText for universal
+ * text extraction. Non-JSON content is forwarded as raw text.
+ */
+export async function readStream(body, contentType, callbacks) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    const isSSE = contentType.includes('text/event-stream');
+    const isNDJSON = contentType.includes('application/x-ndjson');
+    let buffer = '';
+    let doneSent = false;
+    const emitDone = async () => {
+        if (doneSent)
+            return;
+        doneSent = true;
+        await callbacks.onDone();
+    };
+    const processJsonEvent = async (data) => {
+        const sid = extractSessionId(data);
+        if (sid)
+            await callbacks.onSessionId?.(sid);
+        if (isStreamDone(data)) {
+            await emitDone();
+            return;
+        }
+        const text = deepFindText(data);
+        if (text)
+            await callbacks.onChunk(text);
+    };
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            if (isSSE) {
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || '';
+                for (const line of lines) {
+                    if (!line || line.startsWith(':'))
+                        continue;
+                    if (!line.startsWith('data: '))
+                        continue;
+                    const payload = line.slice(6).trim();
+                    if (!payload)
+                        continue;
+                    if (payload === '[DONE]') {
+                        await emitDone();
+                        continue;
+                    }
+                    try {
+                        await processJsonEvent(JSON.parse(payload));
+                    }
+                    catch {
+                        // Not valid JSON — forward as raw text chunk
+                        await callbacks.onChunk(payload);
+                    }
+                }
+            }
+            else if (isNDJSON) {
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || '';
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed)
+                        continue;
+                    try {
+                        await processJsonEvent(JSON.parse(trimmed));
+                    }
+                    catch {
+                        // Not valid JSON — forward as raw text chunk
+                        await callbacks.onChunk(trimmed);
+                    }
+                }
+            }
+            else {
+                const chunk = buffer;
+                buffer = '';
+                if (chunk)
+                    await callbacks.onChunk(chunk);
+            }
+        }
+        await emitDone();
+    }
+    catch (err) {
+        console.error('Stream reading error:', err);
+        await emitDone().catch(() => { });
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/dist/transport/websocket.d.ts

@@ -0,0 +1,178 @@
+/**
+ * WebSocket transport envelope — the wire-framing layer for the live channel.
+ *
+ * The live channel is the live session plane between core-mcp and the
+ * user. This file defines HOW that plane is framed on a WebSocket:
+ * the dispatch discriminator
+ * (`WebSocketMessageType`), the discriminated union envelope
+ * (`WebSocketMessage`), and the client-side connection-lifecycle enum
+ * (`ConnectionStatus`).
+ *
+ * The CONTRACT payload shapes (what each variant carries —
+ * `SubscribePayload`, `AckPayload`, `StreamEnvelope`, etc.) live in
+ * `../types/live-channel`. Renaming the envelope or swapping in an
+ * alternate transport (e.g., a binary-framed variant, or SSE fallback)
+ * would not change the payload contract; that asymmetry is why the
+ * split exists.
+ *
+ * This module is exported as a subpath — `@ggui-ai/protocol/transport/
+ * websocket` — so only transport implementors (hosted Lambda handlers,
+ * OSS `/ws` server, web/RN WebSocketManager, connector ws-connection)
+ * pay its type/build cost. Consumers that only need contract payloads
+ * stay on the root import.
+ */
+import type { ActionEnvelope } from '../types/events';
+import type { JsonObject } from '../types/data-contract';
+import type { SubscribePayload, GeneratePayload, PopPayload, ClosePayload, GetStackPayload, AckPayload, ErrorPayload, PushPayload, StreamEnvelope, StreamPayload, SessionPayload, ProgressPayload, AgentMsgPayload, PropsUpdatePayload, UrlPayload, SystemPayload, InternalProgressPayload, ChannelSubscribePayload, ChannelUnsubscribePayload, ChannelPayloadFrame, ChannelErrorPayload, DrainAckPayload } from '../types/live-channel';
+import type { HostContextObservedPayload } from '../types/host-context';
+/**
+ * WebSocket message types for client-server communication.
+ * Each type maps to a specific payload shape in the {@link WebSocketMessage} discriminated union.
+ */
+export type WebSocketMessageType = 'action' | 'subscribe' | 'generate' | 'pop' | 'close' | 'get_stack' | 'feedback' | 'ping' | 'pong' | 'ack' | 'error' | 'push' | 'data' | 'stream' | 'session' | 'progress' | 'agent-msg' | 'props_update' | 'url' | 'system' | 'internal:progress' | 'channel_subscribe' | 'channel_unsubscribe' | 'channel_payload' | 'channel_error' | 'drain_ack' | 'host_context_observed' | 'canvas_navigated';
+/** Fields shared by all WebSocket message variants. */
+interface WsMessageBase {
+    requestId?: string;
+}
+/**
+ * Discriminated union of all WebSocket messages.
+ * The `type` field narrows `payload` automatically in switch/if blocks —
+ * no type casts needed. Each variant pairs a `WebSocketMessageType` with
+ * its corresponding payload interface.
+ *
+ * @example
+ * ```typescript
+ * function handle(msg: WebSocketMessage) {
+ *   switch (msg.type) {
+ *     case 'ack':
+ *       msg.payload.sequence; // AckPayload — auto-narrowed
+ *       break;
+ *     case 'error':
+ *       msg.payload.message; // ErrorPayload — auto-narrowed
+ *       msg.payload.details; // JsonValue | undefined
+ *       break;
+ *     case 'push':
+ *       msg.payload.stackItem; // PushPayload — auto-narrowed
+ *       break;
+ *     case 'data':
+ *       msg.payload.payload; // StreamEnvelope.payload
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export type WebSocketMessage = (WsMessageBase & {
+    type: 'action';
+    payload: ActionEnvelope;
+}) | (WsMessageBase & {
+    type: 'subscribe';
+    payload: SubscribePayload;
+}) | (WsMessageBase & {
+    type: 'generate';
+    payload: GeneratePayload;
+}) | (WsMessageBase & {
+    type: 'pop';
+    payload: PopPayload;
+}) | (WsMessageBase & {
+    type: 'close';
+    payload: ClosePayload;
+}) | (WsMessageBase & {
+    type: 'get_stack';
+    payload: GetStackPayload;
+}) | (WsMessageBase & {
+    type: 'feedback';
+    payload: JsonObject;
+}) | (WsMessageBase & {
+    type: 'ping';
+    payload: JsonObject;
+}) | (WsMessageBase & {
+    type: 'pong';
+    payload: JsonObject;
+}) | (WsMessageBase & {
+    type: 'ack';
+    payload: AckPayload;
+}) | (WsMessageBase & {
+    type: 'error';
+    payload: ErrorPayload;
+}) | (WsMessageBase & {
+    type: 'push';
+    payload: PushPayload;
+}) | (WsMessageBase & {
+    type: 'data';
+    payload: StreamEnvelope;
+}) | (WsMessageBase & {
+    type: 'stream';
+    payload: StreamPayload;
+}) | (WsMessageBase & {
+    type: 'session';
+    payload: SessionPayload;
+}) | (WsMessageBase & {
+    type: 'progress';
+    payload: ProgressPayload;
+}) | (WsMessageBase & {
+    type: 'agent-msg';
+    payload: AgentMsgPayload;
+}) | (WsMessageBase & {
+    type: 'props_update';
+    payload: PropsUpdatePayload;
+}) | (WsMessageBase & {
+    type: 'url';
+    payload: UrlPayload;
+}) | (WsMessageBase & {
+    type: 'system';
+    payload: SystemPayload;
+}) | (WsMessageBase & {
+    type: 'internal:progress';
+    payload: InternalProgressPayload;
+}) | (WsMessageBase & {
+    type: 'channel_subscribe';
+    payload: ChannelSubscribePayload;
+}) | (WsMessageBase & {
+    type: 'channel_unsubscribe';
+    payload: ChannelUnsubscribePayload;
+}) | (WsMessageBase & {
+    type: 'channel_payload';
+    payload: ChannelPayloadFrame;
+}) | (WsMessageBase & {
+    type: 'channel_error';
+    payload: ChannelErrorPayload;
+}) | (WsMessageBase & {
+    type: 'drain_ack';
+    payload: DrainAckPayload;
+}) | (WsMessageBase & {
+    type: 'host_context_observed';
+    payload: HostContextObservedPayload;
+}) | (WsMessageBase & {
+    type: 'canvas_navigated';
+    payload: CanvasNavigatedPayload;
+});
+/**
+ * Payload for the canvas-mode `canvas_navigated` message. Emitted by
+ * the iframe-runtime's CanvasShell when the user back-navigates — the
+ * server uses `activeItemId` to update `session.activeStackItemId`
+ * (for `ggui_consume`'s active-pipe resolution) and
+ * `previousActiveItemId` to optionally abort the cold-gen
+ * `AbortSignal` keyed on that stack item.
+ */
+export interface CanvasNavigatedPayload {
+    /** Tenancy guard — server compares against subscriber binding. */
+    readonly sessionId: string;
+    /**
+     * Stack-item id the canvas had as active immediately BEFORE the
+     * navigation. Null when navigating from the empty state (no prior
+     * active item).
+     */
+    readonly previousActiveItemId: string | null;
+    /**
+     * Stack-item id the canvas has as active immediately AFTER the
+     * navigation. Null when the user popped to an empty navStack.
+     */
+    readonly activeItemId: string | null;
+}
+/**
+ * WebSocket connection status. Client-side transport enum describing
+ * the browser/Node ws.readyState lifecycle.
+ */
+export type ConnectionStatus = 'connecting' | 'connected' | 'disconnected' | 'reconnecting';
+export {};
+//# sourceMappingURL=websocket.d.ts.map

package/dist/transport/websocket.d.ts.map

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

package/dist/transport/websocket.js

@@ -0,0 +1 @@
+export {};

package/dist/types/app-config.d.ts

@@ -0,0 +1,61 @@
+/**
+ * How a ggui app surfaces in MCP-Apps-capable hosts (Claude Desktop,
+ * claude.ai, future spec-compliant clients).
+ *
+ *   - `'inline'` (default): each `ggui_push` returns its own `ui://`
+ *     resource; the host mounts one iframe per push as a chat-message
+ *     widget. Today's behavior.
+ *   - `'canvas'`: `ggui_new_session` mints a single session-scoped
+ *     iframe (`ui://ggui/session/<sessionId>`) that persists for the
+ *     session; `ggui_push` delivers state via WebSocket to that
+ *     canvas. The canvas owns its own navigation stack + animator
+ *     chrome.
+ *
+ * Selecting `'canvas'` does NOT guarantee canvas rendering — the host
+ * may not support fullscreen / pip display modes. The canvas degrades
+ * gracefully to inline-style rendering when host capability is
+ * missing.
+ *
+ * Distinct from `defaultShellType`. `defaultShellType` controls how
+ * the LLM-generated UI adapts to its chrome (chat-card / fullscreen
+ * swipe / spatial floating). `defaultMcpAppsMode` controls how the
+ * MCP host presents ggui's iframe (one-per-push card / one-per-session
+ * canvas). Same app may set `defaultShellType: 'fullscreen'` AND
+ * `defaultMcpAppsMode: 'canvas'` — they're orthogonal concerns.
+ *
+ *
+ */
+export type McpAppsMode = 'inline' | 'canvas';
+/**
+ * Public display configuration for a ggui app.
+ * Returned by the app config endpoint — no secrets, no auth required.
+ */
+export interface AppDisplayConfig {
+    appId: string;
+    name: string;
+    defaultShellType: 'chat' | 'fullscreen' | 'spatial';
+    themeId: string;
+    defaultScreenPrompt?: string;
+    designSystemPreset?: string;
+    userAuthMode: string;
+    /**
+     * Agent invoke endpoint URL.
+     *
+     * Consumed by the `useInvoke` hook in `@ggui-ai/ggui-react` /
+     * `@ggui-ai/ggui-react-native` — the hook POSTs the user's message +
+     * history to `{endpointUrl}/invoke` and streams back the agent's
+     * response (Streamable Invoke Protocol). NOT used by the
+     * `ggui_handshake` → `ggui_push` mint path, which flows through MCP.
+     *
+     * Absent for apps without a deployed agent endpoint; `useInvoke`
+     * surfaces a clear error in that case.
+     */
+    endpointUrl?: string;
+    /**
+     * How this app surfaces in MCP-Apps-capable hosts. Absent ⇒
+     * `'inline'` (100% backward-compatible default). See {@link McpAppsMode}.
+     *
+     */
+    defaultMcpAppsMode?: McpAppsMode;
+}
+//# sourceMappingURL=app-config.d.ts.map

package/dist/types/app-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-config.d.ts","sourceRoot":"","sources":["../../src/types/app-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,WAAW,CAAC;CAClC"}

package/dist/types/app-config.js

@@ -0,0 +1 @@
+export {};

package/dist/types/auth.d.ts

@@ -0,0 +1,61 @@
+import type { JsonObject } from './data-contract';
+/**
+ * User authentication modes.
+ *
+ * - `anonymous`: no auth gate, cookie-based pseudonymous identity.
+ * - `cognito`: ggui-managed Cognito identity (OAuth/OIDC handled by platform).
+ * - `byo`: builder supplies their own JWT/OIDC issuer; platform validates against JWKS.
+ */
+export type UserAuthMode = 'anonymous' | 'cognito' | 'byo';
+/**
+ * Scopes requestable from ggui identity
+ */
+export type GguiAuthScope = 'email' | 'name' | 'picture';
+/**
+ * User auth config for cognito + byo modes.
+ * Matches the backend UserAuthConfig schema.
+ *
+ * BYO has two flavors:
+ *   - Render-surface HMAC-JWT shortcut: {@link authUrl} / {@link callbackSecret} /
+ *     {@link tokenClaimUserId} (`your-app.example/auth/callback`, iframe UIs).
+ *   - Portal BYO OAuth 2.1 flow: the `oauth*` fields below
+ *     (`your-app.example/oauth/byo/callback`, native Portal).
+ *   The `tokenClaim*` fields are reused across both flavors.
+ */
+export interface UserAuthConfig {
+    authUrl?: string;
+    callbackSecret?: string;
+    tokenClaimUserId?: string;
+    tokenClaimEmail?: string;
+    tokenClaimName?: string;
+    oauthAuthorizationUrl?: string;
+    oauthTokenUrl?: string;
+    oauthJwksUrl?: string;
+    oauthIssuer?: string;
+    oauthClientIdPublic?: string;
+    oauthScopes?: string[];
+    oauthRedirectUriAllowlist?: string[];
+    requestedScopes?: GguiAuthScope[];
+}
+/**
+ * Authenticated end-user identity.
+ * Attached to sessions and included in events consumed by agents.
+ *
+ * Extends {@link JsonObject} for direct JSON serialization over WebSocket.
+ */
+export interface EndUserIdentity extends JsonObject {
+    userId: string;
+    email?: string;
+    name?: string;
+    picture?: string;
+    provider: 'ggui' | 'custom';
+    authenticatedAt: string;
+}
+/**
+ * User auth settings for an app (convenience wrapper)
+ */
+export interface UserAuthSettings {
+    mode: UserAuthMode;
+    config?: UserAuthConfig;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/types/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/types/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,SAAS,GAAG,KAAK,CAAC;AAE3D;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAE7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,yBAAyB,CAAC,EAAE,MAAM,EAAE,CAAC;IAIrC,eAAe,CAAC,EAAE,aAAa,EAAE,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB"}

package/dist/types/auth.js

@@ -0,0 +1 @@
+export {};