@adia-ai/a2ui 0.8.37

package/stream.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A2UI Stream Adapters — connect to various transports and yield A2UI messages.
+ */
+
+/** Options shared by stream adapters that accept a catalog and/or AbortSignal. */
+export interface StreamOptions {
+  /** Component type catalog — limits types advertised to the server. */
+  catalog?: Map<string, unknown> | Record<string, unknown>;
+  /** AbortSignal to cancel the stream. */
+  signal?: AbortSignal;
+}
+
+/** Options for mcpStream — also accepts an action callback. */
+export interface McpStreamOptions extends StreamOptions {
+  /** Called when the MCP server emits an a2ui/action RPC method. */
+  onAction?: (name: string, args: unknown) => Promise<unknown>;
+}
+
+/**
+ * SSE (Server-Sent Events) stream adapter.
+ * Returns an AsyncIterable that yields parsed A2UI messages.
+ */
+export declare function sseStream(
+  url: string,
+  options?: StreamOptions,
+): AsyncIterable<unknown>;
+
+/**
+ * WebSocket stream adapter.
+ * Returns an AsyncIterable that yields parsed A2UI messages.
+ */
+export declare function wsStream(
+  url: string,
+  options?: StreamOptions,
+): AsyncIterable<unknown>;
+
+/**
+ * Array / mock stream adapter — for testing.
+ * Yields each message in the array, optionally with a delay between items.
+ */
+export declare function mockStream(
+  messages: readonly unknown[],
+  delay?: number,
+): AsyncIterable<unknown>;
+
+/**
+ * MCP (Model Context Protocol) stream adapter over WebSocket.
+ * Yields A2UI messages extracted from MCP JSON-RPC tool results.
+ */
+export declare function mcpStream(
+  url: string,
+  options?: McpStreamOptions,
+): AsyncIterable<unknown>;
+
+/**
+ * JSONL (newline-delimited JSON) stream adapter via fetch.
+ * Yields each parsed line from the response body.
+ */
+export declare function jsonlStream(
+  url: string,
+  options?: StreamOptions,
+): AsyncIterable<unknown>;

package/stream.js

@@ -0,0 +1,521 @@
+/**
+ * A2UI Stream Adapters — connect to various transports and yield A2UI messages.
+ *
+ * Each adapter returns an AsyncIterable<A2UIMessage>.
+ *
+ * Usage:
+ *   const stream = sseStream('/api/agent');
+ *   for await (const message of stream) { renderer.process(message); }
+ */
+
+/**
+ * SSE (Server-Sent Events) stream adapter.
+ */
+export function sseStream(url, options = {}) {
+  let finalUrl = url;
+  if (options.catalog) {
+    const types = options.catalog instanceof Map ? [...options.catalog.keys()] : Object.keys(options.catalog);
+    const sep = url.includes('?') ? '&' : '?';
+    finalUrl = `${url}${sep}a2ui_catalog=${encodeURIComponent(types.join(','))}`;
+  }
+
+  return {
+    [Symbol.asyncIterator]() {
+      const eventSource = new EventSource(finalUrl);
+      const queue = [];
+      let resolve = null;
+      let done = false;
+
+      eventSource.onmessage = (e) => {
+        try {
+          const message = JSON.parse(e.data);
+          if (resolve) { const r = resolve; resolve = null; r({ value: message, done: false }); }
+          else queue.push(message);
+        } catch { console.warn('A2UI SSE: invalid JSON', e.data); }
+      };
+
+      eventSource.onerror = () => {
+        done = true;
+        eventSource.close();
+        if (resolve) { const r = resolve; resolve = null; r({ value: undefined, done: true }); }
+      };
+
+      if (options.signal) {
+        options.signal.addEventListener('abort', () => {
+          done = true;
+          eventSource.close();
+          if (resolve) { const r = resolve; resolve = null; r({ value: undefined, done: true }); }
+        });
+      }
+
+      return {
+        next() {
+          if (queue.length > 0) return Promise.resolve({ value: queue.shift(), done: false });
+          if (done) return Promise.resolve({ value: undefined, done: true });
+          return new Promise(r => { resolve = r; });
+        },
+        return() {
+          done = true;
+          eventSource.close();
+          return Promise.resolve({ value: undefined, done: true });
+        },
+      };
+    },
+  };
+}
+
+/**
+ * WebSocket stream adapter.
+ */
+export function wsStream(url, options = {}) {
+  return {
+    [Symbol.asyncIterator]() {
+      const ws = new WebSocket(url);
+      const queue = [];
+      let resolve = null;
+      let done = false;
+
+      ws.onopen = () => {
+        if (options.catalog) {
+          const types = options.catalog instanceof Map ? [...options.catalog.keys()] : Object.keys(options.catalog);
+          ws.send(JSON.stringify({ type: 'a2ui:catalog', supportedTypes: types }));
+        }
+      };
+
+      ws.onmessage = (e) => {
+        try {
+          const message = JSON.parse(e.data);
+          if (resolve) { const r = resolve; resolve = null; r({ value: message, done: false }); }
+          else queue.push(message);
+        } catch { console.warn('A2UI WS: invalid JSON', e.data); }
+      };
+
+      ws.onclose = () => {
+        done = true;
+        if (resolve) { const r = resolve; resolve = null; r({ value: undefined, done: true }); }
+      };
+
+      ws.onerror = () => { done = true; ws.close(); };
+
+      return {
+        next() {
+          if (queue.length > 0) return Promise.resolve({ value: queue.shift(), done: false });
+          if (done) return Promise.resolve({ value: undefined, done: true });
+          return new Promise(r => { resolve = r; });
+        },
+        return() { done = true; ws.close(); return Promise.resolve({ value: undefined, done: true }); },
+      };
+    },
+  };
+}
+
+/**
+ * Array/mock stream adapter — for testing.
+ */
+export function mockStream(messages, delay = 0) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      for (const msg of messages) {
+        if (delay > 0) await new Promise(r => setTimeout(r, delay));
+        yield msg;
+      }
+    },
+  };
+}
+
+/**
+ * MCP stream adapter — connects to MCP server, yields A2UI messages.
+ *
+ * Dispatches by URL scheme:
+ *   ws://, wss://     -> WebSocket transport (legacy / custom MCP-over-WS)
+ *   http://, https:// -> MCP Streamable HTTP (spec 2025-11-25)
+ *   relative path     -> assume same-origin Streamable HTTP
+ */
+export function mcpStream(url, options = {}) {
+  const scheme = (url.split(':')[0] || '').toLowerCase();
+  if (scheme === 'ws' || scheme === 'wss') {
+    return mcpStreamWebSocket(url, options);
+  }
+  if (scheme === 'http' || scheme === 'https') {
+    return mcpStreamHttp(url, options);
+  }
+  // Default: relative path -> same-origin HTTP
+  return mcpStreamHttp(url, options);
+}
+
+/**
+ * Helper: extract A2UI messages from a JSON-RPC `result.content` array
+ * and push them into a queue/resolver pair.
+ */
+function _extractA2UIFromRpc(rpc, push) {
+  if (rpc.result?.content) {
+    for (const block of rpc.result.content) {
+      if (block.type === 'resource' && block.resource?.mimeType === 'application/json+a2ui') {
+        try {
+          const messages = JSON.parse(block.resource.text);
+          for (const msg of (Array.isArray(messages) ? messages : [messages])) push(msg);
+        } catch { /* malformed payload */ }
+      } else if (block.type === 'text') {
+        try {
+          const msg = JSON.parse(block.text);
+          if (msg.type && (msg.type.startsWith('create') || msg.type.startsWith('update') || msg.type.startsWith('delete'))) {
+            push(msg);
+          }
+        } catch { /* not A2UI */ }
+      }
+    }
+  }
+}
+
+/**
+ * MCP over WebSocket — original implementation, unchanged behavior.
+ */
+function mcpStreamWebSocket(url, options) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      const { signal, catalog, onAction } = options;
+
+      const ws = new WebSocket(url);
+      await new Promise((resolve, reject) => {
+        ws.onopen = resolve;
+        ws.onerror = reject;
+        if (signal) signal.addEventListener('abort', () => {
+          ws.close();
+          reject(new DOMException('Aborted', 'AbortError'));
+        }, { once: true });
+      });
+
+      if (catalog) {
+        const types = catalog instanceof Map ? [...catalog.keys()] : Object.keys(catalog);
+        ws.send(JSON.stringify({
+          jsonrpc: '2.0',
+          method: 'a2ui/catalog',
+          params: { supportedTypes: types },
+        }));
+      }
+
+      const queue = [];
+      let resolve = null;
+      let done = false;
+      const push = (msg) => {
+        if (resolve) { const r = resolve; resolve = null; r({ value: msg, done: false }); }
+        else queue.push(msg);
+      };
+
+      ws.onmessage = (e) => {
+        try {
+          const rpc = JSON.parse(e.data);
+          _extractA2UIFromRpc(rpc, push);
+
+          if (rpc.method === 'a2ui/action' && onAction) {
+            onAction(rpc.params?.name, rpc.params?.arguments).then(result => {
+              ws.send(JSON.stringify({ jsonrpc: '2.0', id: rpc.id, result }));
+            }).catch(err => {
+              ws.send(JSON.stringify({ jsonrpc: '2.0', id: rpc.id, error: { code: -1, message: err.message } }));
+            });
+          }
+        } catch { console.warn('A2UI MCP: invalid message', e.data); }
+      };
+
+      ws.onclose = () => { done = true; if (resolve) { const r = resolve; resolve = null; r({ value: undefined, done: true }); } };
+      ws.onerror = () => { done = true; ws.close(); };
+      if (signal) signal.addEventListener('abort', () => { done = true; ws.close(); if (resolve) { const r = resolve; resolve = null; r({ value: undefined, done: true }); } });
+
+      while (!done || queue.length > 0) {
+        if (queue.length > 0) { yield queue.shift(); }
+        else if (done) { break; }
+        else {
+          const v = await new Promise(r => { resolve = r; });
+          if (v.done) break;
+          yield v.value;
+        }
+      }
+    },
+  };
+}
+
+/**
+ * MCP over Streamable HTTP — per MCP spec 2025-11-25.
+ *
+ * Protocol:
+ *   1. POST <url> with JSON-RPC `initialize` request. Server replies with
+ *      `mcp-session-id` header and either JSON or an SSE stream.
+ *   2. POST <url> with `notifications/initialized` (header set) to complete handshake.
+ *   3. GET <url> with `mcp-session-id` header (Accept: text/event-stream) opens
+ *      a long-lived SSE stream of server->client JSON-RPC messages.
+ *   4. Each SSE `data:` event is a JSON-RPC message. We extract A2UI messages
+ *      from `result.content` blocks the same way as the WS path.
+ *   5. If the server emits an `a2ui/action` request method, we POST a JSON-RPC
+ *      response back to <url> with the session header.
+ *
+ * Note: this is a minimal client. Tools must be invoked separately by the
+ * consumer (this adapter is the *transport*, not a tool-call orchestrator).
+ * If the consumer needs feature-complete MCP semantics (resumability, request
+ * batching, cancellation tokens), use `@modelcontextprotocol/sdk`'s
+ * `StreamableHTTPClientTransport` directly.
+ */
+function mcpStreamHttp(url, options) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      const { signal, catalog, onAction } = options;
+
+      const queue = [];
+      let resolve = null;
+      let done = false;
+      const push = (msg) => {
+        if (resolve) { const r = resolve; resolve = null; r({ value: msg, done: false }); }
+        else queue.push(msg);
+      };
+      const finish = () => {
+        done = true;
+        if (resolve) { const r = resolve; resolve = null; r({ value: undefined, done: true }); }
+      };
+
+      // --- 1. initialize handshake ---
+      const initBody = {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2025-11-25',
+          capabilities: {},
+          clientInfo: { name: 'a2ui', version: '0.0.0' },
+        },
+      };
+
+      let initResp;
+      try {
+        initResp = await fetch(url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json, text/event-stream',
+          },
+          body: JSON.stringify(initBody),
+          signal,
+        });
+      } catch (err) {
+        console.warn('A2UI MCP HTTP: initialize failed', err);
+        return;
+      }
+
+      if (!initResp.ok) {
+        console.warn(`A2UI MCP HTTP: initialize returned ${initResp.status}`);
+        return;
+      }
+
+      const sessionId = initResp.headers.get('mcp-session-id');
+      if (!sessionId) {
+        console.warn('A2UI MCP HTTP: server did not return mcp-session-id header');
+        // Try to drain body so the connection can be reused
+        try { await initResp.text(); } catch { /* ignore */ }
+        return;
+      }
+
+      // Drain initialize response body (we don't need its result for streaming)
+      try {
+        const ct = initResp.headers.get('content-type') || '';
+        if (ct.includes('text/event-stream')) {
+          // Read & discard
+          const reader = initResp.body.getReader();
+          // Read just enough to consume the initialize response then move on
+          const decoder = new TextDecoder();
+          let buf = '';
+          // eslint-disable-next-line no-constant-condition
+          while (true) {
+            const { done: rd, value } = await reader.read();
+            if (rd) break;
+            buf += decoder.decode(value, { stream: true });
+            if (buf.includes('\n\n')) break; // got at least one SSE event
+          }
+          try { reader.cancel(); } catch { /* ignore */ }
+        } else {
+          await initResp.json().catch(() => null);
+        }
+      } catch { /* ignore */ }
+
+      // --- 2. send `notifications/initialized` ---
+      try {
+        await fetch(url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json, text/event-stream',
+            'mcp-session-id': sessionId,
+          },
+          body: JSON.stringify({
+            jsonrpc: '2.0',
+            method: 'notifications/initialized',
+          }),
+          signal,
+        }).then(r => r.text()).catch(() => null);
+      } catch { /* ignore */ }
+
+      // --- 3. optional: advertise catalog as a custom notification ---
+      if (catalog) {
+        const types = catalog instanceof Map ? [...catalog.keys()] : Object.keys(catalog);
+        try {
+          await fetch(url, {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              'Accept': 'application/json, text/event-stream',
+              'mcp-session-id': sessionId,
+            },
+            body: JSON.stringify({
+              jsonrpc: '2.0',
+              method: 'a2ui/catalog',
+              params: { supportedTypes: types },
+            }),
+            signal,
+          }).then(r => r.text()).catch(() => null);
+        } catch { /* ignore */ }
+      }
+
+      // Helper to POST a JSON-RPC response (for server->client requests)
+      const postRpc = (msg) => {
+        return fetch(url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json, text/event-stream',
+            'mcp-session-id': sessionId,
+          },
+          body: JSON.stringify(msg),
+          signal,
+        }).then(r => r.text()).catch(() => null);
+      };
+
+      // Handle an incoming JSON-RPC message
+      const handleRpc = (rpc) => {
+        _extractA2UIFromRpc(rpc, push);
+        if (rpc.method === 'a2ui/action' && onAction) {
+          Promise.resolve()
+            .then(() => onAction(rpc.params?.name, rpc.params?.arguments))
+            .then(result => postRpc({ jsonrpc: '2.0', id: rpc.id, result }))
+            .catch(err => postRpc({ jsonrpc: '2.0', id: rpc.id, error: { code: -1, message: err.message } }));
+        }
+      };
+
+      // --- 4. open long-lived GET SSE stream ---
+      let getResp;
+      try {
+        getResp = await fetch(url, {
+          method: 'GET',
+          headers: {
+            'Accept': 'text/event-stream',
+            'mcp-session-id': sessionId,
+          },
+          signal,
+        });
+      } catch (err) {
+        if (err?.name !== 'AbortError') console.warn('A2UI MCP HTTP: GET stream failed', err);
+        return;
+      }
+
+      if (!getResp.ok || !getResp.body) {
+        console.warn(`A2UI MCP HTTP: GET stream returned ${getResp.status}`);
+        return;
+      }
+
+      // Wire abort
+      if (signal) {
+        signal.addEventListener('abort', finish, { once: true });
+      }
+
+      // Best-effort: DELETE session on stream close to free server-side state
+      const closeSession = () => {
+        try {
+          fetch(url, {
+            method: 'DELETE',
+            headers: { 'mcp-session-id': sessionId },
+          }).catch(() => null);
+        } catch { /* ignore */ }
+      };
+
+      // SSE parser loop (running concurrently with the yield loop)
+      (async () => {
+        const reader = getResp.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+          while (!done) {
+            const { done: rd, value } = await reader.read();
+            if (rd) break;
+            buffer += decoder.decode(value, { stream: true });
+            let idx;
+            // SSE events separated by blank lines
+            while ((idx = buffer.indexOf('\n\n')) !== -1) {
+              const rawEvent = buffer.slice(0, idx);
+              buffer = buffer.slice(idx + 2);
+              const dataLines = [];
+              for (const line of rawEvent.split('\n')) {
+                if (line.startsWith('data:')) dataLines.push(line.slice(5).trimStart());
+              }
+              if (dataLines.length === 0) continue;
+              const data = dataLines.join('\n');
+              try {
+                const rpc = JSON.parse(data);
+                handleRpc(rpc);
+              } catch {
+                console.warn('A2UI MCP HTTP: invalid JSON-RPC SSE payload', data);
+              }
+            }
+          }
+        } catch (err) {
+          if (err?.name !== 'AbortError') console.warn('A2UI MCP HTTP: stream read error', err);
+        } finally {
+          finish();
+          closeSession();
+        }
+      })();
+
+      while (!done || queue.length > 0) {
+        if (queue.length > 0) { yield queue.shift(); }
+        else if (done) { break; }
+        else {
+          const v = await new Promise(r => { resolve = r; });
+          if (v.done) break;
+          yield v.value;
+        }
+      }
+    },
+  };
+}
+
+/**
+ * JSONL (newline-delimited JSON) stream adapter via fetch.
+ */
+export function jsonlStream(url, options = {}) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      const headers = {};
+      if (options.catalog) {
+        const types = options.catalog instanceof Map ? [...options.catalog.keys()] : Object.keys(options.catalog);
+        headers['X-A2UI-Catalog'] = types.join(',');
+      }
+      const response = await fetch(url, { signal: options.signal, headers });
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop();
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          try { yield JSON.parse(trimmed); }
+          catch { console.warn('A2UI JSONL: invalid JSON', trimmed); }
+        }
+      }
+      if (buffer.trim()) {
+        try { yield JSON.parse(buffer.trim()); }
+        catch { /* ignore */ }
+      }
+    },
+  };
+}

package/surface-manifest.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Surface Manifest — Multi-surface relationship document (A008).
+ */
+
+export interface SurfaceDescriptor {
+  name: string;
+  route?: string;
+  entryPoint?: boolean;
+  requiredParams?: string[];
+  produces?: Record<string, object>;
+  consumes?: Record<string, { keys: string[] }>;
+  status?: 'generated' | 'manual' | 'template' | 'placeholder';
+  generatedBy?: string;
+  tags?: string[];
+}
+
+export type AssociationType =
+  | 'routes-to'
+  | 'feeds'
+  | 'shares-context'
+  | 'depends-on'
+  | 'triggers'
+  | 'contains'
+  | 'slots-into';
+
+export interface Association {
+  type: AssociationType;
+  from: string;
+  to: string;
+  trigger?: string;
+  params?: Record<string, object>;
+  mapping?: object;
+  context?: string;
+  condition?: string;
+  fallback?: string;
+  effect?: string;
+  slot?: string;
+  position?: number;
+  meta?: object;
+}
+
+export interface ManifestValidationResult {
+  valid: boolean;
+  issues: Array<{ severity: 'error' | 'warning'; message: string }>;
+}
+
+export interface ManifestOptions {
+  id: string;
+  name: string;
+  version?: string;
+}
+
+export declare class SurfaceManifest {
+  constructor(opts: ManifestOptions);
+
+  readonly surfaceIds: string[];
+
+  addSurface(surfaceId: string, descriptor: SurfaceDescriptor): void;
+  removeSurface(surfaceId: string): void;
+  getSurface(surfaceId: string): SurfaceDescriptor | null;
+
+  addAssociation(association: Association): void;
+  getAssociationsFrom(surfaceId: string, type?: AssociationType): Association[];
+  getAssociationsTo(surfaceId: string, type?: AssociationType): Association[];
+  getSharedContextPeers(surfaceId: string): Array<{ surfaceId: string; context: string | undefined }>;
+
+  defineSharedContext(name: string, config: object): void;
+  getSharedContext(name: string): object | null;
+
+  validate(): ManifestValidationResult;
+  toJSON(): object;
+  static fromJSON(json: object): SurfaceManifest;
+}