@caltra/assistant-ui 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @caltra/assistant-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The React adapter for a framework-neutral `CaltraSessionRuntime`. Imports no CSS and owns no transport lifecycle. Install `@caltra/client`, `@caltra/assistant-ui`, React, React DOM, and the supported `@assistant-ui/react` peer dependency.
+
+```tsx
+import { useEffect, useState } from "react";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import { useAssistantUiRuntime } from "@caltra/assistant-ui";
+import type { CaltraClient } from "@caltra/client";
+
+function Chat({ client, sessionId }: { client: CaltraClient; sessionId: string }) {
+  const [session] = useState(() => client.createSessionRuntime({ sessionId }));
+  useEffect(() => {
+    void session.start().catch(() => undefined); // Observe session.getSnapshot().error for UI feedback.
+    return () => { void session.stop(); };
+  }, [session]);
+  const runtime = useAssistantUiRuntime(session);
+  return <AssistantRuntimeProvider runtime={runtime}>
+    {/* Compose your own ThreadPrimitive, MessagePrimitive and ComposerPrimitive UI. */}
+  </AssistantRuntimeProvider>;
+}
+// Remount Chat when client identity or sessionId changes, e.g. a keyed boundary.
+```
+
+The caller starts and stops the Caltra runtime. Multiple adapters or chats may observe that same runtime without opening extra event streams; removing an adapter does not stop it. Each adapter owns its assistant-ui presentation state (including its composer draft), while messages and connection state come from the shared Caltra runtime. Treat a runtime identity change as a component remount boundary to discard previous assistant-ui message/composer state immediately.
+
+Use upstream `useAui`, `useAuiState` and primitives directly inside `AssistantRuntimeProvider`. The adapter maps messages, tools, loading, send and cancellation. It does not enable unsupported server features: attachments, editing/regeneration, tool answers and branch persistence require corresponding Caltra backend support.
+
+The adapter forwards the session runtime's authoritative turn state. `isRunning` remains true between messages and tools until the persisted turn completes, fails, or is cancelled. Servers without `is_running` retain legacy message-activity behavior. Turn completion does not prove a larger application workflow finished. For custom threads, use `scrollToBottomOnRunStart={false}` to preserve reading position when a new turn begins; CaltraChat applies this default automatically.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { type AssistantRuntime } from "@assistant-ui/react";
+import type { CaltraSessionRuntime } from "@caltra/client";
+/** Maps an already-started Caltra session runtime into assistant-ui. Never starts or stops it. */
+export declare function useAssistantUiRuntime(store: CaltraSessionRuntime): AssistantRuntime;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,gBAAgB,EAItB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,kGAAkG;AAClG,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,GAAG,gBAAgB,CAkDnF"}

package/dist/index.js

@@ -0,0 +1,52 @@
+"use client";
+import { ExportedMessageRepository, useExternalStoreRuntime, } from "@assistant-ui/react";
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+/** Maps an already-started Caltra session runtime into assistant-ui. Never starts or stops it. */
+export function useAssistantUiRuntime(store) {
+    const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+    const onNew = useCallback(async (message) => {
+        const text = message.content
+            .filter((part) => part.type === "text")
+            .map((part) => part.text)
+            .join("\n");
+        if (text === "")
+            throw new Error("Caltra currently accepts text messages only.");
+        await store.send(text);
+    }, [store]);
+    const messages = useMemo(() => snapshot.messages.map((message) => ({
+        content: [
+            ...(message.text ? [{ type: "text", text: message.text }] : []),
+            ...(message.tool_calls ?? []).map(tool => ({ type: "tool-call", toolCallId: tool.id, toolName: tool.name,
+                args: tool.arguments, argsText: JSON.stringify(tool.arguments),
+                ...(tool.status === "running" ? {} : { result: tool.result ?? null }),
+                isError: tool.status === "failed" || tool.status === "cancelled",
+                // Keep per-tool lifecycle distinct from the enclosing assistant message.
+                artifact: { caltraToolStatus: tool.status }, })),
+        ],
+        createdAt: new Date(message.created_at),
+        id: message.id,
+        role: message.role,
+        ...(message.role === "assistant" ? {
+            status: message.status === "streaming"
+                ? { type: "running" }
+                : message.status === "completed"
+                    ? { type: "complete", reason: "stop" }
+                    : { type: "incomplete", reason: message.status === "cancelled" ? "cancelled" : "error" },
+        } : {}),
+    })), [snapshot.messages]);
+    // Caltra owns a linear transcript. Replace the repository so removed optimistic
+    // IDs cannot survive as phantom edit/regeneration branches in assistant-ui.
+    const messageRepository = useMemo(() => ExportedMessageRepository.fromArray(messages), [messages]);
+    const runtime = useExternalStoreRuntime({
+        isLoading: !snapshot.historyLoaded,
+        isRunning: snapshot.isRunning,
+        isSendDisabled: snapshot.connection !== "connected",
+        messageRepository,
+        onNew,
+        // assistant-ui calls this from its native Cancel primitive. The store exposes
+        // failures via the existing alert; avoid an unhandled event-handler rejection.
+        onCancel: async () => { await store.cancel().catch(() => undefined); },
+    });
+    return runtime;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,56 @@
 {
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
   "name": "@caltra/assistant-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "assistant-ui adapter for framework-neutral Caltra session runtimes",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prebuild": "npm run build --workspace=@caltra/client",
+    "test": "vitest run tests",
+    "pretest": "npm run build --workspace=@caltra/client",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pretypecheck": "npm run build --workspace=@caltra/client"
+  },
+  "dependencies": {
+    "@caltra/client": "0.10.0"
+  },
+  "peerDependencies": {
+    "@assistant-ui/react": "^0.15.16",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@assistant-ui/react": "0.15.16",
+    "@testing-library/react": "16.3.2",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "jsdom": "30.0.1",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caltra-dev/caltra-sdk.git",
+    "directory": "packages/assistant-ui"
+  }
+}