lemma-sdk 0.2.10 → 0.2.11

package/README.md

@@ -169,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/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 {};