@blocksdiy/react-common 1.48.0 → 1.49.0

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

@@ -1,36 +1,18 @@
 import { getApiHost } from "@blocksdiy/blocks-client-api/envService";
 import { websocketsService } from "@blocksdiy/blocks-client-api/websocketService";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { agentThreadKey, applyAgentThreadUpdate, isAgentThreadItem, matchesAgentThreadFilters, optimisticThreadAfterSend, overlayOptimisticThreads, } from "./agent-thread-live-update.js";
-// Wire types, the identity key, and the realtime merge logic live in
-// ./agent-thread-live-update (dependency-free, unit-testable); re-exported so
-// consumers keep importing everything from this module.
+import { agentThreadKey, applyAgentThreadUpdate, isAgentThreadItem, matchesAgentThreadFilters, optimisticThreadAfterSend, overlayOptimisticThreads, reconcileWalkWithLive, removeAgentThread, retireOptimisticThreadsTakenOver, } from "./agent-thread-live-update.js";
 export * from "./agent-thread-live-update.js";
-/* public decouple - AGENT_THREAD_UPDATED rides AgentThreadEventPayload (packages/common
-   agent-thread-events.ts): the event's `thread` field is exactly the list/GET item shape,
-   relayed verbatim from wf-actions-py to the app's Pusher channel. */
+export { agentThreadStandIn, nextRunStaleAt, RUN_STALE_MS, useAgentConversation, useAgentConversationSelection, } from "./use-agent-conversation.js";
+export { AgentConversationProvider, useAgentConversationContext, } from "./agent-conversation-context.js";
 const AGENT_THREAD_UPDATED = "AGENT_THREAD_UPDATED";
-/**
- * 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 const AGENT_INBOX_CHAT_PREFIX = "agent-inbox-";
 export const agentInboxChatId = (agentId) => `${AGENT_INBOX_CHAT_PREFIX}${agentId}`;
-/**
- * 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 const agentThreadShortLabel = (thread) => {
     const varying = thread.chatId.startsWith(AGENT_INBOX_CHAT_PREFIX) ? thread.chatThreadId : thread.chatId;
     const other = varying === thread.chatId ? thread.chatThreadId : thread.chatId;
     return (varying === "_" ? other : varying).slice(0, 8);
 };
-/** How a row is labelled: its title, or the id-based short label while it has none. */
 export const agentThreadDisplayTitle = (thread) => thread.title ?? `Chat ${agentThreadShortLabel(thread)}`;
 const buildQuery = (filters, cursor) => {
     const params = new URLSearchParams();
@@ -62,82 +44,45 @@ const appendPage = (existing, page) => {
     const seen = new Set(existing.map(agentThreadKey));
     return [...existing, ...page.filter((thread) => !seen.has(agentThreadKey(thread)))];
 };
-/**
- * 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 const useAgentThreads = (options) => {
     const { agentId, status, source, chatId, limit, sort, order, baseUrl } = options;
+    const [optimisticThreads, setOptimisticThreads] = useState(new Map());
+    const optimisticThreadsRef = useRef(optimisticThreads);
+    const applyOptimisticThreads = useCallback((next) => {
+        optimisticThreadsRef.current = next;
+        setOptimisticThreads(next);
+    }, []);
     const [threads, setThreads] = useState([]);
-    // Mirror of `threads` for reads outside render (a refresh needs the loaded count without
-    // re-closing over state). Every write goes through applyThreads so the two can't diverge;
-    // reads are race-free because writers are serialized (loadMore awaits any in-flight
-    // refresh, and every write re-checks the request sequence first).
     const threadsRef = useRef([]);
     const applyThreads = useCallback((items) => {
         threadsRef.current = items;
         setThreads(items);
-    }, []);
+        const remaining = retireOptimisticThreadsTakenOver(optimisticThreadsRef.current, items);
+        if (remaining !== optimisticThreadsRef.current) {
+            applyOptimisticThreads(remaining);
+        }
+    }, [applyOptimisticThreads]);
     const [nextCursor, setNextCursor] = useState(null);
-    // Cursor mirror, same contract as threadsRef: loadMore reads it after awaiting an
-    // in-flight refresh, when its render-time closure value is stale by definition.
     const nextCursorRef = useRef(null);
     const applyCursor = useCallback((cursor) => {
         nextCursorRef.current = cursor;
         setNextCursor(cursor);
     }, []);
-    // Starts true (when a fetch is coming): the first-page effect only runs AFTER the mount
-    // paint, so initializing false would flash the "no threads" empty state for a frame.
     const [isLoading, setIsLoading] = useState(Boolean(agentId));
     const [isLoadingMore, setIsLoadingMore] = useState(false);
     const [error, setError] = useState(null);
-    // ChatGPT-style optimistic rows, keyed by thread identity: conversations listed from
-    // the moment a prompt is sent (see notifyThreadActivity), before/ahead of their server
-    // row. The display overlay hands each one over to its server row as events land.
-    // Ref-mirrored like threadsRef, for reads outside render (renameThread's snapshots).
-    const [optimisticThreads, setOptimisticThreads] = useState(new Map());
-    const optimisticThreadsRef = useRef(optimisticThreads);
-    const applyOptimisticThreads = useCallback((next) => {
-        optimisticThreadsRef.current = next;
-        setOptimisticThreads(next);
-    }, []);
-    // The realtime merge's list-shape inputs, shared by the display overlay, the live
-    // event handler, and the walk-result reconciliation in loadFirstPage.
     const liveUpdateOptions = useMemo(() => ({ status, source, chatId, sort, order }), [status, source, chatId, sort, order]);
-    // What consumers see: the loaded pages with the optimistic rows overlaid.
     const displayThreads = useMemo(() => overlayOptimisticThreads(threads, optimisticThreads, liveUpdateOptions), [threads, optimisticThreads, liveUpdateOptions]);
-    /**
-     * Report a user send on a conversation — ChatGPT-style optimistic listing. 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 (turn end, title generation), the provisional title
-     * holding until the generated one arrives.
-     */
     const notifyThreadActivity = useCallback((thread, prompt) => {
         const prev = optimisticThreadsRef.current;
         const next = new Map(prev);
         next.set(agentThreadKey(thread), optimisticThreadAfterSend(thread, prev.get(agentThreadKey(thread)), prompt, new Date().toISOString()));
         applyOptimisticThreads(next);
     }, [applyOptimisticThreads]);
-    // Auth material is read at request time via refs so an inline `headers` object literal
-    // doesn't churn the effect below into a refetch loop.
     const authRef = useRef({ token: options.token, headers: options.headers });
     authRef.current = { token: options.token, headers: options.headers };
-    // Every state-writing path checks it still owns the latest request before touching state,
-    // so a stale response (filter switched mid-flight, unmount) can never clobber a newer one.
     const requestSeqRef = useRef(0);
-    // Authed request against the platform host, JSON-decoded — shared by the page and
-    // getOne fetchers below and by renameThread.
     const fetchJson = useCallback(async (path, init) => {
         const { token, headers } = authRef.current;
         const response = await fetch(`${baseUrl ?? getApiHost()}${path}`, {
@@ -154,27 +99,13 @@ export const useAgentThreads = (options) => {
         return (await response.json());
     }, [baseUrl]);
     const fetchPage = useCallback((cursor) => fetchJson(`/agent-threads/${encodeURIComponent(agentId)}${buildQuery({ status, source, chatId, limit, sort, order }, cursor)}`), [agentId, status, source, chatId, limit, sort, order, fetchJson]);
-    // getOne, mirroring the upstream GET /thread endpoint — the realtime fallback for
-    // events whose payload doesn't carry the full row.
     const fetchThread = useCallback((threadChatId, threadChatThreadId) => fetchJson(`/agent-threads/${encodeURIComponent(agentId)}/thread?${new URLSearchParams({ chatId: threadChatId, chatThreadId: threadChatThreadId })}`), [agentId, fetchJson]);
-    /**
-     * Rename a conversation — optimistic with rollback, rejecting on failure so callers
-     * can surface it. The new title is applied to every local title source: the loaded
-     * row and any optimistic entry (whose snapshot the overlay may currently be showing).
-     * A conversation the list does not hold (a filter dropped its row) has no local title
-     * here — the consumer keeps its own copy of that row and applies the rename itself.
-     * Other tabs get the rename via the pusher event; this tab is excluded from the echo
-     * (x-socket-id), matching the optimistic apply.
-     */
     const renameThread = useCallback(async (thread, title) => {
         const trimmed = title.trim();
         if (!trimmed) {
             return;
         }
         const key = agentThreadKey(thread);
-        // `undefined` means "that source held no row when we started" — leave whatever is
-        // there now alone. Collapsing it to null would let a rollback erase a title that
-        // landed from the server while the request was in flight.
         const setLocalTitle = (rowTitle, entryTitle) => {
             const row = threadsRef.current.find((item) => agentThreadKey(item) === key);
             if (row && rowTitle !== undefined && row.title !== rowTitle) {
@@ -200,9 +131,6 @@ export const useAgentThreads = (options) => {
                 },
                 body: JSON.stringify({ chatId: thread.chatId, chatThreadId: thread.chatThreadId, title: trimmed }),
             });
-            // `updated: false` means no such row upstream (e.g. renaming before the first
-            // turn indexes the conversation) — a failure like any other, or the optimistic
-            // title would stick locally and silently vanish on reload.
             if (!updated) {
                 throw new Error("Thread rename was not applied");
             }
@@ -212,19 +140,10 @@ export const useAgentThreads = (options) => {
             throw error;
         }
     }, [agentId, fetchJson, applyThreads, applyOptimisticThreads]);
-    // Realtime rows that land while a refresh walk is in flight: the walk's fetches may
-    // predate those writes, so replacing the list with the raw walk result could silently
-    // revert or drop them — re-merging afterwards keeps whichever side is newer (the
-    // merge's staleness guard makes this idempotent).
     const liveWhileWalkingRef = useRef(null);
-    // The in-flight refresh, if any, so loadMore can wait it out instead of dropping the
-    // gesture (a click on "Load more" often arrives right behind the window-focus refresh
-    // the same gesture triggered).
     const refreshPromiseRef = useRef(null);
     const loadFirstPage = useCallback(() => {
         if (!agentId) {
-            // Nothing will fetch — make sure the optimistic initial `true` (or a fetch
-            // superseded by agentId turning falsy) can't leave the loading flag latched on.
             setIsLoading(false);
             return Promise.resolve();
         }
@@ -234,15 +153,6 @@ export const useAgentThreads = (options) => {
         setError(null);
         const run = (async () => {
             try {
-                // A refresh re-covers every page the user has already loaded — one request in the
-                // common one-page case (the query-change effect blanks the list first, so filter
-                // switches also fetch a single page). The alternatives both break pagination:
-                // replacing with page one collapses the list back to page one on every focus
-                // refresh, and splicing page one over the old tail either rewinds the cursor
-                // ("Load more" then refetches known rows and looks dead) or keeps the old cursor
-                // and permanently skips rows that arrived beyond page one while the user was away.
-                // Walking the cursor keeps the list contiguous from the top, in server order,
-                // with the cursor pointing past everything shown.
                 const loadedCount = threadsRef.current.length;
                 let items = [];
                 let cursor = null;
@@ -252,21 +162,21 @@ export const useAgentThreads = (options) => {
                         return;
                     }
                     if (page.items.length === 0) {
-                        // Defensive: an empty page must terminate the walk even with a non-null cursor.
                         cursor = null;
                         break;
                     }
                     items = appendPage(items, page.items);
                     if (page.nextCursor === cursor) {
-                        // Defensive: dedupe can hold items.length under loadedCount, so a
-                        // non-advancing cursor must terminate too or the walk loops unbounded.
                         cursor = null;
                         break;
                     }
                     cursor = page.nextCursor;
                 } while (cursor !== null && items.length < loadedCount);
-                for (const live of liveWhileWalkingRef.current?.values() ?? []) {
-                    items = applyAgentThreadUpdate(items, live, { ...liveUpdateOptions, hasMore: cursor !== null });
+                if (liveWhileWalkingRef.current) {
+                    items = reconcileWalkWithLive(items, liveWhileWalkingRef.current, {
+                        ...liveUpdateOptions,
+                        hasMore: cursor !== null,
+                    });
                 }
                 applyThreads(items);
                 applyCursor(cursor);
@@ -287,8 +197,6 @@ export const useAgentThreads = (options) => {
         refreshPromiseRef.current = run;
         return run;
     }, [agentId, fetchPage, liveUpdateOptions, applyThreads, applyCursor]);
-    // Ref-guarded rather than state-guarded: after the awaited refresh below, the closure's
-    // state flags are stale by definition — and a ref also makes double-clicks race-free.
     const loadMoreInFlightRef = useRef(false);
     const loadMore = useCallback(async () => {
         if (!agentId || loadMoreInFlightRef.current) {
@@ -296,14 +204,8 @@ export const useAgentThreads = (options) => {
         }
         loadMoreInFlightRef.current = true;
         setIsLoadingMore(true);
-        // Captured BEFORE the wait below: this closure's fetchPage belongs to the render the
-        // click landed on, so anything that supersedes the list while we sit behind the
-        // refresh (a query change, a newer refresh) must invalidate this gesture too.
         const requestSeq = requestSeqRef.current;
         try {
-            // A refresh may be in flight — typically fired by the very window-focus that
-            // preceded this click. Wait it out instead of silently swallowing the gesture;
-            // the cursor ref then points past everything the refresh walk re-covered.
             if (refreshPromiseRef.current) {
                 await refreshPromiseRef.current;
             }
@@ -328,8 +230,6 @@ export const useAgentThreads = (options) => {
             setError(fetchError instanceof Error ? fetchError : new Error(String(fetchError)));
         }
         finally {
-            // Unconditional: even when a refresh superseded this request the flags must clear
-            // or pagination locks up.
             loadMoreInFlightRef.current = false;
             setIsLoadingMore(false);
         }
@@ -337,59 +237,51 @@ export const useAgentThreads = (options) => {
     useEffect(() => {
         applyThreads([]);
         applyCursor(null);
-        // Server-side filters know nothing of the optimistic rows — drop them on a query
-        // change rather than risk re-listing a snapshot whose server truth the new filter
-        // excludes (see the retire-on-eviction note in the realtime handler below).
         applyOptimisticThreads(new Map());
         void loadFirstPage();
         return () => {
-            // Invalidate in-flight requests on unmount / query change.
             requestSeqRef.current += 1;
         };
     }, [loadFirstPage, applyThreads, applyCursor, applyOptimisticThreads]);
-    // Live sync: every threads-table write lands here as a serialized row, so the happy
-    // path is a pure client-side upsert; a payload without the full row falls back to the
-    // getOne endpoint. The service-level filter drops other agents' events.
     useEffect(() => {
         if (!agentId) {
             return;
         }
         const onThreadUpdated = async (data) => {
-            // Same superseded-request contract as the fetch paths, guarding the async fallback
-            // (trivially true on the no-await happy path).
             const requestSeq = requestSeqRef.current;
             try {
-                const raw = data?.thread;
-                let incoming;
-                if (isAgentThreadItem(raw)) {
-                    incoming = raw;
-                }
-                else if (typeof raw?.chatId === "string" && typeof raw.chatThreadId === "string") {
-                    incoming = await fetchThread(raw.chatId, raw.chatThreadId);
+                const event = data;
+                const raw = event?.thread;
+                if (typeof raw?.chatId !== "string" || typeof raw.chatThreadId !== "string") {
+                    return;
                 }
-                else {
+                const identity = { chatId: raw.chatId, chatThreadId: raw.chatThreadId };
+                const key = agentThreadKey(identity);
+                if (event?.removed) {
+                    const removed = { ...identity, runningRunId: raw.runningRunId };
+                    const removal = removeAgentThread(threadsRef.current, optimisticThreadsRef.current, removed);
+                    if (!removal) {
+                        return;
+                    }
+                    liveWhileWalkingRef.current?.set(key, { removed });
+                    if (removal.threads !== threadsRef.current) {
+                        applyThreads(removal.threads);
+                    }
+                    if (removal.optimistic !== optimisticThreadsRef.current) {
+                        applyOptimisticThreads(removal.optimistic);
+                    }
                     return;
                 }
+                const incoming = isAgentThreadItem(raw) ? raw : await fetchThread(identity.chatId, identity.chatThreadId);
                 if (requestSeqRef.current !== requestSeq) {
                     return;
                 }
-                const key = agentThreadKey(incoming);
-                // An authoritative row the active filters reject must retire the thread's
-                // optimistic entry too: the merge below evicts the server row, and with no
-                // listed row there is no staleness guard to stop the overlay from re-adding
-                // the entry's stale snapshot — which no later event or refresh walk could
-                // correct, since the server filters the row out as well. Gated on turnCount
-                // (server-monotonic, like the overlay's handover) rather than the entry's
-                // CLIENT-stamped lastActivityAt, which a fast browser clock could hold ahead
-                // of every server timestamp.
                 const entry = optimisticThreadsRef.current.get(key);
                 if (entry && !matchesAgentThreadFilters(incoming, liveUpdateOptions) && incoming.turnCount >= entry.turnCount) {
                     const next = new Map(optimisticThreadsRef.current);
                     next.delete(key);
                     applyOptimisticThreads(next);
                 }
-                // Park the row for the in-flight refresh walk (if any) — its fetches may
-                // predate this write — then merge it into the current list.
                 liveWhileWalkingRef.current?.set(key, incoming);
                 applyThreads(applyAgentThreadUpdate(threadsRef.current, incoming, {
                     ...liveUpdateOptions,
@@ -397,8 +289,7 @@ export const useAgentThreads = (options) => {
                 }));
             }
             catch {
-                // Best-effort: a failed fallback fetch skips this event — the next event or a
-                // recovery refresh re-converges. Must not reject; the websocket service doesn't catch.
+                // Best-effort: websocket handler must not reject.
             }
         };
         websocketsService.listen(AGENT_THREAD_UPDATED, onThreadUpdated, { filter: { agentId } });
@@ -406,6 +297,18 @@ export const useAgentThreads = (options) => {
             websocketsService.unlisten(AGENT_THREAD_UPDATED, onThreadUpdated);
         };
     }, [agentId, liveUpdateOptions, fetchThread, applyThreads, applyOptimisticThreads]);
+    // Realtime has no replay — reconnect re-walks; last socket id lives in a ref so a filter switch while offline does not look like a first connect.
+    const lastSocketIdRef = useRef(undefined);
+    useEffect(() => websocketsService.onSocketIdChange((socketId) => {
+        if (!socketId) {
+            return;
+        }
+        const reconnected = lastSocketIdRef.current !== undefined && socketId !== lastSocketIdRef.current;
+        lastSocketIdRef.current = socketId;
+        if (reconnected) {
+            void loadFirstPage();
+        }
+    }), [loadFirstPage]);
     return {
         threads: displayThreads,
         notifyThreadActivity,

package/dist/utils/composer-message.d.ts

@@ -0,0 +1,57 @@
+export interface TextPart {
+    type: "text";
+    text: string;
+}
+/** Arms the next send; cleared by the send and by a conversation switch. */
+export interface ComposerMessageMeta {
+    name?: string;
+    leadingParts?: TextPart[];
+}
+export declare const isFeedbackTag: (text: string) => boolean;
+export declare const buildArmedMessageContent: <Part extends {
+    type: string;
+}>(meta: ComposerMessageMeta, composed: string | Part[]) => (TextPart | Part)[];
+/** What the user wrote: the last text part that is not the feedback marker, else empty. */
+export declare const userTextOfContent: (content: string | readonly {
+    type: string;
+    text?: string;
+}[]) => string;
+/** User message `name` that marks a feedback send; the marker carries the rating. */
+export declare const FEEDBACK_MESSAGE_NAME = "feedback";
+export type FeedbackRate = 1 | -1 | 0;
+/** What a feedback send is about: the rating, and the rated message (absent: the whole conversation). */
+export interface FeedbackDraft {
+    rate: FeedbackRate;
+    messageId?: string;
+}
+export declare const isFeedbackMessage: (message: {
+    role: string;
+    name?: string;
+}) => boolean;
+/**
+ * A rating sent as it is, no comment: the name, and the marker as the whole message. The server
+ * records it on the conversation and opens no thread (a thread's prompt is what the user typed).
+ */
+export declare const feedbackMessage: (draft: FeedbackDraft) => {
+    name: string;
+    content: TextPart[];
+};
+/** Arms the composer for a feedback send: the name, and the marker as the one leading part. */
+export declare const feedbackComposerMeta: (draft: FeedbackDraft) => ComposerMessageMeta;
+/** The marker's rating and subject, read the way the server reads them; null when `text` is not a marker. */
+export declare const parseFeedbackTag: (text: string | undefined) => FeedbackDraft | null;
+/** The feedback draft a composer is armed with, or null when it is not armed for feedback. */
+export declare const feedbackDraftOf: (meta: ComposerMessageMeta | null | undefined) => FeedbackDraft | null;
+export interface ParsedFeedback extends FeedbackDraft {
+    /** What the user typed, the marker stripped. */
+    body: string;
+}
+/**
+ * A sent feedback message as the server reads it (`parse_feedback_message`): the marker is the
+ * FIRST text part only — later parts are the user's text whatever they look like — blank parts
+ * are skipped, and an unreadable marker reads as unrated.
+ */
+export declare const parseFeedbackContent: (content: unknown) => ParsedFeedback;
+/** The thread a feedback on one message opens — the server's key, so repeats land on the same thread. */
+export declare const feedbackThreadId: (messageId: string) => string;
+//# sourceMappingURL=composer-message.d.ts.map

package/dist/utils/composer-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composer-message.d.ts","sourceRoot":"","sources":["../../src/utils/composer-message.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,QAAQ,EAAE,CAAC;CAC3B;AAID,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,OAA0C,CAAC;AAExF,eAAO,MAAM,wBAAwB,GAAI,IAAI,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACpE,MAAM,mBAAmB,EACzB,UAAU,MAAM,GAAG,IAAI,EAAE,KACxB,CAAC,QAAQ,GAAG,IAAI,CAAC,EAGnB,CAAC;AAgBF,2FAA2F;AAC3F,eAAO,MAAM,iBAAiB,GAAI,SAAS,MAAM,GAAG,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,KAAG,MAQhG,CAAC;AASF,qFAAqF;AACrF,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAEhD,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;AAEtC,yGAAyG;AACzG,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,iBAAiB,GAAI,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,OACV,CAAC;AAYpE;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,aAAa,KAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,QAAQ,EAAE,CAAA;CAGxF,CAAC;AAEH,+FAA+F;AAC/F,eAAO,MAAM,oBAAoB,GAAI,OAAO,aAAa,KAAG,mBAG3D,CAAC;AASF,6GAA6G;AAC7G,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,GAAG,SAAS,KAAG,aAAa,GAAG,IAS3E,CAAC;AAEF,8FAA8F;AAC9F,eAAO,MAAM,eAAe,GAAI,MAAM,mBAAmB,GAAG,IAAI,GAAG,SAAS,KAAG,aAAa,GAAG,IACD,CAAC;AAE/F,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;CACd;AAID;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,OAAO,KAAG,cAUvD,CAAC;AAEF,yGAAyG;AACzG,eAAO,MAAM,gBAAgB,GAAI,WAAW,MAAM,KAAG,MAA2B,CAAC"}

package/dist/utils/composer-message.js

@@ -0,0 +1,96 @@
+// Composer send shape and read-back helpers; dependency-free for tests.
+const FEEDBACK_TAG_PATTERN = /^\s*<feedback\b[^>]*\/?>\s*$/i;
+export const isFeedbackTag = (text) => FEEDBACK_TAG_PATTERN.test(text);
+export const buildArmedMessageContent = (meta, composed) => [
+    ...(meta.leadingParts ?? []),
+    ...(typeof composed === "string" ? [{ type: "text", text: composed }] : composed),
+];
+/** The message's text, part by part; non-text parts skipped (the server's `message_text_parts`). */
+const textPartsOf = (content) => {
+    if (typeof content === "string") {
+        return [content];
+    }
+    if (!Array.isArray(content)) {
+        return [];
+    }
+    return content.flatMap((part) => {
+        const text = part?.type === "text" ? part.text : undefined;
+        return typeof text === "string" ? [text] : [];
+    });
+};
+/** What the user wrote: the last text part that is not the feedback marker, else empty. */
+export const userTextOfContent = (content) => {
+    const parts = textPartsOf(content);
+    for (let index = parts.length - 1; index >= 0; index -= 1) {
+        if (!isFeedbackTag(parts[index])) {
+            return parts[index];
+        }
+    }
+    return "";
+};
+/* ---- Feedback wire protocol ------------------------------------------------------------
+ * A feedback send is a user message named FEEDBACK_MESSAGE_NAME whose FIRST text part is the
+ * marker `<feedback rate="…" messageId="…" />` (no messageId for the conversation as a whole).
+ * The server reads the marker from that part only and files the agent's reply under
+ * `fb-<messageId>`. Mirrors wf-actions-py agent_feedback_action.
+ * -------------------------------------------------------------------------------------- */
+/** User message `name` that marks a feedback send; the marker carries the rating. */
+export const FEEDBACK_MESSAGE_NAME = "feedback";
+export const isFeedbackMessage = (message) => message.role === "user" && message.name === FEEDBACK_MESSAGE_NAME;
+// The server reads an attribute as `"([^"]*)"` inside `<feedback [^>]*>`: a quote or an angle
+// bracket in the id would end the attribute or the tag early.
+const MARKER_SAFE_ID_PATTERN = /^[^"<>\s]+$/;
+/** The marker text; `messageId` rides only when the id can sit inside a quoted attribute. */
+const feedbackMarker = ({ rate, messageId }) => messageId && MARKER_SAFE_ID_PATTERN.test(messageId)
+    ? `<feedback rate="${rate}" messageId="${messageId}" />`
+    : `<feedback rate="${rate}" />`;
+/**
+ * A rating sent as it is, no comment: the name, and the marker as the whole message. The server
+ * records it on the conversation and opens no thread (a thread's prompt is what the user typed).
+ */
+export const feedbackMessage = (draft) => ({
+    name: FEEDBACK_MESSAGE_NAME,
+    content: [{ type: "text", text: feedbackMarker(draft) }],
+});
+/** Arms the composer for a feedback send: the name, and the marker as the one leading part. */
+export const feedbackComposerMeta = (draft) => {
+    const { name, content } = feedbackMessage(draft);
+    return { name, leadingParts: content };
+};
+const ATTRIBUTE_PATTERN = /([A-Za-z_][A-Za-z0-9_]*)\s*=\s*"([^"]*)"/g;
+const toRate = (value) => {
+    const rate = Number(value);
+    return rate > 0 ? 1 : rate < 0 ? -1 : 0;
+};
+/** The marker's rating and subject, read the way the server reads them; null when `text` is not a marker. */
+export const parseFeedbackTag = (text) => {
+    if (text === undefined || !isFeedbackTag(text)) {
+        return null;
+    }
+    const attributes = {};
+    for (const [, key, value] of text.matchAll(ATTRIBUTE_PATTERN)) {
+        attributes[key.toLowerCase()] = value;
+    }
+    return { rate: toRate(attributes.rate), messageId: attributes.messageid?.trim() || undefined };
+};
+/** The feedback draft a composer is armed with, or null when it is not armed for feedback. */
+export const feedbackDraftOf = (meta) => meta?.name === FEEDBACK_MESSAGE_NAME ? parseFeedbackTag(meta.leadingParts?.[0]?.text) : null;
+const UNRATED = { rate: 0 };
+/**
+ * A sent feedback message as the server reads it (`parse_feedback_message`): the marker is the
+ * FIRST text part only — later parts are the user's text whatever they look like — blank parts
+ * are skipped, and an unreadable marker reads as unrated.
+ */
+export const parseFeedbackContent = (content) => {
+    const parts = textPartsOf(content);
+    const marker = parseFeedbackTag(parts[0]);
+    return {
+        ...(marker ?? UNRATED),
+        body: (marker ? parts.slice(1) : parts)
+            .filter((text) => text.trim())
+            .join("\n")
+            .trim(),
+    };
+};
+/** The thread a feedback on one message opens — the server's key, so repeats land on the same thread. */
+export const feedbackThreadId = (messageId) => `fb-${messageId}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocksdiy/react-common",
-  "version": "1.48.0",
+  "version": "1.49.0",
   "type": "module",
   "description": "React common",
   "keywords": [],