@raisindb/client 0.1.0 → 0.1.1

package/dist/react.js

@@ -0,0 +1,2569 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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/integrations/react/index.ts
+var react_exports = {};
+__export(react_exports, {
+  createRaisinReact: () => createRaisinReact
+});
+module.exports = __toCommonJS(react_exports);
+
+// src/integrations/react/use-auth.ts
+function createUseAuth(react, context) {
+  return function useAuth() {
+    const { useState, useEffect, useRef, useCallback, useContext } = react;
+    const ctx = useContext(context);
+    if (!ctx) {
+      throw new Error("useAuth must be used within a <RaisinProvider>");
+    }
+    const { client } = ctx;
+    const [user, setUser] = useState(client.getStoredUser());
+    const [isLoading, setIsLoading] = useState(false);
+    const mountedRef = useRef(true);
+    useEffect(() => {
+      mountedRef.current = true;
+      const unsubAuth = client.onAuthStateChange(({ event, session }) => {
+        if (!mountedRef.current) return;
+        if (event === "SIGNED_IN" || event === "TOKEN_REFRESHED" || event === "USER_UPDATED") {
+          setUser(session.user);
+        } else if (event === "SIGNED_OUT" || event === "SESSION_EXPIRED") {
+          setUser(null);
+        }
+      });
+      const unsubUser = client.onUserChange(({ node }) => {
+        if (!mountedRef.current) return;
+        setUser((prev) => {
+          if (!prev) return prev;
+          return {
+            ...prev,
+            home: node.path,
+            displayName: node.properties.display_name ?? prev.displayName,
+            avatarUrl: node.properties.avatar_url ?? prev.avatarUrl
+          };
+        });
+      });
+      return () => {
+        mountedRef.current = false;
+        unsubAuth();
+        unsubUser();
+      };
+    }, [client]);
+    const login = useCallback(async (email, password, repository) => {
+      setIsLoading(true);
+      try {
+        const result = await client.loginWithEmail(email, password, repository);
+        return result;
+      } finally {
+        if (mountedRef.current) setIsLoading(false);
+      }
+    }, [client]);
+    const register = useCallback(async (email, password, repository, displayName) => {
+      setIsLoading(true);
+      try {
+        const result = await client.registerWithEmail(email, password, repository, displayName);
+        return result;
+      } finally {
+        if (mountedRef.current) setIsLoading(false);
+      }
+    }, [client]);
+    const logout = useCallback(async (options) => {
+      setIsLoading(true);
+      try {
+        await client.logout(options);
+      } finally {
+        if (mountedRef.current) setIsLoading(false);
+      }
+    }, [client]);
+    const initSession = useCallback(async (repository) => {
+      setIsLoading(true);
+      try {
+        const result = await client.initSession(repository);
+        return result;
+      } finally {
+        if (mountedRef.current) setIsLoading(false);
+      }
+    }, [client]);
+    return {
+      user,
+      isAuthenticated: user !== null,
+      isLoading,
+      login,
+      register,
+      logout,
+      initSession
+    };
+  };
+}
+
+// src/connection.ts
+var import_events = require("events");
+
+// src/utils/reconnect.ts
+var ReconnectManager = class {
+  constructor(options = {}) {
+    this.attempts = 0;
+    this.isReconnecting = false;
+    this.initialDelay = options.initialDelay ?? 1e3;
+    this.maxDelay = options.maxDelay ?? 3e4;
+    this.backoffMultiplier = options.backoffMultiplier ?? 2;
+    this.maxAttempts = options.maxAttempts ?? Infinity;
+    this.jitter = options.jitter ?? true;
+    this.currentDelay = this.initialDelay;
+  }
+  /**
+   * Schedule a reconnection attempt
+   *
+   * @param callback - Function to call when it's time to reconnect
+   * @returns true if reconnection was scheduled, false if max attempts reached
+   */
+  scheduleReconnect(callback) {
+    if (this.attempts >= this.maxAttempts) {
+      return false;
+    }
+    this.cancelReconnect();
+    this.isReconnecting = true;
+    this.attempts++;
+    let delay = this.currentDelay;
+    if (this.jitter) {
+      const jitterRange = delay * 0.25;
+      delay += (Math.random() * 2 - 1) * jitterRange;
+      delay = Math.max(0, Math.round(delay));
+    }
+    this.reconnectTimeout = setTimeout(async () => {
+      try {
+        await callback();
+        this.reset();
+      } catch (error) {
+        this.currentDelay = Math.min(
+          this.currentDelay * this.backoffMultiplier,
+          this.maxDelay
+        );
+      }
+    }, delay);
+    return true;
+  }
+  /**
+   * Cancel any pending reconnection attempt
+   */
+  cancelReconnect() {
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = void 0;
+    }
+    this.isReconnecting = false;
+  }
+  /**
+   * Reset the reconnection state (call after successful connection)
+   */
+  reset() {
+    this.cancelReconnect();
+    this.currentDelay = this.initialDelay;
+    this.attempts = 0;
+  }
+  /**
+   * Check if currently in reconnection mode
+   */
+  isActive() {
+    return this.isReconnecting;
+  }
+  /**
+   * Get the current number of reconnection attempts
+   */
+  getAttempts() {
+    return this.attempts;
+  }
+  /**
+   * Get the current delay in milliseconds
+   */
+  getCurrentDelay() {
+    return this.currentDelay;
+  }
+  /**
+   * Check if max attempts have been reached
+   */
+  hasReachedMaxAttempts() {
+    return this.attempts >= this.maxAttempts;
+  }
+};
+
+// src/logger.ts
+var config = {
+  level: 1 /* Error */,
+  prefix: "[RaisinDB]"
+};
+function setLogLevel(level) {
+  config.level = level;
+}
+function getLogLevel() {
+  return config.level;
+}
+var logger = {
+  /**
+   * Log debug message (only shown when level >= Debug)
+   */
+  debug(...args) {
+    if (config.level >= 4 /* Debug */) {
+      console.log(config.prefix, ...args);
+    }
+  },
+  /**
+   * Log info message (only shown when level >= Info)
+   */
+  info(...args) {
+    if (config.level >= 3 /* Info */) {
+      console.log(config.prefix, ...args);
+    }
+  },
+  /**
+   * Log warning message (only shown when level >= Warn)
+   */
+  warn(...args) {
+    if (config.level >= 2 /* Warn */) {
+      console.warn(config.prefix, ...args);
+    }
+  },
+  /**
+   * Log error message (only shown when level >= Error)
+   */
+  error(...args) {
+    if (config.level >= 1 /* Error */) {
+      console.error(config.prefix, ...args);
+    }
+  }
+};
+if (typeof globalThis !== "undefined") {
+  globalThis.__raisinDebug = (enable = true) => {
+    setLogLevel(enable ? 4 /* Debug */ : 1 /* Error */);
+    console.log(`[RaisinDB] Debug logging ${enable ? "ENABLED" : "DISABLED"} (includes server handler logs)`);
+  };
+}
+
+// src/integrations/react/use-connection.ts
+function createUseConnection(react, context) {
+  return function useConnection() {
+    const { useState, useEffect, useCallback, useContext } = react;
+    const ctx = useContext(context);
+    if (!ctx) {
+      throw new Error("useConnection must be used within a <RaisinProvider>");
+    }
+    const { client } = ctx;
+    const [state, setState] = useState(client.getConnectionState());
+    const [isReady, setIsReady] = useState(client.isReady());
+    useEffect(() => {
+      const unsubConn = client.onConnectionStateChange((newState) => {
+        setState(newState);
+      });
+      const unsubReady = client.onReadyStateChange((ready) => {
+        setIsReady(ready);
+      });
+      return () => {
+        unsubConn();
+        unsubReady();
+      };
+    }, [client]);
+    const connect = useCallback(async () => {
+      await client.connect();
+    }, [client]);
+    const disconnect = useCallback(() => {
+      client.disconnect();
+    }, [client]);
+    return {
+      state,
+      isConnected: state === "connected" /* Connected */,
+      isReady,
+      connect,
+      disconnect
+    };
+  };
+}
+
+// src/integrations/react/use-sql.ts
+function rowsToObjects(result) {
+  return result.rows;
+}
+function createUseSql(react, context) {
+  return function useSql(sql, params, options) {
+    const { useState, useEffect, useRef, useCallback, useContext } = react;
+    const ctx = useContext(context);
+    if (!ctx) {
+      throw new Error("useSql must be used within a <RaisinProvider>");
+    }
+    const { client, repository: defaultRepo } = ctx;
+    const [data, setData] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const mountedRef = useRef(true);
+    const enabled = options?.enabled !== false;
+    const repo = options?.repository ?? defaultRepo;
+    const refetchOnReconnect = options?.refetchOnReconnect !== false;
+    const realtime = options?.realtime;
+    const paramsKey = params ? JSON.stringify(params) : "";
+    const fetchData = useCallback(async () => {
+      if (!repo) return;
+      setIsLoading(true);
+      setError(null);
+      try {
+        const db = client.database(repo);
+        const result = await db.executeSql(sql, params);
+        if (mountedRef.current) {
+          setData(rowsToObjects(result));
+        }
+      } catch (err) {
+        if (mountedRef.current) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+        }
+      } finally {
+        if (mountedRef.current) {
+          setIsLoading(false);
+        }
+      }
+    }, [client, repo, sql, paramsKey]);
+    useEffect(() => {
+      mountedRef.current = true;
+      if (enabled) {
+        fetchData();
+      }
+      return () => {
+        mountedRef.current = false;
+      };
+    }, [enabled, fetchData]);
+    useEffect(() => {
+      if (!enabled || !refetchOnReconnect) return;
+      const unsub = client.onReconnected(() => {
+        fetchData();
+      });
+      return unsub;
+    }, [client, enabled, refetchOnReconnect, fetchData]);
+    useEffect(() => {
+      if (!enabled || !realtime || !repo) return;
+      const db = client.database(repo);
+      let unsubscribe;
+      db.events().subscribe(
+        {
+          workspace: realtime.workspace,
+          event_types: realtime.eventTypes,
+          path: realtime.path,
+          node_type: realtime.nodeType
+        },
+        () => {
+          fetchData();
+        }
+      ).then((sub) => {
+        unsubscribe = () => sub.unsubscribe();
+      });
+      return () => {
+        unsubscribe?.();
+      };
+    }, [client, enabled, repo, realtime?.workspace, realtime?.path, realtime?.nodeType, fetchData]);
+    return {
+      data,
+      isLoading,
+      error,
+      refetch: fetchData
+    };
+  };
+}
+
+// src/integrations/react/use-subscription.ts
+function createUseSubscription(react, context) {
+  return function useSubscription(options, callback) {
+    const { useEffect, useRef, useContext } = react;
+    const ctx = useContext(context);
+    if (!ctx) {
+      throw new Error("useSubscription must be used within a <RaisinProvider>");
+    }
+    const { client, repository } = ctx;
+    const callbackRef = useRef(callback);
+    callbackRef.current = callback;
+    const enabled = options.enabled !== false;
+    useEffect(() => {
+      if (!enabled || !repository || !options.workspace) return;
+      const db = client.database(repository);
+      let unsubscribe;
+      let cancelled = false;
+      db.events().subscribe(
+        {
+          workspace: options.workspace,
+          event_types: options.event_types,
+          path: options.path,
+          node_type: options.node_type,
+          include_node: options.include_node
+        },
+        (event) => {
+          if (!cancelled) {
+            callbackRef.current(event);
+          }
+        }
+      ).then((sub) => {
+        if (cancelled) {
+          sub.unsubscribe();
+        } else {
+          unsubscribe = () => sub.unsubscribe();
+        }
+      });
+      return () => {
+        cancelled = true;
+        unsubscribe?.();
+      };
+    }, [client, repository, enabled, options.workspace, options.path, options.node_type, options.include_node]);
+  };
+}
+
+// src/utils/plan-projection.ts
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value;
+}
+function asString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function parsePlanTasks(rawTasks) {
+  if (!Array.isArray(rawTasks)) return [];
+  return rawTasks.map((rawTask, index) => {
+    if (typeof rawTask === "string") {
+      return {
+        title: rawTask,
+        status: "pending"
+      };
+    }
+    const task = asRecord(rawTask);
+    if (!task) return null;
+    const delegation = asRecord(task.delegation);
+    return {
+      taskId: asString(task.task_id) ?? asString(task.id),
+      title: asString(task.title) ?? `Task ${index + 1}`,
+      status: asString(task.status) ?? "pending",
+      description: asString(task.description),
+      priority: asString(task.priority),
+      delegation: delegation ? {
+        id: asString(delegation.id),
+        status: asString(delegation.status) ?? "unknown",
+        agentRef: asString(delegation.agent_ref) ?? asString(delegation.agentRef),
+        flowInstanceId: asString(delegation.flow_instance_id) ?? asString(delegation.flowInstanceId),
+        branch: asString(delegation.branch),
+        baseBranch: asString(delegation.base_branch) ?? asString(delegation.baseBranch),
+        result: delegation.result,
+        error: asString(delegation.error)
+      } : void 0
+    };
+  }).filter((task) => task !== null);
+}
+var TERMINAL_TASK_STATUSES = /* @__PURE__ */ new Set(["completed", "cancelled"]);
+var TERMINAL_PLAN_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+function setPlanStatus(plan, nextStatus) {
+  if (!nextStatus) return;
+  if (TERMINAL_PLAN_STATUSES.has(plan.status) && !TERMINAL_PLAN_STATUSES.has(nextStatus)) {
+    return;
+  }
+  plan.status = nextStatus;
+}
+function upsertTask(plan, nextTask) {
+  const existingIndex = plan.tasks.findIndex(
+    (task) => nextTask.taskId && task.taskId === nextTask.taskId || !nextTask.taskId && task.title === nextTask.title
+  );
+  if (existingIndex === -1) {
+    plan.tasks.push(nextTask);
+    return;
+  }
+  const existing = plan.tasks[existingIndex];
+  if (TERMINAL_TASK_STATUSES.has(existing.status) && !TERMINAL_TASK_STATUSES.has(nextTask.status)) {
+    return;
+  }
+  plan.tasks[existingIndex] = {
+    ...existing,
+    ...nextTask
+  };
+}
+function ensurePlan(plans, key, fallbackTitle, timestamp) {
+  const existing = plans.get(key);
+  if (existing) {
+    if (timestamp) existing.updatedAt = timestamp;
+    return existing;
+  }
+  const created = {
+    key,
+    title: fallbackTitle,
+    status: "pending_approval",
+    requiresApproval: true,
+    tasks: [],
+    updatedAt: timestamp
+  };
+  plans.set(key, created);
+  return created;
+}
+function projectPlansFromMessages(messages) {
+  const ordered = [...messages].sort((a, b) => {
+    const aTime = Date.parse(a.timestamp || "");
+    const bTime = Date.parse(b.timestamp || "");
+    return (Number.isNaN(aTime) ? 0 : aTime) - (Number.isNaN(bTime) ? 0 : bTime);
+  });
+  const plans = /* @__PURE__ */ new Map();
+  for (const message of ordered) {
+    const timestamp = message.timestamp;
+    const data = asRecord(message.data);
+    if (message.messageType === "ai_plan" && data) {
+      const planPath = asString(data.plan_path);
+      const planId = asString(data.plan_id);
+      const key = planPath || planId || message.path || message.id || `plan:${timestamp}`;
+      const plan = ensurePlan(
+        plans,
+        key,
+        asString(data.title) || message.content || "Plan",
+        timestamp
+      );
+      plan.planPath = planPath ?? plan.planPath;
+      plan.planId = planId ?? plan.planId;
+      plan.title = asString(data.title) || plan.title;
+      setPlanStatus(plan, asString(data.status));
+      plan.requiresApproval = Boolean(data.requires_approval) || plan.status === "pending_approval";
+      plan.sourceMessagePath = message.path ?? plan.sourceMessagePath;
+      const parsedTasks = parsePlanTasks(data.tasks);
+      if (parsedTasks.length > 0) {
+        plan.tasks = parsedTasks;
+      }
+    }
+    if (message.messageType === "ai_task_update" && data) {
+      const planPath = asString(data.plan_path);
+      const planId = asString(data.plan_id);
+      const key = planPath || planId;
+      if (!key) continue;
+      const plan = ensurePlan(plans, key, "Plan", timestamp);
+      plan.planPath = planPath ?? plan.planPath;
+      plan.planId = planId ?? plan.planId;
+      setPlanStatus(plan, asString(data.plan_status));
+      plan.requiresApproval = plan.status === "pending_approval";
+      const taskUpdate = {
+        taskId: asString(data.task_id),
+        title: asString(data.task_title) || asString(data.title) || "Task",
+        status: asString(data.status) || "pending"
+      };
+      upsertTask(plan, taskUpdate);
+    }
+    if (Array.isArray(message.children)) {
+      for (const child of message.children) {
+        if (child.type !== "plan") continue;
+        const key = child.path || message.path || message.id || `plan-child:${child.id}:${timestamp}`;
+        const plan = ensurePlan(plans, key, child.planTitle || message.content || "Plan", timestamp);
+        plan.title = child.planTitle || plan.title;
+        plan.status = child.status || plan.status;
+        plan.requiresApproval = plan.status === "pending_approval";
+        if (Array.isArray(child.tasks) && child.tasks.length > 0) {
+          plan.tasks = child.tasks.map((task) => ({
+            taskId: task.id,
+            title: task.title,
+            status: task.status,
+            delegation: task.delegation ? {
+              id: task.delegation.id,
+              status: task.delegation.status,
+              agentRef: task.delegation.agentRef,
+              flowInstanceId: task.delegation.flowInstanceId,
+              branch: task.delegation.branch,
+              baseBranch: task.delegation.baseBranch,
+              result: task.delegation.result,
+              error: task.delegation.error
+            } : void 0
+          }));
+        }
+      }
+    }
+  }
+  for (const plan of plans.values()) {
+    if (!TERMINAL_PLAN_STATUSES.has(plan.status) && plan.tasks.length > 0 && plan.tasks.every((task) => TERMINAL_TASK_STATUSES.has(task.status))) {
+      plan.status = "completed";
+      plan.requiresApproval = false;
+    }
+  }
+  return [...plans.values()].sort((a, b) => {
+    const aTime = Date.parse(a.updatedAt || "");
+    const bTime = Date.parse(b.updatedAt || "");
+    return (Number.isNaN(bTime) ? 0 : bTime) - (Number.isNaN(aTime) ? 0 : aTime);
+  });
+}
+
+// src/utils/chat-events.ts
+function isRecoveredDoneEvent(event) {
+  if (event.type !== "done") return false;
+  const done = event;
+  if (done.recovered !== true) return false;
+  return typeof done.content !== "string" || done.content.trim().length === 0;
+}
+
+// src/stores/conversation-store.ts
+var ConversationStore = class {
+  constructor(options) {
+    this.subscribers = /* @__PURE__ */ new Set();
+    // Persistent SSE subscription
+    this.subscription = null;
+    this._messages = [];
+    this._isStreaming = false;
+    this._isWaiting = false;
+    this._streamingText = "";
+    this._error = null;
+    this._activeToolCalls = [];
+    this._isLoading = false;
+    this._conversationType = null;
+    this._streamingTimer = null;
+    this._watchdogTimer = null;
+    this.manager = options.database.conversations;
+    this._conversationPath = options.conversationPath ?? null;
+    this.createOptions = options.createOptions;
+    this.onEvent = options.onEvent;
+    this._streamingTimeoutMs = options.streamingTimeoutMs ?? 12e4;
+    this._watchdogIntervalMs = options.watchdogIntervalMs ?? 3e4;
+    if (this._conversationPath) {
+      this.ensureSubscription();
+    } else if (this.createOptions?.anonymous) {
+      void this.resumeAnonymous();
+    }
+  }
+  anonymousOptions() {
+    const a = this.createOptions?.anonymous;
+    if (!a) return null;
+    return a === true ? {} : a;
+  }
+  /**
+   * Resume the visitor conversation this tab already has (the session secret
+   * and conversation id live in sessionStorage), and load its history. A tab
+   * without one starts nothing until the first message.
+   */
+  async resumeAnonymous() {
+    const opts = this.anonymousOptions();
+    if (!opts || !this.createOptions || this._conversationPath) return;
+    const agent = this.createOptions.participant;
+    try {
+      if (!this.manager.hasStoredAnonymous(agent, opts)) return;
+      const convo = await this.manager.startAnonymous(agent, opts);
+      if (this._conversationPath) return;
+      this._conversationPath = convo.conversationPath;
+      this._conversationType = convo.type;
+      this.ensureSubscription();
+      await this.loadMessages();
+    } catch (err) {
+      logger.debug("[ConversationStore] No visitor conversation to resume", err);
+    }
+  }
+  // ==========================================================================
+  // Subscription
+  // ==========================================================================
+  /**
+   * Subscribe to state changes.
+   * Returns an unsubscribe function.
+   */
+  subscribe(callback) {
+    this.subscribers.add(callback);
+    callback(this.getSnapshot());
+    return () => {
+      this.subscribers.delete(callback);
+    };
+  }
+  /**
+   * Get the current state snapshot.
+   */
+  getSnapshot() {
+    return {
+      conversation: this._conversationPath ? { conversationPath: this._conversationPath, type: this._conversationType || "ai_chat" } : null,
+      messages: [...this._messages],
+      isStreaming: this._isStreaming,
+      isWaiting: this._isWaiting,
+      streamingText: this._streamingText,
+      error: this._error,
+      activeToolCalls: [...this._activeToolCalls],
+      plans: projectPlansFromMessages(this._messages),
+      isLoading: this._isLoading,
+      conversationPath: this._conversationPath
+    };
+  }
+  // ==========================================================================
+  // Actions
+  // ==========================================================================
+  /**
+   * Send a user message and stream the AI response.
+   *
+   * If no conversation exists yet and `createOptions` was provided,
+   * the conversation is created automatically on the first call.
+   */
+  async sendMessage(content) {
+    if (this._isStreaming) {
+      logger.warn("[ConversationStore] Cannot send message while streaming");
+      return;
+    }
+    logger.info("[ConversationStore] Sending message", { path: this._conversationPath });
+    this._error = null;
+    if (!this._conversationPath) {
+      if (!this.createOptions) {
+        throw new Error("No conversationPath and no createOptions provided");
+      }
+      try {
+        const anonymous = this.anonymousOptions();
+        const convo = anonymous ? await this.manager.startAnonymous(this.createOptions.participant, anonymous) : await this.manager.create({
+          participant: this.createOptions.participant,
+          input: this.createOptions.input
+        });
+        this._conversationPath = convo.conversationPath;
+        this._conversationType = convo.type;
+        for (const event of convo.initialEvents ?? []) {
+          this.onEvent?.(event);
+          this.handleEvent(event);
+        }
+        this.notify();
+      } catch (err) {
+        this._error = err instanceof Error ? err.message : String(err);
+        this.notify();
+        return;
+      }
+    }
+    const userMessage = {
+      role: "user",
+      content,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this._messages.push(userMessage);
+    this._isStreaming = true;
+    this._isWaiting = false;
+    this._streamingText = "";
+    this._activeToolCalls = [];
+    this.resetStreamingTimer();
+    this.startWatchdog();
+    this.notify();
+    try {
+      this.ensureSubscription();
+      await this.subscription.waitUntilConnected();
+      await this.manager.createUserMessage(this._conversationPath, content);
+    } catch (err) {
+      logger.error("[ConversationStore] Send failed", err);
+      this._error = err instanceof Error ? err.message : String(err);
+      this._isStreaming = false;
+      this.clearStreamingTimer();
+      this.stopWatchdog();
+      this.notify();
+    }
+  }
+  /**
+   * Load messages from the persisted node tree.
+   * Useful for loading history on page reload.
+   */
+  async loadMessages() {
+    if (!this._conversationPath) return [];
+    this._isLoading = true;
+    this.notify();
+    try {
+      const messages = await this.manager.getMessages(this._conversationPath);
+      logger.debug(`[ConversationStore] Loaded ${messages.length} messages`);
+      if (messages.length > 0) {
+        this._messages = messages;
+        this._activeToolCalls = [];
+      }
+      return messages;
+    } finally {
+      this._isLoading = false;
+      this.notify();
+    }
+  }
+  /**
+   * Approve a pending plan.
+   */
+  async approvePlan(planPath) {
+    await this.manager.approvePlan(planPath);
+  }
+  /**
+   * Reject a pending plan.
+   */
+  async rejectPlan(planPath, feedback) {
+    await this.manager.rejectPlan(planPath, feedback);
+  }
+  /**
+   * Mark a single message as read.
+   */
+  async markMessageAsRead(messagePath) {
+    await this.manager.markMessageAsRead(messagePath);
+  }
+  /**
+   * Stop the current streaming response.
+   */
+  stop() {
+    this._isStreaming = false;
+    this.clearStreamingTimer();
+    this.stopWatchdog();
+    this.notify();
+  }
+  /**
+   * Clean up the store and release resources.
+   */
+  destroy() {
+    this.stop();
+    this.clearStreamingTimer();
+    this.stopWatchdog();
+    this.subscription?.unsubscribe();
+    this.subscription = null;
+    this.subscribers.clear();
+  }
+  /**
+   * Get the conversation path.
+   */
+  getConversationPath() {
+    return this._conversationPath;
+  }
+  // ==========================================================================
+  // Internal
+  // ==========================================================================
+  ensureSubscription() {
+    if (this.subscription) return;
+    if (!this._conversationPath) return;
+    this.subscription = this.manager.subscribe(
+      this._conversationPath,
+      (event) => {
+        this.onEvent?.(event);
+        this.handleEvent(event);
+      }
+    );
+  }
+  handleEvent(event) {
+    logger.debug("[ConversationStore] SSE:", event.type);
+    if (this._isStreaming) {
+      this.resetStreamingTimer();
+    }
+    switch (event.type) {
+      case "text_chunk":
+        this.markStreamingActivity();
+        this._streamingText += event.text;
+        this.notify();
+        break;
+      case "thought_chunk":
+        this.markStreamingActivity();
+        this.notify();
+        break;
+      case "assistant_message":
+        this._messages.push(event.message);
+        this._streamingText = "";
+        this.notify();
+        break;
+      case "tool_call_started": {
+        this.markStreamingActivity();
+        logger.debug("[ConversationStore] Tool started:", event.functionName);
+        const info = {
+          id: event.toolCallId,
+          functionName: event.functionName,
+          arguments: event.arguments,
+          status: "running"
+        };
+        this._activeToolCalls.push(info);
+        this.notify();
+        break;
+      }
+      case "tool_call_completed": {
+        this.markStreamingActivity();
+        logger.debug("[ConversationStore] Tool completed:", event.toolCallId);
+        const idx = this._activeToolCalls.findIndex((tc) => tc.id === event.toolCallId);
+        if (idx >= 0) {
+          this._activeToolCalls[idx] = {
+            ...this._activeToolCalls[idx],
+            status: event.error ? "failed" : "completed",
+            result: event.result,
+            durationMs: event.durationMs
+          };
+        }
+        this.notify();
+        break;
+      }
+      case "waiting": {
+        logger.info("[ConversationStore] Waiting for input");
+        this.flushStreamingText(event.timestamp);
+        this._isStreaming = false;
+        this._isWaiting = true;
+        this._activeToolCalls = [];
+        this.clearStreamingTimer();
+        this.stopWatchdog();
+        this.notify();
+        this.deferredReload();
+        break;
+      }
+      case "done": {
+        if (isRecoveredDoneEvent(event)) {
+          logger.debug("[ConversationStore] Ignoring recovered done event");
+          this.reconcileRecoveredDone();
+          break;
+        }
+        const doneEvent = event;
+        if (doneEvent.dispatchPhase && doneEvent.dispatchPhase !== "terminal") {
+          logger.debug("[ConversationStore] Ignoring non-terminal done event");
+          break;
+        }
+        logger.info("[ConversationStore] Turn done");
+        this.flushStreamingText(event.timestamp);
+        if (doneEvent.content && !this.lastMessageIsAssistant()) {
+          this._messages.push({
+            role: doneEvent.role || "assistant",
+            content: doneEvent.content,
+            timestamp: event.timestamp,
+            senderDisplayName: doneEvent.senderDisplayName,
+            finishReason: doneEvent.finishReason
+          });
+        }
+        this._isStreaming = false;
+        this._isWaiting = true;
+        this._activeToolCalls = [];
+        this.clearStreamingTimer();
+        this.stopWatchdog();
+        this.notify();
+        this.deferredReload();
+        break;
+      }
+      case "completed": {
+        this.flushStreamingText(event.timestamp);
+        if (event.messages && event.messages.length > 0) {
+          this._messages = event.messages;
+        }
+        this._isStreaming = false;
+        this._isWaiting = false;
+        this._activeToolCalls = [];
+        this.clearStreamingTimer();
+        this.stopWatchdog();
+        this.notify();
+        this.deferredReload();
+        break;
+      }
+      case "failed":
+        logger.error("[ConversationStore] Turn failed", event.error);
+        this._error = event.error;
+        this._isStreaming = false;
+        this._isWaiting = false;
+        this._streamingText = "";
+        this._activeToolCalls = [];
+        this.clearStreamingTimer();
+        this.stopWatchdog();
+        this.notify();
+        break;
+      case "conversation_created":
+        this._conversationPath = event.conversationPath;
+        this.notify();
+        break;
+      case "message_saved":
+        this.silentReload().catch(() => {
+        });
+        this.notify();
+        break;
+      case "message_delivered":
+        this._messages.push(event.message);
+        this.notify();
+        break;
+      case "log": {
+        const logEvent = event;
+        const currentLevel = getLogLevel();
+        const levelMap = {
+          debug: 4 /* Debug */,
+          info: 3 /* Info */,
+          warn: 2 /* Warn */,
+          error: 1 /* Error */
+        };
+        const eventLevel = levelMap[logEvent.level] ?? 4 /* Debug */;
+        if (currentLevel >= eventLevel) {
+          const fn = logEvent.level === "error" ? console.error : logEvent.level === "warn" ? console.warn : logEvent.level === "debug" ? console.debug : console.info;
+          fn("[server]", logEvent.message);
+        }
+        break;
+      }
+    }
+  }
+  /**
+   * Agent activity observed while the store thought the turn was over.
+   *
+   * This happens when execution continues WITHOUT a user message — plan
+   * approval in approve_then_auto / step_by_step (approvePlan() returns an
+   * enqueue receipt and the agent starts executing), or agent-initiated
+   * follow-ups. The events arrive over the persistent live subscription
+   * (no history replay), so activity is always "now": re-enter streaming
+   * state so UIs show progress and the end-of-turn handling (done/waiting
+   * → deferred reload) runs again for this continuation.
+   */
+  markStreamingActivity() {
+    if (this._isStreaming) return;
+    logger.debug("[ConversationStore] Agent activity while idle \u2014 re-entering streaming state");
+    this._isStreaming = true;
+    this._isWaiting = false;
+    this._streamingText = "";
+    this.resetStreamingTimer();
+    this.startWatchdog();
+  }
+  /**
+   * If accumulated streaming text hasn't been captured in an assistant_message,
+   * synthesize one.
+   */
+  flushStreamingText(timestamp) {
+    if (this._streamingText && !this.lastMessageIsAssistant()) {
+      this._messages.push({
+        role: "assistant",
+        content: this._streamingText,
+        timestamp
+      });
+    }
+    this._streamingText = "";
+  }
+  lastMessageIsAssistant() {
+    const last = this._messages[this._messages.length - 1];
+    return last?.role === "assistant";
+  }
+  /**
+   * After a turn completes, reload canonical messages from the node tree
+   * to catch any events missed during SSE gaps.
+   */
+  deferredReload() {
+    if (!this._conversationPath) return;
+    logger.debug("[ConversationStore] Scheduling deferred reload");
+    const attemptReload = (delay, retriesLeft) => {
+      setTimeout(async () => {
+        try {
+          const prevCount = this._messages.length;
+          await this.silentReload();
+          if (this._messages.length === prevCount && retriesLeft > 0) {
+            attemptReload(delay * 2, retriesLeft - 1);
+          }
+        } catch {
+        }
+      }, delay);
+    };
+    attemptReload(500, 2);
+  }
+  async silentReload() {
+    if (!this._conversationPath) return;
+    try {
+      const fresh = await this.manager.getMessages(this._conversationPath);
+      if (fresh.length === 0) return;
+      let matchCount = 0;
+      const limit = Math.min(this._messages.length, fresh.length);
+      for (let i = 0; i < limit; i++) {
+        if (this._messages[i].role !== fresh[i].role || this._messages[i].content !== fresh[i].content) break;
+        matchCount++;
+      }
+      if (matchCount === this._messages.length && fresh.length === matchCount) {
+        for (let i = 0; i < matchCount; i++) {
+          const f = fresh[i];
+          const e = this._messages[i];
+          if (f.id) e.id = f.id;
+          if (f.path) e.path = f.path;
+          if (f.messageType) e.messageType = f.messageType;
+          if (f.data) e.data = f.data;
+          if (f.children) e.children = f.children;
+          if (f.finishReason) e.finishReason = f.finishReason;
+        }
+        await this.rebuildToolCallState();
+        return;
+      }
+      if (matchCount === this._messages.length && fresh.length > matchCount) {
+        for (let i = matchCount; i < fresh.length; i++) {
+          this._messages.push(fresh[i]);
+        }
+        for (let i = 0; i < matchCount; i++) {
+          const f = fresh[i];
+          const e = this._messages[i];
+          if (f.id) e.id = f.id;
+          if (f.path) e.path = f.path;
+          if (f.messageType) e.messageType = f.messageType;
+          if (f.data) e.data = f.data;
+          if (f.children) e.children = f.children;
+        }
+        await this.rebuildToolCallState();
+        this.notify();
+        return;
+      }
+      if (matchCount === fresh.length && fresh.length < this._messages.length) {
+        for (let i = 0; i < matchCount; i++) {
+          const f = fresh[i];
+          const e = this._messages[i];
+          if (f.id) e.id = f.id;
+          if (f.path) e.path = f.path;
+          if (f.messageType) e.messageType = f.messageType;
+          if (f.data) e.data = f.data;
+          if (f.children) e.children = f.children;
+        }
+        await this.rebuildToolCallState();
+        return;
+      }
+      this._messages = fresh;
+      await this.rebuildToolCallState();
+      this.notify();
+    } catch (err) {
+      logger.debug("[ConversationStore] Silent reload failed:", err);
+    }
+  }
+  // ==========================================================================
+  // Streaming timeout (Fix A) — auto-recover on SSE inactivity
+  // ==========================================================================
+  resetStreamingTimer() {
+    this.clearStreamingTimer();
+    if (!this._isStreaming) return;
+    this._streamingTimer = setTimeout(() => {
+      if (this._isStreaming) {
+        logger.warn("[ConversationStore] Streaming timeout \u2014 no SSE activity for", this._streamingTimeoutMs, "ms");
+        this.recoverFromHang();
+      }
+    }, this._streamingTimeoutMs);
+  }
+  clearStreamingTimer() {
+    if (this._streamingTimer) {
+      clearTimeout(this._streamingTimer);
+      this._streamingTimer = null;
+    }
+  }
+  // ==========================================================================
+  // Activity watchdog (Fix B) — periodic backend health check
+  // ==========================================================================
+  startWatchdog() {
+    this.stopWatchdog();
+    if (!this._conversationPath) return;
+    this._watchdogTimer = setInterval(async () => {
+      if (!this._isStreaming || !this._conversationPath) {
+        this.stopWatchdog();
+        return;
+      }
+      try {
+        const health = await this.manager.checkTurnHealth(this._conversationPath);
+        if (health === "done" && this._isStreaming) {
+          logger.warn("[ConversationStore] Watchdog detected completed turn while still streaming \u2014 recovering");
+          this.recoverFromHang();
+        }
+      } catch {
+      }
+    }, this._watchdogIntervalMs);
+  }
+  stopWatchdog() {
+    if (this._watchdogTimer) {
+      clearInterval(this._watchdogTimer);
+      this._watchdogTimer = null;
+    }
+  }
+  // ==========================================================================
+  // Hang recovery (shared by timeout + watchdog)
+  // ==========================================================================
+  recoverFromHang() {
+    logger.info("[ConversationStore] Recovering from hang");
+    this.clearStreamingTimer();
+    this.stopWatchdog();
+    this._isStreaming = false;
+    this._isWaiting = true;
+    this._streamingText = "";
+    this.notify();
+    this.silentReload().catch(() => {
+    });
+  }
+  /**
+   * Reconcile a recovered done event against persisted state.
+   * If the backend turn is actually complete, finalize the local state.
+   * Otherwise keep streaming active and let normal events continue.
+   */
+  reconcileRecoveredDone() {
+    if (!this._conversationPath) return;
+    void this.manager.checkTurnHealth(this._conversationPath).then((health) => {
+      if (health !== "done") return;
+      if (!this._isStreaming) return;
+      this._isStreaming = false;
+      this._isWaiting = true;
+      this._activeToolCalls = [];
+      this.clearStreamingTimer();
+      this.stopWatchdog();
+      this.notify();
+      this.deferredReload();
+    }).catch(() => {
+    });
+  }
+  // ==========================================================================
+  // Tool call state rebuild (Fix C) — reconstruct from node tree on reload
+  // ==========================================================================
+  async rebuildToolCallState() {
+    if (!this._conversationPath) {
+      this._activeToolCalls = [];
+      return;
+    }
+    try {
+      const pendingCalls = await this.manager.getActiveToolCalls(this._conversationPath);
+      if (pendingCalls.length > 0) {
+        this._activeToolCalls = pendingCalls.map((tc) => ({
+          id: tc.id,
+          functionName: tc.name,
+          arguments: void 0,
+          status: "running"
+        }));
+        if (!this._isStreaming) {
+          this._isStreaming = true;
+          this.resetStreamingTimer();
+          this.startWatchdog();
+        }
+      } else {
+        this._activeToolCalls = [];
+        if (this._isStreaming) {
+          const lastMsg = this._messages[this._messages.length - 1];
+          const isLastAssistantDone = lastMsg?.role === "assistant" && (lastMsg.dispatchPhase ? lastMsg.dispatchPhase === "terminal" : !!lastMsg.finishReason && lastMsg.finishReason !== "tool_calls");
+          if (isLastAssistantDone) {
+            this._isStreaming = false;
+            this._isWaiting = true;
+            this.clearStreamingTimer();
+            this.stopWatchdog();
+          }
+        }
+      }
+    } catch {
+      this._activeToolCalls = [];
+    }
+  }
+  notify() {
+    const snapshot = this.getSnapshot();
+    for (const sub of this.subscribers) {
+      try {
+        sub(snapshot);
+      } catch (err) {
+        logger.error("Error in conversation store subscriber:", err);
+      }
+    }
+  }
+};
+
+// src/utils/home-path.ts
+var ACCESS_CONTROL_PREFIX = "/raisin:access_control";
+function normalizeHomePath(home) {
+  if (home === null || home === void 0) return null;
+  let path = home.trim();
+  if (path.length === 0) return null;
+  if (path === ACCESS_CONTROL_PREFIX) return "/";
+  if (path.startsWith(`${ACCESS_CONTROL_PREFIX}/`)) {
+    path = path.slice(ACCESS_CONTROL_PREFIX.length);
+  }
+  while (path.length > 1 && path.endsWith("/")) {
+    path = path.slice(0, -1);
+  }
+  return path;
+}
+
+// src/stores/conversation-list-store.ts
+function buildChatsSubscriptionFilters(userHome) {
+  const home = normalizeHomePath(userHome) ?? userHome;
+  return {
+    workspace: "raisin:access_control",
+    path: `${home}/inbox/chats/**`,
+    event_types: ["node:created", "node:updated"]
+  };
+}
+var ConversationListStore = class {
+  constructor(options) {
+    this.subscribers = /* @__PURE__ */ new Set();
+    // Internal state
+    this._conversations = [];
+    this._isLoading = false;
+    this._error = null;
+    // Cached ConversationStore instances
+    this._stores = /* @__PURE__ */ new Map();
+    // Real-time subscription
+    this._realtimeSubscription = null;
+    this.database = options.database;
+    this.type = options.type;
+    this.realtime = options.realtime ?? false;
+  }
+  // ==========================================================================
+  // Subscription
+  // ==========================================================================
+  subscribe(callback) {
+    this.subscribers.add(callback);
+    callback(this.getSnapshot());
+    return () => {
+      this.subscribers.delete(callback);
+    };
+  }
+  getSnapshot() {
+    return {
+      conversations: [...this._conversations],
+      totalUnreadCount: this._conversations.reduce((sum, c) => sum + (c.unreadCount ?? 0), 0),
+      isLoading: this._isLoading,
+      error: this._error
+    };
+  }
+  // ==========================================================================
+  // Actions
+  // ==========================================================================
+  /**
+   * Load conversations from the server.
+   */
+  async load() {
+    this._isLoading = true;
+    this._error = null;
+    this.notify();
+    try {
+      const conversations = await this.database.conversations.list({
+        type: this.type
+      });
+      logger.debug(`[ConversationListStore] Loaded ${conversations.length} conversations`);
+      this._conversations = conversations;
+      if (this.realtime) {
+        this.startRealtimeSubscription();
+      }
+    } catch (err) {
+      logger.error("[ConversationListStore] Failed to load conversations", err);
+      this._error = err instanceof Error ? err.message : String(err);
+    } finally {
+      this._isLoading = false;
+      this.notify();
+    }
+  }
+  /**
+   * Create a new conversation.
+   */
+  async createConversation(options) {
+    const convo = await this.database.conversations.create(options);
+    const listItem = {
+      id: convo.id,
+      type: convo.type,
+      conversationPath: convo.conversationPath,
+      conversationWorkspace: convo.conversationWorkspace,
+      agentRef: convo.agentRef,
+      participants: convo.participants,
+      unreadCount: 0,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this._conversations = [listItem, ...this._conversations];
+    this.notify();
+    return listItem;
+  }
+  /**
+   * Delete a conversation.
+   */
+  async deleteConversation(conversationPath) {
+    const store = this._stores.get(conversationPath);
+    if (store) {
+      store.destroy();
+      this._stores.delete(conversationPath);
+    }
+    await this.database.conversations.delete(conversationPath);
+    this._conversations = this._conversations.filter((c) => c.conversationPath !== conversationPath);
+    this.notify();
+  }
+  /**
+   * Mark a conversation as read.
+   */
+  async markAsRead(conversationPath) {
+    await this.database.conversations.markAsRead(conversationPath);
+    this._conversations = this._conversations.map(
+      (c) => c.conversationPath === conversationPath ? { ...c, unreadCount: 0 } : c
+    );
+    this.notify();
+  }
+  /**
+   * Get or create a ConversationStore for a specific conversation.
+   * Caches instances so repeated calls return the same store.
+   */
+  getConversationStore(conversationPath, overrides) {
+    let store = this._stores.get(conversationPath);
+    if (!store) {
+      store = new ConversationStore({
+        database: this.database,
+        conversationPath,
+        ...overrides
+      });
+      this._stores.set(conversationPath, store);
+    }
+    return store;
+  }
+  /**
+   * Clean up all resources.
+   */
+  destroy() {
+    this._realtimeSubscription?.unsubscribe();
+    this._realtimeSubscription = null;
+    for (const store of this._stores.values()) {
+      store.destroy();
+    }
+    this._stores.clear();
+    this.subscribers.clear();
+  }
+  // ==========================================================================
+  // Internal
+  // ==========================================================================
+  async startRealtimeSubscription() {
+    if (this._realtimeSubscription) return;
+    logger.debug("[ConversationListStore] Starting realtime subscription");
+    try {
+      const workspace = this.database.workspace("raisin:access_control");
+      const events = workspace.events();
+      const result = await this.database.executeSql(
+        `SELECT RAISIN_CURRENT_USER()->>'path'::String as home`
+      );
+      const rows = result.rows;
+      const userHome = rows?.[0]?.home;
+      if (!userHome) return;
+      this._realtimeSubscription = await events.subscribe(
+        buildChatsSubscriptionFilters(userHome),
+        async (event) => {
+          const eventData = event;
+          const nodeId = eventData.payload?.node_id;
+          if (!nodeId) return;
+          try {
+            const nodeResult = await this.database.executeSql(
+              `SELECT id, path, node_type, properties, created_at, updated_at FROM 'raisin:access_control' WHERE id = $1 LIMIT 1`,
+              [nodeId]
+            );
+            const row = nodeResult.rows?.[0];
+            if (!row || row.node_type !== "raisin:Conversation") return;
+            const convPath = row.path;
+            const props = row.properties ?? {};
+            const item = {
+              id: row.id,
+              type: props.conversation_type ?? "ai_chat",
+              conversationPath: convPath,
+              conversationWorkspace: "raisin:access_control",
+              agentRef: props.agent_ref,
+              participants: props.participants,
+              unreadCount: props.unread_count ?? 0,
+              lastMessage: props.last_message,
+              updatedAt: row.updated_at ?? row.created_at
+            };
+            const existingIdx = this._conversations.findIndex((c) => c.conversationPath === convPath);
+            if (existingIdx >= 0) {
+              this._conversations.splice(existingIdx, 1);
+            }
+            this._conversations = [item, ...this._conversations];
+            this.notify();
+          } catch (err) {
+            logger.debug("Failed to process conversation event:", err);
+          }
+        }
+      );
+    } catch (err) {
+      logger.debug("Failed to start realtime subscription:", err);
+    }
+  }
+  notify() {
+    const snapshot = this.getSnapshot();
+    for (const sub of this.subscribers) {
+      try {
+        sub(snapshot);
+      } catch (err) {
+        logger.error("Error in conversation list store subscriber:", err);
+      }
+    }
+  }
+};
+
+// src/integrations/react-conversation.ts
+var INITIAL_SNAPSHOT = {
+  conversation: null,
+  messages: [],
+  isStreaming: false,
+  isWaiting: false,
+  streamingText: "",
+  error: null,
+  activeToolCalls: [],
+  plans: [],
+  isLoading: false,
+  conversationPath: null
+};
+function useConversation(react, options) {
+  const { useState, useEffect, useRef, useCallback } = react;
+  const [snapshot, setSnapshot] = useState(INITIAL_SNAPSHOT);
+  const storeRef = useRef(null);
+  useEffect(() => {
+    const store = new ConversationStore(options);
+    storeRef.current = store;
+    const unsubscribe = store.subscribe((next) => setSnapshot(next));
+    return () => {
+      unsubscribe();
+      store.destroy();
+      storeRef.current = null;
+    };
+  }, [options.conversationPath]);
+  const sendMessage = useCallback(async (content) => {
+    await storeRef.current?.sendMessage(content);
+  }, []);
+  const approvePlan = useCallback(async (planPath) => {
+    await storeRef.current?.approvePlan(planPath);
+  }, []);
+  const rejectPlan = useCallback(async (planPath, feedback) => {
+    await storeRef.current?.rejectPlan(planPath, feedback);
+  }, []);
+  const stop = useCallback(() => {
+    storeRef.current?.stop();
+  }, []);
+  const loadMessages = useCallback(async () => {
+    return await storeRef.current?.loadMessages() ?? [];
+  }, []);
+  return {
+    ...snapshot,
+    sendMessage,
+    approvePlan,
+    rejectPlan,
+    stop,
+    loadMessages
+  };
+}
+var INITIAL_LIST_SNAPSHOT = {
+  conversations: [],
+  totalUnreadCount: 0,
+  isLoading: true,
+  error: null
+};
+function useConversationList(react, options) {
+  const { useState, useEffect, useRef, useCallback } = react;
+  const [snapshot, setSnapshot] = useState(INITIAL_LIST_SNAPSHOT);
+  const storeRef = useRef(null);
+  useEffect(() => {
+    const store = new ConversationListStore(options);
+    storeRef.current = store;
+    const unsubscribe = store.subscribe((next) => setSnapshot(next));
+    store.load();
+    return () => {
+      unsubscribe();
+      store.destroy();
+      storeRef.current = null;
+    };
+  }, [options.type, options.realtime]);
+  const createConversation = useCallback(async (opts) => {
+    return storeRef.current.createConversation(opts);
+  }, []);
+  const deleteConversation = useCallback(async (conversationPath) => {
+    await storeRef.current?.deleteConversation(conversationPath);
+  }, []);
+  const markAsRead = useCallback(async (conversationPath) => {
+    await storeRef.current?.markAsRead(conversationPath);
+  }, []);
+  return {
+    ...snapshot,
+    createConversation,
+    deleteConversation,
+    markAsRead
+  };
+}
+
+// src/errors.ts
+var RaisinError = class extends Error {
+  constructor(message, code, details) {
+    super(message);
+    this.name = "RaisinError";
+    this.code = code;
+    this.details = details;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var RaisinConnectionError = class extends RaisinError {
+  constructor(message, code, options) {
+    super(message, code, options?.details);
+    this.name = "RaisinConnectionError";
+    this.status = options?.status;
+  }
+};
+var RaisinAuthError = class extends RaisinError {
+  constructor(message, code, status, details) {
+    super(message, code, details);
+    this.name = "RaisinAuthError";
+    this.status = status;
+  }
+};
+var RaisinFlowError = class extends RaisinError {
+  constructor(message, code, instanceId, details) {
+    super(message, code, details);
+    this.name = "RaisinFlowError";
+    this.instanceId = instanceId;
+  }
+};
+var RaisinTimeoutError = class extends RaisinError {
+  constructor(message, code, timeoutMs, details) {
+    super(message, code, details);
+    this.name = "RaisinTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+var RaisinAbortError = class extends RaisinError {
+  constructor(message = "Operation was aborted") {
+    super(message, "ABORTED");
+    this.name = "RaisinAbortError";
+  }
+};
+function classifyHttpError(status, message, details) {
+  if (status === 401) {
+    return new RaisinAuthError(message, "AUTH_UNAUTHORIZED", status, details);
+  }
+  if (status === 403) {
+    return new RaisinAuthError(message, "AUTH_FORBIDDEN", status, details);
+  }
+  if (status === 404) {
+    return new RaisinFlowError(message, "FLOW_NOT_FOUND", void 0, details);
+  }
+  return new RaisinConnectionError(message, "CONNECTION_FAILED", { status, details });
+}
+
+// src/streaming/sse-client.ts
+function parseSSEBlock(block) {
+  let event = "message";
+  let data = "";
+  let id;
+  const lines = block.split("\n");
+  for (const line of lines) {
+    if (line.startsWith("event:")) {
+      event = line.slice(6).trim();
+    } else if (line.startsWith("data:")) {
+      if (data) data += "\n";
+      data += line.slice(5).trim();
+    } else if (line.startsWith("id:")) {
+      id = line.slice(3).trim();
+    }
+  }
+  if (!data) return null;
+  return { event, data, id };
+}
+var SSEClient = class {
+  constructor(url, options = {}) {
+    this.abortController = null;
+    this._state = "disconnected";
+    this.url = url;
+    this.options = options;
+    this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this._lastEventId = options.lastEventId;
+    this.autoReconnect = options.reconnect?.enabled ?? true;
+    this.externalSignal = options.signal;
+    this.inactivityTimeoutMs = options.inactivityTimeoutMs;
+    this.eventTypeSet = options.eventTypes?.length ? new Set(options.eventTypes) : null;
+    this.reconnectManager = new ReconnectManager({
+      initialDelay: options.reconnect?.initialDelay ?? 1e3,
+      maxDelay: options.reconnect?.maxDelay ?? 3e4,
+      backoffMultiplier: options.reconnect?.backoffMultiplier ?? 2,
+      maxAttempts: options.reconnect?.maxAttempts ?? Infinity
+    });
+  }
+  /** Current connection state */
+  get state() {
+    return this._state;
+  }
+  /**
+   * Returns a promise that resolves once the SSE connection is established.
+   *
+   * Useful for ensuring the connection is ready before triggering events
+   * on the server side (e.g., calling resume before consuming the stream).
+   * If the client is already connected, resolves immediately.
+   */
+  waitUntilConnected() {
+    if (this._state === "connected") return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const originalOnState = this.options.onStateChange;
+      this.options.onStateChange = (state) => {
+        originalOnState?.(state);
+        if (state === "connected") {
+          this.options.onStateChange = originalOnState;
+          resolve();
+        } else if (state === "disconnected") {
+          this.options.onStateChange = originalOnState;
+          reject(new Error("SSE connection failed"));
+        }
+      };
+    });
+  }
+  /** Last received event ID */
+  get lastEventId() {
+    return this._lastEventId;
+  }
+  setState(state) {
+    if (this._state !== state) {
+      this._state = state;
+      this.options.onStateChange?.(state);
+    }
+  }
+  /**
+   * Connect and consume events via callback.
+   *
+   * @param onEvent - Called for each matching SSE event
+   * @param onError - Called when an error occurs (optional)
+   */
+  async connect(onEvent, onError) {
+    this.close();
+    await this.startStream(onEvent, onError);
+  }
+  /**
+   * Close the SSE connection and stop reconnection attempts.
+   */
+  close() {
+    this.reconnectManager.cancelReconnect();
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    this.setState("disconnected");
+  }
+  /**
+   * AsyncIterable interface: allows `for await (const event of sseClient)`.
+   *
+   * The iterator ends when close() is called or the server closes the stream
+   * (and auto-reconnect is disabled or max attempts are exhausted).
+   */
+  async *[Symbol.asyncIterator]() {
+    const queue = [];
+    let resolve = null;
+    let finished = false;
+    const push = (item) => {
+      if (finished) return;
+      if (resolve) {
+        const r = resolve;
+        resolve = null;
+        r(item);
+      } else {
+        queue.push(item);
+      }
+    };
+    const pull = () => {
+      const queued = queue.shift();
+      if (queued) return Promise.resolve(queued);
+      return new Promise((r) => {
+        resolve = r;
+      });
+    };
+    this.startStream(
+      (event) => push({ done: false, value: event }),
+      (error) => push({ done: true, error })
+    ).then(() => {
+      push({ done: true });
+    }).catch((error) => {
+      push({ done: true, error });
+    });
+    try {
+      while (!finished) {
+        const item = await pull();
+        if (item.done) {
+          finished = true;
+          if (item.error) {
+            throw item.error;
+          }
+          return;
+        }
+        yield item.value;
+      }
+    } finally {
+      finished = true;
+      this.close();
+    }
+  }
+  /**
+   * Core streaming loop: connects, reads the SSE stream, and handles reconnection.
+   */
+  async startStream(onEvent, onError) {
+    while (true) {
+      try {
+        await this.readStream(onEvent);
+        if (!this.autoReconnect || this._state === "disconnected") {
+          return;
+        }
+        this.setState("reconnecting");
+        const scheduled = await this.waitForReconnect();
+        if (!scheduled) {
+          logger.warn("SSE max reconnection attempts reached");
+          this.setState("disconnected");
+          return;
+        }
+      } catch (error) {
+        if (this._state === "disconnected") {
+          return;
+        }
+        const err = error instanceof Error ? error : new Error(String(error));
+        if (err.name === "AbortError" || err instanceof RaisinAbortError) {
+          return;
+        }
+        if (err instanceof RaisinTimeoutError && err.code === "SSE_INACTIVITY_TIMEOUT") {
+          logger.warn("SSE inactivity timeout:", err.message);
+          if (!this.autoReconnect) {
+            this.setState("disconnected");
+            onError?.(err);
+            throw err;
+          }
+          this.setState("reconnecting");
+          const scheduled2 = await this.waitForReconnect();
+          if (!scheduled2) {
+            logger.warn("SSE max reconnection attempts reached");
+            this.setState("disconnected");
+            onError?.(err);
+            throw err;
+          }
+          continue;
+        }
+        logger.error("SSE connection error:", err.message);
+        onError?.(err);
+        if (!this.autoReconnect) {
+          this.setState("disconnected");
+          throw err;
+        }
+        this.setState("reconnecting");
+        const scheduled = await this.waitForReconnect();
+        if (!scheduled) {
+          logger.warn("SSE max reconnection attempts reached");
+          this.setState("disconnected");
+          throw err;
+        }
+      }
+    }
+  }
+  /**
+   * Perform a single fetch and read the response body as SSE stream.
+   */
+  async readStream(onEvent) {
+    this.abortController = new AbortController();
+    this.setState("connecting");
+    if (this.externalSignal) {
+      if (this.externalSignal.aborted) {
+        this.abortController.abort();
+      } else {
+        const ctrl = this.abortController;
+        this.externalSignal.addEventListener("abort", () => ctrl.abort(), { once: true });
+      }
+    }
+    const headers = {
+      Accept: "text/event-stream",
+      "Cache-Control": "no-cache",
+      ...this.options.headers
+    };
+    if (this._lastEventId) {
+      headers["Last-Event-ID"] = this._lastEventId;
+    }
+    const method = this.options.method ?? "GET";
+    const fetchOptions = {
+      method,
+      headers,
+      signal: this.abortController.signal
+    };
+    if (method === "POST" && this.options.body !== void 0) {
+      fetchOptions.headers["Content-Type"] = "application/json";
+      fetchOptions.body = JSON.stringify(this.options.body);
+    }
+    const response = await this.withInactivityTimeout(
+      this.fetchImpl(this.url, fetchOptions)
+    );
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      const msg = `SSE connection failed: ${response.status} ${response.statusText}${text ? ` - ${text}` : ""}`;
+      if (response.status === 401 || response.status === 403) {
+        throw new RaisinAuthError(
+          msg,
+          response.status === 401 ? "AUTH_UNAUTHORIZED" : "AUTH_FORBIDDEN",
+          response.status
+        );
+      }
+      throw new RaisinConnectionError(msg, "SSE_STREAM_ERROR", { status: response.status });
+    }
+    if (!response.body) {
+      throw new RaisinConnectionError("SSE response has no body", "SSE_STREAM_ERROR");
+    }
+    this.setState("connected");
+    this.reconnectManager.reset();
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      while (true) {
+        const { done, value } = await this.withInactivityTimeout(reader.read());
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const blocks = buffer.split("\n\n");
+        buffer = blocks.pop() ?? "";
+        for (const block of blocks) {
+          const trimmed = block.trim();
+          if (!trimmed) continue;
+          const parsed = parseSSEBlock(trimmed);
+          if (!parsed) continue;
+          if (parsed.id) {
+            this._lastEventId = parsed.id;
+          }
+          if (this.eventTypeSet && !this.eventTypeSet.has(parsed.event)) {
+            continue;
+          }
+          let data;
+          try {
+            data = JSON.parse(parsed.data);
+          } catch {
+            data = parsed.data;
+          }
+          const sseEvent = {
+            type: parsed.event,
+            data,
+            id: parsed.id
+          };
+          onEvent(sseEvent);
+        }
+      }
+    } finally {
+      try {
+        reader.releaseLock();
+      } catch {
+      }
+    }
+  }
+  /**
+   * Race a stream operation against the inactivity timeout.
+   *
+   * If no bytes (or response) arrive within `inactivityTimeoutMs`, the
+   * internal connection is aborted and the operation rejects with a
+   * `RaisinTimeoutError` (code `SSE_INACTIVITY_TIMEOUT`). The timer is
+   * effectively reset on every chunk because each `reader.read()` is
+   * wrapped individually.
+   */
+  withInactivityTimeout(promise) {
+    const timeoutMs = this.inactivityTimeoutMs;
+    if (!timeoutMs || timeoutMs <= 0) return promise;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        promise.catch(() => void 0);
+        this.abortController?.abort();
+        reject(
+          new RaisinTimeoutError(
+            `SSE stream inactive for ${timeoutMs}ms`,
+            "SSE_INACTIVITY_TIMEOUT",
+            timeoutMs
+          )
+        );
+      }, timeoutMs);
+      promise.then(
+        (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        (error) => {
+          clearTimeout(timer);
+          reject(error);
+        }
+      );
+    });
+  }
+  /**
+   * Wait for the reconnect manager to schedule a reconnection attempt.
+   * Returns true if reconnection was scheduled, false if max attempts reached.
+   */
+  waitForReconnect() {
+    return new Promise((resolve) => {
+      const scheduled = this.reconnectManager.scheduleReconnect(() => {
+        resolve(true);
+      });
+      if (!scheduled) {
+        resolve(false);
+      }
+    });
+  }
+};
+
+// src/flow-client.ts
+var FlowClient = class _FlowClient {
+  /**
+   * Create a new FlowClient.
+   *
+   * @param baseUrl - Base HTTP URL of the RaisinDB server (e.g., "http://localhost:8081")
+   * @param repository - Repository name
+   * @param authManager - Auth manager for token access
+   * @param options - Additional options
+   * @param flowsApi - Optional FlowsApi for WebSocket-based flow operations
+   */
+  constructor(baseUrl, repository, authManager, options = {}, flowsApi) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.repository = repository;
+    this.authManager = authManager;
+    this.fetchImpl = options.fetch ?? fetch;
+    this.requestTimeout = options.requestTimeout ?? 6e4;
+    this.flowsApi = flowsApi;
+  }
+  /**
+   * Create a FlowClient from an existing RaisinHttpClient.
+   *
+   * @param httpClient - An authenticated RaisinHttpClient instance
+   * @param baseUrl - Base HTTP URL (same as the one used for the HTTP client)
+   * @param repository - Repository name
+   * @param options - Additional options
+   */
+  static fromHttpClient(httpClient, baseUrl, repository, options = {}, flowsApi) {
+    return new _FlowClient(
+      baseUrl,
+      repository,
+      httpClient.getAuthManager(),
+      options,
+      flowsApi
+    );
+  }
+  // ==========================================================================
+  // Flow Execution
+  // ==========================================================================
+  /**
+   * Execute a flow by path.
+   *
+   * Creates a FlowInstance and queues it for execution. Returns immediately
+   * with the instance ID - use `streamEvents()` to monitor progress.
+   *
+   * @param flowPath - Path to the raisin:Flow node (e.g., "/flows/my-flow")
+   * @param input - Input data passed to the flow
+   * @returns Flow run response with instance_id and job_id
+   *
+   * @example
+   * ```typescript
+   * const result = await flows.run('/flows/process-order', {
+   *   orderId: 'ord-123',
+   *   items: [{ sku: 'ABC', qty: 2 }],
+   * });
+   * console.log('Instance:', result.instance_id);
+   * ```
+   */
+  async run(flowPath, input = {}, options) {
+    if (this.flowsApi) {
+      return this.flowsApi.run(flowPath, input);
+    }
+    const response = await this.request({
+      method: "POST",
+      path: `/api/flows/${this.repository}/run`,
+      body: { flow_path: flowPath, input },
+      signal: options?.signal
+    });
+    return response;
+  }
+  // ==========================================================================
+  // Instance Status
+  // ==========================================================================
+  /**
+   * Get the current status of a flow instance.
+   *
+   * Returns the instance status, variables, and metadata. Useful for
+   * polling-based approaches where SSE is not reliable (e.g., initial
+   * flow execution where events may be missed).
+   *
+   * @param instanceId - Flow instance ID (from `run()`)
+   * @returns Instance status including variables and flow path
+   *
+   * @example
+   * ```typescript
+   * const status = await flows.getInstanceStatus('instance-123');
+   * console.log('Status:', status.status); // 'waiting', 'completed', etc.
+   * ```
+   */
+  async getInstanceStatus(instanceId, options) {
+    if (this.flowsApi) {
+      return this.flowsApi.getInstanceStatus(instanceId);
+    }
+    return this.request({
+      method: "GET",
+      path: `/api/flows/${this.repository}/instances/${instanceId}`,
+      signal: options?.signal
+    });
+  }
+  // ==========================================================================
+  // Event Streaming (SSE)
+  // ==========================================================================
+  /**
+   * Stream real-time execution events for a flow instance via SSE.
+   *
+   * Returns an async iterable that yields FlowExecutionEvent objects.
+   * The stream automatically closes when a terminal event is received
+   * (flow_completed or flow_failed).
+   *
+   * @param instanceId - Flow instance ID (from `run()`)
+   * @returns Async iterable of flow execution events
+   *
+   * @example
+   * ```typescript
+   * const { instance_id } = await flows.run('/flows/my-flow', { key: 'value' });
+   *
+   * for await (const event of flows.streamEvents(instance_id)) {
+   *   switch (event.type) {
+   *     case 'step_started':
+   *       console.log(`Step ${event.node_id} started`);
+   *       break;
+   *     case 'step_completed':
+   *       console.log(`Step ${event.node_id} completed in ${event.duration_ms}ms`);
+   *       break;
+   *     case 'text_chunk':
+   *       process.stdout.write(event.text);
+   *       break;
+   *     case 'flow_completed':
+   *       console.log('Flow done:', event.output);
+   *       break;
+   *     case 'flow_failed':
+   *       console.error('Flow failed:', event.error);
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  async *streamEvents(instanceId, options) {
+    if (this.flowsApi) {
+      const sub = await this.flowsApi.subscribeEvents(instanceId);
+      try {
+        for await (const event of sub.events) {
+          if (options?.signal?.aborted) throw new RaisinAbortError();
+          yield event;
+          if (event.type === "flow_completed" || event.type === "flow_failed") {
+            return;
+          }
+        }
+      } finally {
+        await sub.unsubscribe();
+      }
+      return;
+    }
+    const url = `${this.baseUrl}/api/flows/${this.repository}/instances/${instanceId}/events`;
+    const headers = {};
+    const token = this.authManager.getAccessToken();
+    if (token) {
+      headers["Authorization"] = `Bearer ${token}`;
+    }
+    const sse = new SSEClient(url, {
+      headers,
+      eventTypes: ["flow-event", "message"],
+      reconnect: { enabled: false },
+      fetch: this.fetchImpl,
+      signal: options?.signal
+    });
+    try {
+      for await (const sseEvent of sse) {
+        const event = sseEvent.data;
+        yield event;
+        if (event.type === "flow_completed" || event.type === "flow_failed") {
+          return;
+        }
+      }
+    } finally {
+      sse.close();
+    }
+  }
+  /**
+   * Create an eagerly-connected event stream for a flow instance.
+   *
+   * Unlike `streamEvents()` (a lazy async generator), this method opens the
+   * SSE connection immediately and waits until it is established before
+   * returning. This is critical for resume flows: you must subscribe to
+   * events BEFORE calling `resume()`, otherwise events emitted between
+   * the resume and the SSE connection are lost.
+   *
+   * @param instanceId - Flow instance ID
+   * @returns Object with an async iterable `events` and a `close()` method
+   */
+  async createEventStream(instanceId, options) {
+    if (this.flowsApi) {
+      const sub = await this.flowsApi.subscribeEvents(instanceId);
+      return {
+        events: sub.events,
+        close: () => {
+          sub.unsubscribe();
+        }
+      };
+    }
+    const url = `${this.baseUrl}/api/flows/${this.repository}/instances/${instanceId}/events`;
+    const headers = {};
+    const token = this.authManager.getAccessToken();
+    if (token) {
+      headers["Authorization"] = `Bearer ${token}`;
+    }
+    const sse = new SSEClient(url, {
+      headers,
+      eventTypes: ["flow-event", "message"],
+      reconnect: { enabled: false },
+      fetch: this.fetchImpl,
+      signal: options?.signal
+    });
+    const iterator = sse[Symbol.asyncIterator]();
+    let pendingFirst = iterator.next();
+    await sse.waitUntilConnected();
+    const events = {
+      [Symbol.asyncIterator]() {
+        return {
+          async next() {
+            let result;
+            if (pendingFirst) {
+              result = await pendingFirst;
+              pendingFirst = null;
+            } else {
+              result = await iterator.next();
+            }
+            if (result.done) return { done: true, value: void 0 };
+            const event = result.value.data;
+            return { done: false, value: event };
+          },
+          async return() {
+            await iterator.return?.();
+            sse.close();
+            return { done: true, value: void 0 };
+          }
+        };
+      }
+    };
+    return { events, close: () => sse.close() };
+  }
+  // ==========================================================================
+  // Flow Resume & Human Task
+  // ==========================================================================
+  /**
+   * Resume a flow instance that is in a waiting state.
+   *
+   * Use this when a flow is waiting for external input (tool results,
+   * external events, etc.). The resume data is passed to the waiting step.
+   *
+   * @param instanceId - Flow instance ID
+   * @param data - Resume data to pass to the waiting step
+   *
+   * @example
+   * ```typescript
+   * await flows.resume('instance-123', {
+   *   tool_name: 'get_weather',
+   *   result: { temperature: 72, conditions: 'sunny' },
+   * });
+   * ```
+   */
+  async resume(instanceId, data, options) {
+    if (this.flowsApi) {
+      await this.flowsApi.resume(instanceId, data);
+      return;
+    }
+    await this.request({
+      method: "POST",
+      path: `/api/flows/${this.repository}/instances/${instanceId}/resume`,
+      body: { resume_data: data },
+      signal: options?.signal
+    });
+  }
+  /**
+   * Respond to a human task within a flow.
+   *
+   * When a flow is waiting on a human_task step (approval, input, review),
+   * use this method to submit the response. Completion is validated
+   * (caller must be the task's assignee or an admin) and resumes the flow.
+   *
+   * Note: prefer `InboxApi` for full inbox functionality (listing tasks,
+   * task details); this is a convenience passthrough to the same endpoint.
+   *
+   * @param instanceId - Flow instance ID (unused; kept for API stability)
+   * @param taskId - The inbox task node ID (or path)
+   * @param response - The response data
+   *
+   * @example
+   * ```typescript
+   * // Approve a task
+   * await flows.respondToHumanTask('instance-123', 'task-abc', {
+   *   action: 'approve',
+   *   comment: 'Looks good!',
+   * });
+   * ```
+   */
+  async respondToHumanTask(_instanceId, taskId, response, options) {
+    await this.request({
+      method: "POST",
+      path: `/api/inbox/${this.repository}/tasks/${encodeURIComponent(taskId)}/complete`,
+      body: { response },
+      signal: options?.signal
+    });
+  }
+  // ==========================================================================
+  // Convenience Methods
+  // ==========================================================================
+  /**
+   * Run a flow and wait for the final result.
+   *
+   * Starts the flow, streams all events, and returns the terminal outcome.
+   * This is a one-shot helper for fire-and-forget flows where you only
+   * care about the final output.
+   *
+   * @param flowPath - Path to the raisin:Flow node
+   * @param input - Input data passed to the flow
+   * @param options - Optional abort signal
+   * @returns The flow outcome including output or error
+   *
+   * @example
+   * ```typescript
+   * const result = await flows.runAndWait('/flows/process-order', { orderId: '123' });
+   * if (result.status === 'completed') {
+   *   console.log('Output:', result.output);
+   * }
+   * ```
+   */
+  async runAndWait(flowPath, input = {}, options) {
+    const { instance_id } = await this.run(flowPath, input, options);
+    for await (const event of this.streamEvents(instance_id, options)) {
+      if (event.type === "flow_completed") {
+        return {
+          instanceId: instance_id,
+          status: "completed",
+          output: event.output
+        };
+      }
+      if (event.type === "flow_failed") {
+        return {
+          instanceId: instance_id,
+          status: "failed",
+          error: event.error
+        };
+      }
+    }
+    return { instanceId: instance_id, status: "failed", error: "Stream ended without terminal event" };
+  }
+  /**
+   * Run a flow and collect all events into an array.
+   *
+   * Starts the flow, streams all events, and returns them as a collected array.
+   * Useful for testing, logging, or post-processing all flow events.
+   *
+   * @param flowPath - Path to the raisin:Flow node
+   * @param input - Input data passed to the flow
+   * @param options - Optional abort signal
+   * @returns The instance ID and all collected events
+   *
+   * @example
+   * ```typescript
+   * const { events } = await flows.runAndCollect('/flows/etl-pipeline', { source: 'db' });
+   * const steps = events.filter(e => e.type === 'step_completed');
+   * console.log(`Completed ${steps.length} steps`);
+   * ```
+   */
+  async runAndCollect(flowPath, input = {}, options) {
+    const { instance_id } = await this.run(flowPath, input, options);
+    const events = [];
+    for await (const event of this.streamEvents(instance_id, options)) {
+      events.push(event);
+    }
+    return { instanceId: instance_id, events };
+  }
+  // ==========================================================================
+  // Internal HTTP request helper
+  // ==========================================================================
+  async request(options) {
+    const url = `${this.baseUrl}${options.path}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    const token = this.authManager.getAccessToken();
+    if (token) {
+      headers["Authorization"] = `Bearer ${token}`;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.requestTimeout);
+    if (options.signal) {
+      if (options.signal.aborted) {
+        clearTimeout(timeoutId);
+        throw new RaisinAbortError();
+      }
+      options.signal.addEventListener("abort", () => controller.abort(), { once: true });
+    }
+    try {
+      const response = await this.fetchImpl(url, {
+        method: options.method,
+        headers,
+        body: options.body ? JSON.stringify(options.body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorText = await response.text();
+        let errorMessage;
+        try {
+          const errorJson = JSON.parse(errorText);
+          errorMessage = errorJson.message || errorJson.error || errorText;
+        } catch {
+          errorMessage = errorText || `HTTP ${response.status}: ${response.statusText}`;
+        }
+        throw classifyHttpError(response.status, errorMessage);
+      }
+      const contentType = response.headers.get("content-type");
+      if (contentType?.includes("application/json")) {
+        return await response.json();
+      }
+      return void 0;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof RaisinAbortError || error instanceof RaisinTimeoutError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        if (options.signal?.aborted) {
+          throw new RaisinAbortError();
+        }
+        throw new RaisinTimeoutError(
+          `Request timeout after ${this.requestTimeout}ms`,
+          "REQUEST_TIMEOUT",
+          this.requestTimeout
+        );
+      }
+      throw error;
+    }
+  }
+};
+
+// src/integrations/react-flow.ts
+function useFlow(react, options) {
+  const { useState, useEffect, useRef, useCallback } = react;
+  const [events, setEvents] = useState([]);
+  const [status, setStatus] = useState("idle");
+  const [error, setError] = useState(null);
+  const [output, setOutput] = useState(null);
+  const [instanceId, setInstanceId] = useState(null);
+  const clientRef = useRef(null);
+  const abortRef = useRef(false);
+  useEffect(() => {
+    if (options.database) {
+      clientRef.current = options.database.flow;
+    } else if (options.baseUrl && options.repository && options.authManager) {
+      clientRef.current = new FlowClient(
+        options.baseUrl,
+        options.repository,
+        options.authManager,
+        options.clientOptions,
+        options.flowsApi
+      );
+    }
+    return () => {
+      abortRef.current = true;
+      clientRef.current = null;
+    };
+  }, [options.database, options.baseUrl, options.repository]);
+  const run = useCallback(async (flowPath, input = {}) => {
+    const client = clientRef.current;
+    if (!client) return;
+    abortRef.current = false;
+    setEvents([]);
+    setError(null);
+    setOutput(null);
+    setStatus("running");
+    try {
+      const result = await client.run(flowPath, input);
+      setInstanceId(result.instance_id);
+      for await (const event of client.streamEvents(result.instance_id)) {
+        if (abortRef.current) break;
+        setEvents((prev) => [...prev, event]);
+        if (event.type === "flow_waiting") {
+          setStatus("waiting");
+        } else if (event.type === "flow_completed") {
+          setOutput(event.output);
+          setStatus("completed");
+        } else if (event.type === "flow_failed") {
+          setError(event.error);
+          setStatus("failed");
+        }
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+      setStatus("failed");
+    }
+  }, []);
+  const resume = useCallback(async (data) => {
+    const client = clientRef.current;
+    if (!client || !instanceId) return;
+    setStatus("running");
+    setError(null);
+    try {
+      const stream = await client.createEventStream(instanceId);
+      await client.resume(instanceId, data);
+      for await (const event of stream.events) {
+        if (abortRef.current) break;
+        setEvents((prev) => [...prev, event]);
+        if (event.type === "flow_waiting") {
+          setStatus("waiting");
+          stream.close();
+          return;
+        } else if (event.type === "flow_completed") {
+          setOutput(event.output);
+          setStatus("completed");
+          stream.close();
+          return;
+        } else if (event.type === "flow_failed") {
+          setError(event.error);
+          setStatus("failed");
+          stream.close();
+          return;
+        }
+      }
+      stream.close();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+      setStatus("failed");
+    }
+  }, [instanceId]);
+  const reset = useCallback(() => {
+    abortRef.current = true;
+    setEvents([]);
+    setStatus("idle");
+    setError(null);
+    setOutput(null);
+    setInstanceId(null);
+  }, []);
+  return {
+    events,
+    status,
+    isRunning: status === "running",
+    error,
+    output,
+    instanceId,
+    run,
+    resume,
+    reset
+  };
+}
+
+// src/integrations/react/index.ts
+function createRaisinReact(react) {
+  const RaisinContext = react.createContext(null);
+  function RaisinProvider(props) {
+    const { client, repository, children } = props;
+    const value = react.useMemo(
+      () => ({ client, repository }),
+      [client, repository]
+    );
+    return react.createElement(
+      RaisinContext.Provider,
+      { value },
+      children
+    );
+  }
+  function useRaisinClient() {
+    const ctx = react.useContext(RaisinContext);
+    if (!ctx) {
+      throw new Error("useRaisinClient must be used within a <RaisinProvider>");
+    }
+    return ctx.client;
+  }
+  function useDatabase(repository) {
+    const ctx = react.useContext(RaisinContext);
+    if (!ctx) {
+      throw new Error("useDatabase must be used within a <RaisinProvider>");
+    }
+    const repo = repository ?? ctx.repository;
+    if (!repo) {
+      throw new Error("useDatabase requires a repository \u2014 pass it as an argument or set it on <RaisinProvider>");
+    }
+    return react.useMemo(() => ctx.client.database(repo), [ctx.client, repo]);
+  }
+  const useAuth = createUseAuth(react, RaisinContext);
+  const useConnection = createUseConnection(react, RaisinContext);
+  const useSql = createUseSql(react, RaisinContext);
+  const useSubscription = createUseSubscription(react, RaisinContext);
+  function useConversation2(options) {
+    return useConversation(react, options);
+  }
+  function useConversationList2(options) {
+    return useConversationList(react, options);
+  }
+  function useFlow2(options) {
+    return useFlow(react, options);
+  }
+  return {
+    RaisinProvider,
+    useRaisinClient,
+    useDatabase,
+    useAuth,
+    useConnection,
+    useSql,
+    useSubscription,
+    useConversation: useConversation2,
+    useConversationList: useConversationList2,
+    useFlow: useFlow2
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createRaisinReact
+});
+//# sourceMappingURL=react.js.map