@butlerw/vellum 0.1.0

package/src/tui/adapters/index.ts

@@ -0,0 +1,48 @@
+/**
+ * TUI Adapters
+ *
+ * Adapters for integrating external systems with the Vellum TUI.
+ *
+ * @module tui/adapters
+ */
+
+// Agent Adapter - AgentLoop ↔ Context integration
+export {
+  type AdapterDispatchers,
+  type AgentAdapter,
+  createAgentAdapter,
+  type UseAgentAdapterOptions,
+  type UseAgentAdapterReturn,
+  useAgentAdapter,
+} from "./agent-adapter.js";
+
+// Message Adapter - Session ↔ UI message conversion
+export {
+  createUIMessage,
+  getSessionToolIds,
+  sessionHasToolCalls,
+  sessionHasToolResults,
+  toSessionMessage,
+  toSessionMessages,
+  toUIMessage,
+  toUIMessages,
+} from "./message-adapter.js";
+// Persistence Bridge - Advanced persistence integration
+export {
+  createPersistenceBridge,
+  PersistenceBridge,
+  type PersistenceBridgeCallbacks,
+  type PersistenceBridgeOptions,
+  type SyncResult,
+  type SyncState,
+} from "./persistence-bridge.js";
+// Session Adapter - Session persistence
+export {
+  createMemorySessionStorage,
+  createSessionAdapter,
+  type SessionAdapter,
+  type SessionStorage,
+  type UseSessionAdapterOptions,
+  type UseSessionAdapterReturn,
+  useSessionAdapter,
+} from "./session-adapter.js";

package/src/tui/adapters/message-adapter.ts

@@ -0,0 +1,315 @@
+/**
+ * Message Adapter for Session ↔ UI Message Conversion
+ *
+ * Provides bidirectional conversion between @vellum/core SessionMessage
+ * and TUI Message types for seamless integration between the agent loop
+ * and the user interface.
+ *
+ * @module tui/adapters/message-adapter
+ */
+
+import type {
+  SessionMessage,
+  SessionMessagePart,
+  SessionRole,
+  SessionTextPart,
+  SessionToolPart,
+  SessionToolResultPart,
+} from "@vellum/core";
+import { createId } from "@vellum/shared";
+import type { Message, MessageRole, ToolCallInfo } from "../context/MessagesContext.js";
+
+// =============================================================================
+// Role Mapping
+// =============================================================================
+
+/**
+ * Map from session role to UI message role
+ */
+const SESSION_TO_UI_ROLE: Record<SessionRole, MessageRole> = {
+  user: "user",
+  assistant: "assistant",
+  system: "system",
+  tool_result: "tool",
+};
+
+/**
+ * Map from UI message role to session role
+ */
+const UI_TO_SESSION_ROLE: Record<MessageRole, SessionRole> = {
+  user: "user",
+  assistant: "assistant",
+  system: "system",
+  tool: "tool_result",
+  tool_group: "tool_result", // tool_group maps to tool_result for session storage
+};
+
+// =============================================================================
+// Content Extraction Helpers
+// =============================================================================
+
+/**
+ * Extract text content from session message parts
+ *
+ * @param parts - Array of session message parts
+ * @returns Combined text content
+ */
+function extractTextContent(parts: readonly SessionMessagePart[]): string {
+  return parts
+    .filter((part): part is SessionTextPart => part.type === "text")
+    .map((part) => part.text)
+    .join("\n");
+}
+
+/**
+ * Extract reasoning content from session message parts
+ *
+ * @param parts - Array of session message parts
+ * @returns Combined reasoning content or undefined
+ */
+function extractReasoningContent(parts: readonly SessionMessagePart[]): string | undefined {
+  const reasoningParts = parts.filter((part) => part.type === "reasoning");
+  if (reasoningParts.length === 0) {
+    return undefined;
+  }
+  return reasoningParts.map((part) => part.text).join("");
+}
+
+/**
+ * Extract tool calls from session message parts
+ *
+ * @param parts - Array of session message parts
+ * @returns Array of tool call info objects
+ */
+function extractToolCalls(parts: readonly SessionMessagePart[]): readonly ToolCallInfo[] {
+  return parts
+    .filter((part): part is SessionToolPart => part.type === "tool")
+    .map((part) => ({
+      id: part.id,
+      name: part.name,
+      arguments: part.input,
+      status: "completed" as const,
+    }));
+}
+
+/**
+ * Extract tool results from session message parts
+ *
+ * @param parts - Array of session message parts
+ * @returns Array of tool call info with results
+ */
+function extractToolResults(parts: readonly SessionMessagePart[]): readonly ToolCallInfo[] {
+  return parts
+    .filter((part): part is SessionToolResultPart => part.type === "tool_result")
+    .map((part) => ({
+      id: part.toolId,
+      name: "tool_result",
+      arguments: {},
+      result: part.content,
+      status: part.isError ? ("error" as const) : ("completed" as const),
+    }));
+}
+
+// =============================================================================
+// Session → UI Conversion
+// =============================================================================
+
+/**
+ * Convert a single session message to UI message format
+ *
+ * @param sessionMessage - Message from session/core
+ * @returns UI message for display
+ *
+ * @example
+ * ```typescript
+ * const sessionMsg = createUserMessage([SessionParts.text("Hello")]);
+ * const uiMsg = toUIMessage(sessionMsg);
+ * // { id: "...", role: "user", content: "Hello", timestamp: Date, ... }
+ * ```
+ */
+export function toUIMessage(sessionMessage: SessionMessage): Message {
+  const textContent = extractTextContent(sessionMessage.parts);
+  const reasoningContent = extractReasoningContent(sessionMessage.parts);
+  const toolCalls = extractToolCalls(sessionMessage.parts);
+  const toolResults = extractToolResults(sessionMessage.parts);
+
+  // Combine tool calls and tool results
+  const allToolCalls = [...toolCalls, ...toolResults];
+
+  // Build content - for tool_result messages, stringify the result if no text
+  let content = textContent;
+  if (!content && sessionMessage.role === "tool_result" && toolResults.length > 0) {
+    content = toolResults
+      .map((tr) => (typeof tr.result === "string" ? tr.result : JSON.stringify(tr.result, null, 2)))
+      .join("\n");
+  }
+
+  return {
+    id: sessionMessage.id,
+    role: SESSION_TO_UI_ROLE[sessionMessage.role],
+    content,
+    timestamp: new Date(sessionMessage.metadata.createdAt),
+    isStreaming: false,
+    toolCalls: allToolCalls.length > 0 ? allToolCalls : undefined,
+    ...(reasoningContent ? { thinking: reasoningContent } : {}),
+  };
+}
+
+/**
+ * Convert an array of session messages to UI messages
+ *
+ * @param sessionMessages - Array of session messages
+ * @returns Array of UI messages
+ *
+ * @example
+ * ```typescript
+ * const session = { messages: [...] };
+ * const uiMessages = toUIMessages(session.messages);
+ * ```
+ */
+export function toUIMessages(sessionMessages: readonly SessionMessage[]): readonly Message[] {
+  return sessionMessages.map(toUIMessage);
+}
+
+// =============================================================================
+// UI → Session Conversion
+// =============================================================================
+
+/**
+ * Convert a UI message to session message format
+ *
+ * @param uiMessage - UI message from MessagesContext
+ * @returns Session message for core/agent loop
+ *
+ * @example
+ * ```typescript
+ * const uiMsg = { id: "1", role: "user", content: "Hello", timestamp: new Date() };
+ * const sessionMsg = toSessionMessage(uiMsg);
+ * ```
+ */
+export function toSessionMessage(uiMessage: Message): SessionMessage {
+  const parts: SessionMessagePart[] = [];
+
+  if (uiMessage.thinking) {
+    parts.push({
+      type: "reasoning",
+      text: uiMessage.thinking,
+    });
+  }
+
+  // Add text content if present
+  if (uiMessage.content) {
+    parts.push({
+      type: "text",
+      text: uiMessage.content,
+    });
+  }
+
+  // Add tool calls if present (for assistant messages)
+  if (uiMessage.toolCalls && uiMessage.role === "assistant") {
+    for (const toolCall of uiMessage.toolCalls) {
+      parts.push({
+        type: "tool",
+        id: toolCall.id,
+        name: toolCall.name,
+        input: toolCall.arguments,
+      });
+    }
+  }
+
+  // Add tool results if present (for tool messages)
+  if (uiMessage.toolCalls && uiMessage.role === "tool") {
+    for (const toolCall of uiMessage.toolCalls) {
+      parts.push({
+        type: "tool_result",
+        toolId: toolCall.id,
+        content: toolCall.result ?? "",
+        isError: toolCall.status === "error",
+      });
+    }
+  }
+
+  return {
+    id: uiMessage.id,
+    role: UI_TO_SESSION_ROLE[uiMessage.role],
+    parts,
+    metadata: {
+      createdAt: uiMessage.timestamp.getTime(),
+      completedAt: uiMessage.isStreaming ? undefined : uiMessage.timestamp.getTime(),
+    },
+  };
+}
+
+/**
+ * Convert an array of UI messages to session messages
+ *
+ * @param uiMessages - Array of UI messages
+ * @returns Array of session messages
+ *
+ * @example
+ * ```typescript
+ * const chatHistory = messagesState.messages;
+ * const sessionMsgs = toSessionMessages(chatHistory);
+ * ```
+ */
+export function toSessionMessages(uiMessages: readonly Message[]): readonly SessionMessage[] {
+  return uiMessages.map(toSessionMessage);
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Create a new UI message with generated ID and timestamp
+ *
+ * @param role - Message role
+ * @param content - Message content
+ * @param options - Optional additional properties
+ * @returns New UI message
+ */
+export function createUIMessage(
+  role: MessageRole,
+  content: string,
+  options: Partial<Omit<Message, "id" | "role" | "content" | "timestamp">> = {}
+): Message {
+  return {
+    id: createId(),
+    role,
+    content,
+    timestamp: new Date(),
+    ...options,
+  };
+}
+
+/**
+ * Check if a session message contains tool calls
+ *
+ * @param sessionMessage - Session message to check
+ * @returns True if message has tool calls
+ */
+export function sessionHasToolCalls(sessionMessage: SessionMessage): boolean {
+  return sessionMessage.parts.some((part) => part.type === "tool");
+}
+
+/**
+ * Check if a session message contains tool results
+ *
+ * @param sessionMessage - Session message to check
+ * @returns True if message has tool results
+ */
+export function sessionHasToolResults(sessionMessage: SessionMessage): boolean {
+  return sessionMessage.parts.some((part) => part.type === "tool_result");
+}
+
+/**
+ * Get all tool IDs from a session message
+ *
+ * @param sessionMessage - Session message to extract from
+ * @returns Array of tool call IDs
+ */
+export function getSessionToolIds(sessionMessage: SessionMessage): readonly string[] {
+  return sessionMessage.parts
+    .filter((part): part is SessionToolPart => part.type === "tool")
+    .map((part) => part.id);
+}

package/src/tui/adapters/persistence-bridge.ts

@@ -0,0 +1,331 @@
+/**
+ * Persistence Bridge
+ *
+ * Provides bidirectional conversion and synchronization between
+ * TUI Message types and @vellum/core SessionMessage types for
+ * advanced persistence operations.
+ *
+ * @module tui/adapters/persistence-bridge
+ */
+
+import type { PersistenceManager, Session, SessionMessage } from "@vellum/core";
+import type { Message } from "../context/MessagesContext.js";
+import { toSessionMessage, toUIMessage } from "./message-adapter.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Synchronization state for incremental updates
+ */
+export interface SyncState {
+  /** Last synchronized message index */
+  lastSyncedIndex: number;
+  /** Session ID being tracked */
+  sessionId: string | null;
+}
+
+/**
+ * Sync result from a synchronization operation
+ */
+export interface SyncResult {
+  /** Whether sync was successful */
+  success: boolean;
+  /** Number of messages synced */
+  syncedCount: number;
+  /** Error message if failed */
+  error?: string;
+}
+
+/**
+ * Event callbacks for persistence bridge
+ */
+export interface PersistenceBridgeCallbacks {
+  /** Called when a save operation completes */
+  onSave?: (session: Session) => void;
+  /** Called when a save operation fails */
+  onError?: (error: Error) => void;
+  /** Called when a checkpoint is created */
+  onCheckpointCreated?: (checkpointId: string) => void;
+  /** Called when a rollback completes */
+  onRollbackComplete?: (success: boolean) => void;
+}
+
+/**
+ * Options for creating a persistence bridge
+ */
+export interface PersistenceBridgeOptions {
+  /** PersistenceManager instance */
+  persistence: PersistenceManager;
+  /** Optional callbacks */
+  callbacks?: PersistenceBridgeCallbacks;
+}
+
+// =============================================================================
+// Persistence Bridge Class
+// =============================================================================
+
+/**
+ * Bridge between TUI messages and PersistenceManager.
+ *
+ * Handles:
+ * - Message ↔ SessionMessage bidirectional conversion
+ * - EventEmitter → callback bridging
+ * - Incremental synchronization (only sync changes)
+ *
+ * @example
+ * ```typescript
+ * const bridge = createPersistenceBridge({
+ *   persistence: persistenceManager,
+ *   callbacks: {
+ *     onSave: (session) => console.log('Saved:', session.metadata.id),
+ *     onError: (err) => console.error('Error:', err.message),
+ *   },
+ * });
+ *
+ * // Sync messages incrementally
+ * await bridge.syncMessages(uiMessages);
+ *
+ * // Full sync from persistence to UI
+ * const uiMessages = bridge.loadAsUIMessages();
+ * ```
+ */
+export class PersistenceBridge {
+  private readonly persistence: PersistenceManager;
+  private readonly callbacks: PersistenceBridgeCallbacks;
+  private syncState: SyncState;
+  private eventListenersAttached = false;
+
+  constructor(options: PersistenceBridgeOptions) {
+    this.persistence = options.persistence;
+    this.callbacks = options.callbacks ?? {};
+    this.syncState = {
+      lastSyncedIndex: 0,
+      sessionId: null,
+    };
+  }
+
+  // ===========================================================================
+  // Event Bridging
+  // ===========================================================================
+
+  /**
+   * Attach event listeners to bridge PersistenceManager events to callbacks.
+   */
+  attachEventListeners(): void {
+    if (this.eventListenersAttached) {
+      return;
+    }
+
+    this.persistence.on("save", (session) => {
+      this.callbacks.onSave?.(session);
+    });
+
+    this.persistence.on("error", (error) => {
+      this.callbacks.onError?.(error);
+    });
+
+    this.eventListenersAttached = true;
+  }
+
+  /**
+   * Detach event listeners.
+   */
+  detachEventListeners(): void {
+    if (!this.eventListenersAttached) {
+      return;
+    }
+
+    this.persistence.removeAllListeners("save");
+    this.persistence.removeAllListeners("error");
+    this.eventListenersAttached = false;
+  }
+
+  // ===========================================================================
+  // Message Conversion
+  // ===========================================================================
+
+  /**
+   * Convert UI messages to session messages.
+   *
+   * @param messages - Array of UI messages
+   * @returns Array of session messages
+   */
+  toSessionMessages(messages: readonly Message[]): SessionMessage[] {
+    return messages
+      .filter((msg): msg is Message => msg.role !== "tool" && msg.role !== "tool_group")
+      .map((msg) => toSessionMessage(msg));
+  }
+
+  /**
+   * Convert session messages to UI messages.
+   *
+   * @param sessionMessages - Array of session messages
+   * @returns Array of UI messages
+   */
+  toUIMessages(sessionMessages: readonly SessionMessage[]): Message[] {
+    return sessionMessages.map((msg) => toUIMessage(msg));
+  }
+
+  /**
+   * Load current session messages as UI messages.
+   *
+   * @returns Array of UI messages, or empty array if no session
+   */
+  loadAsUIMessages(): Message[] {
+    const session = this.persistence.currentSession;
+    if (!session) {
+      return [];
+    }
+    return this.toUIMessages(session.messages);
+  }
+
+  // ===========================================================================
+  // Incremental Synchronization
+  // ===========================================================================
+
+  /**
+   * Sync UI messages to persistence incrementally.
+   *
+   * Only processes messages that haven't been synced yet.
+   *
+   * @param messages - Current UI messages
+   * @returns Sync result
+   */
+  async syncMessages(messages: readonly Message[]): Promise<SyncResult> {
+    const session = this.persistence.currentSession;
+    if (!session) {
+      return {
+        success: false,
+        syncedCount: 0,
+        error: "No active session",
+      };
+    }
+
+    // Reset sync state if session changed
+    if (this.syncState.sessionId !== session.metadata.id) {
+      this.syncState = {
+        lastSyncedIndex: 0,
+        sessionId: session.metadata.id,
+      };
+    }
+
+    // Get new messages since last sync
+    const newMessages = messages.slice(this.syncState.lastSyncedIndex);
+    if (newMessages.length === 0) {
+      return {
+        success: true,
+        syncedCount: 0,
+      };
+    }
+
+    try {
+      // Convert and add each new message
+      for (const msg of newMessages) {
+        if (msg.role === "tool" || msg.role === "tool_group") {
+          continue;
+        }
+        const sessionMsg = toSessionMessage(msg);
+        await this.persistence.onMessage(sessionMsg);
+      }
+
+      // Update sync state
+      this.syncState.lastSyncedIndex = messages.length;
+
+      return {
+        success: true,
+        syncedCount: newMessages.length,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        syncedCount: 0,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  /**
+   * Reset sync state (e.g., after rollback or session change).
+   */
+  resetSyncState(): void {
+    this.syncState = {
+      lastSyncedIndex: 0,
+      sessionId: this.persistence.currentSession?.metadata.id ?? null,
+    };
+  }
+
+  // ===========================================================================
+  // Checkpoint Operations
+  // ===========================================================================
+
+  /**
+   * Create a checkpoint and notify via callback.
+   *
+   * @param description - Optional checkpoint description
+   * @returns Checkpoint ID or null if failed
+   */
+  async createCheckpoint(description?: string): Promise<string | null> {
+    try {
+      const checkpointId = await this.persistence.createCheckpointAt(description);
+      this.callbacks.onCheckpointCreated?.(checkpointId);
+      return checkpointId;
+    } catch (error) {
+      this.callbacks.onError?.(error instanceof Error ? error : new Error(String(error)));
+      return null;
+    }
+  }
+
+  /**
+   * Rollback to a checkpoint and notify via callback.
+   *
+   * @param checkpointId - ID of checkpoint to rollback to
+   * @returns Success status
+   */
+  async rollbackToCheckpoint(checkpointId: string): Promise<boolean> {
+    try {
+      const success = await this.persistence.rollbackToCheckpoint(checkpointId);
+      this.callbacks.onRollbackComplete?.(success);
+      if (success) {
+        this.resetSyncState();
+      }
+      return success;
+    } catch (error) {
+      this.callbacks.onError?.(error instanceof Error ? error : new Error(String(error)));
+      this.callbacks.onRollbackComplete?.(false);
+      return false;
+    }
+  }
+
+  // ===========================================================================
+  // Disposal
+  // ===========================================================================
+
+  /**
+   * Dispose the bridge and clean up resources.
+   */
+  dispose(): void {
+    this.detachEventListeners();
+    this.syncState = {
+      lastSyncedIndex: 0,
+      sessionId: null,
+    };
+  }
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+/**
+ * Create a new persistence bridge instance.
+ *
+ * @param options - Bridge configuration options
+ * @returns Configured PersistenceBridge instance
+ */
+export function createPersistenceBridge(options: PersistenceBridgeOptions): PersistenceBridge {
+  const bridge = new PersistenceBridge(options);
+  bridge.attachEventListeners();
+  return bridge;
+}