lemma-sdk 0.2.36 → 0.2.38

package/README.md

@@ -2,7 +2,7 @@
 
 `lemma-sdk` is the headless TypeScript SDK for Lemma. Use `lemma-sdk` for the core client and shared helpers, and use `lemma-sdk/react` as the main app-building surface for hooks and auth primitives.
 
-`AuthGuard` intentionally stays in `lemma-sdk/react`. The product direction remains hooks-first and shell-agnostic, and the registry ships stock Lemma UI blocks when you want installable assistant, records, file, workflow, collaboration, or shell surfaces.
+`AuthGuard` intentionally stays in `lemma-sdk/react`. The product direction remains hooks-first and shell-agnostic, and the registry ships stock Lemma UI blocks when you want installable agent conversation, records, file, workflow, collaboration, or shell surfaces.
 
 ## Install
 
@@ -43,7 +43,7 @@ const tables = await client.tables.list();
 const records = await client.records.list("tickets");
 ```
 
-Pod-scoped namespaces include `tables`, `records`, `assistants`, `agents`, `tasks`, `workflows`, `functions`, `files`, `desks`, `integrations`, `resources`, and `datastore`.
+Pod-scoped namespaces include `tables`, `records`, `agents`, `conversations`, `workflows`, `functions`, `files`, `desks`, `integrations`, `resources`, and `datastore`. New runtime code should use agents plus conversations.
 
 Org and user surfaces include `users`, `organizations`, `pods`, `podMembers`, `podJoinRequests`, and `podSurfaces`.
 
@@ -60,7 +60,6 @@ npm install react react-dom
 ```tsx
 import {
   AuthGuard,
-  useAgentRun,
   useConversationMessages,
   useConversations,
   useRecordForm,
@@ -77,9 +76,9 @@ import {
 | Tables | `useTables`, `useTable`, `useRecords`, `useRecord`, `useJoinedRecords`, `useRelatedRecords`, `useReverseRelatedRecords`, `useReferencingRecords`, `useDatastoreQuery`, `useRecordAggregates` | Stable | Build custom table browsers, details views, related-record views, raw SQL-backed reads, and chart/KPI queries. |
 | Record mutations | `useCreateRecord`, `useUpdateRecord`, `useDeleteRecord`, `useBulkRecords` | Stable | Create, update, delete, or bulk-delete rows from headless UI. Function-backed mutations via `createVia`/`updateVia` options. |
 | Record forms | `useRecordSchema`, `useRecordForm`, `useForeignKeyOptions`, `useSchemaForm` | Stable | Render schema-driven record forms, enum fields, and foreign-key selectors. `useRecordForm` is the canonical table-bound form hook; `useSchemaForm` remains available for raw JSON-schema flows. |
-| Files | `useFiles`, `useFile`, `useUploadFile`, `useUpdateFile`, `useDeleteFile`, `useCreateFolder`, `useFileSearch`, `useFileTree`, `useFilePreview`, `useGlobalSearch` | Stable | Browse datastore folders, mutate file state, search indexed files, load directory trees, preview content, and compose multi-source desk search. |
-| Assistant | `useConversations`, `useConversation`, `useConversationMessages`, `useAssistantRun`, `useAssistantSession`, `useAssistantRuntime`, `useAssistantController` | Stable except controller/runtime | Build custom chat, conversation lists, streaming output, and final-output views. |
-| Agents | `useAgentRun`, `useAgentRuns`, `useAgentInputSchema`, `useTaskSession` | Stable except raw session | Start agent tasks, submit follow-up input, read task history, and inspect input/output schemas. |
+| Files | `useFiles`, `useFile`, `useUploadFile`, `useUpdateFile`, `useDeleteFile`, `useCreateFolder`, `useFileSearch`, `useFileTree`, `useFilePreview`, `useGlobalSearch` | Stable | Browse private or pod folders, mutate file state, search indexed files, load directory trees, preview content, and compose multi-source desk search. |
+| Conversations | `useConversations`, `useConversation`, `useConversationMessages`, `useAssistantSession`, `useAssistantRuntime`, `useAssistantController` | Stable except controller/runtime | Build custom chat, conversation lists, streaming output, and final-answer views for default assistant conversations or named agents. |
+| Agents | `useAgentInputSchema` | Stable | Inspect structured input/output schemas for named agents. Agent execution goes through conversations. |
 | Workflows | `useWorkflowStart`, `useWorkflowRun`, `useWorkflowRuns`, `useWorkflowResume` | Stable | Start, poll, resume, cancel, retry, and inspect workflow runs. |
 | Workflow compatibility | `useFlowSession`, `useFlowRunHistory` | Deprecated naming | Kept for existing callers; prefer workflow-named hooks for new code. |
 | Functions | `useFunctionRun`, `useFunctionRuns`, `useFunctionSession` | Stable except raw session | Run functions, poll function runs, and list function history. |
@@ -107,7 +106,7 @@ List hooks generally expose:
 
 Run hooks generally expose:
 
-- `run` or `task`
+- `run`
 - `status`
 - `isPolling`, `isStreaming`, or `isRunning`
 - `output`
@@ -147,7 +146,7 @@ function TicketList() {
 }
 ```
 
-Assistant final output:
+Agent conversation final output:
 
 ```tsx
 import { useConversationMessages, useConversations } from "lemma-sdk/react";
@@ -155,7 +154,7 @@ import { useConversationMessages, useConversations } from "lemma-sdk/react";
 function SupportThread({ client }: { client: LemmaClient }) {
   const conversations = useConversations({
     client,
-    assistantName: "support_assistant",
+    agentName: "support_agent",
   });
 
   const messages = useConversationMessages({
@@ -168,25 +167,35 @@ function SupportThread({ client }: { client: LemmaClient }) {
 }
 ```
 
-Agent run:
+Start an agent conversation:
 
 ```tsx
-import { useAgentRun } from "lemma-sdk/react";
+import { useConversationMessages } from "lemma-sdk/react";
 
 function AgentButton({ client }: { client: LemmaClient }) {
-  const agent = useAgentRun({
+  const conversation = useConversationMessages({
     client,
     agentName: "triage_agent",
+    autoResume: true,
   });
 
   return (
     <button
-      disabled={agent.isStreaming}
+      disabled={conversation.isStreaming}
       onClick={() => {
-        void agent.start({ ticket_id: "ticket_123" });
+        void (async () => {
+          const thread = await conversation.createConversation({
+            title: "Triage ticket ticket_123",
+            setActive: true,
+          });
+          await conversation.sendMessage(JSON.stringify({
+            ticket_id: "ticket_123",
+            prompt: "Triage this ticket.",
+          }), { conversationId: thread.id });
+        })();
       }}
     >
-      {agent.status ?? "Run agent"}
+      {conversation.status ?? "Message agent"}
     </button>
   );
 }
@@ -233,14 +242,14 @@ npx shadcn@latest add @lemma/lemma-comments
 npx shadcn@latest add @lemma/lemma-assistant-experience
 ```
 
-The registry currently ships 19 canonical blocks:
+The registry currently ships 19 canonical blocks plus the shared `lemma-ui` primitive bundle:
 
 | Area | Items |
 | --- | --- |
 | Core operator blocks | `lemma-records-view`, `lemma-detail-panel`, `lemma-record-form`, `lemma-status-flow` |
 | Search, files, and pages | `lemma-global-search`, `lemma-breadcrumbs`, `lemma-file-browser`, `lemma-markdown-editor`, `lemma-page-tree`, `lemma-document-workspace` |
 | Collaboration and analytics | `lemma-comments`, `lemma-activity-feed`, `lemma-insights`, `lemma-action-surface`, `lemma-workflow-runner` |
-| Assistant and shell | `lemma-assistant-experience`, `lemma-members`, `lemma-notification-bell`, `lemma-user-menu` |
+| Agent and shell | `lemma-assistant-experience`, `lemma-members`, `lemma-notification-bell`, `lemma-user-menu` |
 
 Registry blocks now install against a shared `lemma-ui` primitive layer that ships with this registry. Consumers no longer need a pre-existing app-local `@/components/ui/*` shadcn tree just to use Lemma blocks.
 
@@ -267,7 +276,7 @@ Core registry blocks:
 - `lemma-file-browser` and `lemma-document-workspace` for file browsing, editing, preview, and document-native workflows
 - `lemma-comments`, `lemma-activity-feed`, and `lemma-insights` for collaboration and reporting
 - `lemma-action-surface` and `lemma-workflow-runner` for long-running actions and workflow history
-- `lemma-assistant-experience`, `lemma-members`, `lemma-notification-bell`, and `lemma-user-menu` for assistant and shell surfaces
+- `lemma-assistant-experience`, `lemma-members`, `lemma-notification-bell`, and `lemma-user-menu` for agent conversation and shell surfaces
 
 ### Block Defaults
 
@@ -302,11 +311,11 @@ For records workspaces, the split is:
 - optional file search with `searchMethod`, `href`, `onSelect`, and `openMode`
 - progressive table/file result groups, smooth loading/error source states, hidden empty sources, keyboard navigation, and built-in `cmd/ctrl+k` handling
 - `minQueryLength`, `debounceMs`, `appearance`, `density`, trigger label, and placeholder customization
-- assistant handoff by `assistantName`, with optional query/results message shaping and conversation routing
+- agent handoff by `agentName`, with optional query/results message shaping and conversation routing
 
 Document blocks support:
 
-- Notion/Coda-style block documents through `lemma-document-workspace`, with ProseKit JSON content, page/modal modes, title and summary chrome, file/reference/assistant blocks, save state, metadata, backlinks, and assistant-context rails
+- Notion/Coda-style block documents through `lemma-document-workspace`, with ProseKit JSON content, page/modal modes, title and summary chrome, file/reference/agent blocks, save state, metadata, backlinks, and agent-context rails
 - pod-file-native creation, reading, editing, and preview through one workspace, with folder targeting, title/summary setup, pod-file metadata, and `mode="page" | "modal"`
 - non-document file previews through the same workspace, including image, PDF, text, markdown, converted HTML, and download fallback behavior
 - records and attachments should pass pod file paths into `lemma-document-workspace`; records should not own document bodies directly
@@ -329,7 +338,7 @@ Navigation and file blocks support:
 
 - route, record, and file-path breadcrumb builders through `lemma-breadcrumbs`
 - native pod-file hierarchy navigation through `lemma-page-tree`
-- datastore folder navigation, upload, rename, move, folder creation, picker mode, and delete handling through `lemma-file-browser`
+- private/pod datastore navigation, upload, rename, move, folder creation, picker mode, publish-to-pod, and delete handling through `lemma-file-browser`
 - write, preview, and split modes through `lemma-markdown-editor`
 
 Collaboration and analytics blocks support:
@@ -338,12 +347,12 @@ Collaboration and analytics blocks support:
 - unified audit and history timelines through `lemma-activity-feed`
 - dashboard-style stat cards and charts through `lemma-insights`
 
-Assistant blocks support:
+Agent conversation blocks support:
 
-- assistant-name-first configuration through `assistantName`
-- shared `appearance` and `density` controls on the assistant experience surface
+- agent-name-first configuration through `agentName` today; omit it to target the default pod agent conversation
+- shared `appearance` and `density` controls on the conversation experience surface
 - `chromeStyle`, `statusPlacement`, `radius`, model picker, conversation list, and render overrides for deeper customization
-- bounded default heights for `page` and `side-panel` modes so the message viewport scrolls instead of stretching with content; pass `className="h-full min-h-0"` inside an explicit-height parent when you want a fill-layout assistant like inbox CRM
+- bounded default heights for `page` and `side-panel` modes so the message viewport scrolls instead of stretching with content; pass `className="h-full min-h-0"` inside an explicit-height parent when you want a fill-layout agent conversation like inbox CRM
 
 ```tsx
 import { LemmaRecordsView } from "@/components/lemma/lemma-records-view";
@@ -393,8 +402,8 @@ import { LemmaGlobalSearch } from "@/components/lemma/lemma-global-search";
     },
   ]}
   files={{ enabled: true, openMode: "new-tab" }}
-  assistant={{
-    assistantName: "sales-copilot",
+  agent={{
+    agentName: "sales-copilot",
     label: "Ask CRM",
     resultLimit: 8,
   }}
@@ -412,7 +421,7 @@ import { LemmaGlobalSearch } from "@/components/lemma/lemma-global-search";
 
 <LemmaAssistantExperience
   client={client}
-  assistantName="sales-copilot"
+  agentName="sales-copilot"
 />;
 ```
 
@@ -439,10 +448,16 @@ From `0.2.30` onward:
 - `lemma-sdk/react` should be treated as hooks plus auth primitives.
 - `AuthGuard` remains in `lemma-sdk/react`.
 - Stock UI should be installed from the shadcn registry.
-- Assistant UI source and CSS are no longer part of the React SDK internals.
-- `react-markdown` and `remark-gfm` are registry-block dependencies for assistant UI, not core SDK dependencies.
+- Conversation UI source and CSS are no longer part of the React SDK internals.
+- `react-markdown` and `remark-gfm` are registry-block dependencies for conversation UI, not core SDK dependencies.
 - New workflow code should prefer `useWorkflowRun`, `useWorkflowRuns`, and `useWorkflowResume` over the older `flow`-named hooks.
 
+From `0.2.37` onward:
+
+- Agent APIs are the runtime abstraction. `client.assistants` is removed; use `client.agents` for definitions and `client.conversations` for turns/messages.
+- Conversations are pod-scoped under the agent conversation API; message sends stream conversation events until final output.
+- File APIs are namespace-aware. Shared pod files are the default for backwards-compatible file workspaces; pass `namespace: "PRIVATE"` for personal file input/upload flows and `namespace: "POD"` when you want to be explicit. The live OpenAPI currently names the private namespace `PERSONAL`; the SDK accepts `PRIVATE` as the product-facing alias.
+
 ## Local Development
 
 From the root of this repository: