@cosmoops/connect-sdk 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -3,6 +3,123 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.30.0
+
+`<ConnectAskAi>` forgot everything on reload. Connect's own panel has had
+History and a New-conversation button since it shipped; this is the same two
+controls, backed by the same storage, for the panel a partner mounts.
+
+The reason it took a server change rather than a component one: the
+application chat lane deliberately stored nothing, because a conversation
+belongs to a *person* and an API key names an application. That is still true
+of a server-to-server call — it persists nothing, exactly as before. What
+changed is that the browser path was already sending a signed-in user's
+session token, so there has been a real owner to file a transcript under for
+some time, and nothing was doing it.
+
+### Added
+
+- **History and New in `<ConnectAskAi>`.** Two buttons in the panel header. New
+  clears the transcript and starts a fresh conversation without deleting the
+  old one; History lists what this user has asked *in your application*, and
+  pressing a row reopens the transcript and keeps writing into it.
+
+  Nothing to wire up: if your API key carries `ai:chat` it already works. There
+  is no prop to turn it on, and none to turn it off — a chat panel that cannot
+  show you what you asked yesterday is the odd one out, not the default.
+
+- `connect.ai.listConversations({ asUser, limit?, cursor? })`,
+  `connect.ai.getConversation({ conversationId, asUser })` and
+  `connect.ai.deleteConversation({ conversationId, asUser })`, plus the types
+  they answer with: `AiConversation`, `AiConversationList`,
+  `AiConversationTurn` and `AiConversationDetail`.
+
+  `asUser` is **required** on all three, unlike on `ai.chat` where it is
+  optional. There is no application-wide view of these rows to fall back to:
+  they are scoped to a person, and a version of this call that read every
+  user's transcripts is not a smaller feature, it is a different and worse one.
+
+  `turns[].parts` comes back as the AI SDK's own `UIMessage` parts, in the
+  order the model produced them — prose, reasoning and tool calls interleaved.
+  Hand them to your chat UI as they are. Flattening a turn to text loses the
+  model's own argument and makes the conversation unresumable, which is why
+  these are typed `unknown[]` rather than restated in a schema that would start
+  rejecting transcripts the day the AI SDK adds a part kind.
+
+- `connect.ai.chat({ conversationId })`, optional. Generate one id per
+  conversation client-side and send it with every turn of it; Connect upserts
+  against it. **No id, nothing stored** — which is how a caller opts out of
+  history entirely, and it stays the behaviour for any call made without
+  `asUser`.
+
+- `createConnectHandler` answers three more routes —
+  `GET /ai/conversations`, `GET /ai/conversation?id=`,
+  `DELETE /ai/conversation?id=` — and relays `conversationId` on
+  `POST /ai/chat`. The owner comes from the caller's own session on all four;
+  there is no parameter that could name somebody else.
+
+### Changed
+
+- `mutateResource(path, body?, method?)` takes an optional third argument,
+  `"POST"` (the default, and what every existing call gets) or `"DELETE"`.
+  Existing calls are unaffected.
+
+### Notes
+
+- **Scoped to your application, not just to the workspace.** A workspace
+  subscribing to two products on Connect keeps two separate histories, and
+  neither can read the other's — nor the one that user keeps in the Connect
+  portal itself. An id from the wrong one answers `404`, not somebody else's
+  transcript.
+
+- **A transcript is not an audit trail.** It records what was asked and
+  answered, and a user can delete their own. If you need a durable record of
+  something the assistant *did*, that is your own write and your own log.
+
+## 0.29.0
+
+Voice was readable and writing was not. `calls.list` has always let a partner
+read back what a customer said out loud; the WhatsApp threads a workspace's
+agents hold had no partner surface at all, so a CRM could show every call on a
+contact and nothing they had typed.
+
+### Added
+
+- `connect.conversations.list({ workspaceId, contactAddress?, status? })` and
+  `connect.conversations.get(id, { workspaceId })`, plus the four types they
+  answer with: `ConnectConversation`, `ConnectConversationMessage`,
+  `ConversationsPage` and `ConversationDetail`.
+
+  **These are the *workspace's* threads, not your application's**, which is the
+  difference from `calls` and it decides how they are gated. A call arrived on
+  a channel you hold, so `calls.list` is scoped to your application by the key
+  alone. A conversation lives in the workspace's own subtree and belongs to it
+  the way its contact book does — so reading one needs the `conversations:read`
+  scope **and** a live subscription in that workspace, and, when the call comes
+  through the browser bridge, the signed-in member's own `agent:read`.
+
+  Three things are worth reading before you render one:
+
+  `contactAddress` is the filter to reach for beside your own customer record.
+  You hold a phone number, and you cannot derive a conversation id from one —
+  the id is built from a hashed key, deliberately, so an id you could guess is
+  an id you could probe. Send the number however your records spell it.
+
+  `canReplyFreely` is computed against Connect's clock, and re-deriving it from
+  `lastInboundAt` against yours is the mistake to avoid: WhatsApp allows a
+  free-form reply only inside 24 hours of the customer's last message, and a
+  skew between your server and Connect's shows up as a thread your UI calls
+  answerable when it is not.
+
+  Messages that sent nothing are included and carry `failure`. Render them — a
+  transcript that silently drops them reads as a customer being ignored, which
+  is the opposite of what happened. `refused` is not a failure at all: it is
+  the agent deciding not to answer, which is what it is for.
+
+  Read-only, and deliberately. Sending on a thread would mean saying whether it
+  is a free-form reply or an approved template, and what that means for the
+  agent still answering it.
+
 ## 0.28.0
 
 Connect's webhook bus carried four events, all of them about billing and

package/dist/cjs/client/components/ask-ai-history.js

@@ -0,0 +1,106 @@
+"use client";
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AskAiHistory = AskAiHistory;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const react_2 = require("@heroui/react");
+const lucide_react_1 = require("lucide-react");
+const provider_js_1 = require("../provider.js");
+/** Bridge paths, spelled once - the list is read and invalidated from three places. */
+const LIST_PATH = "/ai/conversations";
+const detailPath = (id) => `/ai/conversation?id=${encodeURIComponent(id)}`;
+/**
+ * Past Ask AI conversations, for reopening or deleting.
+ *
+ * ## It fetches only while it is open
+ *
+ * `<ConnectAskAi>` is mounted for the whole application shell, so an
+ * unconditional read here would put a request on every page load to populate a
+ * list most people never open. It reads on open, and again whenever the panel
+ * has written a new conversation since - which is what `refreshKey` is for.
+ *
+ * ## Deletion confirms inline, not in a dialog
+ *
+ * Destructive actions confirm; this one does it at the weight it deserves.
+ * Losing a transcript is recoverable by asking again, not a cancelled
+ * subscription, and a modal over a 400px panel would be heavier than the thing
+ * it guards. The row swaps to "Delete? / Cancel" and stays there until
+ * answered.
+ */
+function AskAiHistory({ refreshKey, activeConversationId, onOpenConversation, }) {
+    const { fetchResource, mutateResource, invalidateResource } = (0, provider_js_1.useConnect)();
+    const [conversations, setConversations] = (0, react_1.useState)(null);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [confirmingId, setConfirmingId] = (0, react_1.useState)(null);
+    const [busyId, setBusyId] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        let active = true;
+        // The cached entry is dropped first. This component mounts only when the
+        // user asks for the list, and the provider's cache would otherwise hand
+        // them the copy taken before the last three questions they asked.
+        invalidateResource(LIST_PATH);
+        fetchResource(LIST_PATH)
+            .then((page) => {
+            if (!active)
+                return;
+            setConversations(page.conversations);
+            setError(null);
+        })
+            .catch((cause) => {
+            if (!active)
+                return;
+            // An empty list rather than a permanent skeleton: the error is shown
+            // beside it, and a panel stuck loading says nothing at all.
+            setConversations([]);
+            setError(cause instanceof Error ? cause.message : "Could not load your conversations");
+        });
+        return () => {
+            active = false;
+        };
+    }, [fetchResource, invalidateResource, refreshKey]);
+    const open = async (id) => {
+        setBusyId(id);
+        try {
+            const detail = await fetchResource(detailPath(id));
+            onOpenConversation(id, detail);
+        }
+        catch (cause) {
+            setError(cause instanceof Error ? cause.message : "Could not open that conversation");
+        }
+        finally {
+            setBusyId(null);
+        }
+    };
+    const remove = async (id) => {
+        setBusyId(id);
+        // Removed from the list before the response lands. The confirmation was the
+        // decision point, and a row that lingers while the request flies reads as a
+        // press that did not take - so the list is patched and put back on failure.
+        const previous = conversations;
+        setConversations((current) => current?.filter((row) => row.id !== id) ?? null);
+        setConfirmingId(null);
+        try {
+            await mutateResource(detailPath(id), undefined, "DELETE");
+            invalidateResource(LIST_PATH);
+        }
+        catch (cause) {
+            setConversations(previous);
+            setError(cause instanceof Error ? cause.message : "Could not delete that conversation");
+        }
+        finally {
+            setBusyId(null);
+        }
+    };
+    if (conversations === null) {
+        return ((0, jsx_runtime_1.jsx)("div", { className: "space-y-2 p-4", "aria-busy": "true", children: [0, 1, 2].map((row) => ((0, jsx_runtime_1.jsx)("div", { className: "h-9 animate-pulse rounded-md bg-surface-secondary" }, row))) }));
+    }
+    if (conversations.length === 0) {
+        return ((0, jsx_runtime_1.jsx)("div", { className: "p-4", children: error ? ((0, jsx_runtime_1.jsx)("p", { className: "text-xs text-danger", children: error })) : ((0, jsx_runtime_1.jsx)("p", { className: "text-center text-xs text-muted", children: "Nothing here yet. Conversations you have are saved automatically." })) }));
+    }
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "p-2", children: [error && (0, jsx_runtime_1.jsx)("p", { className: "px-2 pb-2 text-xs text-danger", children: error }), (0, jsx_runtime_1.jsx)("ul", { className: "space-y-0.5", children: conversations.map((conversation) => {
+                    const isConfirming = confirmingId === conversation.id;
+                    const isActive = conversation.id === activeConversationId;
+                    return ((0, jsx_runtime_1.jsx)("li", { children: isConfirming ? ((0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-2 rounded-md border border-border px-2 py-1.5", children: [(0, jsx_runtime_1.jsx)("span", { className: "flex-1 truncate text-xs text-muted", children: "Delete this conversation?" }), (0, jsx_runtime_1.jsx)(react_2.Button, { size: "sm", variant: "danger", className: "h-7 px-2 text-xs", isDisabled: busyId === conversation.id, onPress: () => void remove(conversation.id), children: "Delete" }), (0, jsx_runtime_1.jsx)(react_2.Button, { size: "sm", variant: "tertiary", className: "h-7 px-2 text-xs", onPress: () => setConfirmingId(null), children: "Cancel" })] })) : ((0, jsx_runtime_1.jsxs)("div", { className: `group flex items-center gap-1 rounded-md ${isActive ? "bg-surface-secondary" : ""}`, children: [(0, jsx_runtime_1.jsxs)(react_2.Button, { variant: "ghost", className: "h-auto min-w-0 flex-1 justify-start gap-2 px-2 py-1.5 text-start", isDisabled: busyId === conversation.id, onPress: () => void open(conversation.id), children: [(0, jsx_runtime_1.jsx)(lucide_react_1.MessageSquare, { className: "size-3.5 shrink-0 text-muted" }), (0, jsx_runtime_1.jsx)("span", { className: "min-w-0 flex-1 truncate text-xs font-normal", children: conversation.title })] }), (0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "ghost", className: "shrink-0", "aria-label": `Delete "${conversation.title}"`, onPress: () => setConfirmingId(conversation.id), children: (0, jsx_runtime_1.jsx)(lucide_react_1.Trash2, { className: "size-3.5 text-muted" }) })] })) }, conversation.id));
+                }) })] }));
+}

package/dist/cjs/client/components/ask-ai-turns.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lastTextBlockIndex = lastTextBlockIndex;
+exports.appendText = appendText;
+exports.turnsFromStored = turnsFromStored;
+/**
+ * Index of the final text block, or `-1`. A reverse loop rather than
+ * `findLastIndex`, which is ES2023 - this package targets ES2022 so its
+ * published output stays usable on the runtimes its `engines` field claims.
+ */
+function lastTextBlockIndex(blocks) {
+    for (let index = blocks.length - 1; index >= 0; index--) {
+        if (blocks[index]?.kind === "text")
+            return index;
+    }
+    return -1;
+}
+/** Appends a text delta to the open text block, or opens one after a widget. */
+function appendText(blocks, text) {
+    const last = blocks.at(-1);
+    if (last?.kind === "text") {
+        return [...blocks.slice(0, -1), { kind: "text", text: last.text + text }];
+    }
+    return [...blocks, { kind: "text", text }];
+}
+/**
+ * Rebuilds the panel's turns from a stored transcript.
+ *
+ * The inverse of what the stream reader does live, and it has to agree with it
+ * or a reopened conversation renders differently from the one the user just
+ * had. Two shapes, one source: the stream delivers `text-delta`,
+ * `reasoning-delta` and `tool-input-available` frames, and storage keeps the
+ * settled `UIMessage` parts those frames built - `{ type: "text" }`,
+ * `{ type: "reasoning" }`, and `{ type: "tool-<name>" }` carrying the input the
+ * widget was drawn from.
+ *
+ * Three rules, each of which is a thing that would otherwise render wrong:
+ *
+ * - **A tool part with no input is dropped, not restored.** `input: null` means
+ *   "still arriving" to the renderer, which draws a skeleton - correct live,
+ *   and a shimmer that never resolves on a transcript that finished days ago.
+ * - **Reasoning is hoisted per turn**, not left in place. It is rendered above
+ *   the answer in a disclosure, which is where it sat while streaming.
+ * - **A part this build cannot place is skipped rather than guessed at.**
+ *   `parts` is the AI SDK's own shape and gains kinds over time; an unknown one
+ *   costs a widget, and inventing a rendering for it costs the whole turn.
+ */
+function turnsFromStored(turns) {
+    return turns.map((turn) => {
+        let blocks = [];
+        let reasoning = "";
+        for (const raw of turn.parts) {
+            const part = raw;
+            if (typeof part?.type !== "string")
+                continue;
+            if (part.type === "text") {
+                if (typeof part.text === "string" && part.text.length > 0) {
+                    blocks = appendText(blocks, part.text);
+                }
+                continue;
+            }
+            if (part.type === "reasoning") {
+                if (typeof part.text === "string")
+                    reasoning += part.text;
+                continue;
+            }
+            if (part.type.startsWith("tool-")) {
+                // See the note above: an absent input is a skeleton forever.
+                if (part.input === undefined || part.input === null)
+                    continue;
+                blocks = [
+                    ...blocks,
+                    {
+                        kind: "tool",
+                        // The stored call id when there is one. Falling back to the block's
+                        // position keeps React keys unique within the turn, which is all
+                        // this id is used for once the turn is settled.
+                        id: typeof part.toolCallId === "string" ? part.toolCallId : `${turn.id}-${blocks.length}`,
+                        name: part.type.slice("tool-".length),
+                        input: part.input,
+                    },
+                ];
+            }
+        }
+        return { id: turn.id, role: turn.role, blocks, reasoning };
+    });
+}

package/dist/cjs/client/components/ask-ai.js

@@ -11,6 +11,8 @@ const provider_js_1 = require("../provider.js");
 const use_active_path_js_1 = require("../use-active-path.js");
 const ai_screens_js_1 = require("./ai-screens.js");
 const ai_widgets_js_1 = require("./ai-widgets.js");
+const ask_ai_history_js_1 = require("./ask-ai-history.js");
+const ask_ai_turns_js_1 = require("./ask-ai-turns.js");
 /**
  * The panel's open width. The *inner* pane always carries it, so the content
  * keeps its layout while the outer shell's width animates to zero around it.
@@ -170,26 +172,6 @@ async function readStream(response, onChunk) {
         }
     }
 }
-/**
- * Index of the final text block, or `-1`. A reverse loop rather than
- * `findLastIndex`, which is ES2023 - this package targets ES2022 so its
- * published output stays usable on the runtimes its `engines` field claims.
- */
-function lastTextBlockIndex(blocks) {
-    for (let index = blocks.length - 1; index >= 0; index--) {
-        if (blocks[index]?.kind === "text")
-            return index;
-    }
-    return -1;
-}
-/** Appends a text delta to the open text block, or opens one after a widget. */
-function appendText(blocks, text) {
-    const last = blocks.at(-1);
-    if (last?.kind === "text") {
-        return [...blocks.slice(0, -1), { kind: "text", text: last.text + text }];
-    }
-    return [...blocks, { kind: "text", text }];
-}
 /**
  * Ask AI - a chat panel grounded in the signed-in workspace's Context Index,
  * streamed through your own bridge.
@@ -238,6 +220,31 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
     const [input, setInput] = (0, react_1.useState)("");
     const [isBusy, setIsBusy] = (0, react_1.useState)(false);
     const [error, setError] = (0, react_1.useState)(null);
+    const [showHistory, setShowHistory] = (0, react_1.useState)(false);
+    /**
+     * The conversation being written to.
+     *
+     * Generated here, before the first message, because the server cannot hand
+     * one back: it is streaming a response, and there is no point in that stream
+     * at which a new id could reach the browser ahead of the first token. So the
+     * client picks it and Connect upserts - safe because ownership is checked
+     * rather than assumed, and an id naming somebody else's conversation is
+     * refused.
+     *
+     * Lazily initialised rather than computed in a `useMemo`: this has to survive
+     * re-renders and change only when the user starts a new conversation, which
+     * is precisely what `useMemo` does not promise.
+     */
+    const [conversationId, setConversationId] = (0, react_1.useState)(() => newConversationId());
+    /**
+     * Bumped whenever a turn has been written, so the history list re-reads the
+     * next time it is opened.
+     *
+     * A counter rather than a refetch call, because the list is unmounted while
+     * closed - there is nothing to tell. It is *why* the list re-reads, not the
+     * list itself.
+     */
+    const [writeCount, setWriteCount] = (0, react_1.useState)(0);
     const abortRef = (0, react_1.useRef)(null);
     const bottomRef = (0, react_1.useRef)(null);
     // Ids only have to be unique within one mounted conversation, so a counter is
@@ -312,6 +319,11 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
                 // decide what anyone may do. See `ConnectScreen`.
                 ...(resolvedPath ? { screenContext: { pathname: resolvedPath } } : {}),
                 ...(screens.length > 0 ? { screens } : {}),
+                // What makes the conversation resumable. Connect stores the turn
+                // against it and `<AskAiHistory>` reads it back; a turn sent
+                // without one is answered exactly the same way and remembered by
+                // nobody.
+                conversationId,
             }, { signal: controller.signal });
             // The assistant's turn is appended only once the stream is live, so a
             // failed request leaves an error under the question rather than an
@@ -319,7 +331,7 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
             setTurns((current) => [...current, { id: answerId, role: "assistant", blocks: [], reasoning: "" }]);
             await readStream(response, (chunk) => {
                 if (chunk.text) {
-                    patchAnswer((turn) => ({ ...turn, blocks: appendText(turn.blocks, chunk.text) }));
+                    patchAnswer((turn) => ({ ...turn, blocks: (0, ask_ai_turns_js_1.appendText)(turn.blocks, chunk.text) }));
                 }
                 if (chunk.reasoning) {
                     patchAnswer((turn) => ({ ...turn, reasoning: turn.reasoning + chunk.reasoning }));
@@ -348,13 +360,46 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
             if (abortRef.current === controller)
                 abortRef.current = null;
             setIsBusy(false);
+            // Even on an aborted or failed turn: the user's own question has
+            // already been persisted by the time anything can go wrong downstream
+            // of it, so the list is stale either way.
+            setWriteCount((count) => count + 1);
         }
-    }, [streamResource, turns]);
+    }, [streamResource, turns, conversationId]);
+    /**
+     * Clears the transcript and starts writing into a fresh conversation.
+     *
+     * The old one is not deleted - it is in History, which is the whole point.
+     */
+    const startNewConversation = (0, react_1.useCallback)(() => {
+        abortRef.current?.abort();
+        abortRef.current = null;
+        setIsBusy(false);
+        setTurns([]);
+        setError(null);
+        setShowHistory(false);
+        setConversationId(newConversationId());
+    }, []);
+    /**
+     * Replaces the transcript with a stored one, and continues writing into it.
+     *
+     * Writing continues into the conversation that was opened rather than forking
+     * a new one, which is what makes "come back to this tomorrow" work at all.
+     */
+    const openConversation = (0, react_1.useCallback)((id, detail) => {
+        abortRef.current?.abort();
+        abortRef.current = null;
+        setIsBusy(false);
+        setError(null);
+        setTurns((0, ask_ai_turns_js_1.turnsFromStored)(detail.turns));
+        setConversationId(id);
+        setShowHistory(false);
+    }, []);
     const lastTurn = turns.at(-1);
     const isAnswering = isBusy && lastTurn?.role === "assistant";
     const rendered = (0, react_1.useMemo)(() => turns.map((turn) => {
         const isLive = isAnswering && turn.id === lastTurn?.id;
-        const lastTextIndex = lastTextBlockIndex(turn.blocks);
+        const lastTextIndex = (0, ask_ai_turns_js_1.lastTextBlockIndex)(turn.blocks);
         return ((0, jsx_runtime_1.jsxs)("div", { className: `connect-ai-host rounded-md border border-border p-2.5 text-sm ${turn.role === "user" ? "bg-surface-secondary" : "bg-accent/5"}`, children: [(0, jsx_runtime_1.jsx)("p", { className: "mb-1 text-[11px] font-semibold tracking-wide text-muted uppercase", children: turn.role === "user" ? "You" : assistantName }), turn.role === "assistant" && ((0, jsx_runtime_1.jsx)(ThinkingDisclosure, { text: turn.reasoning, isStreaming: isLive && lastTextIndex === -1 })), turn.blocks.map((block, index) => block.kind === "text" ? (
                 // The user's own turn is shown as they typed it - running a
                 // question that happens to start with `#` through the markdown
@@ -371,9 +416,34 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
         if (!text || isBusy)
             return;
         setInput("");
+        // Typing sends you back to the conversation: staying on the history list
+        // while an answer streams behind it would hide the thing just asked for.
+        setShowHistory(false);
         void send(text);
     };
-    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [!isOpen && ((0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, variant: "primary", "aria-label": title, onPress: () => setIsOpen(true), className: "fixed bottom-4 end-4 z-30 size-12 rounded-full shadow-lg sm:bottom-6 sm:end-6", children: (0, jsx_runtime_1.jsx)(lucide_react_1.Sparkles, { className: "size-5" }) })), (0, jsx_runtime_1.jsx)("div", { className: `fixed inset-0 z-40 bg-backdrop transition-opacity lg:hidden ${isOpen ? "pointer-events-auto opacity-100" : "pointer-events-none opacity-0"}`, onClick: () => setIsOpen(false), "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)("aside", { "aria-hidden": !isOpen, className: `fixed inset-y-0 end-0 z-50 flex flex-col border-s border-border bg-surface shadow-xl transition-transform duration-300 ease-in-out ${panelShellWidth(isOpen)} ${isOpen ? "translate-x-0" : "translate-x-full rtl:-translate-x-full"} lg:static lg:z-auto lg:translate-x-0 lg:shadow-none lg:transition-[width]`, children: (0, jsx_runtime_1.jsxs)("div", { className: `flex h-full shrink-0 flex-col ${PANEL_WIDTH}`, children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-2 border-b border-border px-4 py-3", children: [(0, jsx_runtime_1.jsx)(lucide_react_1.Sparkles, { className: "size-4 shrink-0 text-accent" }), (0, jsx_runtime_1.jsx)("span", { className: "flex-1 text-sm font-semibold", children: title }), (0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": "Close", onPress: () => setIsOpen(false), children: (0, jsx_runtime_1.jsx)(lucide_react_1.X, { className: "size-4" }) })] }), (0, jsx_runtime_1.jsxs)("div", { className: "flex-1 space-y-3 overflow-y-auto p-4", children: [turns.length === 0 && ((0, jsx_runtime_1.jsxs)("div", { className: "space-y-3", children: [(0, jsx_runtime_1.jsx)("p", { className: "text-sm text-muted", children: hint }), currentScreen?.suggestions?.length ? ((0, jsx_runtime_1.jsx)("div", { className: "flex flex-wrap gap-1.5", children: currentScreen.suggestions.map((suggestion) => ((0, jsx_runtime_1.jsx)(react_2.Button, { size: "sm", variant: "secondary", className: "h-auto rounded-full px-2.5 py-1 text-start text-xs whitespace-normal", isDisabled: isBusy, onPress: () => void send(suggestion), children: suggestion }, suggestion))) })) : null] })), rendered, isBusy && lastTurn?.role === "user" && ((0, jsx_runtime_1.jsxs)("div", { className: "rounded-md border border-border bg-accent/5 p-2.5 text-sm", children: [(0, jsx_runtime_1.jsx)("p", { className: "mb-1 text-[11px] font-semibold tracking-wide text-muted uppercase", children: assistantName }), (0, jsx_runtime_1.jsx)(ThinkingShimmer, {})] })), error && (0, jsx_runtime_1.jsx)("p", { className: "text-xs text-danger", children: error }), (0, jsx_runtime_1.jsx)("div", { ref: bottomRef })] }), (0, jsx_runtime_1.jsxs)("form", { onSubmit: handleSubmit, className: "flex gap-2 border-t border-border p-3", children: [(0, jsx_runtime_1.jsxs)(react_2.TextField, { variant: "secondary", className: "flex-1", children: [(0, jsx_runtime_1.jsx)(react_2.Label, { className: "sr-only", children: placeholder }), (0, jsx_runtime_1.jsx)(react_2.Input, { placeholder: placeholder, value: input, onChange: (event) => setInput(event.currentTarget.value), disabled: isBusy })] }), isBusy ? ((0, jsx_runtime_1.jsx)(react_2.Button, { type: "button", isIconOnly: true, variant: "secondary", "aria-label": "Stop generating", onPress: stop, children: (0, jsx_runtime_1.jsx)(lucide_react_1.Square, { className: "size-3.5" }) })) : ((0, jsx_runtime_1.jsx)(react_2.Button, { type: "submit", isIconOnly: true, variant: "primary", "aria-label": "Send", isDisabled: !input.trim(), children: (0, jsx_runtime_1.jsx)(lucide_react_1.Send, { className: "size-3.5" }) }))] })] }) })] }));
+    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [!isOpen && ((0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, variant: "primary", "aria-label": title, onPress: () => setIsOpen(true), className: "fixed bottom-4 end-4 z-30 size-12 rounded-full shadow-lg sm:bottom-6 sm:end-6", children: (0, jsx_runtime_1.jsx)(lucide_react_1.Sparkles, { className: "size-5" }) })), (0, jsx_runtime_1.jsx)("div", { className: `fixed inset-0 z-40 bg-backdrop transition-opacity lg:hidden ${isOpen ? "pointer-events-auto opacity-100" : "pointer-events-none opacity-0"}`, onClick: () => setIsOpen(false), "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)("aside", { "aria-hidden": !isOpen, className: `fixed inset-y-0 end-0 z-50 flex flex-col border-s border-border bg-surface shadow-xl transition-transform duration-300 ease-in-out ${panelShellWidth(isOpen)} ${isOpen ? "translate-x-0" : "translate-x-full rtl:-translate-x-full"} lg:static lg:z-auto lg:translate-x-0 lg:shadow-none lg:transition-[width]`, children: (0, jsx_runtime_1.jsxs)("div", { className: `flex h-full shrink-0 flex-col ${PANEL_WIDTH}`, children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-2 border-b border-border px-4 py-3", children: [(0, jsx_runtime_1.jsx)(lucide_react_1.Sparkles, { className: "size-4 shrink-0 text-accent" }), (0, jsx_runtime_1.jsx)("span", { className: "flex-1 text-sm font-semibold", children: title }), (0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": "New conversation", 
+                                    // Disabled on an empty one rather than hidden: a control that
+                                    // appears and disappears as you use the panel is harder to find
+                                    // than one that is always in the same place.
+                                    isDisabled: turns.length === 0, onPress: startNewConversation, children: (0, jsx_runtime_1.jsx)(lucide_react_1.Plus, { className: "size-4" }) }), (0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": showHistory ? "Hide past conversations" : "Past conversations", "aria-pressed": showHistory, onPress: () => setShowHistory((open) => !open), children: (0, jsx_runtime_1.jsx)(lucide_react_1.History, { className: "size-4" }) }), (0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": "Close", onPress: () => setIsOpen(false), children: (0, jsx_runtime_1.jsx)(lucide_react_1.X, { className: "size-4" }) })] }), showHistory ? ((0, jsx_runtime_1.jsx)("div", { className: "min-h-0 flex-1 overflow-y-auto", children: (0, jsx_runtime_1.jsx)(ask_ai_history_js_1.AskAiHistory, { refreshKey: writeCount, activeConversationId: conversationId, onOpenConversation: openConversation }) })) : ((0, jsx_runtime_1.jsxs)("div", { className: "flex-1 space-y-3 overflow-y-auto p-4", children: [turns.length === 0 && ((0, jsx_runtime_1.jsxs)("div", { className: "space-y-3", children: [(0, jsx_runtime_1.jsx)("p", { className: "text-sm text-muted", children: hint }), currentScreen?.suggestions?.length ? ((0, jsx_runtime_1.jsx)("div", { className: "flex flex-wrap gap-1.5", children: currentScreen.suggestions.map((suggestion) => ((0, jsx_runtime_1.jsx)(react_2.Button, { size: "sm", variant: "secondary", className: "h-auto rounded-full px-2.5 py-1 text-start text-xs whitespace-normal", isDisabled: isBusy, onPress: () => void send(suggestion), children: suggestion }, suggestion))) })) : null] })), rendered, isBusy && lastTurn?.role === "user" && ((0, jsx_runtime_1.jsxs)("div", { className: "rounded-md border border-border bg-accent/5 p-2.5 text-sm", children: [(0, jsx_runtime_1.jsx)("p", { className: "mb-1 text-[11px] font-semibold tracking-wide text-muted uppercase", children: assistantName }), (0, jsx_runtime_1.jsx)(ThinkingShimmer, {})] })), error && (0, jsx_runtime_1.jsx)("p", { className: "text-xs text-danger", children: error }), (0, jsx_runtime_1.jsx)("div", { ref: bottomRef })] })), (0, jsx_runtime_1.jsxs)("form", { onSubmit: handleSubmit, className: "flex gap-2 border-t border-border p-3", children: [(0, jsx_runtime_1.jsxs)(react_2.TextField, { variant: "secondary", className: "flex-1", children: [(0, jsx_runtime_1.jsx)(react_2.Label, { className: "sr-only", children: placeholder }), (0, jsx_runtime_1.jsx)(react_2.Input, { placeholder: placeholder, value: input, onChange: (event) => setInput(event.currentTarget.value), disabled: isBusy })] }), isBusy ? ((0, jsx_runtime_1.jsx)(react_2.Button, { type: "button", isIconOnly: true, variant: "secondary", "aria-label": "Stop generating", onPress: stop, children: (0, jsx_runtime_1.jsx)(lucide_react_1.Square, { className: "size-3.5" }) })) : ((0, jsx_runtime_1.jsx)(react_2.Button, { type: "submit", isIconOnly: true, variant: "primary", "aria-label": "Send", isDisabled: !input.trim(), children: (0, jsx_runtime_1.jsx)(lucide_react_1.Send, { className: "size-3.5" }) }))] })] }) })] }));
 }
 /** Hoisted for the same reference-equality reason as `ANIMATED` - Streamdown compares it by identity. */
 const LINK_SAFETY = { enabled: false };
+/**
+ * A fresh conversation id.
+ *
+ * `crypto.randomUUID` where it exists, and it usually does - but it is gated on
+ * a *secure context*, so it is simply absent on an `http://` origin that is not
+ * localhost. That is somebody's LAN dev server or a staging box on a bare IP,
+ * and a panel that throws there rather than chatting would be a poor trade for
+ * four lines. The fallback is not cryptographically strong and does not need to
+ * be: the id selects among the caller's own conversations and grants nothing -
+ * Connect refuses one belonging to another user or another application - so its
+ * only real job is not to collide with itself.
+ */
+function newConversationId() {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+        return crypto.randomUUID();
+    }
+    return `c-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+}

package/dist/cjs/client/provider.js

@@ -108,9 +108,9 @@ function ConnectProvider({ clientId = "", basePath = "/api/connect", redirectUri
         cache.current.set(key, pending);
         return pending;
     }, [basePath, fetchImpl]);
-    const mutateResource = (0, react_1.useCallback)(async (path, body) => {
+    const mutateResource = (0, react_1.useCallback)(async (path, body, method = "POST") => {
         const response = await (fetchImpl ?? globalThis.fetch)(`${basePath}${path}`, {
-            method: "POST",
+            method,
             credentials: "same-origin",
             headers: {
                 accept: "application/json",

package/dist/cjs/server/client.js

@@ -11,6 +11,7 @@ const scheduling_js_1 = require("./resources/scheduling.js");
 const contacts_js_1 = require("./resources/contacts.js");
 const channels_js_1 = require("./resources/channels.js");
 const calls_js_1 = require("./resources/calls.js");
+const conversations_js_1 = require("./resources/conversations.js");
 const kv_js_1 = require("./resources/kv.js");
 const billing_js_1 = require("./resources/billing.js");
 const drive_js_1 = require("./resources/drive.js");
@@ -92,6 +93,8 @@ class ConnectClient {
     channels;
     /** The calls that arrived on those channels, with their transcripts. */
     calls;
+    /** The message threads a subscribing workspace's agents are holding. */
+    conversations;
     /** RAG chat and structured extraction. */
     ai;
     enrichment;
@@ -145,6 +148,7 @@ class ConnectClient {
         this.contacts = new contacts_js_1.ContactsResource(transport);
         this.channels = new channels_js_1.ChannelsResource(transport);
         this.calls = new calls_js_1.CallsResource(transport);
+        this.conversations = new conversations_js_1.ConversationsResource(transport);
         this.ai = new ai_js_1.AiResource(transport);
         this.enrichment = new enrichment_js_1.EnrichmentResource(transport);
         this.data = new data_js_1.DataResource(transport);
@@ -161,4 +165,4 @@ class ConnectClient {
 }
 exports.ConnectClient = ConnectClient;
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-exports.SDK_VERSION = "0.28.0";
+exports.SDK_VERSION = "0.30.0";

package/dist/cjs/server/handler.js

@@ -391,6 +391,12 @@ function createConnectHandler(options) {
                 // decision, so there is nothing for this layer to check more strictly.
                 screenContext: body.screenContext,
                 screens: body.screens,
+                // The browser's own id for this conversation, so the turn is stored
+                // and can be reopened. Safe to relay: it decides *which* of the
+                // caller's own conversations is written to, never whose - Connect
+                // refuses an id belonging to another user or another application, and
+                // the owner comes from `asUser` below.
+                ...(typeof body.conversationId === "string" ? { conversationId: body.conversationId } : {}),
                 // Connect re-derives the workspace from this token, so the line above
                 // is belt to its braces - the browser cannot reach another tenant's
                 // Context Index even if this route were changed to trust the request.
@@ -409,6 +415,75 @@ function createConnectHandler(options) {
                 },
             });
         },
+        /**
+         * Ask AI history - the list, one transcript, and a deletion.
+         *
+         * The same rule as every other route: the user comes from the caller's own
+         * session, forwarded as `asUser`, and Connect reads both the person and
+         * the workspace from it. Nothing here takes an owner from the request, so
+         * a browser cannot page through anybody else's conversations - which
+         * matters more here than on most routes, because a transcript is the most
+         * candid record this API holds of what somebody was trying to do.
+         *
+         * The id is the only thing a browser supplies. It selects among the
+         * caller's own conversations and nothing more: an id belonging to another
+         * user is a 404, and one belonging to another application the same, so a
+         * shared workspace's two products cannot read each other's.
+         *
+         * It travels as `?id=` rather than as a path segment, and the store routes
+         * are why. This table is keyed by an exact `METHOD /path` string; the only
+         * thing that matches a *prefix* is `isStoreRoute`, kept to a closed list
+         * precisely so the bridge cannot drift into a generic proxy. Widening that
+         * matcher for one more resource would be the first step of exactly that
+         * drift, so the id goes in the query and the route keys stay exact.
+         *
+         * `requireToken` rather than `requireWorkspace`: Connect resolves the
+         * workspace from the token itself and refuses a staff session there, so
+         * the extra identity round trip would buy a differently-worded 403 and
+         * nothing else.
+         */
+        "GET /ai/conversations": async (request) => {
+            const url = new URL(request.url);
+            const limit = url.searchParams.get("limit");
+            const cursor = url.searchParams.get("cursor");
+            return json(await client.ai.listConversations({
+                asUser: await requireToken(request),
+                // Forwarded only when present, so Connect's own defaults apply
+                // rather than this layer inventing a second set of them.
+                ...(limit !== null ? { limit: Number(limit) } : {}),
+                ...(cursor ? { cursor } : {}),
+            }));
+        },
+        "GET /ai/conversation": async (request) => {
+            const conversationId = new URL(request.url).searchParams.get("id");
+            if (!conversationId) {
+                throw new errors_js_1.ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "id is required",
+                    endpoint: "GET /ai/conversation",
+                });
+            }
+            return json(await client.ai.getConversation({
+                conversationId,
+                asUser: await requireToken(request),
+            }));
+        },
+        "DELETE /ai/conversation": async (request) => {
+            const conversationId = new URL(request.url).searchParams.get("id");
+            if (!conversationId) {
+                throw new errors_js_1.ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "id is required",
+                    endpoint: "DELETE /ai/conversation",
+                });
+            }
+            return json(await client.ai.deleteConversation({
+                conversationId,
+                asUser: await requireToken(request),
+            }));
+        },
         /**
          * The store, forwarded.
          *