lemma-sdk 0.2.10 → 0.2.12

package/README.md

@@ -169,6 +169,94 @@ 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.
+
+Useful UI primitives exported from `lemma-sdk/react`:
+
+- `AssistantHeader`
+- `AssistantConversationList`
+- `AssistantModelPicker`
+- `AssistantShellLayout`
+- `AssistantComposer`
+- `AssistantMessageViewport`
+- `AssistantAskOverlay`
+- `AssistantPendingFileChip`
+- `AssistantStatusPill`
+- `MessageGroup`
+- `PlanSummaryStrip`
+
+For a direct plug-and-play component, `AssistantEmbedded` wires `useAssistantController` into the default assistant experience:
+
+```tsx
+import { AssistantEmbedded } from "lemma-sdk/react";
+
+function SupportAssistant() {
+  return (
+    <AssistantEmbedded
+      client={client}
+      assistantId="support_assistant"
+      podId="pod_123"
+      title="Support Assistant"
+      subtitle="Ask questions about this pod."
+      placeholder="Message Support Assistant"
+      showConversationList
+    />
+  );
+}
+```
+
 ### Assistant names (resource key)
 
 Assistant CRUD is name-based:

package/dist/react/components/AssistantChrome.d.ts

@@ -0,0 +1,77 @@
+import { type ComponentPropsWithoutRef, type ReactNode } from "react";
+import type { AssistantConversationListItem, AssistantConversationRenderArgs } from "./assistant-types.js";
+export interface AssistantHeaderProps {
+    title: ReactNode;
+    subtitle?: ReactNode;
+    badge?: ReactNode;
+    controls?: ReactNode;
+    className?: string;
+}
+export interface AssistantMessageViewportProps extends ComponentPropsWithoutRef<"div"> {
+    innerClassName?: string;
+    children: ReactNode;
+}
+export declare const AssistantMessageViewport: import("react").ForwardRefExoticComponent<AssistantMessageViewportProps & import("react").RefAttributes<HTMLDivElement>>;
+export interface AssistantShellLayoutProps {
+    sidebar?: ReactNode;
+    sidebarVisible?: boolean;
+    main: ReactNode;
+    className?: string;
+}
+export declare function AssistantShellLayout({ sidebar, sidebarVisible, main, className, }: AssistantShellLayoutProps): import("react/jsx-runtime").JSX.Element;
+export declare function AssistantHeader({ title, subtitle, badge, controls, className, }: AssistantHeaderProps): import("react/jsx-runtime").JSX.Element;
+export interface AssistantConversationListProps {
+    conversations: AssistantConversationListItem[];
+    activeConversationId: string | null;
+    onSelectConversation: (conversationId: string) => void;
+    onNewConversation?: () => void;
+    renderConversationLabel?: (args: AssistantConversationRenderArgs) => ReactNode;
+    title?: ReactNode;
+    newLabel?: ReactNode;
+    className?: string;
+}
+export declare function AssistantConversationList({ conversations, activeConversationId, onSelectConversation, onNewConversation, renderConversationLabel, title, newLabel, className, }: AssistantConversationListProps): import("react/jsx-runtime").JSX.Element;
+export interface AssistantModelPickerProps<TValue extends string = string> {
+    value: TValue | null;
+    options: TValue[];
+    disabled?: boolean;
+    autoLabel?: ReactNode;
+    getOptionLabel?: (value: TValue) => ReactNode;
+    onChange: (value: TValue | null) => void;
+    className?: string;
+}
+export declare function AssistantModelPicker<TValue extends string = string>({ value, options, disabled, autoLabel, getOptionLabel, onChange, className, }: AssistantModelPickerProps<TValue>): import("react/jsx-runtime").JSX.Element;
+export interface AssistantAskOverlayProps {
+    questionNumber: number;
+    totalQuestions: number;
+    question: ReactNode;
+    options: string[];
+    selectedOptions: string[];
+    canContinue: boolean;
+    continueLabel: ReactNode;
+    onSelectOption: (option: string) => void;
+    onContinue?: () => void;
+    onSkip?: () => void;
+    mode?: "single_select" | "multi_select" | "rank_priorities";
+}
+export declare function AssistantAskOverlay({ questionNumber, totalQuestions, question, options, selectedOptions, canContinue, continueLabel, onSelectOption, onContinue, onSkip, mode, }: AssistantAskOverlayProps): import("react/jsx-runtime").JSX.Element;
+export interface AssistantPendingFileChipProps {
+    label: ReactNode;
+    onRemove?: () => void;
+    className?: string;
+}
+export interface AssistantComposerProps {
+    floating?: ReactNode;
+    status?: ReactNode;
+    pendingFiles?: ReactNode;
+    children: ReactNode;
+    className?: string;
+}
+export declare function AssistantComposer({ floating, status, pendingFiles, children, className, }: AssistantComposerProps): import("react/jsx-runtime").JSX.Element;
+export declare function AssistantPendingFileChip({ label, onRemove, className, }: AssistantPendingFileChipProps): import("react/jsx-runtime").JSX.Element;
+export interface AssistantStatusPillProps {
+    label: ReactNode;
+    subtle?: boolean;
+    className?: string;
+}
+export declare function AssistantStatusPill({ label, subtle, className, }: AssistantStatusPillProps): import("react/jsx-runtime").JSX.Element;

package/dist/react/components/AssistantChrome.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from "react";
+function cx(...values) {
+    return values.filter(Boolean).join(" ");
+}
+export const AssistantMessageViewport = forwardRef(function AssistantMessageViewport({ className, innerClassName, children, ...props }, ref) {
+    return (_jsx("div", { ref: ref, className: cx("min-h-0 flex-1 overflow-y-auto bg-[var(--bg-surface)] px-4 py-4", className), ...props, children: _jsx("div", { className: cx("mx-auto flex w-full max-w-5xl flex-col gap-3", innerClassName), children: children }) }));
+});
+export function AssistantShellLayout({ sidebar, sidebarVisible = false, main, className, }) {
+    return (_jsxs("div", { className: cx("mx-auto flex h-full w-full min-h-0 flex-col gap-3 font-sans antialiased", !!sidebar && sidebarVisible && "lg:grid lg:grid-cols-[280px_minmax(0,1fr)] lg:gap-3", className), children: [sidebar && sidebarVisible ? (_jsx("div", { className: "hidden h-full min-h-0 lg:block", children: sidebar })) : null, main] }));
+}
+export function AssistantHeader({ title, subtitle, badge, controls, className, }) {
+    return (_jsxs("div", { className: cx("flex items-center justify-between border-b border-[color:color-mix(in_srgb,_var(--border-default)_80%,_transparent)] px-4 py-3", className), children: [_jsxs("div", { className: "flex items-center gap-2.5", children: [badge ? (_jsx("div", { className: "flex h-7 w-7 items-center justify-center rounded-full bg-[linear-gradient(135deg,var(--brand-primary),var(--brand-secondary))] shadow-[var(--shadow-xs)]", children: badge })) : null, _jsxs("div", { children: [_jsx("h3", { className: "text-[13px] font-semibold leading-tight text-[var(--text-primary)]", children: title }), subtitle ? (_jsx("p", { className: "text-[11px] text-[var(--text-tertiary)]", children: subtitle })) : null] })] }), controls ? (_jsx("div", { className: "flex items-center gap-1", children: controls })) : null] }));
+}
+export function AssistantConversationList({ conversations, activeConversationId, onSelectConversation, onNewConversation, renderConversationLabel, title = "Conversations", newLabel = "New", className, }) {
+    return (_jsxs("aside", { className: cx("flex h-full min-h-0 flex-col overflow-hidden rounded-2xl border border-[color:color-mix(in_srgb,_var(--border-default)_80%,_transparent)] bg-[var(--bg-surface)] shadow-[var(--shadow-lg)]", className), children: [_jsx("div", { className: "border-b border-[color:color-mix(in_srgb,_var(--border-default)_80%,_transparent)] px-4 py-3", children: _jsxs("div", { className: "flex items-center justify-between gap-3", children: [_jsxs("div", { children: [_jsx("div", { className: "text-[13px] font-semibold text-[var(--text-primary)]", children: title }), _jsxs("div", { className: "mt-1 text-[11px] text-[var(--text-tertiary)]", children: [conversations.length, " total"] })] }), onNewConversation ? (_jsx("button", { type: "button", onClick: onNewConversation, className: "rounded-full border border-[var(--border-default)] bg-[var(--bg-surface)] px-3 py-1.5 text-[11px] font-medium text-[var(--text-secondary)] hover:text-[var(--text-primary)]", children: newLabel })) : null] }) }), _jsx("div", { className: "min-h-0 flex-1 overflow-y-auto p-3 space-y-2", children: conversations.map((conversation) => {
+                    const isActive = conversation.id === activeConversationId;
+                    return (_jsxs("button", { type: "button", onClick: () => onSelectConversation(conversation.id), className: cx("w-full rounded-xl border px-3 py-2.5 text-left transition-colors", isActive
+                            ? "border-[color:color-mix(in_srgb,_var(--brand-primary)_44%,_var(--border-default))] bg-[color:color-mix(in_srgb,_var(--brand-glow)_42%,_var(--bg-surface))]"
+                            : "border-[var(--border-default)] bg-[var(--bg-surface)] hover:bg-[var(--bg-subtle)]"), children: [_jsx("div", { className: "truncate text-[12px] font-medium text-[var(--text-primary)]", children: renderConversationLabel
+                                    ? renderConversationLabel({ conversation, isActive })
+                                    : (conversation.title || "Untitled conversation") }), _jsx("div", { className: "mt-1 text-[10px] uppercase tracking-[0.08em] text-[var(--text-tertiary)]", children: (conversation.status || "waiting").toLowerCase() })] }, conversation.id));
+                }) })] }));
+}
+export function AssistantModelPicker({ value, options, disabled, autoLabel = "Auto", getOptionLabel, onChange, className, }) {
+    const autoValue = "__AUTO__";
+    return (_jsxs("select", { value: value ?? autoValue, onChange: (event) => onChange(event.target.value === autoValue ? null : event.target.value), disabled: disabled, className: cx("h-8 rounded-full border border-[color:color-mix(in_srgb,_var(--border-default)_80%,_transparent)] bg-[var(--bg-surface)] px-3 text-[11px] text-[var(--text-secondary)]", className), "aria-label": "Conversation model", title: "Conversation model", children: [_jsx("option", { value: autoValue, children: autoLabel }), options.map((option) => (_jsx("option", { value: option, children: getOptionLabel ? getOptionLabel(option) : option }, option)))] }));
+}
+export function AssistantAskOverlay({ questionNumber, totalQuestions, question, options, selectedOptions, canContinue, continueLabel, onSelectOption, onContinue, onSkip, mode = "single_select", }) {
+    return (_jsxs("div", { className: "space-y-2", children: [_jsxs("div", { className: "flex items-start justify-between gap-3", children: [_jsxs("div", { children: [_jsxs("div", { className: "text-[11px] uppercase tracking-[0.12em] text-[var(--text-tertiary)]", children: ["Question ", questionNumber, " of ", totalQuestions] }), _jsx("p", { className: "mt-1 text-[14px] font-medium leading-6 text-[var(--text-primary)]", children: question })] }), onSkip ? (_jsx("button", { type: "button", onClick: onSkip, className: "rounded-md px-2 py-1 text-[12px] text-[var(--text-tertiary)] transition-colors hover:bg-[var(--bg-subtle)] hover:text-[var(--text-primary)]", children: "Skip" })) : null] }), _jsx("div", { className: "max-h-[260px] space-y-1.5 overflow-y-auto pr-1", children: options.map((option, optionIndex) => {
+                    const isSelected = selectedOptions.includes(option);
+                    const rankLabel = mode === "rank_priorities" && isSelected
+                        ? selectedOptions.indexOf(option) + 1
+                        : null;
+                    return (_jsx("button", { type: "button", onClick: () => onSelectOption(option), className: cx("w-full rounded-lg border px-2.5 py-2 text-left text-[13px] transition-colors", isSelected
+                            ? "border-[color:color-mix(in_srgb,_var(--brand-primary)_64%,_var(--border-subtle))] bg-[color:color-mix(in_srgb,_var(--brand-primary)_14%,_transparent)] text-[var(--text-primary)]"
+                            : "border-[var(--border-default)] bg-[var(--bg-canvas)] text-[var(--text-secondary)] hover:bg-[var(--bg-subtle)] hover:text-[var(--text-primary)]"), children: _jsxs("span", { className: "inline-flex items-center gap-2", children: [rankLabel ? (_jsx("span", { className: "inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-[var(--brand-primary)] px-1 text-[10px] font-semibold text-[var(--text-on-brand)]", children: rankLabel })) : (_jsx("span", { className: cx("inline-block h-2.5 w-2.5 rounded-full border", isSelected
+                                        ? "border-[var(--brand-primary)] bg-[var(--brand-primary)]"
+                                        : "border-[var(--border-default)] bg-transparent") })), option] }) }, `${option}-${optionIndex}`));
+                }) }), onContinue ? (_jsx("div", { className: "flex justify-end", children: _jsx("button", { type: "button", onClick: onContinue, disabled: !canContinue, className: cx("rounded-md px-2.5 py-1.5 text-[12px] font-medium transition-colors", canContinue
+                        ? "bg-[var(--brand-primary)] text-[var(--text-on-brand)] hover:bg-[color:color-mix(in_srgb,_var(--brand-primary)_88%,_var(--text-primary))]"
+                        : "bg-[var(--bg-subtle)] text-[var(--text-tertiary)]"), children: continueLabel }) })) : null] }));
+}
+export function AssistantComposer({ floating, status, pendingFiles, children, className, }) {
+    return (_jsxs("div", { className: cx("relative rounded-2xl border border-[color:color-mix(in_srgb,_var(--border-default)_80%,_transparent)] bg-[var(--bg-surface)] p-2 shadow-[var(--shadow-md)]", className), children: [floating ? (_jsx("div", { className: "absolute bottom-[calc(100%+8px)] left-0 right-0 z-20", children: floating })) : null, _jsx("div", { className: "min-h-[34px] px-2 pb-1", children: _jsx("div", { className: "flex min-h-[26px] items-center transition-opacity duration-200", children: status || _jsx("span", { "aria-hidden": "true", className: "inline-block h-[30px]" }) }) }), pendingFiles ? (_jsx("div", { className: "flex flex-wrap items-center gap-1.5 px-1 pb-1.5", children: pendingFiles })) : null, children] }));
+}
+export function AssistantPendingFileChip({ label, onRemove, className, }) {
+    return (_jsxs("span", { className: cx("inline-flex max-w-full items-center gap-1.5 rounded-full bg-[var(--bg-subtle)] px-2 py-1 text-[11px] text-[var(--text-secondary)]", className), children: [_jsx("span", { className: "truncate max-w-[180px]", children: label }), onRemove ? (_jsx("button", { type: "button", onClick: onRemove, className: "inline-flex h-4 w-4 items-center justify-center rounded-full hover:bg-[var(--bg-canvas)]", title: "Remove file", children: "\u00D7" })) : null] }));
+}
+export function AssistantStatusPill({ label, subtle = false, className, }) {
+    return (_jsxs("div", { className: cx("inline-flex min-h-[30px] max-w-full items-center gap-2 rounded-full px-3 py-1.5 text-[12px] transition-all duration-200", subtle
+            ? "border border-[color:color-mix(in_srgb,_var(--border-default)_72%,_transparent)] bg-[color:color-mix(in_srgb,_var(--bg-surface)_90%,_transparent)] text-[var(--text-tertiary)]"
+            : "border border-[color:color-mix(in_srgb,_var(--brand-primary)_24%,_var(--border-default))] bg-[color:color-mix(in_srgb,_var(--brand-glow)_28%,_var(--bg-surface))] text-[var(--text-secondary)]", className), children: [_jsxs("span", { className: "relative inline-flex h-2.5 w-2.5 shrink-0", children: [_jsx("span", { className: "absolute inline-flex h-full w-full animate-ping rounded-full bg-[var(--brand-primary)]/45" }), _jsx("span", { className: "relative inline-flex h-2.5 w-2.5 rounded-full bg-[var(--brand-primary)]" })] }), _jsx("span", { className: "truncate", children: label })] }));
+}

package/dist/react/components/AssistantEmbedded.d.ts

@@ -0,0 +1,8 @@
+import type { LemmaClient } from "../../client.js";
+import { type AssistantConversationScope } from "../useAssistantController.js";
+import { type AssistantExperienceViewProps } from "./AssistantExperience.js";
+export interface AssistantEmbeddedProps extends Omit<AssistantExperienceViewProps, "controller">, AssistantConversationScope {
+    client: LemmaClient;
+    enabled?: boolean;
+}
+export declare function AssistantEmbedded({ client, podId, assistantId, organizationId, enabled, ...props }: AssistantEmbeddedProps): import("react/jsx-runtime").JSX.Element;

package/dist/react/components/AssistantEmbedded.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useAssistantController } from "../useAssistantController.js";
+import { AssistantExperienceView } from "./AssistantExperience.js";
+export function AssistantEmbedded({ client, podId, assistantId, organizationId, enabled = true, ...props }) {
+    const controller = useAssistantController({
+        client,
+        podId: podId ?? undefined,
+        assistantId: assistantId ?? undefined,
+        organizationId: organizationId ?? undefined,
+        enabled,
+    });
+    return _jsx(AssistantExperienceView, { controller: controller, ...props });
+}

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 {};