lemma-sdk 0.2.9 → 0.2.11

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
@@ -111,6 +169,60 @@ Notes:
 
 ## Assistants + Agent Runs
 
+### React assistant controller + primitives
+
+`lemma-sdk/react` now exposes the assistant controller plus the reusable UI primitives used by the app shell. A simple integration looks like this:
+
+```tsx
+import {
+  MessageGroup,
+  PlanSummaryStrip,
+  ThinkingIndicator,
+  buildDisplayMessageRows,
+  getActiveToolBanner,
+  latestPlanSummary,
+  useAssistantController,
+} from "lemma-sdk/react";
+
+function AssistantSurface() {
+  const assistant = useAssistantController({
+    client,
+    assistantId: "support_assistant",
+    podId: "pod_123",
+  });
+
+  const rows = buildDisplayMessageRows(assistant.messages);
+  const plan = latestPlanSummary(assistant.messages);
+  const activeToolBanner = getActiveToolBanner(assistant.messages);
+
+  return (
+    <div>
+      {plan ? <PlanSummaryStrip plan={plan} onHide={() => {}} /> : null}
+      {activeToolBanner ? <div>{activeToolBanner.summary}</div> : null}
+
+      {rows.map((row, index) => (
+        <MessageGroup
+          key={row.id}
+          message={row.message}
+          conversationId={assistant.activeConversationId}
+          onWidgetSendPrompt={(text) => assistant.sendMessage(text)}
+          isStreaming={assistant.isActiveConversationRunning && row.sourceIndexes.includes(assistant.messages.length - 1)}
+          showAssistantHeader={index === 0 || rows[index - 1]?.message.role !== "assistant"}
+          renderMessageContent={({ message }) => <div>{message.content}</div>}
+        />
+      ))}
+
+      {assistant.isActiveConversationRunning ? <ThinkingIndicator /> : null}
+    </div>
+  );
+}
+```
+
+The intended split is:
+
+- SDK: `useAssistantController`, message/tool normalization, plan parsing, tool rollups, and assistant UI primitives.
+- App: modal shell, fullscreen behavior, route navigation, workspace/file viewers, and product-specific renderers.
+
 ### Assistant names (resource key)
 
 Assistant CRUD is name-based:

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/components/AssistantExperience.d.ts

@@ -0,0 +1,79 @@
+import { type ReactNode } from "react";
+import type { AssistantRenderableMessage, AssistantToolInvocation } from "../useAssistantController.js";
+import type { AssistantControllerView, AssistantConversationRenderArgs, AssistantMessageRenderArgs, AssistantPendingFileRenderArgs, AssistantPresentedFileRenderArgs, AssistantToolRenderArgs } from "./assistant-types.js";
+type PlanStatus = "pending" | "in_progress" | "completed";
+export interface PlanStepState {
+    step: string;
+    status: PlanStatus;
+}
+export interface PlanSummaryState {
+    steps: PlanStepState[];
+    completedCount: number;
+    inProgressCount: number;
+    running: boolean;
+    activeStep?: string;
+}
+type AskQuestionType = "single_select" | "multi_select" | "rank_priorities";
+export interface AskUserInputQuestion {
+    question: string;
+    options: string[];
+    type: AskQuestionType;
+}
+export interface PendingAskUserInput {
+    toolCallId: string;
+    messageIndex: number;
+    questions: AskUserInputQuestion[];
+}
+export interface DisplayMessageRow {
+    id: string;
+    message: AssistantRenderableMessage;
+    sourceIndexes: number[];
+}
+export interface ActiveToolBanner {
+    summary: string;
+    activeCount: number;
+}
+export interface AssistantExperienceViewProps {
+    controller: AssistantControllerView;
+    title?: ReactNode;
+    subtitle?: ReactNode;
+    placeholder?: string;
+    emptyState?: ReactNode;
+    draft?: string;
+    onDraftChange?: (value: string) => void;
+    showConversationList?: boolean;
+    onNavigateResource?: (resourceType: string, resourceId: string, meta?: Record<string, unknown>) => void;
+    renderConversationLabel?: (args: AssistantConversationRenderArgs) => ReactNode;
+    renderMessageContent?: (args: AssistantMessageRenderArgs) => ReactNode;
+    renderPresentedFile?: (args: AssistantPresentedFileRenderArgs) => ReactNode;
+    renderPendingFile?: (args: AssistantPendingFileRenderArgs) => ReactNode;
+    renderToolInvocation?: (args: AssistantToolRenderArgs) => ReactNode;
+}
+export declare function dedupToolInvocations(message: AssistantRenderableMessage): AssistantToolInvocation[];
+export declare function latestPlanSummary(messages: AssistantRenderableMessage[]): PlanSummaryState | null;
+export declare function findPendingAskUserInput(messages: AssistantRenderableMessage[]): PendingAskUserInput | null;
+export declare function formatAskUserInputAnswers(questions: AskUserInputQuestion[], answers: string[][]): string;
+export declare function extractPresentFilePathsFromInvocation(invocation: AssistantToolInvocation): string[];
+export declare function buildDisplayMessageRows(messages: AssistantRenderableMessage[]): DisplayMessageRow[];
+export declare function getActiveToolBanner(messages: AssistantRenderableMessage[]): ActiveToolBanner | null;
+export declare function PlanSummaryStrip({ plan, onHide }: {
+    plan: PlanSummaryState;
+    onHide: () => void;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function ThinkingIndicator(): import("react/jsx-runtime").JSX.Element | null;
+export declare function EmptyState({ onSendMessage }: {
+    onSendMessage: (msg: string) => void;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function MessageGroup({ message, conversationId, onNavigateResource, onWidgetSendPrompt, isStreaming, showAssistantHeader, renderMessageContent, renderPresentedFile, renderToolInvocation, }: {
+    message: AssistantRenderableMessage;
+    conversationId?: string | null;
+    onNavigateResource?: (resourceType: string, resourceId: string, meta?: Record<string, unknown>) => void;
+    onWidgetSendPrompt: (text: string) => void | Promise<void>;
+    isStreaming: boolean;
+    showAssistantHeader: boolean;
+    renderMessageContent: (args: AssistantMessageRenderArgs) => ReactNode;
+    renderPresentedFile?: (args: AssistantPresentedFileRenderArgs) => ReactNode;
+    renderToolInvocation?: (args: AssistantToolRenderArgs) => ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function AssistantExperienceView({ controller, title, subtitle, placeholder, emptyState, draft: controlledDraft, onDraftChange, showConversationList, onNavigateResource, renderConversationLabel, renderMessageContent, renderPresentedFile, renderPendingFile, renderToolInvocation, }: AssistantExperienceViewProps): import("react/jsx-runtime").JSX.Element;
+export {};