freesail 0.0.1 → 0.1.0

package/packages/server/src/adapters/openai.ts

@@ -0,0 +1,209 @@
+/**
+ * OpenAI Adapter
+ * 
+ * Converts Freesail tools to OpenAI function calling format.
+ * This adapter allows using Freesail with the OpenAI API directly.
+ * 
+ * NOTE: This adapter requires 'openai' as a peer dependency.
+ */
+
+import type { FreesailStream } from '../stream.js';
+import type { CatalogToToolConverter, OpenAITool } from '../catalog-loader.js';
+import { toolCallToMessages, updateDataToMessage } from '../catalog-loader.js';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface OpenAIAdapterOptions {
+  /** The SSE stream to send messages to */
+  stream: FreesailStream;
+  /** Catalog ID being used */
+  catalogId: string;
+  /** Tool converter instance */
+  converter: CatalogToToolConverter;
+}
+
+export interface ToolCallResult {
+  success: boolean;
+  message: string;
+  surfaceId?: string;
+}
+
+// =============================================================================
+// OpenAI Adapter
+// =============================================================================
+
+/**
+ * OpenAIAdapter handles tool calls from OpenAI and converts them
+ * to A2UX messages sent via the stream.
+ */
+export class OpenAIAdapter {
+  private stream: FreesailStream;
+  private catalogId: string;
+  private converter: CatalogToToolConverter;
+
+  constructor(options: OpenAIAdapterOptions) {
+    this.stream = options.stream;
+    this.catalogId = options.catalogId;
+    this.converter = options.converter;
+  }
+
+  /**
+   * Get tools in OpenAI format
+   */
+  getTools(): OpenAITool[] {
+    return this.converter.generateOpenAITools(this.catalogId);
+  }
+
+  /**
+   * Handle a tool call from OpenAI
+   */
+  handleToolCall(
+    toolName: string, 
+    args: Record<string, unknown>
+  ): ToolCallResult {
+    switch (toolName) {
+      case 'render_ui':
+        return this.handleRenderUI(args);
+      case 'update_data':
+        return this.handleUpdateData(args);
+      default:
+        return { 
+          success: false, 
+          message: `Unknown tool: ${toolName}` 
+        };
+    }
+  }
+
+  /**
+   * Handle render_ui tool call
+   */
+  private handleRenderUI(args: Record<string, unknown>): ToolCallResult {
+    const { surfaceId, components } = args as {
+      surfaceId: string;
+      components: Array<{ id: string; component: string; [key: string]: unknown }>;
+    };
+
+    if (!surfaceId || !components) {
+      return { 
+        success: false, 
+        message: 'Missing required parameters: surfaceId, components' 
+      };
+    }
+
+    try {
+      const messages = toolCallToMessages({ surfaceId, components }, this.catalogId);
+      
+      for (const message of messages) {
+        this.stream.send(message);
+      }
+
+      return {
+        success: true,
+        message: `UI surface "${surfaceId}" created with ${components.length} components.`,
+        surfaceId,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        message: `Failed to render UI: ${error}`,
+      };
+    }
+  }
+
+  /**
+   * Handle update_data tool call
+   */
+  private handleUpdateData(args: Record<string, unknown>): ToolCallResult {
+    const { surfaceId, path, value, operation } = args as {
+      surfaceId: string;
+      path?: string;
+      value: unknown;
+      operation?: string;
+    };
+
+    if (!surfaceId || value === undefined) {
+      return {
+        success: false,
+        message: 'Missing required parameters: surfaceId, value',
+      };
+    }
+
+    try {
+      const message = updateDataToMessage({ surfaceId, path, value, operation });
+      this.stream.send(message);
+
+      return {
+        success: true,
+        message: `Data updated at path "${path || '/'}" in surface "${surfaceId}".`,
+        surfaceId,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        message: `Failed to update data: ${error}`,
+      };
+    }
+  }
+}
+
+/**
+ * Create an OpenAI adapter instance
+ */
+export function createOpenAIAdapter(options: OpenAIAdapterOptions): OpenAIAdapter {
+  return new OpenAIAdapter(options);
+}
+
+// =============================================================================
+// OpenAI Chat Completions Helper
+// =============================================================================
+
+/**
+ * Process OpenAI chat completion response and handle tool calls
+ * 
+ * @example
+ * ```ts
+ * const response = await openai.chat.completions.create({
+ *   model: 'gpt-4',
+ *   messages,
+ *   tools: adapter.getTools(),
+ * });
+ * 
+ * const results = processOpenAIResponse(response, adapter);
+ * ```
+ */
+export function processOpenAIResponse(
+  response: { 
+    choices: Array<{ 
+      message: { 
+        tool_calls?: Array<{ 
+          function: { name: string; arguments: string } 
+        }> 
+      } 
+    }> 
+  },
+  adapter: OpenAIAdapter
+): ToolCallResult[] {
+  const results: ToolCallResult[] = [];
+  const toolCalls = response.choices[0]?.message?.tool_calls;
+
+  if (!toolCalls) {
+    return results;
+  }
+
+  for (const toolCall of toolCalls) {
+    try {
+      const args = JSON.parse(toolCall.function.arguments);
+      const result = adapter.handleToolCall(toolCall.function.name, args);
+      results.push(result);
+    } catch (error) {
+      results.push({
+        success: false,
+        message: `Failed to parse tool call arguments: ${error}`,
+      });
+    }
+  }
+
+  return results;
+}

package/packages/server/src/catalog-loader.ts

@@ -0,0 +1,311 @@
+/**
+ * Catalog Loader & Tool Converter
+ * 
+ * Converts catalog definitions to LLM-compatible tool schemas.
+ * This is the core of the "Context Injector" - generating
+ * JSON Schema tools from component catalogs.
+ */
+
+import type { ServerToClientMessage, A2UXComponent } from '@freesail/core';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface CatalogComponent {
+  description?: string;
+  properties?: Record<string, PropertySchema>;
+  required?: string[];
+}
+
+export interface PropertySchema {
+  type: string;
+  description?: string;
+  enum?: string[];
+  default?: unknown;
+  items?: PropertySchema;
+}
+
+export interface CatalogDefinition {
+  id: string;
+  version: string;
+  name?: string;
+  description?: string;
+  components: Record<string, CatalogComponent>;
+}
+
+export interface ToolSchema {
+  name: string;
+  description: string;
+  parameters: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required: string[];
+  };
+}
+
+export interface OpenAITool {
+  type: 'function';
+  function: ToolSchema;
+}
+
+// =============================================================================
+// Catalog Loader
+// =============================================================================
+
+/**
+ * Load a catalog from a URL or file path
+ */
+export async function loadCatalog(source: string): Promise<CatalogDefinition> {
+  if (source.startsWith('http://') || source.startsWith('https://')) {
+    const response = await fetch(source);
+    if (!response.ok) {
+      throw new Error(`Failed to load catalog: ${response.statusText}`);
+    }
+    return response.json() as Promise<CatalogDefinition>;
+  }
+  
+  // For file paths, use dynamic import (works in ESM)
+  const fs = await import('fs/promises');
+  const content = await fs.readFile(source, 'utf-8');
+  return JSON.parse(content) as CatalogDefinition;
+}
+
+// =============================================================================
+// Tool Converter
+// =============================================================================
+
+/**
+ * CatalogToToolConverter generates LLM tool definitions from catalog schemas.
+ * It's the bridge between UI catalogs and AI function calling.
+ */
+export class CatalogToToolConverter {
+  private catalogs: Map<string, CatalogDefinition> = new Map();
+
+  /**
+   * Register a catalog
+   */
+  addCatalog(catalog: CatalogDefinition): void {
+    this.catalogs.set(catalog.id, catalog);
+  }
+
+  /**
+   * Get registered catalog
+   */
+  getCatalog(catalogId: string): CatalogDefinition | undefined {
+    return this.catalogs.get(catalogId);
+  }
+
+  /**
+   * Generate the render_ui tool schema for a catalog
+   */
+  generateRenderUITool(catalogId: string): ToolSchema {
+    const catalog = this.catalogs.get(catalogId);
+    if (!catalog) {
+      throw new Error(`Catalog not found: ${catalogId}`);
+    }
+
+    // Build component union schema
+    const componentSchemas = this.buildComponentSchemas(catalog);
+
+    return {
+      name: 'render_ui',
+      description: `Render a user interface using the ${catalog.name || catalogId} component catalog. ` +
+        `Use this tool to create visual UI elements. Components are specified as a flat list with ` +
+        `parent-child relationships defined by ID references in the 'children' array.`,
+      parameters: {
+        type: 'object',
+        properties: {
+          surfaceId: {
+            type: 'string',
+            description: 'Unique identifier for this UI surface',
+          },
+          components: {
+            type: 'array',
+            description: 'Array of component definitions. First component should have id "root".',
+            items: {
+              type: 'object',
+              properties: {
+                id: {
+                  type: 'string',
+                  description: 'Unique identifier for this component',
+                },
+                component: {
+                  type: 'string',
+                  description: 'Component type from catalog',
+                  enum: Object.keys(catalog.components),
+                },
+                children: {
+                  type: 'array',
+                  description: 'Array of child component IDs (for container components)',
+                  items: { type: 'string' },
+                },
+                ...componentSchemas,
+              },
+              required: ['id', 'component'],
+            },
+          },
+        },
+        required: ['surfaceId', 'components'],
+      },
+    };
+  }
+
+  /**
+   * Generate update_data tool schema
+   */
+  generateUpdateDataTool(): ToolSchema {
+    return {
+      name: 'update_data',
+      description: 'Update data in a UI surface without recreating components. ' +
+        'Use this to change text, values, or state in an existing UI.',
+      parameters: {
+        type: 'object',
+        properties: {
+          surfaceId: {
+            type: 'string',
+            description: 'The surface ID to update',
+          },
+          path: {
+            type: 'string',
+            description: 'JSON Pointer path to the data to update (e.g., "/user/name")',
+          },
+          value: {
+            description: 'The new value to set',
+          },
+          operation: {
+            type: 'string',
+            enum: ['add', 'replace', 'remove'],
+            description: 'The operation to perform (default: replace)',
+          },
+        },
+        required: ['surfaceId', 'value'],
+      },
+    };
+  }
+
+  /**
+   * Generate all tools for a catalog as OpenAI format
+   */
+  generateOpenAITools(catalogId: string): OpenAITool[] {
+    return [
+      { type: 'function', function: this.generateRenderUITool(catalogId) },
+      { type: 'function', function: this.generateUpdateDataTool() },
+    ];
+  }
+
+  /**
+   * Generate system prompt section describing available components
+   */
+  generateSystemPromptSection(catalogId: string): string {
+    const catalog = this.catalogs.get(catalogId);
+    if (!catalog) {
+      throw new Error(`Catalog not found: ${catalogId}`);
+    }
+
+    let prompt = `## Available UI Components (${catalog.name || catalogId})\n\n`;
+    prompt += `You can create UIs using the following components:\n\n`;
+
+    for (const [name, component] of Object.entries(catalog.components)) {
+      prompt += `### ${name}\n`;
+      prompt += `${component.description || 'No description'}\n\n`;
+      
+      if (component.properties) {
+        prompt += `Properties:\n`;
+        for (const [propName, prop] of Object.entries(component.properties)) {
+          const required = component.required?.includes(propName) ? ' (required)' : '';
+          const enumValues = prop.enum ? ` [${prop.enum.join(', ')}]` : '';
+          prompt += `- \`${propName}\` (${prop.type}${required}): ${prop.description || ''}${enumValues}\n`;
+        }
+        prompt += '\n';
+      }
+    }
+
+    prompt += `\n## UI Structure\n`;
+    prompt += `Components are defined as a flat array with relationships via 'children' IDs:\n`;
+    prompt += `\`\`\`json
+{
+  "surfaceId": "my_surface",
+  "components": [
+    { "id": "root", "component": "Column", "children": ["title", "content"] },
+    { "id": "title", "component": "Text", "text": "Hello", "variant": "h1" },
+    { "id": "content", "component": "Text", "text": "World" }
+  ]
+}
+\`\`\`\n`;
+
+    return prompt;
+  }
+
+  // ===========================================================================
+  // Private Methods
+  // ===========================================================================
+
+  private buildComponentSchemas(catalog: CatalogDefinition): Record<string, unknown> {
+    const allProperties: Record<string, unknown> = {};
+
+    for (const component of Object.values(catalog.components)) {
+      if (component.properties) {
+        for (const [propName, prop] of Object.entries(component.properties)) {
+          // Merge property schemas (last wins for duplicates)
+          allProperties[propName] = this.convertPropertySchema(prop);
+        }
+      }
+    }
+
+    return allProperties;
+  }
+
+  private convertPropertySchema(prop: PropertySchema): Record<string, unknown> {
+    const schema: Record<string, unknown> = {
+      type: prop.type === 'integer' ? 'number' : prop.type,
+    };
+
+    if (prop.description) {
+      schema.description = prop.description;
+    }
+
+    if (prop.enum) {
+      schema.enum = prop.enum;
+    }
+
+    if (prop.items) {
+      schema.items = this.convertPropertySchema(prop.items);
+    }
+
+    return schema;
+  }
+}
+
+// =============================================================================
+// Tool Execution Helpers
+// =============================================================================
+
+/**
+ * Convert render_ui tool call to A2UX messages
+ */
+export function toolCallToMessages(
+  toolCall: { surfaceId: string; components: A2UXComponent[] },
+  catalogId: string
+): ServerToClientMessage[] {
+  return [
+    { createSurface: { surfaceId: toolCall.surfaceId, catalogId } },
+    { updateComponents: { surfaceId: toolCall.surfaceId, components: toolCall.components } },
+  ];
+}
+
+/**
+ * Convert update_data tool call to A2UX message
+ */
+export function updateDataToMessage(
+  toolCall: { surfaceId: string; path?: string; value: unknown; operation?: string }
+): ServerToClientMessage {
+  return {
+    updateDataModel: {
+      surfaceId: toolCall.surfaceId,
+      path: toolCall.path ?? '/',
+      op: (toolCall.operation as 'add' | 'replace' | 'remove') ?? 'replace',
+      value: toolCall.value,
+    },
+  };
+}

package/packages/server/src/index.ts

@@ -0,0 +1,142 @@
+/**
+ * Freesail Server
+ * 
+ * SSE Stream Engine & Framework Adapters for A2UX Protocol.
+ */
+
+// Stream
+export { FreesailStream, StreamStore } from './stream.js';
+export type { StreamOptions, StreamStats } from './stream.js';
+
+// Catalog Loader
+export { 
+  CatalogToToolConverter, 
+  loadCatalog,
+  toolCallToMessages,
+  updateDataToMessage,
+} from './catalog-loader.js';
+export type { 
+  CatalogDefinition, 
+  CatalogComponent, 
+  PropertySchema,
+  ToolSchema,
+  OpenAITool,
+} from './catalog-loader.js';
+
+// Adapters
+export {
+  // LangChain
+  createLangChainTools,
+  createLangChainRenderUITool,
+  createLangChainUpdateDataTool,
+  // OpenAI  
+  OpenAIAdapter,
+  createOpenAIAdapter,
+  processOpenAIResponse,
+} from './adapters/index.js';
+
+export type {
+  LangChainAdapterOptions,
+  OpenAIAdapterOptions,
+  ToolCallResult,
+} from './adapters/index.js';
+
+// =============================================================================
+// Express Middleware Helper
+// =============================================================================
+
+import type { IncomingMessage, ServerResponse } from 'http';
+import { FreesailStream, StreamStore } from './stream.js';
+
+export interface ExpressRequest extends IncomingMessage {
+  body?: unknown;
+}
+
+export interface ExpressResponse extends ServerResponse {
+  // Express adds these
+}
+
+const globalStreamStore = new StreamStore();
+
+/**
+ * Create SSE endpoint middleware for Express
+ * 
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { createSSEHandler } from '@freesail/server';
+ * 
+ * const app = express();
+ * 
+ * app.get('/api/stream', createSSEHandler(async (stream, req) => {
+ *   // Your agent logic here
+ *   stream.createSurface('main', 'standard_catalog_v1');
+ *   stream.updateComponents('main', [...]);
+ * }));
+ * ```
+ */
+export function createSSEHandler(
+  handler: (stream: FreesailStream, req: ExpressRequest) => Promise<void>,
+  options?: { debug?: boolean }
+): (req: ExpressRequest, res: ExpressResponse) => void {
+  return async (req: ExpressRequest, res: ExpressResponse) => {
+    const stream = globalStreamStore.create({
+      response: res,
+      debug: options?.debug,
+    });
+
+    try {
+      await handler(stream, req);
+    } catch (error) {
+      console.error('[Freesail SSE Handler Error]', error);
+      stream.sendRaw('error', { message: String(error) });
+    }
+  };
+}
+
+/**
+ * Create action endpoint middleware for Express
+ * Handles userAction messages from clients.
+ * 
+ * @example
+ * ```ts
+ * app.post('/api/action', express.json(), createActionHandler(async (action, req) => {
+ *   console.log('User action:', action);
+ *   // Handle action and potentially trigger new UI updates
+ * }));
+ * ```
+ */
+export function createActionHandler(
+  handler: (
+    action: { surfaceId: string; action: string; context: Record<string, unknown> },
+    req: ExpressRequest
+  ) => Promise<void>
+): (req: ExpressRequest, res: ExpressResponse) => void {
+  return async (req: ExpressRequest, res: ExpressResponse) => {
+    try {
+      const body = req.body as { userAction?: { surfaceId: string; action: string; context: Record<string, unknown> } };
+      
+      if (!body?.userAction) {
+        res.statusCode = 400;
+        res.end(JSON.stringify({ error: 'Invalid request: missing userAction' }));
+        return;
+      }
+
+      await handler(body.userAction, req);
+      
+      res.statusCode = 200;
+      res.end(JSON.stringify({ success: true }));
+    } catch (error) {
+      console.error('[Freesail Action Handler Error]', error);
+      res.statusCode = 500;
+      res.end(JSON.stringify({ error: String(error) }));
+    }
+  };
+}
+
+/**
+ * Get the global stream store
+ */
+export function getStreamStore(): StreamStore {
+  return globalStreamStore;
+}