@blocksdiy/react-common 1.47.0 → 1.49.0

package/dist/hooks/agent-thread-live-update.d.ts

@@ -1,94 +1,65 @@
-export type AgentThreadStatus = "idle" | "interrupted" | "error";
-export type AgentThreadSource = "direct_chat" | "agent_call" | "send_message" | "feedback" | "unknown";
+declare const THREAD_STATUSES: readonly ["idle", "interrupted", "waiting_on_agent", "busy", "error"];
+export type AgentThreadStatus = (typeof THREAD_STATUSES)[number];
+declare const THREAD_SOURCES: readonly ["direct_chat", "send_message", "feedback", "self_config_resume", "unknown"];
+export type AgentThreadSource = (typeof THREAD_SOURCES)[number] | "agent_call";
 export interface AgentThreadItem {
     agentId: string | null;
-    /** Never null — pass back verbatim to open the conversation. */
     chatId: string;
-    /** Never null — pass back verbatim to open the conversation. */
     chatThreadId: string;
     source: AgentThreadSource;
     status: AgentThreadStatus;
     title: string | null;
     turnCount: number;
-    /**
-     * What KIND of conversation this is — `"feedback"` for a thread opened by a feedback send,
-     * absent/null for an ordinary chat. Optional in the type, not on the wire: a server that
-     * predates it sends nothing, and `undefined` must read as "an ordinary chat", not as a
-     * missing field to work around.
-     */
     type?: string | null;
-    /**
-     * For a thread spawned from another conversation: that conversation's `chatThreadId` — pass
-     * it back verbatim to open the source, exactly like `chatThreadId` itself. Null when the
-     * source predates this field; a UI must then say where the thread came from without linking.
-     */
     fromSourceChatThreadId?: string | null;
-    /** The message the feedback was about, when it was about one rather than the conversation. */
     fromSourceMessageId?: string | null;
-    /** First seen by the index — NOT thread creation time. */
     firstSeenAt: string;
     lastActivityAt: string;
+    runningSince?: string | null;
+    runningRunId?: string | null;
 }
-/** The (chatId, chatThreadId) pair — the only stable identity of a thread row. */
 export declare const agentThreadKey: (thread: Pick<AgentThreadItem, "chatId" | "chatThreadId">) => string;
-/**
- * Whether a realtime payload's `thread` is a complete list-item row. The server
- * serializes the exact item shape into every event, so this normally passes; when
- * it doesn't (contract drift), the consumer falls back to the getOne endpoint.
- */
 export declare const isAgentThreadItem: (value: unknown) => value is AgentThreadItem;
-/**
- * Provisional row title from the prompt that started a conversation (ChatGPT-style):
- * one line, whitespace collapsed, capped like the server's generated titles. Null when
- * there's nothing usable (attachment-only sends) — the UI keeps its id-based fallback.
- */
 export declare const provisionalThreadTitle: (prompt: string | undefined) => string | null;
-/**
- * The optimistic row for a user send on `thread`, replacing `previous` (its current
- * optimistic entry, if any): the same identity, its recency bumped to `now`, and a title
- * that never regresses — the provisional title already shown, else the row's own, else
- * one from this prompt (null when the prompt has nothing usable).
- */
 export declare const optimisticThreadAfterSend: (thread: AgentThreadItem, previous: AgentThreadItem | undefined, prompt: string | undefined, now: string) => AgentThreadItem;
+export type RemovedAgentThread = Pick<AgentThreadItem, "chatId" | "chatThreadId" | "runningRunId">;
+export declare const removeAgentThread: (threads: AgentThreadItem[], optimistic: ReadonlyMap<string, AgentThreadItem>, removed: RemovedAgentThread) => {
+    threads: AgentThreadItem[];
+    optimistic: ReadonlyMap<string, AgentThreadItem>;
+} | null;
 export interface AgentThreadLiveUpdateOptions {
-    /** Active server-side filters — an updated row that stops matching leaves the list. */
     status?: AgentThreadStatus;
     source?: AgentThreadSource;
     chatId?: string;
-    /** Active sort, mirroring the endpoint's defaults (lastActivity, desc). */
     sort?: "lastActivity" | "firstSeen";
     order?: "asc" | "desc";
-    /** True when more pages exist server-side beyond the loaded window. */
     hasMore?: boolean;
 }
-/**
- * Merge one realtime thread update into a loaded list. Pure; returns the input array
- * untouched when the event is stale, filtered out, or out of the loaded window.
- *
- * - Out-of-order delivery can't regress a row: events older than the loaded row (by
- *   lastActivityAt) are dropped — checked FIRST, so a stale event can't evict a
- *   still-current row through the filter check below either. Renames keep
- *   lastActivityAt, so equal passes.
- * - A row that stops matching the active filters is removed; a matching one is upserted
- *   and the list re-sorted by the active sort (stable, so ties keep their server order).
- * - A NEW row sorting past every loaded row while more pages exist may belong beyond the
- *   loaded window; it's skipped so the list stays contiguous with the pagination cursor
- *   (unreachable under the default lastActivity-desc sort, where fresh activity sorts first).
- */
-/** Whether a row passes the list's active server-side filters. */
 export declare const matchesAgentThreadFilters: (item: AgentThreadItem, options?: AgentThreadLiveUpdateOptions) => boolean;
 export declare const applyAgentThreadUpdate: (threads: AgentThreadItem[], incoming: AgentThreadItem, options?: AgentThreadLiveUpdateOptions) => AgentThreadItem[];
-/**
- * Overlay optimistic rows (conversations the user just acted on, ChatGPT-style) onto the
- * loaded list. Each row goes through the same merge as a realtime event, so filters and
- * sorting apply — except that a server row still untitled borrows the optimistic
- * (prompt-derived) title until the generated one lands. Pure; returns `threads` untouched
- * when nothing changes.
- *
- * An entry steps aside once the loaded row has recorded MORE turns than it did: turnCount
- * is server-monotonic, so the handover can't be held off by a client clock running ahead
- * of the server (the entry's lastActivityAt is stamped locally, and the merge's staleness
- * guard compares it against server timestamps).
- */
+/** Parked removal for an in-flight refresh walk (see reconcileWalkWithLive). */
+export interface ParkedRemoval {
+    removed: RemovedAgentThread;
+}
+export declare const reconcileWalkWithLive: (items: AgentThreadItem[], live: ReadonlyMap<string, AgentThreadItem | ParkedRemoval>, options?: AgentThreadLiveUpdateOptions) => AgentThreadItem[];
 export declare const overlayOptimisticThreads: (threads: AgentThreadItem[], optimistic: ReadonlyMap<string, AgentThreadItem>, options?: AgentThreadLiveUpdateOptions) => AgentThreadItem[];
+export declare const retireOptimisticThreadsTakenOver: (optimistic: ReadonlyMap<string, AgentThreadItem>, threads: AgentThreadItem[]) => ReadonlyMap<string, AgentThreadItem>;
+/** The server's cap on a title a person sets (RENAME_TITLE_MAX_CHARS in wf-actions-py). */
+export declare const RENAME_TITLE_MAX_CHARS = 255;
+/** Conversation-index groups, in display order; a row's group follows its write-once `source`. */
+export declare const AGENT_THREAD_GROUPS: readonly ["chats", "workflows", "feedback"];
+export type AgentThreadGroup = (typeof AGENT_THREAD_GROUPS)[number];
+/** Where a row files; a source this copy predates files under chats, so a row never renders nowhere. */
+export declare const agentThreadGroup: (source: AgentThreadSource) => AgentThreadGroup;
+export interface AgentThreadGroupRows {
+    group: AgentThreadGroup;
+    rows: AgentThreadItem[];
+}
+/** Rows by group in group order, each group in input order; empty groups dropped. */
+export declare const groupAgentThreads: (threads: readonly AgentThreadItem[]) => AgentThreadGroupRows[];
+/** A thread the agent opened to act on feedback — by `type`, or by `source` for rows from before the column. */
+export declare const isFeedbackThread: (row: Pick<AgentThreadItem, "type" | "source">) => boolean;
+/** The conversation a feedback thread was opened from, when `threads` lists it (same chat, the row's pointer). */
+export declare const feedbackSourceThread: (row: AgentThreadItem, threads: readonly AgentThreadItem[]) => AgentThreadItem | undefined;
+export {};
 //# sourceMappingURL=agent-thread-live-update.d.ts.map

package/dist/hooks/agent-thread-live-update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-thread-live-update.d.ts","sourceRoot":"","sources":["../../src/hooks/agent-thread-live-update.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,aAAa,GAAG,OAAO,CAAC;AAEjE,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,YAAY,GAAG,cAAc,GAAG,UAAU,GAAG,SAAS,CAAC;AAEvG,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,8FAA8F;IAC9F,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,kFAAkF;AAClF,eAAO,MAAM,cAAc,GAAI,QAAQ,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,cAAc,CAAC,KAAG,MAC9C,CAAC;AAW7C;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAiB3D,CAAC;AAKF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,QAAQ,MAAM,GAAG,SAAS,KAAG,MAAM,GAAG,IAQ5E,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GACpC,QAAQ,eAAe,EACvB,UAAU,eAAe,GAAG,SAAS,EACrC,QAAQ,MAAM,GAAG,SAAS,EAC1B,KAAK,MAAM,KACV,eAID,CAAC;AAEH,MAAM,WAAW,4BAA4B;IAC3C,uFAAuF;IACvF,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,cAAc,GAAG,WAAW,CAAC;IACpC,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAOD;;;;;;;;;;;;;GAaG;AACH,kEAAkE;AAClE,eAAO,MAAM,yBAAyB,GAAI,MAAM,eAAe,EAAE,UAAS,4BAAiC,KAAG,OAGzD,CAAC;AAEtD,eAAO,MAAM,sBAAsB,GACjC,SAAS,eAAe,EAAE,EAC1B,UAAU,eAAe,EACzB,UAAS,4BAAiC,KACzC,eAAe,EAqBjB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,GACnC,SAAS,eAAe,EAAE,EAC1B,YAAY,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,EAChD,UAAS,4BAAiC,KACzC,eAAe,EAkBjB,CAAC"}
+{"version":3,"file":"agent-thread-live-update.d.ts","sourceRoot":"","sources":["../../src/hooks/agent-thread-live-update.ts"],"names":[],"mappings":"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"}

package/dist/hooks/agent-thread-live-update.js

@@ -1,21 +1,7 @@
-// Wire types and pure merge logic for the agent-threads index and its realtime
-// AGENT_THREAD_UPDATED events. Dependency-free on purpose: use-agent-threads
-// re-exports everything here, and node tests load this module directly.
-/** The (chatId, chatThreadId) pair — the only stable identity of a thread row. */
+// Wire types and pure merge logic for the agent-threads index; dependency-free for tests.
+const THREAD_STATUSES = ["idle", "interrupted", "waiting_on_agent", "busy", "error"];
+const THREAD_SOURCES = ["direct_chat", "send_message", "feedback", "self_config_resume", "unknown"];
 export const agentThreadKey = (thread) => `${thread.chatId}::${thread.chatThreadId}`;
-const THREAD_STATUSES = ["idle", "interrupted", "error"];
-const THREAD_SOURCES = [
-    "direct_chat",
-    "agent_call",
-    "send_message",
-    "feedback",
-    "unknown",
-];
-/**
- * Whether a realtime payload's `thread` is a complete list-item row. The server
- * serializes the exact item shape into every event, so this normally passes; when
- * it doesn't (contract drift), the consumer falls back to the getOne endpoint.
- */
 export const isAgentThreadItem = (value) => {
     const item = value;
     return (typeof item === "object" &&
@@ -30,15 +16,11 @@ export const isAgentThreadItem = (value) => {
         (typeof item.title === "string" || item.title === null) &&
         typeof item.turnCount === "number" &&
         typeof item.firstSeenAt === "string" &&
-        typeof item.lastActivityAt === "string");
+        typeof item.lastActivityAt === "string" &&
+        (item.runningSince == null || typeof item.runningSince === "string") &&
+        (item.runningRunId == null || typeof item.runningRunId === "string"));
 };
-// Matches the server's cap for LLM-generated titles (wf-actions-py TITLE_MAX_CHARS).
 const PROVISIONAL_TITLE_MAX_CHARS = 80;
-/**
- * Provisional row title from the prompt that started a conversation (ChatGPT-style):
- * one line, whitespace collapsed, capped like the server's generated titles. Null when
- * there's nothing usable (attachment-only sends) — the UI keeps its id-based fallback.
- */
 export const provisionalThreadTitle = (prompt) => {
     const collapsed = prompt?.replace(/\s+/g, " ").trim();
     if (!collapsed) {
@@ -48,42 +30,46 @@ export const provisionalThreadTitle = (prompt) => {
         ? `${collapsed.slice(0, PROVISIONAL_TITLE_MAX_CHARS - 1).trimEnd()}…`
         : collapsed;
 };
-/**
- * The optimistic row for a user send on `thread`, replacing `previous` (its current
- * optimistic entry, if any): the same identity, its recency bumped to `now`, and a title
- * that never regresses — the provisional title already shown, else the row's own, else
- * one from this prompt (null when the prompt has nothing usable).
- */
+// Optimistic send row; never carries a run — the server's row for this send owns busy.
 export const optimisticThreadAfterSend = (thread, previous, prompt, now) => ({
     ...thread,
-    title: previous?.title ?? thread.title ?? provisionalThreadTitle(prompt),
+    status: thread.status === "busy" ? "idle" : thread.status,
+    runningSince: null,
+    runningRunId: null,
+    title: thread.title ?? previous?.title ?? provisionalThreadTitle(prompt),
     lastActivityAt: now,
 });
+// Stands aside when the listed row has turns or a different run in flight.
+const removeListedAgentThread = (threads, removed) => {
+    const key = agentThreadKey(removed);
+    const listed = threads.find((thread) => agentThreadKey(thread) === key);
+    if (listed &&
+        (listed.turnCount > 0 || (listed.runningRunId != null && listed.runningRunId !== removed.runningRunId))) {
+        return null;
+    }
+    return listed ? threads.filter((thread) => thread !== listed) : threads;
+};
+export const removeAgentThread = (threads, optimistic, removed) => {
+    const remaining = removeListedAgentThread(threads, removed);
+    if (remaining === null) {
+        return null;
+    }
+    const key = agentThreadKey(removed);
+    const withoutEntry = new Map(optimistic);
+    withoutEntry.delete(key);
+    return { threads: remaining, optimistic: optimistic.has(key) ? withoutEntry : optimistic };
+};
 const sortTime = (item, sort) => {
     const parsed = new Date(sort === "firstSeen" ? item.firstSeenAt : item.lastActivityAt).getTime();
     return Number.isNaN(parsed) ? 0 : parsed;
 };
-/**
- * Merge one realtime thread update into a loaded list. Pure; returns the input array
- * untouched when the event is stale, filtered out, or out of the loaded window.
- *
- * - Out-of-order delivery can't regress a row: events older than the loaded row (by
- *   lastActivityAt) are dropped — checked FIRST, so a stale event can't evict a
- *   still-current row through the filter check below either. Renames keep
- *   lastActivityAt, so equal passes.
- * - A row that stops matching the active filters is removed; a matching one is upserted
- *   and the list re-sorted by the active sort (stable, so ties keep their server order).
- * - A NEW row sorting past every loaded row while more pages exist may belong beyond the
- *   loaded window; it's skipped so the list stays contiguous with the pagination cursor
- *   (unreachable under the default lastActivity-desc sort, where fresh activity sorts first).
- */
-/** Whether a row passes the list's active server-side filters. */
 export const matchesAgentThreadFilters = (item, options = {}) => (!options.status || item.status === options.status) &&
     (!options.source || item.source === options.source) &&
     (!options.chatId || item.chatId === options.chatId);
 export const applyAgentThreadUpdate = (threads, incoming, options = {}) => {
     const key = agentThreadKey(incoming);
     const existing = threads.find((thread) => agentThreadKey(thread) === key);
+    // Stale by lastActivityAt is dropped; equal passes (renames keep lastActivityAt).
     if (existing && sortTime(incoming, "lastActivity") < sortTime(existing, "lastActivity")) {
         return threads;
     }
@@ -99,18 +85,16 @@ export const applyAgentThreadUpdate = (threads, incoming, options = {}) => {
     }
     return next;
 };
-/**
- * Overlay optimistic rows (conversations the user just acted on, ChatGPT-style) onto the
- * loaded list. Each row goes through the same merge as a realtime event, so filters and
- * sorting apply — except that a server row still untitled borrows the optimistic
- * (prompt-derived) title until the generated one lands. Pure; returns `threads` untouched
- * when nothing changes.
- *
- * An entry steps aside once the loaded row has recorded MORE turns than it did: turnCount
- * is server-monotonic, so the handover can't be held off by a client clock running ahead
- * of the server (the entry's lastActivityAt is stamped locally, and the merge's staleness
- * guard compares it against server timestamps).
- */
+export const reconcileWalkWithLive = (items, live, options = {}) => {
+    let merged = items;
+    for (const entry of live.values()) {
+        merged =
+            "removed" in entry
+                ? (removeListedAgentThread(merged, entry.removed) ?? merged)
+                : applyAgentThreadUpdate(merged, entry, options);
+    }
+    return merged;
+};
 export const overlayOptimisticThreads = (threads, optimistic, options = {}) => {
     if (optimistic.size === 0) {
         return threads;
@@ -122,11 +106,44 @@ export const overlayOptimisticThreads = (threads, optimistic, options = {}) => {
             merged = applyAgentThreadUpdate(merged, row, options);
         }
     }
-    if (!merged.some((row) => row.title === null && optimistic.get(agentThreadKey(row))?.title)) {
-        return merged;
+    return merged;
+};
+// Retires for good once the server row shows a run — a settled error must not be hidden.
+export const retireOptimisticThreadsTakenOver = (optimistic, threads) => {
+    const taken = threads.filter((thread) => (thread.status === "busy" || thread.runningRunId != null) && optimistic.has(agentThreadKey(thread)));
+    if (taken.length === 0) {
+        return optimistic;
+    }
+    const next = new Map(optimistic);
+    for (const thread of taken) {
+        next.delete(agentThreadKey(thread));
+    }
+    return next;
+};
+/** The server's cap on a title a person sets (RENAME_TITLE_MAX_CHARS in wf-actions-py). */
+export const RENAME_TITLE_MAX_CHARS = 255;
+/** Conversation-index groups, in display order; a row's group follows its write-once `source`. */
+export const AGENT_THREAD_GROUPS = ["chats", "workflows", "feedback"];
+const GROUP_OF_SOURCE = {
+    direct_chat: "chats",
+    self_config_resume: "chats",
+    unknown: "chats",
+    send_message: "workflows",
+    feedback: "feedback",
+};
+/** Where a row files; a source this copy predates files under chats, so a row never renders nowhere. */
+export const agentThreadGroup = (source) => GROUP_OF_SOURCE[source] ?? "chats";
+/** Rows by group in group order, each group in input order; empty groups dropped. */
+export const groupAgentThreads = (threads) => {
+    const grouped = AGENT_THREAD_GROUPS.map((group) => ({ group, rows: [] }));
+    for (const thread of threads) {
+        grouped[AGENT_THREAD_GROUPS.indexOf(agentThreadGroup(thread.source))].rows.push(thread);
     }
-    return merged.map((row) => {
-        const provisional = row.title === null ? optimistic.get(agentThreadKey(row))?.title : null;
-        return provisional ? { ...row, title: provisional } : row;
-    });
+    return grouped.filter(({ rows }) => rows.length > 0);
 };
+/** A thread the agent opened to act on feedback — by `type`, or by `source` for rows from before the column. */
+export const isFeedbackThread = (row) => row.type === "feedback" || row.source === "feedback";
+/** The conversation a feedback thread was opened from, when `threads` lists it (same chat, the row's pointer). */
+export const feedbackSourceThread = (row, threads) => row.fromSourceChatThreadId
+    ? threads.find((candidate) => candidate.chatId === row.chatId && candidate.chatThreadId === row.fromSourceChatThreadId)
+    : undefined;

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

@@ -0,0 +1,105 @@
+import { type AgentThreadItem } from "./agent-thread-live-update.js";
+import type { UseAgentThreadsResult } from "./use-agent-threads.js";
+/** A conversation is the (chatId, chatThreadId) PAIR — rows under a fixed thread id differ by chat. */
+export type AgentConversationRef = Pick<AgentThreadItem, "chatId" | "chatThreadId">;
+/**
+ * A new chat is a draft: a thread id minted here, listed nowhere until the first send. "New
+ * chat" on an untouched draft keeps it; once sent, the draft is a thread like any other.
+ */
+export interface AgentConversationSelection {
+    conversation: AgentConversationRef;
+    draftThreadId: string;
+    draftSent: boolean;
+}
+export declare const newDraftSelection: (chatId: string, draftThreadId?: string) => AgentConversationSelection;
+/** A draft stands by even when the URL opens a thread: "New chat" from there must not mint twice. */
+export declare const initialSelection: (ownChatId: string, urlConversation: AgentConversationRef | undefined) => AgentConversationSelection;
+export declare const isDraftSelection: ({ conversation, draftThreadId, draftSent }: AgentConversationSelection) => boolean;
+/** After choosing a thread; the same object when it is already open (no re-render). */
+export declare const selectionWithThread: (prev: AgentConversationSelection, conversation: AgentConversationRef) => AgentConversationSelection;
+/** After "New chat": an untouched draft stays; anything else mints a fresh one. */
+export declare const selectionWithNewChat: (prev: AgentConversationSelection, ownChatId: string) => AgentConversationSelection;
+/** After the first send on the draft; unchanged when the draft is not the open conversation. */
+export declare const selectionAfterDraftSent: (prev: AgentConversationSelection) => AgentConversationSelection;
+/** What the URL names: a thread, the new chat, or no conversation (one of the surface's pages). */
+export type AgentConversationUrlTarget = AgentConversationRef | "new" | null;
+/** Identity of a URL target; the selection follows the URL whenever this changes. */
+export declare const urlSelectionKey: (target: AgentConversationUrlTarget) => string | null;
+export interface UseAgentConversationSelectionOptions {
+    /** The chat the surface's own conversations live under (agentInboxChatId). */
+    ownChatId: string;
+    urlTarget: AgentConversationUrlTarget;
+}
+export interface UseAgentConversationSelectionResult {
+    conversation: AgentConversationRef;
+    /** The new chat, nothing sent on it yet. */
+    isDraft: boolean;
+    /** After the first send on the draft — the caller then navigates to the draft's thread URL. */
+    markDraftSent: () => void;
+}
+/**
+ * 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 declare const useAgentConversationSelection: ({ ownChatId, urlTarget, }: UseAgentConversationSelectionOptions) => UseAgentConversationSelectionResult;
+export declare const RUN_STALE_MS: number;
+/** A row for a conversation the index lists nothing for (yet): the draft, or a thread whose row has not landed. */
+export declare const agentThreadStandIn: (agentId: string, conversation: AgentConversationRef, isDraft: boolean) => AgentThreadItem;
+/** When the oldest run mark among `rows` reaches the stale ceiling (epoch ms); null with no mark. */
+export declare const nextRunStaleAt: (rows: readonly AgentThreadItem[]) => number | null;
+/** The turns this client has accounted for on one conversation (`key`: agentThreadKey). */
+export interface AccountedTurns {
+    key: string;
+    turns: number;
+}
+/**
+ * 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 declare const accountedTurnsAfterRow: (accounted: AccountedTurns | null, key: string, turnCount: number, isThinking: boolean) => {
+    accounted: AccountedTurns | null;
+    replay: boolean;
+};
+/**
+ * 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 declare const accountedTurnsAfterOwnSend: (accounted: AccountedTurns | null, key: string, isDraft: boolean) => AccountedTurns | null;
+/** The chat runtime's side of the bridge — a subset of react-common's AgentChatContextValue. */
+export interface AgentConversationChat {
+    isThinking: boolean;
+    reloadMessages: () => Promise<void>;
+    /** Optional as on AgentChatContextValue: a context a host builds by hand may omit it. */
+    setRunningElsewhere?: (runId: string | null) => void;
+}
+export interface UseAgentConversationOptions {
+    /** The index the conversation is listed in. */
+    threads: UseAgentThreadsResult;
+    agentId: string;
+    conversation: AgentConversationRef;
+    isDraft: boolean;
+    chat: AgentConversationChat;
+}
+export interface UseAgentConversationResult {
+    /** The conversation's row: listed, else the last listed, else a stand-in. */
+    row: AgentThreadItem;
+    /** `row` is invented locally — the index lists nothing for this conversation. */
+    isStandIn: boolean;
+    /** `threads.renameThread`, keeping the remembered row's title current too. */
+    renameThread: UseAgentThreadsResult["renameThread"];
+    /** After this client sends on the conversation (the chat root's onUserMessageSent). */
+    notifyMessageSent: (text: string, message?: {
+        name?: string;
+    }) => void;
+}
+/**
+ * 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 declare const useAgentConversation: ({ threads, agentId, conversation, isDraft, chat, }: UseAgentConversationOptions) => UseAgentConversationResult;
+//# sourceMappingURL=use-agent-conversation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-agent-conversation.d.ts","sourceRoot":"","sources":["../../src/hooks/use-agent-conversation.ts"],"names":[],"mappings":"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"}