@blocksdiy/react-common 1.52.1 → 1.53.0

package/dist/hooks/agent-conversation-context.d.ts

@@ -27,6 +27,19 @@ export interface AgentConversationProviderProps extends Pick<UseAgentThreadsOpti
     chat: AgentConversationChat;
     children?: ReactNode;
 }
+/**
+ * The Root over the agent's whole index: the sidebar's list under its filters, and the open
+ * conversation's bridge to the chat. The agent-layout registry item renders it.
+ */
 export declare function AgentConversationProvider({ agentId, conversation, isDraft, chat, token, headers, baseUrl, children, }: AgentConversationProviderProps): import("react").JSX.Element;
+export type AgentThreadConversationProviderProps = AgentConversationProviderProps;
+/**
+ * The Root over ONE conversation, with no index: the same bridge to the chat, fed by the
+ * single-conversation reader (useAgentThread) — which costs nothing beside a mounted index for
+ * the agent, one read otherwise, and nothing for a draft. For a surface that shows a conversation
+ * without the agent's list (the floating agent chat). The context's `threads` lists that one
+ * row; its filters are inert.
+ */
+export declare function AgentThreadConversationProvider({ agentId, conversation, isDraft, chat, token, headers, baseUrl, children, }: AgentThreadConversationProviderProps): import("react").JSX.Element;
 export declare const useAgentConversationContext: () => AgentConversationContextValue;
 //# sourceMappingURL=agent-conversation-context.d.ts.map

package/dist/hooks/agent-conversation-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-conversation-context.d.ts","sourceRoot":"","sources":["../../src/hooks/agent-conversation-context.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAiB,KAAK,SAAS,EAAwB,MAAM,OAAO,CAAC;AAE5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAEzB,KAAK,0BAA0B,EAChC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAmB,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE/G,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,sBAAsB,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;AAEnF,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,oBAAoB,CAAC;IACnC,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,iHAAiH;IACjH,OAAO,EAAE,qBAAqB,CAAC;IAC/B,gGAAgG;IAChG,GAAG,EAAE,eAAe,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,UAAU,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAClD,gBAAgB,EAAE,OAAO,CAAC;IAC1B,uFAAuF;IACvF,iBAAiB,EAAE,0BAA0B,CAAC,mBAAmB,CAAC,CAAC;CACpE;AAID,MAAM,WAAW,8BAA+B,SAAQ,IAAI,CAAC,sBAAsB,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IACnH,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,oBAAoB,CAAC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,IAAI,EAAE,qBAAqB,CAAC;IAC5B,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,wBAAgB,yBAAyB,CAAC,EACxC,OAAO,EACP,YAAY,EACZ,OAAO,EACP,IAAI,EACJ,KAAK,EACL,OAAO,EACP,OAAO,EACP,QAAQ,GACT,EAAE,8BAA8B,+BA4BhC;AAED,eAAO,MAAM,2BAA2B,QAAO,6BAM9C,CAAC"}
+{"version":3,"file":"agent-conversation-context.d.ts","sourceRoot":"","sources":["../../src/hooks/agent-conversation-context.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAiB,KAAK,SAAS,EAAwB,MAAM,OAAO,CAAC;AAE5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAEzB,KAAK,0BAA0B,EAChC,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAmB,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE/G,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,sBAAsB,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;AAEnF,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,oBAAoB,CAAC;IACnC,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,iHAAiH;IACjH,OAAO,EAAE,qBAAqB,CAAC;IAC/B,gGAAgG;IAChG,GAAG,EAAE,eAAe,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,UAAU,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAClD,gBAAgB,EAAE,OAAO,CAAC;IAC1B,uFAAuF;IACvF,iBAAiB,EAAE,0BAA0B,CAAC,mBAAmB,CAAC,CAAC;CACpE;AAID,MAAM,WAAW,8BAA+B,SAAQ,IAAI,CAAC,sBAAsB,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IACnH,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,oBAAoB,CAAC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,IAAI,EAAE,qBAAqB,CAAC;IAC5B,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,OAAO,EACP,YAAY,EACZ,OAAO,EACP,IAAI,EACJ,KAAK,EACL,OAAO,EACP,OAAO,EACP,QAAQ,GACT,EAAE,8BAA8B,+BAgBhC;AAED,MAAM,MAAM,oCAAoC,GAAG,8BAA8B,CAAC;AAKlF;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAAC,EAC9C,OAAO,EACP,YAAY,EACZ,OAAO,EACP,IAAI,EACJ,KAAK,EACL,OAAO,EACP,OAAO,EACP,QAAQ,GACT,EAAE,oCAAoC,+BAetC;AA2CD,eAAO,MAAM,2BAA2B,QAAO,6BAQ9C,CAAC"}

package/dist/hooks/agent-conversation-context.js

@@ -5,11 +5,32 @@ import { jsx as _jsx } from "react/jsx-runtime";
 // agent-layout registry item renders it; a custom UI over the same behaviour can too.
 import { createContext, useContext, useState } from "react";
 import { useAgentConversation, } from "./use-agent-conversation.js";
+import { useAgentThread } from "./use-agent-thread.js";
 import { useAgentThreads } from "./use-agent-threads.js";
 const AgentConversationContext = createContext(null);
+/**
+ * The Root over the agent's whole index: the sidebar's list under its filters, and the open
+ * conversation's bridge to the chat. The agent-layout registry item renders it.
+ */
 export function AgentConversationProvider({ agentId, conversation, isDraft, chat, token, headers, baseUrl, children, }) {
     const [filters, setFilters] = useState({});
     const threads = useAgentThreads({ agentId, status: filters.status, source: filters.source, token, headers, baseUrl });
+    return (_jsx(AgentConversationRoot, { agentId: agentId, conversation: conversation, isDraft: isDraft, chat: chat, threads: threads, filters: filters, setFilters: setFilters, children: children }));
+}
+const NO_FILTERS = {};
+const noFilters = () => undefined;
+/**
+ * The Root over ONE conversation, with no index: the same bridge to the chat, fed by the
+ * single-conversation reader (useAgentThread) — which costs nothing beside a mounted index for
+ * the agent, one read otherwise, and nothing for a draft. For a surface that shows a conversation
+ * without the agent's list (the floating agent chat). The context's `threads` lists that one
+ * row; its filters are inert.
+ */
+export function AgentThreadConversationProvider({ agentId, conversation, isDraft, chat, token, headers, baseUrl, children, }) {
+    const threads = useAgentThread({ agentId, conversation, isDraft, token, headers, baseUrl });
+    return (_jsx(AgentConversationRoot, { agentId: agentId, conversation: conversation, isDraft: isDraft, chat: chat, threads: threads, filters: NO_FILTERS, setFilters: noFilters, children: children }));
+}
+function AgentConversationRoot({ agentId, conversation, isDraft, chat, threads, filters, setFilters, children, }) {
     const { row, isStandIn, renameThread, notifyMessageSent } = useAgentConversation({
         threads,
         agentId,
@@ -33,7 +54,7 @@ export function AgentConversationProvider({ agentId, conversation, isDraft, chat
 export const useAgentConversationContext = () => {
     const context = useContext(AgentConversationContext);
     if (!context) {
-        throw new Error("useAgentConversationContext must be used within <AgentConversationProvider>.");
+        throw new Error("useAgentConversationContext must be used within <AgentConversationProvider> or <AgentThreadConversationProvider>.");
     }
     return context;
 };

package/dist/hooks/agent-thread-store.d.ts

@@ -0,0 +1,62 @@
+import { type AgentThreadItem, type RemovedAgentThread } from "./agent-thread-live-update.js";
+export declare const AGENT_THREAD_UPDATED = "AGENT_THREAD_UPDATED";
+export type AgentThreadStoreEvent = {
+    kind: "upsert";
+    thread: AgentThreadItem;
+} | {
+    kind: "removed";
+    removed: RemovedAgentThread;
+}
+/**
+ * The cache may have changed (an index walk or page landed rows), or the index stopped
+ * walking (done, failed, or unmounted): readers waiting on the index re-check it.
+ */
+ | {
+    kind: "primed";
+};
+export type AgentThreadStoreListener = (event: AgentThreadStoreEvent) => void;
+/** Fetch one row by identity — the single-thread read; supplied by the acquiring reader (it holds the auth). */
+export type AgentThreadFetcher = (conversation: Pick<AgentThreadItem, "chatId" | "chatThreadId">) => Promise<AgentThreadItem>;
+export interface AgentThreadStore {
+    readonly agentId: string;
+    /** The latest row known for a conversation (`agentThreadKey`), from any reader or the wire. */
+    getRow(key: string): AgentThreadItem | undefined;
+    /** An index reader is mounted and walking: its pages will prime the cache, so wait for them. */
+    readonly isIndexLoading: boolean;
+    subscribe(listener: AgentThreadStoreListener): () => void;
+    /** Remember rows a reader fetched or walked, for everyone else; announces `primed`. */
+    prime(rows: readonly AgentThreadItem[]): void;
+}
+/** The websocket seam, injectable for tests. */
+export interface AgentThreadStoreTransport {
+    listen(event: string, handler: (data: unknown) => Promise<void>, options: {
+        filter: {
+            agentId: string;
+        };
+    }): void;
+    unlisten(event: string, handler: (data: unknown) => Promise<void>): void;
+}
+/**
+ * The cache's one rule: a row older than the cached one (by lastActivityAt) is stale and
+ * dropped; equal passes, since renames keep lastActivityAt. The same rule the index applies.
+ */
+export declare const isNewerOrSameRow: (incoming: AgentThreadItem, cached: AgentThreadItem | undefined) => boolean;
+/** The wire payload's identity, or null for a payload that names no conversation. */
+export declare const agentThreadEventIdentity: (data: unknown) => RemovedAgentThread | null;
+declare const createRegistry: (transport: AgentThreadStoreTransport) => {
+    acquire: (agentId: string, options: {
+        fetchThread: AgentThreadFetcher;
+        isIndex?: boolean;
+    }) => {
+        store: AgentThreadStore;
+        setIndexLoading: (loading: boolean) => void;
+        release: () => void;
+    };
+    size: () => number;
+};
+export type AgentThreadStoreRegistry = ReturnType<typeof createRegistry>;
+/** A registry over an injected transport — for tests. Production uses {@link acquireAgentThreadStore}. */
+export declare const createAgentThreadStoreRegistry: (transport: AgentThreadStoreTransport) => AgentThreadStoreRegistry;
+export declare const acquireAgentThreadStore: AgentThreadStoreRegistry["acquire"];
+export {};
+//# sourceMappingURL=agent-thread-store.d.ts.map

package/dist/hooks/agent-thread-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-thread-store.d.ts","sourceRoot":"","sources":["../../src/hooks/agent-thread-store.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,KAAK,eAAe,EAGpB,KAAK,kBAAkB,EACxB,MAAM,4BAA4B,CAAC;AAEpC,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE;AAClD;;;GAGG;GACD;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEvB,MAAM,MAAM,wBAAwB,GAAG,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAE9E,gHAAgH;AAChH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,YAAY,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,cAAc,CAAC,KAC3D,OAAO,CAAC,eAAe,CAAC,CAAC;AAE9B,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+FAA+F;IAC/F,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IACjD,gGAAgG;IAChG,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,SAAS,CAAC,QAAQ,EAAE,wBAAwB,GAAG,MAAM,IAAI,CAAC;IAC1D,uFAAuF;IACvF,KAAK,CAAC,IAAI,EAAE,SAAS,eAAe,EAAE,GAAG,IAAI,CAAC;CAC/C;AAED,gDAAgD;AAChD,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE;QAAE,MAAM,EAAE;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,IAAI,CAAC;IACjH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC1E;AAOD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,UAAU,eAAe,EAAE,QAAQ,eAAe,GAAG,SAAS,KAAG,OACjB,CAAC;AAElF,qFAAqF;AACrF,eAAO,MAAM,wBAAwB,GAAI,MAAM,OAAO,KAAG,kBAAkB,GAAG,IAO7E,CAAC;AA+GF,QAAA,MAAM,cAAc,GAAI,WAAW,yBAAyB;uBAQ/C,MAAM,WACN;QAAE,WAAW,EAAE,kBAAkB,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,KAC9D;QAAE,KAAK,EAAE,gBAAgB,CAAC;QAAC,eAAe,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE;;CAoCjG,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AAEzE,0GAA0G;AAC1G,eAAO,MAAM,8BAA8B,GAAI,WAAW,yBAAyB,KAAG,wBAC3D,CAAC;AAO5B,eAAO,MAAM,uBAAuB,EAAE,wBAAwB,CAAC,SAAS,CAC7B,CAAC"}

package/dist/hooks/agent-thread-store.js

@@ -0,0 +1,170 @@
+// One live subscription and one row cache per agent, shared by every reader in the app: the
+// conversation index (useAgentThreads) and the single-conversation reader (useAgentThread).
+// Readers acquire the store for an agent and release it when they unmount; the first acquire
+// opens the websocket listener, the last release closes it and drops the rows. The store
+// resolves a thin event payload to a full row once, for everyone, and remembers every row it
+// sees — a list walk primes it, so a single-conversation reader mounted beside the index never
+// fetches what the index already has.
+import { websocketsService } from "@blocksdiy/blocks-client-api/websocketService";
+import { agentThreadKey, isAgentThreadItem, } from "./agent-thread-live-update.js";
+export const AGENT_THREAD_UPDATED = "AGENT_THREAD_UPDATED";
+const sortTime = (iso) => {
+    const parsed = new Date(iso).getTime();
+    return Number.isNaN(parsed) ? 0 : parsed;
+};
+/**
+ * The cache's one rule: a row older than the cached one (by lastActivityAt) is stale and
+ * dropped; equal passes, since renames keep lastActivityAt. The same rule the index applies.
+ */
+export const isNewerOrSameRow = (incoming, cached) => !cached || sortTime(incoming.lastActivityAt) >= sortTime(cached.lastActivityAt);
+/** The wire payload's identity, or null for a payload that names no conversation. */
+export const agentThreadEventIdentity = (data) => {
+    const event = data;
+    const raw = event?.thread;
+    if (typeof raw?.chatId !== "string" || typeof raw.chatThreadId !== "string") {
+        return null;
+    }
+    return { chatId: raw.chatId, chatThreadId: raw.chatThreadId, runningRunId: raw.runningRunId };
+};
+class AgentThreadStoreImpl {
+    agentId;
+    transport;
+    rows = new Map();
+    listeners = new Set();
+    /** The most recent reader's fetcher — all readers in one app share auth, so any of them serves. */
+    fetchThread = null;
+    indexLoadingCount = 0;
+    constructor(agentId, transport) {
+        this.agentId = agentId;
+        this.transport = transport;
+    }
+    get isIndexLoading() {
+        return this.indexLoadingCount > 0;
+    }
+    /**
+     * An index reader starts or stops walking. Back at idle, readers waiting on the index are
+     * told to re-check: a failed walk, or an index unmounting mid-walk, primes nothing, and they
+     * must not wait forever.
+     */
+    setIndexLoading(loading) {
+        this.indexLoadingCount += loading ? 1 : -1;
+        if (this.indexLoadingCount === 0) {
+            this.emit({ kind: "primed" });
+        }
+    }
+    getRow(key) {
+        return this.rows.get(key);
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    prime(rows) {
+        for (const row of rows) {
+            this.remember(row);
+        }
+        this.emit({ kind: "primed" });
+    }
+    open() {
+        this.transport.listen(AGENT_THREAD_UPDATED, this.onEvent, { filter: { agentId: this.agentId } });
+    }
+    close() {
+        this.transport.unlisten(AGENT_THREAD_UPDATED, this.onEvent);
+        this.rows.clear();
+        this.listeners.clear();
+    }
+    remember(row) {
+        const key = agentThreadKey(row);
+        if (!isNewerOrSameRow(row, this.rows.get(key))) {
+            return false;
+        }
+        this.rows.set(key, row);
+        return true;
+    }
+    emit(event) {
+        for (const listener of [...this.listeners]) {
+            listener(event);
+        }
+    }
+    onEvent = (data) => this.handleEvent(data);
+    async handleEvent(data) {
+        try {
+            const identity = agentThreadEventIdentity(data);
+            if (!identity) {
+                return;
+            }
+            const event = data;
+            if (event.removed) {
+                // A ghost thread (a run that ended before any turn) leaves the cache; a row with turns
+                // stays — the index decides for itself, with its own rule, whether to drop the listing.
+                const cached = this.rows.get(agentThreadKey(identity));
+                if (cached && cached.turnCount === 0) {
+                    this.rows.delete(agentThreadKey(identity));
+                }
+                this.emit({ kind: "removed", removed: identity });
+                return;
+            }
+            // A thin payload (an older server) resolves to the full row ONCE here, not per reader.
+            const incoming = isAgentThreadItem(event.thread) ? event.thread : await this.fetchThread?.(identity);
+            if (!incoming) {
+                return;
+            }
+            this.remember(incoming);
+            this.emit({ kind: "upsert", thread: incoming });
+        }
+        catch {
+            // Best-effort: a websocket handler must not reject.
+        }
+    }
+}
+const createRegistry = (transport) => {
+    const entries = new Map();
+    /**
+     * A reader's handle on the agent's store. `isIndex` marks the conversation index: while any
+     * index reader is walking, single-conversation readers wait for its pages instead of fetching.
+     */
+    const acquire = (agentId, options) => {
+        let entry = entries.get(agentId);
+        if (!entry) {
+            const store = new AgentThreadStoreImpl(agentId, transport);
+            store.open();
+            entry = { store, refCount: 0, indexReaders: 0 };
+            entries.set(agentId, entry);
+        }
+        const current = entry;
+        current.refCount += 1;
+        current.store.fetchThread = options.fetchThread;
+        let loading = false;
+        const setIndexLoading = (next) => {
+            if (next === loading) {
+                return;
+            }
+            loading = next;
+            current.store.setIndexLoading(next);
+        };
+        let released = false;
+        const release = () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            setIndexLoading(false);
+            current.refCount -= 1;
+            if (current.refCount === 0 && entries.get(agentId) === current) {
+                current.store.close();
+                entries.delete(agentId);
+            }
+        };
+        return { store: current.store, setIndexLoading, release };
+    };
+    return { acquire, size: () => entries.size };
+};
+/** A registry over an injected transport — for tests. Production uses {@link acquireAgentThreadStore}. */
+export const createAgentThreadStoreRegistry = (transport) => createRegistry(transport);
+const defaultRegistry = createRegistry({
+    listen: (event, handler, options) => websocketsService.listen(event, handler, options),
+    unlisten: (event, handler) => websocketsService.unlisten(event, handler),
+});
+export const acquireAgentThreadStore = (agentId, options) => defaultRegistry.acquire(agentId, options);

package/dist/hooks/floating-agent-chat.d.ts

@@ -0,0 +1,77 @@
+import type { AgentConversationRef } from "./use-agent-conversation.js";
+/** The agent-chat handle an opener holds (`useAgentChat(<Agent>ChatAgentChat)` in an app). */
+export interface FloatingAgentChatHandle {
+    getAgentChatComponentProps(): {
+        agentChatId: string;
+        token?: string;
+        isAdmin?: boolean;
+    };
+}
+/** What to open: a conversation (the `chatId` + `chatThreadId` pair), or the new chat. */
+export type FloatingAgentChatTarget = AgentConversationRef | "new";
+/**
+ * Where the panel's expand goes for the conversation it shows — the opener knows the full route
+ * (an agent mini-app's thread page); `null` hides the expand control. Never asked for a draft:
+ * an unsent new chat has no page, so the panel shows no expand for it.
+ */
+export type FloatingAgentChatExpandHref = (conversation: AgentConversationRef) => string | null;
+export interface FloatingAgentChatOpenOptions<Handle extends FloatingAgentChatHandle = FloatingAgentChatHandle> {
+    /** The agent to talk to — the surface's own agent-chat block. */
+    agentChat: Handle;
+    /** A conversation to pick up, or the new chat (the default). */
+    target?: FloatingAgentChatTarget;
+    expandHref?: FloatingAgentChatExpandHref;
+    /** Extra context handed to the agent on every turn (like `AgentChat`'s `chatContext`). */
+    chatContext?: unknown;
+}
+/** The open options with the ids resolved from the handle. */
+export interface FloatingAgentChatOpenRequest<Handle extends FloatingAgentChatHandle = FloatingAgentChatHandle> extends Omit<FloatingAgentChatOpenOptions<Handle>, "target"> {
+    agentChatId: string;
+    /** The chat the agent's own conversations live under (agentInboxChatId). */
+    ownChatId: string;
+    target: FloatingAgentChatTarget;
+}
+export interface FloatingAgentChatState<Handle extends FloatingAgentChatHandle = FloatingAgentChatHandle> {
+    agentChat: Handle;
+    agentChatId: string;
+    ownChatId: string;
+    conversation: AgentConversationRef;
+    /** The draft's thread id — the new chat, until its first send turns it into a thread. */
+    draftThreadId: string;
+    draftSent: boolean;
+    expandHref?: FloatingAgentChatExpandHref;
+    chatContext?: unknown;
+}
+/** The panel shows the new chat, nothing sent on it yet. */
+export declare const isFloatingAgentChatDraft: (state: FloatingAgentChatState) => boolean;
+/**
+ * The state after an open. Within one agent the draft's bookkeeping carries over — the new chat
+ * is kept while untouched, stands by while a thread is open, and is minted afresh once sent;
+ * another agent starts clean. Opening what is already shown changes nothing but the opener's
+ * `expandHref` / `chatContext`.
+ */
+export declare const floatingAgentChatAfterOpen: <Handle extends FloatingAgentChatHandle>(prev: FloatingAgentChatState<Handle> | null, request: FloatingAgentChatOpenRequest<Handle>, mintThreadId: () => string) => FloatingAgentChatState<Handle>;
+/** After the first send on the draft; unchanged when the draft is not what is shown. */
+export declare const floatingAgentChatAfterDraftSent: <Handle extends FloatingAgentChatHandle>(prev: FloatingAgentChatState<Handle> | null) => FloatingAgentChatState<Handle> | null;
+export interface UseFloatingAgentChatControllerResult<Handle extends FloatingAgentChatHandle = FloatingAgentChatHandle> {
+    /** What the panel shows; null while it is closed. */
+    state: FloatingAgentChatState<Handle> | null;
+    isOpen: boolean;
+    /** Open (or re-point) the panel. The same agent's draft carries over; another agent starts clean. */
+    open: (options: FloatingAgentChatOpenOptions<Handle>) => void;
+    close: () => void;
+    /**
+     * Close the panel when it shows one of this agent's conversations — for a surface that puts
+     * that agent's full transcript on screen (an agent mini-app's conversation routes).
+     */
+    closeForAgent: (agentChatId: string) => void;
+    /** The panel's seam: the draft's first send made it a thread. */
+    markDraftSent: () => void;
+}
+/**
+ * The floating agent chat's state and transitions, for ONE provider at the app's root. Remembers
+ * what had focus on the open that showed the panel (a sidebar row, an "Ask" button) and hands it
+ * back on close, so keyboard users land where they were.
+ */
+export declare const useFloatingAgentChatController: <Handle extends FloatingAgentChatHandle = FloatingAgentChatHandle>() => UseFloatingAgentChatControllerResult<Handle>;
+//# sourceMappingURL=floating-agent-chat.d.ts.map

package/dist/hooks/floating-agent-chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"floating-agent-chat.d.ts","sourceRoot":"","sources":["../../src/hooks/floating-agent-chat.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAGrE,8FAA8F;AAC9F,MAAM,WAAW,uBAAuB;IACtC,0BAA0B,IAAI;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1F;AAED,0FAA0F;AAC1F,MAAM,MAAM,uBAAuB,GAAG,oBAAoB,GAAG,KAAK,CAAC;AAEnE;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,YAAY,EAAE,oBAAoB,KAAK,MAAM,GAAG,IAAI,CAAC;AAEhG,MAAM,WAAW,4BAA4B,CAAC,MAAM,SAAS,uBAAuB,GAAG,uBAAuB;IAC5G,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,UAAU,CAAC,EAAE,2BAA2B,CAAC;IACzC,0FAA0F;IAC1F,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,8DAA8D;AAC9D,MAAM,WAAW,4BAA4B,CAC3C,MAAM,SAAS,uBAAuB,GAAG,uBAAuB,CAChE,SAAQ,IAAI,CAAC,4BAA4B,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,uBAAuB,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB,CAAC,MAAM,SAAS,uBAAuB,GAAG,uBAAuB;IACtG,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,oBAAoB,CAAC;IACnC,yFAAyF;IACzF,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,2BAA2B,CAAC;IACzC,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,4DAA4D;AAC5D,eAAO,MAAM,wBAAwB,GAAI,OAAO,sBAAsB,KAAG,OACI,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,GAAI,MAAM,SAAS,uBAAuB,EAC/E,MAAM,sBAAsB,CAAC,MAAM,CAAC,GAAG,IAAI,EAC3C,SAAS,4BAA4B,CAAC,MAAM,CAAC,EAC7C,cAAc,MAAM,MAAM,KACzB,sBAAsB,CAAC,MAAM,CAwB/B,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,+BAA+B,GAAI,MAAM,SAAS,uBAAuB,EACpF,MAAM,sBAAsB,CAAC,MAAM,CAAC,GAAG,IAAI,KAC1C,sBAAsB,CAAC,MAAM,CAAC,GAAG,IAC0C,CAAC;AAE/E,MAAM,WAAW,oCAAoC,CACnD,MAAM,SAAS,uBAAuB,GAAG,uBAAuB;IAEhE,qDAAqD;IACrD,KAAK,EAAE,sBAAsB,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC7C,MAAM,EAAE,OAAO,CAAC;IAChB,qGAAqG;IACrG,IAAI,EAAE,CAAC,OAAO,EAAE,4BAA4B,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAC9D,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;OAGG;IACH,aAAa,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,iEAAiE;IACjE,aAAa,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,GACzC,MAAM,SAAS,uBAAuB,GAAG,uBAAuB,OAC7D,oCAAoC,CAAC,MAAM,CAuD/C,CAAC"}

package/dist/hooks/floating-agent-chat.js

@@ -0,0 +1,89 @@
+// The floating agent chat's state, headless: what the panel shows (which agent, which
+// conversation), the draft the new chat is until its first send, and the opener that gets focus
+// back on close. The agent-chat registry item renders it. Mirrors the conversation selection
+// rules of useAgentConversationSelection: a new chat is a draft minted here and listed nowhere
+// until the first send; "New chat" on an untouched draft keeps it; a thread opened beside it
+// leaves it standing by. The reducers are pure and tested; the hook is the thin React shell.
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { agentInboxChatId } from "./use-agent-threads.js";
+/** The panel shows the new chat, nothing sent on it yet. */
+export const isFloatingAgentChatDraft = (state) => state.conversation.chatThreadId === state.draftThreadId && !state.draftSent;
+/**
+ * The state after an open. Within one agent the draft's bookkeeping carries over — the new chat
+ * is kept while untouched, stands by while a thread is open, and is minted afresh once sent;
+ * another agent starts clean. Opening what is already shown changes nothing but the opener's
+ * `expandHref` / `chatContext`.
+ */
+export const floatingAgentChatAfterOpen = (prev, request, mintThreadId) => {
+    const sameAgent = prev !== null && prev.agentChatId === request.agentChatId;
+    const draft = sameAgent && prev
+        ? { draftThreadId: prev.draftThreadId, draftSent: prev.draftSent }
+        : { draftThreadId: mintThreadId(), draftSent: false };
+    const base = {
+        agentChat: request.agentChat,
+        agentChatId: request.agentChatId,
+        ownChatId: request.ownChatId,
+        expandHref: request.expandHref,
+        chatContext: request.chatContext,
+    };
+    if (request.target !== "new") {
+        return { ...base, ...draft, conversation: request.target };
+    }
+    // A sent draft is a thread now; the new chat needs a fresh one.
+    const draftThreadId = draft.draftSent ? mintThreadId() : draft.draftThreadId;
+    return {
+        ...base,
+        draftThreadId,
+        draftSent: false,
+        conversation: { chatId: request.ownChatId, chatThreadId: draftThreadId },
+    };
+};
+/** After the first send on the draft; unchanged when the draft is not what is shown. */
+export const floatingAgentChatAfterDraftSent = (prev) => prev && isFloatingAgentChatDraft(prev) ? { ...prev, draftSent: true } : prev;
+/**
+ * The floating agent chat's state and transitions, for ONE provider at the app's root. Remembers
+ * what had focus on the open that showed the panel (a sidebar row, an "Ask" button) and hands it
+ * back on close, so keyboard users land where they were.
+ */
+export const useFloatingAgentChatController = () => {
+    const [state, setState] = useState(null);
+    const openerRef = useRef(null);
+    // Focus goes back to the opener once the panel is gone — after the close commits, so the
+    // panel's own focused element has left the DOM by then.
+    useEffect(() => {
+        if (state !== null) {
+            return;
+        }
+        const opener = openerRef.current;
+        openerRef.current = null;
+        if (opener?.isConnected) {
+            opener.focus({ preventScroll: true });
+        }
+    }, [state]);
+    const open = useCallback((options) => {
+        const active = typeof document !== "undefined" &&
+            document.activeElement instanceof HTMLElement &&
+            document.activeElement !== document.body
+            ? document.activeElement
+            : null;
+        const { agentChatId } = options.agentChat.getAgentChatComponentProps();
+        setState((prev) => {
+            // Remembered on the open that shows the panel, not on a re-point while it is up.
+            if (prev === null && active) {
+                openerRef.current = active;
+            }
+            return floatingAgentChatAfterOpen(prev, {
+                agentChat: options.agentChat,
+                agentChatId,
+                ownChatId: agentInboxChatId(agentChatId),
+                target: options.target ?? "new",
+                expandHref: options.expandHref,
+                chatContext: options.chatContext,
+            }, () => crypto.randomUUID());
+        });
+    }, []);
+    const close = useCallback(() => setState(null), []);
+    const closeForAgent = useCallback((agentChatId) => setState((prev) => (prev?.agentChatId === agentChatId ? null : prev)), []);
+    const markDraftSent = useCallback(() => setState(floatingAgentChatAfterDraftSent), []);
+    return useMemo(() => ({ state, isOpen: state !== null, open, close, closeForAgent, markDraftSent }), [state, open, close, closeForAgent, markDraftSent]);
+};

package/dist/hooks/use-agent-thread.d.ts

@@ -0,0 +1,67 @@
+import { type AgentThreadItem } from "./agent-thread-live-update.js";
+import { type AgentThreadStore, type AgentThreadStoreEvent } from "./agent-thread-store.js";
+import type { AgentConversationRef } from "./use-agent-conversation.js";
+import { type UseAgentThreadsOptions, type UseAgentThreadsResult } from "./use-agent-threads.js";
+export interface UseAgentThreadOptions extends Pick<UseAgentThreadsOptions, "token" | "headers" | "baseUrl"> {
+    agentId: string;
+    conversation: AgentConversationRef;
+    /**
+     * The conversation is the new chat, nothing sent on it yet: the server has no row for it, so
+     * nothing is read (not on mount, not on `refresh`). Once sent, its row arrives on the wire
+     * like any other — the store is already listening.
+     */
+    isDraft?: boolean;
+}
+export interface UseAgentThreadResult extends UseAgentThreadsResult {
+    /** The conversation's row, or null until read (and for a conversation the server has no row for yet). */
+    thread: AgentThreadItem | null;
+}
+/** The store, as the reader's decisions see it. */
+export type AgentThreadStoreView = Pick<AgentThreadStore, "getRow" | "isIndexLoading">;
+/** What the reader does when it mounts on a conversation. */
+export type SingleThreadMountPlan = {
+    kind: "cached";
+    thread: AgentThreadItem;
+}
+/** A draft: nothing to read; the first send puts its row on the wire. */
+ | {
+    kind: "draft";
+}
+/** An index for the agent is walking: its pages arrive as `primed`; read only if they miss the row. */
+ | {
+    kind: "await-index";
+} | {
+    kind: "read";
+};
+/**
+ * Mount: the store's row when the index already has it; a draft reads nothing; otherwise one
+ * read — deferred while an index is walking, so the two never race for the same row.
+ */
+export declare const singleThreadMountPlan: (store: AgentThreadStoreView, key: string, isDraft: boolean) => SingleThreadMountPlan;
+/** What a store event means for the reader of ONE conversation. */
+export type SingleThreadEventOutcome = {
+    kind: "ignore";
+}
+/** Show this row — the cache's, the newest seen from any reader or the wire, never the raw event's. */
+ | {
+    kind: "row";
+    thread: AgentThreadItem;
+}
+/** The index stopped walking without the row: read it. */
+ | {
+    kind: "read";
+}
+/** The conversation left the wire (a ghost run); a row with turns stays. */
+ | {
+    kind: "removed";
+};
+/**
+ * The cache is the row's source of truth: it keeps the newest row it has seen, so what it holds
+ * is what the surface shows — a stale wire event, or a page an index walked later, never
+ * regresses it. `awaitingIndex`: the mount deferred its read to a walking index.
+ */
+export declare const singleThreadEventOutcome: (event: AgentThreadStoreEvent, store: AgentThreadStoreView, key: string, awaitingIndex: boolean) => SingleThreadEventOutcome;
+/** The single-thread read's "no row" answer — a conversation the server has not seen — as opposed to a failure. */
+export declare const isMissingRowError: (error: unknown) => boolean;
+export declare const useAgentThread: ({ agentId, conversation, isDraft, token, headers, baseUrl, }: UseAgentThreadOptions) => UseAgentThreadResult;
+//# sourceMappingURL=use-agent-thread.d.ts.map

package/dist/hooks/use-agent-thread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-agent-thread.d.ts","sourceRoot":"","sources":["../../src/hooks/use-agent-thread.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,KAAK,eAAe,EAKrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAA2B,KAAK,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAKL,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC3B,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CAAC,sBAAsB,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IAC1G,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,oBAAoB,CAAC;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;IACjE,yGAAyG;IACzG,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;CAChC;AAED,mDAAmD;AACnD,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,gBAAgB,CAAC,CAAC;AAEvF,6DAA6D;AAC7D,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE;AAC7C,yEAAyE;GACvE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE;AACnB,uGAAuG;GACrG;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAChC,OAAO,oBAAoB,EAC3B,KAAK,MAAM,EACX,SAAS,OAAO,KACf,qBASF,CAAC;AAEF,mEAAmE;AACnE,MAAM,MAAM,wBAAwB,GAChC;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE;AACpB,uGAAuG;GACrG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE;AAC1C,0DAA0D;GACxD;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;AAClB,4EAA4E;GAC1E;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,qBAAqB,EAC5B,OAAO,oBAAoB,EAC3B,KAAK,MAAM,EACX,eAAe,OAAO,KACrB,wBAeF,CAAC;AAEF,mHAAmH;AACnH,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,OACgB,CAAC;AAIpE,eAAO,MAAM,cAAc,GAAI,8DAO5B,qBAAqB,KAAG,oBA4J1B,CAAC"}