lemma-sdk 0.2.8 → 0.2.10

package/README.md

@@ -47,6 +47,64 @@ const supportAssistant = await client.assistants.get("support_assistant");
 - Ergonomic type aliases exported at top level: `Agent`, `Assistant`, `Conversation`, `Task`, `TaskMessage`, `CreateAgentInput`, `CreateAssistantInput`, etc.
 - `client.withPod(podId)` returns a pod-scoped client that shares auth state with the parent client.
 
+## Table Access Grants (`accessible_tables`)
+
+For function, agent, and assistant payloads, `accessible_tables` must be an array of objects:
+
+- `table_name`: target table
+- `mode`: `READ` or `WRITE`
+
+`accessible_tables: ["table_name"]` is no longer valid.
+
+You do not pass a datastore name in SDK calls. Table and file operations are pod-scoped (`client.tables`, `client.records`, `client.files`) and take table/file identifiers directly.
+
+Examples:
+
+```ts
+import {
+  TableAccessMode,
+  type CreateFunctionRequest,
+  type CreateAgentInput,
+  type CreateAssistantInput,
+} from "lemma-sdk";
+
+const functionPayload: CreateFunctionRequest = {
+  name: "expense_summary",
+  code: "def handler(ctx):\n    return {'ok': True}",
+  config: {},
+  accessible_tables: [
+    { table_name: "expenses", mode: TableAccessMode.READ },
+    { table_name: "expense_summaries", mode: TableAccessMode.WRITE },
+  ],
+  accessible_folders: ["/reports"],
+  accessible_applications: [],
+};
+
+const agentPayload: CreateAgentInput = {
+  name: "expense-summarizer",
+  instruction: "Summarize expenses without mutating data.",
+  tool_sets: [],
+  accessible_tables: [
+    { table_name: "expenses", mode: TableAccessMode.READ },
+    { table_name: "expense_notes", mode: TableAccessMode.WRITE },
+  ],
+  accessible_folders: [],
+  accessible_applications: [],
+};
+
+const assistantPayload: CreateAssistantInput = {
+  name: "expense_assistant",
+  instruction: "Answer expense questions and save approved notes.",
+  tool_sets: [],
+  accessible_tables: [
+    { table_name: "expenses", mode: TableAccessMode.READ },
+    { table_name: "expense_notes", mode: TableAccessMode.WRITE },
+  ],
+  accessible_folders: ["/notes"],
+  accessible_applications: [],
+};
+```
+
 ## Auth Helpers
 
 ```ts

package/dist/assistant-events.d.ts

@@ -2,6 +2,7 @@ import type { ConversationMessage } from "./types.js";
 export interface ParsedAssistantStreamEvent {
     message?: ConversationMessage;
     status?: string;
+    token?: string;
 }
 export declare function parseAssistantStreamEvent(value: unknown): ParsedAssistantStreamEvent;
 export declare function upsertConversationMessage(messages: ConversationMessage[], incoming: ConversationMessage): ConversationMessage[];

package/dist/assistant-events.js

@@ -51,6 +51,9 @@ export function parseAssistantStreamEvent(value) {
     }
     const eventType = typeof value.type === "string" ? value.type.toLowerCase() : "";
     const payload = extractPayload(value);
+    if (eventType === "token" && typeof payload === "string") {
+        return { token: payload };
+    }
     if (eventType === "message" || eventType === "message_added") {
         const message = toConversationMessage(payload);
         return message ? { message } : {};

package/dist/react/useAssistantSession.d.ts

@@ -13,6 +13,8 @@ export interface UseAssistantSessionOptions {
     organizationId?: string;
     conversationId?: string | null;
     autoLoad?: boolean;
+    autoResume?: boolean;
+    syncOnTurnEnd?: boolean;
     onEvent?: (event: SseRawEvent, payload: unknown | null) => void;
     onStatus?: (status: string) => void;
     onMessage?: (message: ConversationMessage) => void;
@@ -30,12 +32,22 @@ export interface SendAssistantMessageOptions {
     conversationId?: string | null;
     createIfMissing?: boolean;
     createConversation?: CreateConversationInput;
+    syncOnTurnEnd?: boolean;
+}
+export interface ResumeAssistantOptions {
+    conversationId?: string | null;
+    /**
+     * When true, skips resume unless conversation status is currently RUNNING.
+     */
+    onlyIfRunning?: boolean;
+    syncOnTurnEnd?: boolean;
 }
 export interface UseAssistantSessionResult {
     conversationId: string | null;
     conversation: Conversation | null;
     status?: string;
     messages: ConversationMessage[];
+    streamingText: string;
     isStreaming: boolean;
     error: Error | null;
     setConversationId: (conversationId: string | null) => void;
@@ -52,7 +64,8 @@ export interface UseAssistantSessionResult {
         pageToken?: string;
     }) => Promise<CursorPage<ConversationMessage>>;
     sendMessage: (content: string, options?: SendAssistantMessageOptions) => Promise<Conversation>;
-    resume: (conversationId?: string | null) => Promise<void>;
+    resume: (conversationId?: string | null | ResumeAssistantOptions) => Promise<void>;
+    resumeIfRunning: (conversationId?: string | null) => Promise<boolean>;
     stop: (conversationId?: string | null) => Promise<void>;
     cancel: () => void;
     clearMessages: () => void;

package/dist/react/useAssistantSession.js

@@ -29,26 +29,89 @@ function normalizeScope(client, defaults, override) {
         organizationId: override?.organizationId ?? defaults.organizationId ?? null,
     };
 }
+function normalizeConversationStatus(status) {
+    if (typeof status !== "string")
+        return undefined;
+    const normalized = status.trim().toUpperCase();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function isConversationRunningStatus(status) {
+    const normalized = normalizeConversationStatus(status);
+    if (!normalized)
+        return false;
+    return normalized === "RUNNING" || normalized === "IN_PROGRESS" || normalized === "PROCESSING";
+}
+function resolveResumeInput(input) {
+    if (typeof input === "string" || input === null) {
+        return { conversationId: input };
+    }
+    return input ?? {};
+}
 export function useAssistantSession(options) {
-    const { client, podId: defaultPodId, assistantId: defaultAssistantId, organizationId: defaultOrganizationId, conversationId: externalConversationId = null, autoLoad = true, onEvent, onStatus, onMessage, onError, } = options;
+    const { client, podId: defaultPodId, assistantId: defaultAssistantId, organizationId: defaultOrganizationId, conversationId: externalConversationId = null, autoLoad = true, autoResume = false, syncOnTurnEnd = false, onEvent, onStatus, onMessage, onError, } = options;
     const [conversationId, setConversationIdState] = useState(externalConversationId);
     const [conversation, setConversation] = useState(null);
     const [status, setStatus] = useState(undefined);
     const [messages, setMessages] = useState([]);
+    const [streamingText, setStreamingText] = useState("");
     const [isStreaming, setIsStreaming] = useState(false);
     const [error, setError] = useState(null);
     const abortRef = useRef(null);
+    const statusRef = useRef(undefined);
+    const streamingTextRef = useRef("");
+    const autoResumedKeyRef = useRef(null);
+    const onEventRef = useRef(onEvent);
+    const onStatusRef = useRef(onStatus);
+    const onMessageRef = useRef(onMessage);
+    const onErrorRef = useRef(onError);
     const setConversationId = useCallback((nextConversationId) => {
         setConversationIdState(nextConversationId);
+        autoResumedKeyRef.current = null;
+        streamingTextRef.current = "";
+        setStreamingText("");
         if (!nextConversationId) {
             setConversation(null);
             setStatus(undefined);
+            statusRef.current = undefined;
             setMessages([]);
         }
     }, []);
     useEffect(() => {
         setConversationIdState(externalConversationId);
     }, [externalConversationId]);
+    useEffect(() => {
+        onEventRef.current = onEvent;
+    }, [onEvent]);
+    useEffect(() => {
+        onStatusRef.current = onStatus;
+    }, [onStatus]);
+    useEffect(() => {
+        onMessageRef.current = onMessage;
+    }, [onMessage]);
+    useEffect(() => {
+        onErrorRef.current = onError;
+    }, [onError]);
+    useEffect(() => {
+        statusRef.current = status;
+    }, [status]);
+    const setConversationStatus = useCallback((nextStatus) => {
+        const normalized = normalizeConversationStatus(nextStatus);
+        setStatus(normalized);
+        statusRef.current = normalized;
+        if (normalized) {
+            onStatusRef.current?.(normalized);
+        }
+    }, []);
+    const clearStreamingText = useCallback(() => {
+        streamingTextRef.current = "";
+        setStreamingText("");
+    }, []);
+    const appendStreamingToken = useCallback((token) => {
+        if (!token)
+            return;
+        streamingTextRef.current += token;
+        setStreamingText(streamingTextRef.current);
+    }, []);
     const cancel = useCallback(() => {
         abortRef.current?.abort();
         abortRef.current = null;
@@ -78,14 +141,14 @@ export function useAssistantSession(options) {
         catch (listError) {
             const normalized = normalizeError(listError, "Failed to list conversations.");
             setError(normalized);
-            onError?.(listError);
+            onErrorRef.current?.(listError);
             return {
                 items: [],
                 limit: input.limit ?? 20,
                 next_page_token: null,
             };
         }
-    }, [client, defaultScope, onError]);
+    }, [client, defaultScope]);
     const createConversation = useCallback(async (input = {}) => {
         applyPodScope(client, input.podId ?? defaultPodId ?? null);
         const payload = {
@@ -101,11 +164,13 @@ export function useAssistantSession(options) {
         if (input.setActive !== false) {
             setConversationIdState(created.id);
             setConversation(created);
-            setStatus(typeof created.status === "string" ? created.status.toUpperCase() : undefined);
+            setConversationStatus(created.status);
             setMessages([]);
+            clearStreamingText();
+            autoResumedKeyRef.current = null;
         }
         return created;
-    }, [client, defaultAssistantId, defaultOrganizationId, defaultPodId]);
+    }, [clearStreamingText, client, defaultAssistantId, defaultOrganizationId, defaultPodId, setConversationStatus]);
     const refreshConversation = useCallback(async (explicitConversationId) => {
         const id = explicitConversationId ?? conversationId;
         if (!id)
@@ -118,36 +183,30 @@ export function useAssistantSession(options) {
             });
             setConversation(nextConversation);
             const nextStatus = typeof nextConversation.status === "string"
-                ? nextConversation.status.toUpperCase()
+                ? nextConversation.status
                 : undefined;
-            setStatus(nextStatus);
-            if (nextStatus) {
-                onStatus?.(nextStatus);
-            }
+            setConversationStatus(nextStatus);
             return nextConversation;
         }
         catch (refreshError) {
             const normalized = normalizeError(refreshError, "Failed to fetch conversation.");
             setError(normalized);
-            onError?.(refreshError);
+            onErrorRef.current?.(refreshError);
             return null;
         }
-    }, [client, conversationId, defaultScope, onError, onStatus]);
+    }, [client, conversationId, defaultScope, setConversationStatus]);
     const loadMessages = useCallback(async (input = {}) => {
         const id = input.conversationId ?? conversationId;
         if (!id) {
             return { items: [], limit: input.limit ?? 20, next_page_token: null };
         }
         try {
-            const scope = normalizeScope(client, defaultScope);
-            applyPodScope(client, scope.podId);
             const response = await client.conversations.messages.list(id, {
-                pod_id: scope.podId ?? undefined,
                 limit: input.limit,
                 page_token: input.pageToken,
             });
             const nextMessages = response.items ?? [];
-            setMessages(nextMessages);
+            setMessages((previous) => nextMessages.reduce((accumulator, message) => upsertConversationMessage(accumulator, message), previous));
             return {
                 items: nextMessages,
                 limit: response.limit ?? input.limit ?? 20,
@@ -157,32 +216,58 @@ export function useAssistantSession(options) {
         catch (messageError) {
             const normalized = normalizeError(messageError, "Failed to fetch conversation messages.");
             setError(normalized);
-            onError?.(messageError);
+            onErrorRef.current?.(messageError);
             return {
                 items: [],
                 limit: input.limit ?? 20,
                 next_page_token: null,
             };
         }
-    }, [client, conversationId, defaultScope, onError]);
-    const consume = useCallback(async (stream, controller) => {
+    }, [clearStreamingText, client, conversationId, defaultScope, setConversationStatus]);
+    const consume = useCallback(async ({ stream, controller, streamConversationId, syncAfterStream, }) => {
         setIsStreaming(true);
         setError(null);
+        clearStreamingText();
+        let sawTerminalStatus = false;
         try {
             for await (const event of readSSE(stream)) {
                 if (controller.signal.aborted) {
                     break;
                 }
                 const payload = parseSSEJson(event);
-                onEvent?.(event, payload);
+                onEventRef.current?.(event, payload);
                 const parsed = parseAssistantStreamEvent(payload);
+                if (parsed.token) {
+                    appendStreamingToken(parsed.token);
+                }
                 if (parsed.message) {
                     setMessages((previous) => upsertConversationMessage(previous, parsed.message));
-                    onMessage?.(parsed.message);
+                    onMessageRef.current?.(parsed.message);
+                    const role = typeof parsed.message.role === "string"
+                        ? parsed.message.role.toLowerCase()
+                        : "";
+                    if (role === "assistant" || role === "tool") {
+                        clearStreamingText();
+                    }
                 }
                 if (parsed.status) {
-                    setStatus(parsed.status);
-                    onStatus?.(parsed.status);
+                    setConversationStatus(parsed.status);
+                    if (!isConversationRunningStatus(parsed.status)) {
+                        sawTerminalStatus = true;
+                        clearStreamingText();
+                    }
+                }
+            }
+            if (!controller.signal.aborted) {
+                if (!sawTerminalStatus && isConversationRunningStatus(statusRef.current)) {
+                    setConversationStatus("WAITING");
+                }
+                clearStreamingText();
+                const shouldSync = syncAfterStream ?? syncOnTurnEnd;
+                const syncConversationId = streamConversationId ?? conversationId;
+                if (shouldSync && syncConversationId) {
+                    await refreshConversation(syncConversationId);
+                    await loadMessages({ conversationId: syncConversationId, limit: 100 });
                 }
             }
         }
@@ -190,7 +275,7 @@ export function useAssistantSession(options) {
             if (!(streamError instanceof Error && streamError.name === "AbortError")) {
                 const normalized = normalizeError(streamError, "Failed to stream assistant run.");
                 setError(normalized);
-                onError?.(streamError);
+                onErrorRef.current?.(streamError);
             }
         }
         finally {
@@ -199,10 +284,22 @@ export function useAssistantSession(options) {
             }
             setIsStreaming(false);
         }
-    }, [onError, onEvent, onMessage, onStatus]);
+    }, [
+        appendStreamingToken,
+        clearStreamingText,
+        conversationId,
+        loadMessages,
+        refreshConversation,
+        setConversationStatus,
+        syncOnTurnEnd,
+    ]);
     const ensureConversation = useCallback(async (overrideConversationId, options) => {
         const existingId = overrideConversationId ?? conversationId;
         if (existingId) {
+            // Avoid a network roundtrip on every send when we already have this conversation in state.
+            if (conversation?.id === existingId) {
+                return conversation;
+            }
             const existing = await refreshConversation(existingId);
             if (existing)
                 return existing;
@@ -215,7 +312,7 @@ export function useAssistantSession(options) {
             ...(options.createConversation ?? {}),
             setActive: true,
         });
-    }, [conversationId, createConversation, refreshConversation]);
+    }, [conversation, conversationId, createConversation, refreshConversation]);
     const sendMessage = useCallback(async (content, input = {}) => {
         const resolvedConversation = await ensureConversation(input.conversationId, input);
         const resolvedConversationId = requireConversationId(resolvedConversation.id);
@@ -228,11 +325,21 @@ export function useAssistantSession(options) {
             pod_id: scope.podId ?? undefined,
             signal: controller.signal,
         });
-        await consume(stream, controller);
+        setConversationStatus("RUNNING");
+        await consume({
+            stream,
+            controller,
+            streamConversationId: resolvedConversationId,
+            syncAfterStream: input.syncOnTurnEnd,
+        });
         return resolvedConversation;
-    }, [cancel, client, consume, defaultScope, ensureConversation]);
-    const resume = useCallback(async (explicitConversationId) => {
-        const id = requireConversationId(explicitConversationId ?? conversationId);
+    }, [cancel, client, consume, defaultScope, ensureConversation, setConversationStatus]);
+    const resume = useCallback(async (input) => {
+        const resumeInput = resolveResumeInput(input);
+        const id = requireConversationId(resumeInput.conversationId ?? conversationId);
+        if (resumeInput.onlyIfRunning && !isConversationRunningStatus(statusRef.current)) {
+            return;
+        }
         cancel();
         const controller = new AbortController();
         abortRef.current = controller;
@@ -242,8 +349,39 @@ export function useAssistantSession(options) {
             pod_id: scope.podId ?? undefined,
             signal: controller.signal,
         });
-        await consume(stream, controller);
-    }, [cancel, client, consume, conversationId, defaultScope]);
+        setConversationStatus("RUNNING");
+        await consume({
+            stream,
+            controller,
+            streamConversationId: id,
+            syncAfterStream: resumeInput.syncOnTurnEnd,
+        });
+    }, [cancel, client, consume, conversationId, defaultScope, setConversationStatus]);
+    const resumeIfRunning = useCallback(async (explicitConversationId) => {
+        const id = explicitConversationId ?? conversationId;
+        if (!id)
+            return false;
+        if (isStreaming)
+            return false;
+        const statusKey = normalizeConversationStatus(statusRef.current);
+        const resumeKey = `${id}:${statusKey ?? "UNKNOWN"}`;
+        if (autoResumedKeyRef.current === resumeKey) {
+            return false;
+        }
+        const knownRunning = isConversationRunningStatus(statusRef.current);
+        if (!knownRunning) {
+            const latestConversation = await refreshConversation(id);
+            if (!latestConversation || !isConversationRunningStatus(latestConversation.status)) {
+                return false;
+            }
+        }
+        autoResumedKeyRef.current = resumeKey;
+        await resume({
+            conversationId: id,
+            onlyIfRunning: true,
+        });
+        return true;
+    }, [conversationId, isStreaming, refreshConversation, resume]);
     const stop = useCallback(async (explicitConversationId) => {
         const id = requireConversationId(explicitConversationId ?? conversationId);
         const scope = normalizeScope(client, defaultScope);
@@ -251,22 +389,50 @@ export function useAssistantSession(options) {
         await client.conversations.stopRun(id, {
             pod_id: scope.podId ?? undefined,
         });
+        setConversationStatus("WAITING");
+        clearStreamingText();
     }, [client, conversationId, defaultScope]);
     const clearMessages = useCallback(() => {
         setMessages([]);
     }, []);
+    useEffect(() => {
+        autoResumedKeyRef.current = null;
+    }, [conversationId]);
+    useEffect(() => {
+        if (!isConversationRunningStatus(status)) {
+            autoResumedKeyRef.current = null;
+        }
+    }, [status]);
     useEffect(() => {
         if (!autoLoad || !conversationId) {
             return;
         }
-        void refreshConversation(conversationId);
-        void loadMessages({ conversationId });
-    }, [autoLoad, conversationId, loadMessages, refreshConversation]);
+        let cancelled = false;
+        const bootstrapConversation = async () => {
+            const latestConversation = await refreshConversation(conversationId);
+            if (cancelled)
+                return;
+            await loadMessages({ conversationId, limit: 100 });
+            if (cancelled)
+                return;
+            if (!autoResume)
+                return;
+            const latestStatus = normalizeConversationStatus(latestConversation?.status) ?? normalizeConversationStatus(statusRef.current);
+            if (!isConversationRunningStatus(latestStatus))
+                return;
+            await resumeIfRunning(conversationId);
+        };
+        void bootstrapConversation();
+        return () => {
+            cancelled = true;
+        };
+    }, [autoLoad, autoResume, conversationId, loadMessages, refreshConversation, resumeIfRunning]);
     return {
         conversationId,
         conversation,
         status,
         messages,
+        streamingText,
         isStreaming,
         error,
         setConversationId,
@@ -276,6 +442,7 @@ export function useAssistantSession(options) {
         loadMessages,
         sendMessage,
         resume,
+        resumeIfRunning,
         stop,
         cancel,
         clearMessages,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lemma-sdk",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Official TypeScript SDK for Lemma pod-scoped APIs",
   "type": "module",
   "main": "dist/index.js",