lemma-sdk 0.2.30 → 0.2.32

package/README.md

@@ -1,6 +1,8 @@
 # Lemma TypeScript SDK
 
-`lemma-sdk` is the headless TypeScript SDK for Lemma. Use `lemma-sdk/react` for hooks and auth primitives, and use the Lemma shadcn registry for stock UI blocks.
+`lemma-sdk` is the headless TypeScript SDK for Lemma. Use `lemma-sdk` for the core client, `lemma-sdk/react` for hooks and auth primitives, and the Lemma shadcn registry for stock UI blocks.
+
+`AuthGuard` intentionally stays in `lemma-sdk/react`. Stock assistant, table, workflow, agent, member, and function UI lives in the registry.
 
 ## Install
 
@@ -26,15 +28,34 @@ That adds this namespace to your app's `components.json`:
 
 If your app does not have `components.json` yet, run `npx shadcn@latest init` first or after the command above.
 
-## React Hooks
+## Core Client
+
+```ts
+import { LemmaClient } from "lemma-sdk";
+
+const client = new LemmaClient({
+  podId: "<pod-id>",
+});
+
+await client.initialize();
+
+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`.
+
+Org and user surfaces include `users`, `organizations`, `pods`, `podMembers`, `podJoinRequests`, and `podSurfaces`.
+
+## React Package
 
-Install React if your app needs it:
+Install React if your app needs hooks:
 
 ```bash
 npm install react react-dom
 ```
 
-`lemma-sdk/react` is intentionally headless-first. It includes hooks plus `AuthGuard`, but not stock assistant or records UI.
+`lemma-sdk/react` is headless-first. It exports hooks plus `AuthGuard`; it does not export stock UI components or CSS.
 
 ```tsx
 import {
@@ -42,105 +63,233 @@ import {
   useAgentRun,
   useConversationMessages,
   useConversations,
-  useForeignKeyOptions,
-  useMembers,
-  useRecordForm,
-  useRecordSchema,
   useRecords,
   useSchemaForm,
-  useTables,
   useWorkflowStart,
 } from "lemma-sdk/react";
 ```
 
-Typical hook groups:
+### Hook Matrix
 
-- data tables: `useTables`, `useTable`, `useRecords`, `useRecord`, `useRelatedRecords`, `useReverseRelatedRecords`
-- record mutations and forms: `useCreateRecord`, `useUpdateRecord`, `useDeleteRecord`, `useBulkRecords`, `useRecordSchema`, `useRecordForm`, `useSchemaForm`
-- assistant and runs: `useConversation`, `useConversations`, `useConversationMessages`, `useAssistantController`, `useAssistantRun`, `useAgentRun`, `useWorkflowStart`
-- org and auth: `AuthGuard`, `useMembers`
+| Area | Hooks | Stability | Use when |
+| --- | --- | --- | --- |
+| Auth | `AuthGuard`, `useAuth`, `useCurrentUser`, `usePodAccess` | Stable | Gate an app, read signed-in user state, or request pod access. |
+| Tables | `useTables`, `useTable`, `useRecords`, `useRecord`, `useJoinedRecords`, `useRelatedRecords`, `useReverseRelatedRecords`, `useReferencingRecords` | Stable | Build custom table browsers, details views, related-record views, and relational reads. |
+| 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 forms, enum fields, and foreign-key selectors. `useRecordForm` supports `submitVia: "function"`, `visibleFields`, `hiddenFields`. |
+| 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. |
+| 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. |
+| Members and org | `useMembers`, `useOrganizationMembers` | Stable | Read pod and organization member lists. `useMembers` is intentionally read-only. |
 
-Minimal example:
+### Common Hook Shapes
+
+For business-facing examples and a decision guide mapping "I want to..." to the right hook, see [docs/hooks-guide.md](docs/hooks-guide.md).
+
+List hooks generally expose:
+
+- `items` named for the resource, such as `records`, `runs`, or `members`
+- `isLoading`
+- `error`
+- `nextPageToken`
+- `refresh(...)`
+- `loadMore(...)` where pagination is useful
+
+Run hooks generally expose:
+
+- `run` or `task`
+- `status`
+- `isPolling`, `isStreaming`, or `isRunning`
+- `output`
+- `finalOutput`
+- `start(...)`
+- `refresh(...)`
+- follow-up helpers such as `resume(...)`, `submitInput(...)`, `cancel(...)`, or `retry(...)`
+
+### Headless Examples
+
+Records:
 
 ```tsx
 import { LemmaClient } from "lemma-sdk";
-import { AuthGuard, useConversations, useConversationMessages } from "lemma-sdk/react";
+import { useRecords } from "lemma-sdk/react";
 
 const client = new LemmaClient({ podId: "<pod-id>" });
 
-function SupportThread() {
+function TicketList() {
+  const tickets = useRecords({
+    client,
+    tableName: "tickets",
+    limit: 25,
+    sortBy: "created_at",
+    order: "desc",
+  });
+
+  if (tickets.error) return <p>{tickets.error.message}</p>;
+
+  return (
+    <ul>
+      {tickets.records.map((ticket) => (
+        <li key={String(ticket.id)}>{String(ticket.title ?? ticket.id)}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Assistant final output:
+
+```tsx
+import { useConversationMessages, useConversations } from "lemma-sdk/react";
+
+function SupportThread({ client }: { client: LemmaClient }) {
   const conversations = useConversations({
     client,
-    podId: "<pod-id>",
     assistantName: "support_assistant",
   });
 
-  const thread = useConversationMessages({
+  const messages = useConversationMessages({
     client,
-    podId: "<pod-id>",
     conversationId: conversations.effectiveSelectedConversationId,
+    autoResume: true,
+  });
+
+  return <pre>{messages.finalOutputText || messages.outputText || "No output yet."}</pre>;
+}
+```
+
+Agent run:
+
+```tsx
+import { useAgentRun } from "lemma-sdk/react";
+
+function AgentButton({ client }: { client: LemmaClient }) {
+  const agent = useAgentRun({
+    client,
+    agentName: "triage_agent",
   });
 
-  return <pre>{thread.finalOutputText ?? "No assistant output yet."}</pre>;
+  return (
+    <button
+      disabled={agent.isStreaming}
+      onClick={() => {
+        void agent.start({ ticket_id: "ticket_123" });
+      }}
+    >
+      {agent.status ?? "Run agent"}
+    </button>
+  );
 }
+```
+
+Workflow run:
+
+```tsx
+import { useWorkflowRun } from "lemma-sdk/react";
+
+function WorkflowButton({ client }: { client: LemmaClient }) {
+  const workflow = useWorkflowRun({
+    client,
+    workflowName: "approve_ticket",
+  });
 
-export function App() {
   return (
-    <AuthGuard client={client}>
-      <SupportThread />
-    </AuthGuard>
+    <button
+      disabled={workflow.isPolling}
+      onClick={() => {
+        void workflow.start({ ticket_id: "ticket_123" });
+      }}
+    >
+      {workflow.status ?? "Start workflow"}
+    </button>
   );
 }
 ```
 
 ## Shadcn Registry
 
-Lemma UI now lives in the registry, not in `lemma-sdk/react`.
+Lemma UI lives in the registry, not in `lemma-sdk/react`.
 
 After running `npx lemma-sdk init-shadcn`, install blocks like:
 
 ```bash
 npx shadcn@latest add @lemma/lemma-records-page
-npx shadcn@latest add @lemma/lemma-assistant-embedded
-npx shadcn@latest add @lemma/lemma-workflow-start-form
+npx shadcn@latest add @lemma/lemma-agent-runner-page
+npx shadcn@latest add @lemma/lemma-workflow-launcher-page
+npx shadcn@latest add @lemma/lemma-function-runner-page
 ```
 
-Current registry items include:
+Current registry items:
 
-- `lemma-assistant-experience`
-- `lemma-assistant-embedded`
-- `lemma-schema-form`
-- `lemma-records-page`
-- `lemma-record-form`
-- `lemma-records-table`
-- `lemma-related-records-table`
-- `lemma-reverse-related-records-table`
-- `lemma-workflow-start-form`
+| Area | Items |
+| --- | --- |
+| Assistant | `lemma-assistant-experience`, `lemma-assistant-embedded` |
+| Schema | `lemma-schema-form` |
+| Tables | `lemma-table-picker`, `lemma-record-picker`, `lemma-record-filters-bar`, `lemma-records-table`, `lemma-record-details-card`, `lemma-record-form`, `lemma-related-records-table`, `lemma-reverse-related-records-table`, `lemma-bulk-actions-bar`, `lemma-records-page` |
+| Agents | `lemma-agent-run-panel`, `lemma-agent-output-card`, `lemma-agent-messages`, `lemma-agent-runner-page` |
+| Workflows | `lemma-workflow-start-form`, `lemma-workflow-history`, `lemma-workflow-run-status`, `lemma-workflow-run-details`, `lemma-workflow-launcher-page` |
+| Members and access | `lemma-members-table`, `lemma-member-picker`, `lemma-org-member-picker`, `lemma-pod-access-card` |
+| Functions | `lemma-function-run-panel`, `lemma-function-run-history`, `lemma-function-runner-page` |
 
 The registry is currently served from jsDelivr against this public repo:
 
 - registry root: `https://cdn.jsdelivr.net/gh/gappyai/lemma-typescript@main/public/r/registry.json`
 - item shape: `https://cdn.jsdelivr.net/gh/gappyai/lemma-typescript@main/public/r/{name}.json`
 
-For more stable installs, prefer pinning the registry URL to a tag or commit SHA instead of `@main`.
+For more stable installs, pin the registry URL to a tag or commit SHA instead of `@main`.
 
-## Core Client
+### Records Workspace Customization
 
-```ts
-import { LemmaClient } from "lemma-sdk";
+The records blocks are meant to be configured with props before you reach for a fork.
 
-const client = new LemmaClient({
-  podId: "<pod-id>",
-});
+`lemma-records-page` supports:
 
-await client.initialize();
+- capability toggles such as `allowCreate`, `allowEdit`, `allowSelection`, `allowBulkDelete`, `allowSearch`, `allowFilters`, `allowSorting`, `allowPageSizeSelect`, and `allowColumnVisibility`
+- layout toggles such as `showTablePicker`, `showRecordPicker`, and `showRecordDetails`
+- column control through `columns`, `hiddenColumnNames`, `defaultHiddenColumnNames`, and `onHiddenColumnNamesChange`
+- non-`id` primary keys through `recordIdField` or `getRecordId`
+- record-form overrides through `recordFormHiddenFields`, `recordFormFieldOrder`, `recordFormFieldLabels`, `recordFormFieldDescriptions`, `createFormTitle`, `editFormTitle`, `createSubmitLabel`, and `editSubmitLabel`
 
-const tables = await client.tables.list();
-const records = await client.records.list("tickets");
-```
+`lemma-records-table` supports richer column definitions:
+
+- `label`, `description`, `type`, `width`, `minWidth`, `align`
+- `searchable`, `hideable`, `hidden`
+- `renderCell(...)` for custom cell output
+- per-row buttons through `rowActions`
 
-Pod-scoped namespaces include `tables`, `records`, `assistants`, `agents`, `workflows`, `functions`, `files`, and `resources`.  
-Org and user surfaces include `users`, `organizations`, `pods`, `podMembers`, and `podJoinRequests`.
+```tsx
+import { LemmaRecordsPage } from "@/components/lemma/lemma-records-page";
+import type { LemmaRecordsTableColumn } from "@/components/lemma/lemma-records-table";
+
+const columns: LemmaRecordsTableColumn[] = [
+  { name: "item_id", label: "Item ID", hideable: false, width: 180 },
+  { name: "group_id", label: "Group", width: 160 },
+  { name: "name", label: "Name", minWidth: 320, searchable: true },
+  {
+    name: "sellable",
+    label: "Sellable",
+    type: "boolean",
+    width: 120,
+    align: "center",
+    renderCell: ({ value }) => (value ? "Yes" : "No"),
+  },
+];
+
+<LemmaRecordsPage
+  allowColumnVisibility
+  allowCreate
+  allowEdit
+  columns={columns}
+  createButtonLabel="New SKU"
+  defaultHiddenColumnNames={["group_id"]}
+  editSubmitLabel="Save SKU"
+  recordFormFieldLabels={{ item_id: "Item ID" }}
+  recordIdField="item_id"
+  tableName="catalog_items"
+/>;
+```
 
 ## Auth
 
@@ -156,6 +305,19 @@ Useful helpers:
 
 When `client.podId` is set and the signed-in user is not a pod member, `AuthGuard` can render the request-access flow and create or show pod join requests.
 
+`usePodAccess` exposes the same membership/request-access state as a hook for custom UI.
+
+## Migration Notes
+
+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.
+- New workflow code should prefer `useWorkflowRun`, `useWorkflowRuns`, and `useWorkflowResume` over the older `flow`-named hooks.
+
 ## Local Development
 
 From the root of this repository:

package/dist/react/index.d.ts

@@ -12,12 +12,22 @@ export { useConversationMessages } from "./useConversationMessages.js";
 export type { UseConversationMessagesOptions, UseConversationMessagesResult, } from "./useConversationMessages.js";
 export { useAgentRun } from "./useAgentRun.js";
 export type { UseAgentRunOptions, UseAgentRunResult } from "./useAgentRun.js";
+export { useAgentRuns } from "./useAgentRuns.js";
+export type { UseAgentRunsOptions, UseAgentRunsResult } from "./useAgentRuns.js";
+export { useAgentInputSchema } from "./useAgentInputSchema.js";
+export type { UseAgentInputSchemaOptions, UseAgentInputSchemaResult, } from "./useAgentInputSchema.js";
 export { useAssistantSession } from "./useAssistantSession.js";
 export type { CreateConversationInput, SendAssistantMessageOptions, UseAssistantSessionOptions, UseAssistantSessionResult, } from "./useAssistantSession.js";
 export { useAssistantRuntime } from "./useAssistantRuntime.js";
 export type { UseAssistantRuntimeOptions, UseAssistantRuntimeResult, } from "./useAssistantRuntime.js";
 export { useMembers } from "./useMembers.js";
 export type { UseMembersOptions, UseMembersResult } from "./useMembers.js";
+export { useOrganizationMembers } from "./useOrganizationMembers.js";
+export type { UseOrganizationMembersOptions, UseOrganizationMembersResult, } from "./useOrganizationMembers.js";
+export { useCurrentUser } from "./useCurrentUser.js";
+export type { UseCurrentUserOptions, UseCurrentUserResult } from "./useCurrentUser.js";
+export { usePodAccess } from "./usePodAccess.js";
+export type { PodAccessStatus, UsePodAccessOptions, UsePodAccessResult, } from "./usePodAccess.js";
 export { useTables } from "./useTables.js";
 export type { UseTablesOptions, UseTablesResult } from "./useTables.js";
 export { useTable } from "./useTable.js";
@@ -35,11 +45,13 @@ export type { UseDeleteRecordOptions, UseDeleteRecordResult } from "./useDeleteR
 export { useBulkRecords } from "./useBulkRecords.js";
 export type { UseBulkRecordsOptions, UseBulkRecordsResult } from "./useBulkRecords.js";
 export { useJoinedRecords } from "./useJoinedRecords.js";
-export type { UseJoinedRecordsOptions, UseJoinedRecordsResult } from "./useJoinedRecords.js";
+export type { JoinedRecordsShorthandJoin, UseJoinedRecordsOptions, UseJoinedRecordsResult, } from "./useJoinedRecords.js";
 export { useRelatedRecords } from "./useRelatedRecords.js";
 export type { RelatedRecordsColumn, RelatedRecordsInclude, RelatedRecordsResolvedInclude, UseRelatedRecordsOptions, UseRelatedRecordsResult, } from "./useRelatedRecords.js";
 export { useReverseRelatedRecords } from "./useReverseRelatedRecords.js";
 export type { ReverseRelatedRecordsColumn, ReverseRelatedRelation, ReverseRelationSelector, UseReverseRelatedRecordsOptions, UseReverseRelatedRecordsResult, } from "./useReverseRelatedRecords.js";
+export { useReferencingRecords } from "./useReferencingRecords.js";
+export type { ReferencingRecordsColumn, UseReferencingRecordsOptions, UseReferencingRecordsResult, } from "./useReferencingRecords.js";
 export { useForeignKeyOptions } from "./useForeignKeyOptions.js";
 export type { ForeignKeyOption, UseForeignKeyOptionsOptions, UseForeignKeyOptionsResult, } from "./useForeignKeyOptions.js";
 export { useRecordSchema } from "./useRecordSchema.js";
@@ -54,9 +66,19 @@ export { useTaskSession } from "./useTaskSession.js";
 export type { CreateTaskInput, UseTaskSessionOptions, UseTaskSessionResult, } from "./useTaskSession.js";
 export { useFunctionSession } from "./useFunctionSession.js";
 export type { UseFunctionSessionOptions, UseFunctionSessionResult, } from "./useFunctionSession.js";
+export { useFunctionRun } from "./useFunctionRun.js";
+export type { UseFunctionRunOptions, UseFunctionRunResult } from "./useFunctionRun.js";
+export { useFunctionRuns } from "./useFunctionRuns.js";
+export type { UseFunctionRunsOptions, UseFunctionRunsResult } from "./useFunctionRuns.js";
 export { useFlowSession } from "./useFlowSession.js";
 export type { UseFlowSessionOptions, UseFlowSessionResult, } from "./useFlowSession.js";
 export { useWorkflowStart } from "./useWorkflowStart.js";
 export type { UseWorkflowStartOptions, UseWorkflowStartResult, } from "./useWorkflowStart.js";
+export { useWorkflowRun } from "./useWorkflowRun.js";
+export type { UseWorkflowRunOptions, UseWorkflowRunResult } from "./useWorkflowRun.js";
+export { useWorkflowRuns } from "./useWorkflowRuns.js";
+export type { UseWorkflowRunsOptions, UseWorkflowRunsResult } from "./useWorkflowRuns.js";
+export { useWorkflowResume } from "./useWorkflowResume.js";
+export type { UseWorkflowResumeOptions, UseWorkflowResumeResult, } from "./useWorkflowResume.js";
 export { useFlowRunHistory } from "./useFlowRunHistory.js";
 export type { UseFlowRunHistoryOptions, UseFlowRunHistoryResult, } from "./useFlowRunHistory.js";

package/dist/react/index.js

@@ -5,9 +5,14 @@ export { useConversations } from "./useConversations.js";
 export { useConversation } from "./useConversation.js";
 export { useConversationMessages } from "./useConversationMessages.js";
 export { useAgentRun } from "./useAgentRun.js";
+export { useAgentRuns } from "./useAgentRuns.js";
+export { useAgentInputSchema } from "./useAgentInputSchema.js";
 export { useAssistantSession } from "./useAssistantSession.js";
 export { useAssistantRuntime } from "./useAssistantRuntime.js";
 export { useMembers } from "./useMembers.js";
+export { useOrganizationMembers } from "./useOrganizationMembers.js";
+export { useCurrentUser } from "./useCurrentUser.js";
+export { usePodAccess } from "./usePodAccess.js";
 export { useTables } from "./useTables.js";
 export { useTable } from "./useTable.js";
 export { useRecords } from "./useRecords.js";
@@ -19,6 +24,7 @@ export { useBulkRecords } from "./useBulkRecords.js";
 export { useJoinedRecords } from "./useJoinedRecords.js";
 export { useRelatedRecords } from "./useRelatedRecords.js";
 export { useReverseRelatedRecords } from "./useReverseRelatedRecords.js";
+export { useReferencingRecords } from "./useReferencingRecords.js";
 export { useForeignKeyOptions } from "./useForeignKeyOptions.js";
 export { useRecordSchema } from "./useRecordSchema.js";
 export { useRecordForm } from "./useRecordForm.js";
@@ -26,6 +32,11 @@ export { useSchemaForm } from "./useSchemaForm.js";
 export { useAssistantController } from "./useAssistantController.js";
 export { useTaskSession } from "./useTaskSession.js";
 export { useFunctionSession } from "./useFunctionSession.js";
+export { useFunctionRun } from "./useFunctionRun.js";
+export { useFunctionRuns } from "./useFunctionRuns.js";
 export { useFlowSession } from "./useFlowSession.js";
 export { useWorkflowStart } from "./useWorkflowStart.js";
+export { useWorkflowRun } from "./useWorkflowRun.js";
+export { useWorkflowRuns } from "./useWorkflowRuns.js";
+export { useWorkflowResume } from "./useWorkflowResume.js";
 export { useFlowRunHistory } from "./useFlowRunHistory.js";

package/dist/react/useAgentInputSchema.d.ts

@@ -0,0 +1,19 @@
+import type { LemmaClient } from "../client.js";
+import type { JsonSchemaLike } from "../schema-form.js";
+import type { Agent } from "../types.js";
+export interface UseAgentInputSchemaOptions {
+    client: LemmaClient;
+    podId?: string;
+    agentName: string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseAgentInputSchemaResult {
+    agent: Agent | null;
+    inputSchema: JsonSchemaLike | null;
+    outputSchema: JsonSchemaLike | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<Agent | null>;
+}
+export declare function useAgentInputSchema({ client, podId, agentName, enabled, autoLoad, }: UseAgentInputSchemaOptions): UseAgentInputSchemaResult;

package/dist/react/useAgentInputSchema.js

@@ -0,0 +1,73 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useAgentInputSchema({ client, podId, agentName, enabled = true, autoLoad = true, }) {
+    const [agent, setAgent] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const trimmedAgentName = agentName.trim();
+    const isEnabled = enabled && trimmedAgentName.length > 0;
+    const refresh = useCallback(async (signal) => {
+        if (!isEnabled) {
+            setAgent(null);
+            setError(null);
+            setIsLoading(false);
+            return null;
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextAgent = await scopedClient.agents.get(trimmedAgentName);
+            if (signal?.aborted)
+                return null;
+            setAgent(nextAgent);
+            return nextAgent;
+        }
+        catch (refreshError) {
+            if (signal?.aborted)
+                return null;
+            const normalized = normalizeError(refreshError, "Failed to load agent schema.");
+            setError(normalized);
+            setAgent(null);
+            return null;
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, isEnabled, podId, trimmedAgentName]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setAgent(null);
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        const controller = new AbortController();
+        let cancelled = false;
+        (async () => {
+            try {
+                await refresh(controller.signal);
+            }
+            catch {
+                if (!cancelled) {
+                    setError(normalizeError(new Error("Failed to load agent schema."), "Failed to load agent schema."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
+    }, [autoLoad, isEnabled, refresh]);
+    return useMemo(() => ({
+        agent,
+        inputSchema: (agent?.input_schema ?? null),
+        outputSchema: (agent?.output_schema ?? null),
+        isLoading,
+        error,
+        refresh,
+    }), [agent, error, isLoading, refresh]);
+}

package/dist/react/useAgentRun.js

@@ -1,5 +1,6 @@
-import { useCallback } from "react";
+import { useCallback, useMemo } from "react";
 import { isTerminalTaskStatus, normalizeRunStatus } from "../run-utils.js";
+import { resolvePodClient } from "./utils.js";
 import { useTaskSession, } from "./useTaskSession.js";
 function resolveAgentName(base, override) {
     const resolved = override ?? base;
@@ -8,11 +9,6 @@ function resolveAgentName(base, override) {
     }
     return resolved;
 }
-function resolvePodClient(client, podId) {
-    if (!podId || podId === client.podId)
-        return client;
-    return client.withPod(podId);
-}
 export function useAgentRun({ client, podId, agentName, taskId = null, autoConnect = true, autoConnectOnStart = true, onEvent, onStatus, onMessage, onError, }) {
     const session = useTaskSession({
         client,
@@ -41,18 +37,20 @@ export function useAgentRun({ client, podId, agentName, taskId = null, autoConne
         await session.loadMessages(resolvedTaskId);
         return session.refreshTask(resolvedTaskId);
     }, [client, podId, session]);
-    const normalizedStatus = normalizeRunStatus(session.status);
-    const isFinished = isTerminalTaskStatus(normalizedStatus);
-    const isWaitingForInput = normalizedStatus === "WAITING";
-    const output = session.task?.output_data ?? null;
-    const finalOutput = isFinished ? output : null;
-    return {
-        ...session,
-        output,
-        finalOutput,
-        isWaitingForInput,
-        isFinished,
-        start,
-        submitInput,
-    };
+    return useMemo(() => {
+        const normalizedStatus = normalizeRunStatus(session.status);
+        const isFinished = isTerminalTaskStatus(normalizedStatus);
+        const isWaitingForInput = normalizedStatus === "WAITING";
+        const output = session.task?.output_data ?? null;
+        const finalOutput = isFinished ? output : null;
+        return {
+            ...session,
+            output,
+            finalOutput,
+            isWaitingForInput,
+            isFinished,
+            start,
+            submitInput,
+        };
+    }, [session, start, submitInput]);
 }

package/dist/react/useAgentRuns.d.ts

@@ -0,0 +1,33 @@
+import type { LemmaClient } from "../client.js";
+import type { Task } from "../types.js";
+export interface UseAgentRunsOptions {
+    client: LemmaClient;
+    podId?: string;
+    agentName?: string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+    limit?: number;
+    pageToken?: string;
+    initialTaskId?: string | null;
+}
+export interface UseAgentRunsResult {
+    runs: Task[];
+    total: number;
+    nextPageToken: string | null;
+    selectedTaskId: string | null;
+    effectiveSelectedTaskId: string | null;
+    selectedRun: Task | null;
+    isLoading: boolean;
+    isLoadingMore: boolean;
+    error: Error | null;
+    selectRun: (taskId: string | null) => void;
+    clearSelection: () => void;
+    refresh: (overrides?: {
+        limit?: number;
+        pageToken?: string;
+    }) => Promise<Task[]>;
+    loadMore: (overrides?: {
+        limit?: number;
+    }) => Promise<Task[]>;
+}
+export declare function useAgentRuns({ client, podId, agentName, enabled, autoLoad, limit, pageToken, initialTaskId, }: UseAgentRunsOptions): UseAgentRunsResult;