@lantos1618/better-ui 0.5.0 → 0.6.0

package/README.md

@@ -52,6 +52,7 @@ npm install @lantos1618/better-ui zod
 |---------|------|
 | **View integration** | Tools render their own results — no other framework does this |
 | **MCP server** | Expose any tool registry to Claude Desktop, Cursor, VS Code |
+| **AG-UI protocol** | Compatible with CopilotKit, LangChain, Google ADK frontends |
 | **Multi-provider** | OpenAI, Anthropic, Google Gemini, OpenRouter |
 | **Streaming views** | Progressive partial data rendering |
 | **Drop-in chat** | `<Chat />` component with automatic tool view rendering |
@@ -404,6 +405,26 @@ zodToJsonSchema(z.object({
 
 ---
 
+## AG-UI Protocol
+
+Expose your tools via the [AG-UI (Agent-User Interaction Protocol)](https://docs.ag-ui.com) — compatible with CopilotKit, LangChain, Google ADK, and any AG-UI frontend.
+
+```typescript
+import { createAGUIServer } from '@lantos1618/better-ui/agui';
+
+const server = createAGUIServer({
+  name: 'my-tools',
+  tools: { weather, search },
+});
+
+// Next.js route handler — returns SSE event stream
+export const POST = server.handler();
+```
+
+The handler emits standard AG-UI events (`RUN_STARTED`, `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_RESULT`, `TOOL_CALL_END`, `RUN_FINISHED`) over Server-Sent Events.
+
+---
+
 ## Providers
 
 ```typescript
@@ -532,8 +553,10 @@ src/
     types.ts             PersistenceAdapter interface
     memory.ts            In-memory adapter
   mcp/
-    server.ts            MCP server (stdio + HTTP)
+    server.ts            MCP server (stdio + HTTP + SSE)
     schema.ts            Zod → JSON Schema converter
+  agui/
+    server.ts            AG-UI protocol server (SSE)
 examples/
   nextjs-demo/           Full Next.js demo app
   vite-demo/             Vite + Express demo app
@@ -545,7 +568,7 @@ examples/
 ```bash
 npm install
 npm run build        # Build library
-npm test             # Run tests (163 tests)
+npm test             # Run tests (226 tests)
 npm run type-check   # TypeScript check
 ```
 

package/dist/agui/index.d.mts

@@ -0,0 +1,116 @@
+import { T as Tool, c as ToolContext } from '../tool-Ca2x-VNK.mjs';
+import 'zod';
+import 'react';
+
+/**
+ * AG-UI (Agent-User Interaction Protocol) Server for Better UI
+ *
+ * Implements the AG-UI protocol, allowing Better UI tools to be used with
+ * CopilotKit, LangChain, and any AG-UI compatible frontend.
+ *
+ * Protocol: Server-Sent Events (SSE) over HTTP
+ *
+ * @see https://docs.ag-ui.com
+ *
+ * @example
+ * ```typescript
+ * import { createAGUIServer } from '@lantos1618/better-ui/agui';
+ *
+ * const server = createAGUIServer({
+ *   name: 'my-tools',
+ *   tools: { weather: weatherTool, search: searchTool },
+ * });
+ *
+ * // Next.js route handler
+ * export const POST = server.handler();
+ * ```
+ */
+
+type AGUIEventType = 'RUN_STARTED' | 'RUN_FINISHED' | 'RUN_ERROR' | 'STEP_STARTED' | 'STEP_FINISHED' | 'TEXT_MESSAGE_START' | 'TEXT_MESSAGE_CONTENT' | 'TEXT_MESSAGE_END' | 'TOOL_CALL_START' | 'TOOL_CALL_ARGS' | 'TOOL_CALL_END' | 'TOOL_CALL_RESULT' | 'STATE_SNAPSHOT' | 'STATE_DELTA' | 'CUSTOM' | 'RAW';
+interface AGUIEvent {
+    type: AGUIEventType;
+    timestamp?: number;
+    [key: string]: unknown;
+}
+interface RunAgentInput {
+    threadId: string;
+    runId: string;
+    /** Tool calls to execute */
+    tools?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    /** Messages context */
+    messages?: Array<{
+        role: string;
+        content: string;
+    }>;
+    /** Tool call to execute (for direct tool invocation) */
+    toolCall?: {
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    };
+    /** State context from the frontend */
+    state?: Record<string, unknown>;
+}
+interface AGUIServerConfig {
+    /** Server name */
+    name: string;
+    /** Tool registry — keys are tool names */
+    tools: Record<string, Tool>;
+    /** Optional context passed to every tool execution */
+    context?: Partial<ToolContext>;
+    /** Called on errors */
+    onError?: (error: Error) => void;
+}
+declare class AGUIServer {
+    private config;
+    constructor(config: AGUIServerConfig);
+    /** Get available tools in AG-UI format */
+    listTools(): Array<{
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    }>;
+    /**
+     * Create an HTTP handler that implements the AG-UI protocol.
+     * Returns an SSE stream of AG-UI events.
+     *
+     * @example
+     * ```typescript
+     * // Next.js: app/api/agui/route.ts
+     * export const POST = server.handler();
+     *
+     * // Express:
+     * app.post('/api/agui', (req, res) => server.handler()(req));
+     * ```
+     */
+    handler(): (req: Request) => Promise<Response>;
+    /**
+     * Execute a tool call and emit AG-UI events.
+     */
+    private executeToolCall;
+    /**
+     * Minimal Zod-to-JSON-Schema for AG-UI tool parameters.
+     * Delegates to the MCP schema converter if available, otherwise provides a basic fallback.
+     */
+    private zodToJsonSchema;
+}
+/**
+ * Create an AG-UI server from a Better UI tool registry.
+ *
+ * @example
+ * ```typescript
+ * const server = createAGUIServer({
+ *   name: 'my-app',
+ *   tools: { weather: weatherTool, search: searchTool },
+ * });
+ *
+ * // Use as Next.js route handler
+ * export const POST = server.handler();
+ * ```
+ */
+declare function createAGUIServer(config: AGUIServerConfig): AGUIServer;
+
+export { type AGUIEvent, type AGUIEventType, AGUIServer, type AGUIServerConfig, type RunAgentInput, createAGUIServer };

package/dist/agui/index.d.ts

@@ -0,0 +1,116 @@
+import { T as Tool, c as ToolContext } from '../tool-Ca2x-VNK.js';
+import 'zod';
+import 'react';
+
+/**
+ * AG-UI (Agent-User Interaction Protocol) Server for Better UI
+ *
+ * Implements the AG-UI protocol, allowing Better UI tools to be used with
+ * CopilotKit, LangChain, and any AG-UI compatible frontend.
+ *
+ * Protocol: Server-Sent Events (SSE) over HTTP
+ *
+ * @see https://docs.ag-ui.com
+ *
+ * @example
+ * ```typescript
+ * import { createAGUIServer } from '@lantos1618/better-ui/agui';
+ *
+ * const server = createAGUIServer({
+ *   name: 'my-tools',
+ *   tools: { weather: weatherTool, search: searchTool },
+ * });
+ *
+ * // Next.js route handler
+ * export const POST = server.handler();
+ * ```
+ */
+
+type AGUIEventType = 'RUN_STARTED' | 'RUN_FINISHED' | 'RUN_ERROR' | 'STEP_STARTED' | 'STEP_FINISHED' | 'TEXT_MESSAGE_START' | 'TEXT_MESSAGE_CONTENT' | 'TEXT_MESSAGE_END' | 'TOOL_CALL_START' | 'TOOL_CALL_ARGS' | 'TOOL_CALL_END' | 'TOOL_CALL_RESULT' | 'STATE_SNAPSHOT' | 'STATE_DELTA' | 'CUSTOM' | 'RAW';
+interface AGUIEvent {
+    type: AGUIEventType;
+    timestamp?: number;
+    [key: string]: unknown;
+}
+interface RunAgentInput {
+    threadId: string;
+    runId: string;
+    /** Tool calls to execute */
+    tools?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    /** Messages context */
+    messages?: Array<{
+        role: string;
+        content: string;
+    }>;
+    /** Tool call to execute (for direct tool invocation) */
+    toolCall?: {
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    };
+    /** State context from the frontend */
+    state?: Record<string, unknown>;
+}
+interface AGUIServerConfig {
+    /** Server name */
+    name: string;
+    /** Tool registry — keys are tool names */
+    tools: Record<string, Tool>;
+    /** Optional context passed to every tool execution */
+    context?: Partial<ToolContext>;
+    /** Called on errors */
+    onError?: (error: Error) => void;
+}
+declare class AGUIServer {
+    private config;
+    constructor(config: AGUIServerConfig);
+    /** Get available tools in AG-UI format */
+    listTools(): Array<{
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    }>;
+    /**
+     * Create an HTTP handler that implements the AG-UI protocol.
+     * Returns an SSE stream of AG-UI events.
+     *
+     * @example
+     * ```typescript
+     * // Next.js: app/api/agui/route.ts
+     * export const POST = server.handler();
+     *
+     * // Express:
+     * app.post('/api/agui', (req, res) => server.handler()(req));
+     * ```
+     */
+    handler(): (req: Request) => Promise<Response>;
+    /**
+     * Execute a tool call and emit AG-UI events.
+     */
+    private executeToolCall;
+    /**
+     * Minimal Zod-to-JSON-Schema for AG-UI tool parameters.
+     * Delegates to the MCP schema converter if available, otherwise provides a basic fallback.
+     */
+    private zodToJsonSchema;
+}
+/**
+ * Create an AG-UI server from a Better UI tool registry.
+ *
+ * @example
+ * ```typescript
+ * const server = createAGUIServer({
+ *   name: 'my-app',
+ *   tools: { weather: weatherTool, search: searchTool },
+ * });
+ *
+ * // Use as Next.js route handler
+ * export const POST = server.handler();
+ * ```
+ */
+declare function createAGUIServer(config: AGUIServerConfig): AGUIServer;
+
+export { type AGUIEvent, type AGUIEventType, AGUIServer, type AGUIServerConfig, type RunAgentInput, createAGUIServer };

package/dist/agui/index.js

@@ -0,0 +1,328 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/mcp/schema.ts
+var schema_exports = {};
+__export(schema_exports, {
+  zodToJsonSchema: () => zodToJsonSchema
+});
+function zodToJsonSchema(schema) {
+  return convert(schema);
+}
+function convert(schema) {
+  const def = schema._def;
+  const typeName = def?.typeName;
+  switch (typeName) {
+    case "ZodString":
+      return convertString(def);
+    case "ZodNumber":
+      return convertNumber(def);
+    case "ZodBoolean":
+      return { type: "boolean" };
+    case "ZodNull":
+      return { type: "null" };
+    case "ZodLiteral":
+      return { enum: [def.value] };
+    case "ZodEnum":
+      return { type: "string", enum: def.values };
+    case "ZodNativeEnum":
+      return { enum: Object.values(def.values) };
+    case "ZodObject":
+      return convertObject(def);
+    case "ZodArray":
+      return convertArray(def);
+    case "ZodOptional":
+      return convert(def.innerType);
+    case "ZodNullable": {
+      const inner = convert(def.innerType);
+      return { anyOf: [inner, { type: "null" }] };
+    }
+    case "ZodDefault":
+      return { ...convert(def.innerType), default: def.defaultValue() };
+    case "ZodUnion":
+      return { anyOf: def.options.map((o) => convert(o)) };
+    case "ZodDiscriminatedUnion":
+      return { oneOf: [...def.options.values()].map((o) => convert(o)) };
+    case "ZodRecord":
+      return {
+        type: "object",
+        additionalProperties: convert(def.valueType)
+      };
+    case "ZodTuple": {
+      const items = def.items.map((item) => convert(item));
+      return { type: "array", items: items.length === 1 ? items[0] : void 0, prefixItems: items };
+    }
+    case "ZodEffects":
+      return convert(def.schema);
+    case "ZodPipeline":
+      return convert(def.in);
+    case "ZodLazy":
+      return convert(def.getter());
+    case "ZodAny":
+      return {};
+    case "ZodUnknown":
+      return {};
+    default:
+      return {};
+  }
+}
+function convertString(def) {
+  const schema = { type: "string" };
+  if (def.checks) {
+    for (const check of def.checks) {
+      switch (check.kind) {
+        case "min":
+          schema.minLength = check.value;
+          break;
+        case "max":
+          schema.maxLength = check.value;
+          break;
+        case "email":
+          schema.format = "email";
+          break;
+        case "url":
+          schema.format = "uri";
+          break;
+        case "uuid":
+          schema.format = "uuid";
+          break;
+        case "regex":
+          schema.pattern = check.regex.source;
+          break;
+      }
+    }
+  }
+  if (def.description) schema.description = def.description;
+  return schema;
+}
+function convertNumber(def) {
+  const schema = { type: "number" };
+  if (def.checks) {
+    for (const check of def.checks) {
+      switch (check.kind) {
+        case "min":
+          schema.minimum = check.value;
+          if (check.inclusive === false) schema.exclusiveMinimum = check.value;
+          break;
+        case "max":
+          schema.maximum = check.value;
+          if (check.inclusive === false) schema.exclusiveMaximum = check.value;
+          break;
+        case "int":
+          schema.type = "integer";
+          break;
+      }
+    }
+  }
+  if (def.description) schema.description = def.description;
+  return schema;
+}
+function convertObject(def) {
+  const shape = def.shape();
+  const properties = {};
+  const required = [];
+  for (const [key, value] of Object.entries(shape)) {
+    properties[key] = convert(value);
+    const fieldDef = value._def;
+    const isOptional = fieldDef?.typeName === "ZodOptional" || fieldDef?.typeName === "ZodDefault";
+    if (!isOptional) {
+      required.push(key);
+    }
+  }
+  const schema = { type: "object", properties };
+  if (required.length > 0) schema.required = required;
+  if (def.description) schema.description = def.description;
+  return schema;
+}
+function convertArray(def) {
+  const schema = {
+    type: "array",
+    items: convert(def.type)
+  };
+  if (def.minLength) schema.minItems = def.minLength.value;
+  if (def.maxLength) schema.maxItems = def.maxLength.value;
+  if (def.description) schema.description = def.description;
+  return schema;
+}
+var init_schema = __esm({
+  "src/mcp/schema.ts"() {
+    "use strict";
+  }
+});
+
+// src/agui/index.ts
+var agui_exports = {};
+__export(agui_exports, {
+  AGUIServer: () => AGUIServer,
+  createAGUIServer: () => createAGUIServer
+});
+module.exports = __toCommonJS(agui_exports);
+
+// src/agui/server.ts
+var AGUIServer = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /** Get available tools in AG-UI format */
+  listTools() {
+    return Object.values(this.config.tools).map((tool) => ({
+      name: tool.name,
+      description: tool.description || tool.name,
+      parameters: this.zodToJsonSchema(tool.inputSchema)
+    }));
+  }
+  /**
+   * Create an HTTP handler that implements the AG-UI protocol.
+   * Returns an SSE stream of AG-UI events.
+   *
+   * @example
+   * ```typescript
+   * // Next.js: app/api/agui/route.ts
+   * export const POST = server.handler();
+   *
+   * // Express:
+   * app.post('/api/agui', (req, res) => server.handler()(req));
+   * ```
+   */
+  handler() {
+    return async (req) => {
+      let input;
+      try {
+        input = await req.json();
+      } catch {
+        return new Response("Invalid JSON", { status: 400 });
+      }
+      const { threadId, runId, toolCall } = input;
+      if (!threadId || !runId) {
+        return new Response("Missing threadId or runId", { status: 400 });
+      }
+      const encoder = new TextEncoder();
+      const self = this;
+      const stream = new ReadableStream({
+        async start(controller) {
+          const emit = (event) => {
+            const data = JSON.stringify({ ...event, timestamp: event.timestamp ?? Date.now() });
+            controller.enqueue(encoder.encode(`data: ${data}
+
+`));
+          };
+          try {
+            emit({ type: "RUN_STARTED", threadId, runId });
+            if (toolCall) {
+              await self.executeToolCall(toolCall, emit);
+            } else {
+              const tools = self.listTools();
+              const messageId = `msg_${runId}`;
+              emit({ type: "TEXT_MESSAGE_START", messageId, role: "assistant" });
+              emit({
+                type: "TEXT_MESSAGE_CONTENT",
+                messageId,
+                delta: `Available tools: ${tools.map((t) => t.name).join(", ")}`
+              });
+              emit({ type: "TEXT_MESSAGE_END", messageId });
+            }
+            emit({ type: "RUN_FINISHED", threadId, runId });
+          } catch (err) {
+            emit({
+              type: "RUN_ERROR",
+              threadId,
+              runId,
+              message: err instanceof Error ? err.message : "Unknown error"
+            });
+            self.config.onError?.(err instanceof Error ? err : new Error(String(err)));
+          }
+          controller.close();
+        }
+      });
+      return new Response(stream, {
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          "Connection": "keep-alive"
+        }
+      });
+    };
+  }
+  /**
+   * Execute a tool call and emit AG-UI events.
+   */
+  async executeToolCall(toolCall, emit) {
+    const { id, name, args } = toolCall;
+    if (!Object.prototype.hasOwnProperty.call(this.config.tools, name)) {
+      emit({
+        type: "TOOL_CALL_START",
+        toolCallId: id,
+        toolCallName: name
+      });
+      emit({
+        type: "TOOL_CALL_END",
+        toolCallId: id
+      });
+      throw new Error(`Unknown tool: ${name}`);
+    }
+    const tool = this.config.tools[name];
+    emit({
+      type: "TOOL_CALL_START",
+      toolCallId: id,
+      toolCallName: name
+    });
+    emit({
+      type: "TOOL_CALL_ARGS",
+      toolCallId: id,
+      delta: JSON.stringify(args)
+    });
+    const result = await tool.run(args, {
+      isServer: true,
+      ...this.config.context
+    });
+    const resultText = typeof result === "string" ? result : JSON.stringify(result);
+    emit({
+      type: "TOOL_CALL_RESULT",
+      toolCallId: id,
+      result: resultText
+    });
+    emit({
+      type: "TOOL_CALL_END",
+      toolCallId: id
+    });
+  }
+  /**
+   * Minimal Zod-to-JSON-Schema for AG-UI tool parameters.
+   * Delegates to the MCP schema converter if available, otherwise provides a basic fallback.
+   */
+  zodToJsonSchema(schema) {
+    try {
+      const { zodToJsonSchema: zodToJsonSchema2 } = (init_schema(), __toCommonJS(schema_exports));
+      return zodToJsonSchema2(schema);
+    } catch {
+      return { type: "object", properties: {} };
+    }
+  }
+};
+function createAGUIServer(config) {
+  return new AGUIServer(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AGUIServer,
+  createAGUIServer
+});