@blocksdiy/react-common 1.47.0 → 1.49.0

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

@@ -0,0 +1,204 @@
+// Headless state for the conversation an agent surface has open, over the threads index
+// (useAgentThreads) and the chat runtime (useAgentChat): which conversation is selected and
+// how a draft becomes a thread; the conversation's row; and the bridge that keeps the index
+// and the transcript agreeing. UI-free — the agent-layout registry item renders it.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { FEEDBACK_MESSAGE_NAME } from "../utils/composer-message.js";
+import { agentThreadKey } from "./agent-thread-live-update.js";
+export const newDraftSelection = (chatId, draftThreadId = crypto.randomUUID()) => ({
+    conversation: { chatId, chatThreadId: draftThreadId },
+    draftThreadId,
+    draftSent: false,
+});
+/** A draft stands by even when the URL opens a thread: "New chat" from there must not mint twice. */
+export const initialSelection = (ownChatId, urlConversation) => {
+    const draft = newDraftSelection(ownChatId);
+    return urlConversation ? { ...draft, conversation: urlConversation } : draft;
+};
+export const isDraftSelection = ({ conversation, draftThreadId, draftSent }) => conversation.chatThreadId === draftThreadId && !draftSent;
+/** After choosing a thread; the same object when it is already open (no re-render). */
+export const selectionWithThread = (prev, conversation) => agentThreadKey(prev.conversation) === agentThreadKey(conversation) ? prev : { ...prev, conversation };
+/** After "New chat": an untouched draft stays; anything else mints a fresh one. */
+export const selectionWithNewChat = (prev, ownChatId) => (isDraftSelection(prev) ? prev : newDraftSelection(ownChatId));
+/** After the first send on the draft; unchanged when the draft is not the open conversation. */
+export const selectionAfterDraftSent = (prev) => isDraftSelection(prev) ? { ...prev, draftSent: true } : prev;
+/** Identity of a URL target; the selection follows the URL whenever this changes. */
+export const urlSelectionKey = (target) => target === null ? null : target === "new" ? "new" : agentThreadKey(target);
+/**
+ * The open conversation follows the URL — the one source of truth, so choosing a thread is a
+ * navigation, never a call here; the draft is local state.
+ */
+export const useAgentConversationSelection = ({ ownChatId, urlTarget, }) => {
+    const urlConversation = urlTarget !== null && urlTarget !== "new" ? urlTarget : undefined;
+    const [selection, setSelection] = useState(() => initialSelection(ownChatId, urlConversation));
+    const markDraftSent = useCallback(() => setSelection(selectionAfterDraftSent), []);
+    // Synced during render (React's "adjusting state when a prop changes"), so the chat root
+    // below never renders a frame on the previous conversation.
+    const urlKey = urlSelectionKey(urlTarget);
+    const [syncedUrlKey, setSyncedUrlKey] = useState(urlKey);
+    if (syncedUrlKey !== urlKey) {
+        setSyncedUrlKey(urlKey);
+        if (urlConversation) {
+            setSelection((prev) => selectionWithThread(prev, urlConversation));
+        }
+        else if (urlTarget === "new") {
+            setSelection((prev) => selectionWithNewChat(prev, ownChatId));
+        }
+    }
+    return { conversation: selection.conversation, isDraft: isDraftSelection(selection), markDraftSent };
+};
+/* ---- The open conversation's row, and the index ↔ chat bridge ----------------------------- */
+// Mirrors wf-actions-py RUN_STALE_AFTER: the server ends a run still marked this long after it
+// started, ahead of a list read — and publishes nothing for it, so a viewer has to ask.
+export const RUN_STALE_MS = 30 * 60 * 1000;
+// A refresh re-walks every loaded page; refocus is throttled to this.
+const FOCUS_REFRESH_MIN_INTERVAL_MS = 15_000;
+// While a mark stays past the ceiling (this clock may run ahead of the server's), ask again each minute.
+const STALE_RUN_REPOLL_MS = 60_000;
+/** A row for a conversation the index lists nothing for (yet): the draft, or a thread whose row has not landed. */
+export const agentThreadStandIn = (agentId, conversation, isDraft) => {
+    const now = new Date().toISOString();
+    return {
+        agentId,
+        chatId: conversation.chatId,
+        chatThreadId: conversation.chatThreadId,
+        source: "direct_chat",
+        status: "idle",
+        title: null,
+        turnCount: isDraft ? 0 : 1,
+        firstSeenAt: now,
+        lastActivityAt: now,
+    };
+};
+/** When the oldest run mark among `rows` reaches the stale ceiling (epoch ms); null with no mark. */
+export const nextRunStaleAt = (rows) => {
+    let next = null;
+    for (const row of rows) {
+        const startedAt = Date.parse(row.runningSince ?? "");
+        if (Number.isFinite(startedAt) && (next === null || startedAt + RUN_STALE_MS < next)) {
+            next = startedAt + RUN_STALE_MS;
+        }
+    }
+    return next;
+};
+/**
+ * The accounting after a row for `key` reports `turnCount` turns. The first row is a baseline —
+ * the chat replayed it on mount — not a turn to fetch. `turnCount` is server-monotonic, so more
+ * turns than accounted is a turn this client did not make: replayed once nothing is streaming
+ * (a run's own stream is the authoritative view; replaying underneath it would fight its events).
+ */
+export const accountedTurnsAfterRow = (accounted, key, turnCount, isThinking) => {
+    if (!accounted || accounted.key !== key) {
+        return { accounted: { key, turns: turnCount }, replay: false };
+    }
+    if (turnCount <= accounted.turns || isThinking) {
+        return { accounted, replay: false };
+    }
+    return { accounted: { key, turns: turnCount }, replay: true };
+};
+/**
+ * The accounting after this client's own send on `key`: one more turn. A draft's first send
+ * starts the count, so the row that lands for it is read as this send's, not a foreign turn.
+ */
+export const accountedTurnsAfterOwnSend = (accounted, key, isDraft) => {
+    if (accounted && accounted.key === key) {
+        return { key, turns: accounted.turns + 1 };
+    }
+    return isDraft ? { key, turns: 1 } : accounted;
+};
+/**
+ * Keeps the index and the transcript agreeing for the open conversation:
+ * - a run on it this client is not streaming (the listed row's `runningRunId`) reads as the chat's own;
+ * - a turn this client did not send (`turnCount` ahead of what it accounted for) replays the transcript;
+ * - a run mark past the stale ceiling asks the server again (the settle publishes no event);
+ * - refocus re-walks the list (realtime has no replay), throttled.
+ */
+export const useAgentConversation = ({ threads, agentId, conversation, isDraft, chat, }) => {
+    const { threads: rows, refresh, notifyThreadActivity, renameThread: renameListedThread } = threads;
+    const { isThinking, reloadMessages, setRunningElsewhere } = chat;
+    const conversationKey = agentThreadKey(conversation);
+    const listedRow = rows.find((row) => agentThreadKey(row) === conversationKey);
+    // A row a filter hides is remembered, so the open conversation keeps its title. Stored
+    // during render (React's "storing information from previous renders"), not in an effect.
+    const [lastListedRow, setLastListedRow] = useState(null);
+    if (listedRow && listedRow !== lastListedRow) {
+        setLastListedRow(listedRow);
+    }
+    const knownRow = listedRow ?? (lastListedRow && agentThreadKey(lastListedRow) === conversationKey ? lastListedRow : undefined);
+    // Not memoised: a stand-in's stamps are "now", and a send stands its row in with them.
+    const row = knownRow ?? agentThreadStandIn(agentId, conversation, isDraft);
+    const rowRef = useRef(row);
+    useEffect(() => {
+        rowRef.current = row;
+    });
+    const renameThread = useCallback(async (thread, title) => {
+        await renameListedThread(thread, title);
+        const trimmed = title.trim();
+        if (!trimmed) {
+            return;
+        }
+        setLastListedRow((prev) => prev && agentThreadKey(prev) === agentThreadKey(thread) && prev.title !== trimmed
+            ? { ...prev, title: trimmed }
+            : prev);
+    }, [renameListedThread]);
+    // A run elsewhere on this conversation — from the LISTED row only: a row a filter hides gets
+    // no live updates, so a remembered one would outlive its run.
+    const runningElsewhereRunId = listedRow?.runningRunId ?? null;
+    useEffect(() => {
+        setRunningElsewhere?.(runningElsewhereRunId);
+        // Nothing else clears it: told once, the chat would stay shut past this surface's lifetime.
+        return () => setRunningElsewhere?.(null);
+    }, [setRunningElsewhere, runningElsewhereRunId]);
+    // The stale ceiling: ask at the oldest mark's ceiling, then each minute while a mark stays.
+    const nextStaleAt = nextRunStaleAt(rows);
+    useEffect(() => {
+        if (nextStaleAt === null) {
+            return;
+        }
+        let timer;
+        const ask = () => {
+            void refresh();
+            timer = setTimeout(ask, STALE_RUN_REPOLL_MS);
+        };
+        timer = setTimeout(ask, Math.max(nextStaleAt - Date.now(), 0));
+        return () => clearTimeout(timer);
+    }, [nextStaleAt, refresh]);
+    // Realtime has no replay — refocus re-walks the list, throttled.
+    const lastFocusRefreshAtRef = useRef(0);
+    useEffect(() => {
+        const onFocus = () => {
+            const now = Date.now();
+            if (now - lastFocusRefreshAtRef.current < FOCUS_REFRESH_MIN_INTERVAL_MS) {
+                return;
+            }
+            lastFocusRefreshAtRef.current = now;
+            void refresh();
+        };
+        window.addEventListener("focus", onFocus);
+        return () => window.removeEventListener("focus", onFocus);
+    }, [refresh]);
+    // Turns this client did not send (see accountedTurnsAfterRow). `isThinking` is a dependency,
+    // so this runs again the moment a run on the conversation settles.
+    const accountedTurnsRef = useRef(null);
+    useEffect(() => {
+        if (!knownRow) {
+            return;
+        }
+        const next = accountedTurnsAfterRow(accountedTurnsRef.current, conversationKey, knownRow.turnCount, isThinking);
+        accountedTurnsRef.current = next.accounted;
+        if (next.replay) {
+            void reloadMessages();
+        }
+    }, [knownRow, conversationKey, isThinking, reloadMessages]);
+    const notifyMessageSent = useCallback((text, message) => {
+        // A feedback send is recorded on the conversation with no reply there: activity moves;
+        // no turn is accounted, and the prompt does not name the thread.
+        const isFeedbackSend = message?.name === FEEDBACK_MESSAGE_NAME;
+        notifyThreadActivity(rowRef.current, isFeedbackSend ? undefined : text);
+        if (isFeedbackSend) {
+            return;
+        }
+        accountedTurnsRef.current = accountedTurnsAfterOwnSend(accountedTurnsRef.current, conversationKey, isDraft);
+    }, [notifyThreadActivity, conversationKey, isDraft]);
+    return { row, isStandIn: knownRow === undefined, renameThread, notifyMessageSent };
+};

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

@@ -1,5 +1,7 @@
 import { type AgentThreadItem, type AgentThreadSource, type AgentThreadStatus } from "./agent-thread-live-update.js";
 export * from "./agent-thread-live-update.js";
+export { type AgentConversationChat, type AgentConversationRef, type AgentConversationUrlTarget, agentThreadStandIn, nextRunStaleAt, RUN_STALE_MS, useAgentConversation, type UseAgentConversationOptions, type UseAgentConversationResult, useAgentConversationSelection, type UseAgentConversationSelectionOptions, type UseAgentConversationSelectionResult, } from "./use-agent-conversation.js";
+export { type AgentConversationContextValue, AgentConversationProvider, type AgentConversationProviderProps, type AgentThreadFilters, useAgentConversationContext, } from "./agent-conversation-context.js";
 export interface AgentThreadsPage {
     items: AgentThreadItem[];
     nextCursor: string | null;
@@ -12,75 +14,26 @@ export interface UseAgentThreadsOptions {
     limit?: number;
     sort?: "lastActivity" | "firstSeen";
     order?: "asc" | "desc";
-    /** Platform host override; defaults to getApiHost() (same convention as the agent chat). */
     baseUrl?: string;
-    /** Bearer token for callers that don't share the platform session cookie. */
     token?: string;
-    /** Extra request headers, merged over the defaults. */
     headers?: Record<string, string>;
 }
 export interface UseAgentThreadsResult {
     threads: AgentThreadItem[];
-    /**
-     * Report a user send on a conversation — ChatGPT-style optimistic listing. Pass the
-     * conversation's row (the listed one when the index has it, else one the consumer
-     * builds from the (chatId, chatThreadId) pair) and the prompt text: a conversation with
-     * no server row yet appears in `threads` immediately, titled by the truncated prompt,
-     * and every send bumps the row's recency; server rows take over under the same identity
-     * as events land. Identity-stable — safe to hand to memoized chat surfaces.
-     */
     notifyThreadActivity: (thread: AgentThreadItem, prompt?: string) => void;
-    /**
-     * Rename a conversation. Optimistic — the list shows the new title immediately and
-     * rolls back on failure (the promise rejects so callers can surface an error).
-     */
     renameThread: (thread: Pick<AgentThreadItem, "chatId" | "chatThreadId">, title: string) => Promise<void>;
-    /** First page (or refresh) in flight. */
     isLoading: boolean;
-    /** A cursor page is being appended. */
     isLoadingMore: boolean;
     error: Error | null;
     hasMore: boolean;
     loadMore: () => Promise<void>;
-    /**
-     * Re-walk every loaded page. Freshness is otherwise live (the hook subscribes to
-     * AGENT_THREAD_UPDATED itself) — keep refresh for recovery, e.g. a throttled
-     * window-focus refresh after a dropped connection.
-     */
     refresh: () => Promise<void>;
 }
-/**
- * The platform inbox's fixed chatId for an agent: one shared value per agent block, so
- * index rows are recognizable as "direct chats with this agent on the platform" at a
- * glance (and filterable via the endpoint's chatId param). Conversations under it are
- * distinguished by their unique chatThreadId.
- */
 export declare const AGENT_INBOX_CHAT_PREFIX = "agent-inbox-";
 export declare const agentInboxChatId: (agentId: string) => string;
-/**
- * Short human label for a row with no generated title yet: the half of the identity
- * pair that varies for the row. Inbox rows share one fixed chatId (above) and vary by
- * thread id; rows from other surfaces (published-app chats) are the reverse. One-sided
- * writers (agent calls) index a "_" placeholder for the missing half — fall back to
- * the real half rather than labeling every such row "_".
- */
 export declare const agentThreadShortLabel: (thread: Pick<AgentThreadItem, "chatId" | "chatThreadId">) => string;
-/** How a row is labelled: its title, or the id-based short label while it has none. */
 export declare const agentThreadDisplayTitle: (thread: Pick<AgentThreadItem, "chatId" | "chatThreadId" | "title">) => string;
-/**
- * Headless agent-threads index: fetches an agent's conversation threads from the platform
- * endpoint with keyset-cursor pagination, then keeps them live — every threads-table write
- * publishes AGENT_THREAD_UPDATED on the app's Pusher channel and the hook upserts the row,
- * falling back to the getOne endpoint when a payload lacks the full row. New conversations
- * list optimistically the moment the first prompt is sent (wire notifyThreadActivity to the
- * chat's send seam). The LIST only — which conversation is open is the consumer's (a
- * conversation is addressed by its (chatId, chatThreadId) pair; a new one is a fresh UUID
- * thread id under the surface's chatId — CopilotKit replaces non-UUID ids per load).
- * Pair it with whatever list UI the host app uses. No per-host wiring: both hosts already
- * run the shared websocketsService singleton and subscribe the app channel (the platform
- * via its layouts' useWebsockets hooks, a boilerplate app via the client SDK's
- * ClientProvider), and listening before the socket connects just parks the handler.
- */
+/** Agent-threads index with pagination, realtime upserts, and optimistic send listing. */
 export declare const useAgentThreads: (options: UseAgentThreadsOptions) => UseAgentThreadsResult;
 export default useAgentThreads;
 //# sourceMappingURL=use-agent-threads.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"use-agent-threads.d.ts","sourceRoot":"","sources":["../../src/hooks/use-agent-threads.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EAMvB,MAAM,4BAA4B,CAAC;AAKpC,cAAc,4BAA4B,CAAC;AAO3C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,cAAc,GAAG,WAAW,CAAC;IACpC,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B;;;;;;;OAOG;IACH,oBAAoB,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzE;;;OAGG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,cAAc,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzG,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAC;IACnB,uCAAuC;IACvC,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B;;;;OAIG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AACtD,eAAO,MAAM,gBAAgB,GAAI,SAAS,MAAM,KAAG,MAAgD,CAAC;AAEpG;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,cAAc,CAAC,KAAG,MAIhG,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,uBAAuB,GAAI,QAAQ,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,cAAc,GAAG,OAAO,CAAC,KAAG,MACpD,CAAC;AAuC1D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,sBAAsB,KAAG,qBAqYjE,CAAC;AAEF,eAAe,eAAe,CAAC"}
+{"version":3,"file":"use-agent-threads.d.ts","sourceRoot":"","sources":["../../src/hooks/use-agent-threads.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EAUvB,MAAM,4BAA4B,CAAC;AAEpC,cAAc,4BAA4B,CAAC;AAC3C,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,6BAA6B,EAC7B,KAAK,oCAAoC,EACzC,KAAK,mCAAmC,GACzC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,6BAA6B,EAClC,yBAAyB,EACzB,KAAK,8BAA8B,EACnC,KAAK,kBAAkB,EACvB,2BAA2B,GAC5B,MAAM,8BAA8B,CAAC;AAItC,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,cAAc,GAAG,WAAW,CAAC;IACpC,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,oBAAoB,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzE,YAAY,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,cAAc,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzG,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AACtD,eAAO,MAAM,gBAAgB,GAAI,SAAS,MAAM,KAAG,MAAgD,CAAC;AAEpG,eAAO,MAAM,qBAAqB,GAAI,QAAQ,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,cAAc,CAAC,KAAG,MAIhG,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,QAAQ,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,cAAc,GAAG,OAAO,CAAC,KAAG,MACpD,CAAC;AAuC1D,0FAA0F;AAC1F,eAAO,MAAM,eAAe,GAAI,SAAS,sBAAsB,KAAG,qBA6UjE,CAAC;AAEF,eAAe,eAAe,CAAC"}