@stigmer/react 3.6.0 → 3.8.0

package/conversation/useConversation.js

@@ -0,0 +1,153 @@
+"use client";
+import { create, equals } from "@bufbuild/protobuf";
+import { isNotFound } from "@stigmer/sdk";
+import { ChannelConversationSchema, GetChannelConversationInputSchema, } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+import { CONVERSATION_DETAIL_POLL_INTERVAL_MS } from "./polling.js";
+/**
+ * Data hook for one conversation's identity and participation state —
+ * the single-row read behind a conversation detail view (who holds
+ * control, whether attention is needed and why, the display name).
+ *
+ * Deliberately NOT built on the shared `useFetch`: participation
+ * commands hand back fresher state than any in-flight poll
+ * ({@link UseConversationReturn.applyServerState}), which needs a write
+ * fence over the fetch state — a seam `useFetch`'s single-writer model
+ * does not have. The fence is an epoch counter: applying server state
+ * bumps it, and a poll that started under an older epoch discards its
+ * answer instead of resurrecting pre-command state under the user's
+ * cursor.
+ *
+ * Pass empty strings to skip fetching (the `null`-fetchFn convention).
+ */
+export function useConversation(agentChannelId, conversationKey, options) {
+    const stigmer = useStigmer();
+    const refetchIntervalMs = options?.refetchIntervalMs ?? CONVERSATION_DETAIL_POLL_INTERVAL_MS;
+    const enabled = agentChannelId !== "" && conversationKey !== "";
+    const [conversation, setConversation] = useState(null);
+    const [awaitingCustomer, setAwaitingCustomer] = useState(false);
+    const [hasAnswer, setHasAnswer] = useState(false);
+    const [isFetching, setIsFetching] = useState(enabled);
+    const [error, setError] = useState(null);
+    const [fetchKey, setFetchKey] = useState(0);
+    // The write fence: bumped by applyServerState and by identity changes;
+    // a fetch that started under an older epoch throws its answer away.
+    const epochRef = useRef(0);
+    // Which fetch is the latest — ONLY the latest fetch's resolution may
+    // clear the in-flight flags, so a fenced stale answer cannot strand
+    // isFetching=true (which would silence the poll interval forever).
+    const fetchIdRef = useRef(0);
+    const isFetchingRef = useRef(false);
+    const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+    const applyServerState = useCallback((fresh) => {
+        epochRef.current += 1;
+        setConversation(fresh);
+        setAwaitingCustomer(false);
+        setHasAnswer(true);
+        setError(null);
+    }, []);
+    useEffect(() => {
+        // Identity change (or disable): reset so channel A's control state
+        // can never render under channel B's key.
+        epochRef.current += 1;
+        setConversation(null);
+        setAwaitingCustomer(false);
+        setHasAnswer(false);
+        setError(null);
+        if (!enabled) {
+            setIsFetching(false);
+            isFetchingRef.current = false;
+        }
+    }, [agentChannelId, conversationKey, stigmer, enabled]);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const epoch = epochRef.current;
+        const fetchId = ++fetchIdRef.current;
+        setIsFetching(true);
+        isFetchingRef.current = true;
+        const settle = () => {
+            if (fetchIdRef.current !== fetchId)
+                return;
+            setIsFetching(false);
+            isFetchingRef.current = false;
+        };
+        stigmer.agentChannel
+            .getConversation(create(GetChannelConversationInputSchema, { agentChannelId, conversationKey }))
+            .then((row) => {
+            if (epochRef.current === epoch) {
+                // Preserve the reference across polls that change nothing —
+                // a fresh-but-equal proto every 5s would defeat React.memo
+                // on everything rendering the row (DD-010).
+                setConversation((current) => current && equals(ChannelConversationSchema, current, row)
+                    ? current
+                    : row);
+                setAwaitingCustomer(false);
+                setHasAnswer(true);
+                setError(null);
+            }
+            settle();
+        }, (err) => {
+            if (epochRef.current === epoch) {
+                if (isNotFound(err)) {
+                    // The legitimate "no row yet" answer — not an error state.
+                    setConversation(null);
+                    setAwaitingCustomer(true);
+                    setHasAnswer(true);
+                    setError(null);
+                }
+                else {
+                    setError(toError(err));
+                }
+            }
+            settle();
+        });
+    }, [enabled, agentChannelId, conversationKey, stigmer, fetchKey]);
+    useEffect(() => {
+        if (!enabled || !refetchIntervalMs || refetchIntervalMs <= 0)
+            return;
+        const id = setInterval(() => {
+            if (!isFetchingRef.current)
+                refetch();
+        }, refetchIntervalMs);
+        return () => clearInterval(id);
+    }, [enabled, refetchIntervalMs, refetch]);
+    // Focus refetch (DD-012 D-a: returning to the tab is fresh), guarded by
+    // the same in-flight flag as the interval. Mirrors useFetch's
+    // refetchOnWindowFocus — the second sighting of this listener shape;
+    // extract a shared helper if a third hand-rolled loop ever needs it.
+    useEffect(() => {
+        if (!enabled)
+            return;
+        if (typeof window === "undefined")
+            return;
+        const onActive = () => {
+            if (!isFetchingRef.current)
+                refetch();
+        };
+        const onVisible = () => {
+            if (document.visibilityState === "visible")
+                onActive();
+        };
+        window.addEventListener("focus", onActive);
+        document.addEventListener("visibilitychange", onVisible);
+        return () => {
+            window.removeEventListener("focus", onActive);
+            document.removeEventListener("visibilitychange", onVisible);
+        };
+    }, [enabled, refetch]);
+    const isLoading = isFetching && !hasAnswer;
+    const isRefetching = isFetching && hasAnswer;
+    return useMemo(() => ({
+        conversation,
+        awaitingCustomer,
+        isLoading,
+        isRefetching,
+        error,
+        refetch,
+        applyServerState,
+    }), [conversation, awaitingCustomer, isLoading, isRefetching, error, refetch, applyServerState]);
+}
+//# sourceMappingURL=useConversation.js.map

package/conversation/useConversation.js.map

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

package/conversation/useConversationList.d.ts

@@ -0,0 +1,98 @@
+import type { ChannelConversation } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { ChannelConversationListFilter } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+/** Options for {@link useConversationList}. */
+export interface UseConversationListOptions {
+    /** Organization whose conversations to list. `null` skips fetching. */
+    readonly org: string | null;
+    /** Optional filter: only conversations on this agent channel. */
+    readonly agentChannelId?: string;
+    /**
+     * Optional server-evaluated predicate filter (channel-conversations
+     * DD-011 D-g). The generated enum is the vocabulary on purpose — the
+     * predicate lives in ONE place, the server, and the hook never
+     * re-expresses it. Defaults to unspecified (no filter).
+     */
+    readonly filter?: ChannelConversationListFilter;
+    /** Page size for the head page and each loadMore page. Default 50. */
+    readonly pageSize?: number;
+    /**
+     * Poll interval in milliseconds; `false` disables polling. Defaults to
+     * {@link CONVERSATION_LIST_POLL_INTERVAL_MS}. Only the head page polls
+     * — loaded older pages refresh on the next full identity change.
+     */
+    readonly refetchIntervalMs?: number | false;
+}
+/** Return value of {@link useConversationList}. */
+export interface UseConversationListReturn {
+    /**
+     * Conversations, newest activity first: the polled head page followed
+     * by the accumulated older pages, deduplicated by conversation
+     * identity (offset pages drift under live activity — a conversation
+     * that moved up between fetches appears once, in its head position),
+     * with any {@link applyServerState} rows overriding both.
+     */
+    readonly conversations: readonly ChannelConversation[];
+    /** Exact total for the current filter, from the server. */
+    readonly totalCount: number;
+    /** `true` while more conversations exist beyond what is loaded. */
+    readonly hasMore: boolean;
+    /** Load the next older page. No-op while one is already loading. */
+    readonly loadMore: () => void;
+    /** `true` while a loadMore page is in flight. */
+    readonly isLoadingMore: boolean;
+    /** Error from the last failed loadMore, or `null`. Cleared on retry. */
+    readonly loadMoreError: Error | null;
+    /** `true` only during the first head-page load. */
+    readonly isLoading: boolean;
+    /** `true` while the head page refreshes in the background. */
+    readonly isRefetching: boolean;
+    /** Error from the last failed head-page fetch, or `null`. */
+    readonly error: Error | null;
+    /** Re-fetch the head page. */
+    readonly refetch: () => void;
+    /**
+     * Adopt a fresh row the server just returned — every participation
+     * command answers the post-command state, and that answer is newer
+     * than anything a poll already in flight will deliver (DD-012 D-a:
+     * your own action reflects immediately, zero polls involved). The row
+     * overrides the listed copy for exactly one round-trip: applying also
+     * starts a fresh head fetch, and the override is dropped when a page
+     * provably fetched after the apply answers.
+     */
+    readonly applyServerState: (fresh: ChannelConversation) => void;
+}
+/**
+ * Data hook for the org-wide conversation list (channel-conversations
+ * DD-004): newest activity first across every channel the caller can
+ * view, optionally narrowed to one channel and/or a server-evaluated
+ * predicate ({@link ChannelConversationListFilter}).
+ *
+ * The head page rides `useFetch` and polls; older pages accumulate via
+ * {@link UseConversationListReturn.loadMore} and are merged with head
+ * precedence — the server's offset pagination shifts under live activity,
+ * so identity dedup (head copy wins: it is the fresher read) is what
+ * keeps a moving conversation from rendering twice.
+ *
+ * Command answers enter through
+ * {@link UseConversationListReturn.applyServerState} as a short-lived
+ * OVERLAY rather than a write into the fetched state, because `useFetch`
+ * has no write fence (the reason `useConversation` is hand-rolled): a
+ * poll answer already in the microtask queue when the command answers can
+ * commit AFTER the apply, and clearing the adopted row on "any head
+ * change" would hand the inbox back to pre-command state for a full poll
+ * period. Instead every head page is stamped with the apply-sequence at
+ * fetch start, and the overlay is dropped only when a page with
+ * `seq >= overlay.seq` — one provably started after the apply — answers.
+ * Applying triggers that fetch immediately, so the overlay lives for
+ * exactly one round-trip.
+ *
+ * Two honesty guards on overlay INSERTS (rows the server has not listed):
+ * a row from another channel never enters a channel-scoped list (identity
+ * equality — the same scope the hook sends to the server), and under a
+ * server-evaluated predicate filter the overlay is update-only, because
+ * the client cannot honestly claim membership the server has not
+ * asserted (the DD-011 A-1 one-predicate discipline). Updates in place
+ * are always honest: the server listed the row.
+ */
+export declare function useConversationList(options: UseConversationListOptions): UseConversationListReturn;
+//# sourceMappingURL=useConversationList.d.ts.map

package/conversation/useConversationList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useConversationList.d.ts","sourceRoot":"","sources":["../../src/conversation/useConversationList.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uEAAuE,CAAC;AACjH,OAAO,EACL,6BAA6B,EAE9B,MAAM,uEAAuE,CAAC;AAO/E,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,6BAA6B,CAAC;IAChD,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC7C;AAED,mDAAmD;AACnD,MAAM,WAAW,yBAAyB;IACxC;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACvD,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,wEAAwE;IACxE,QAAQ,CAAC,aAAa,EAAE,KAAK,GAAG,IAAI,CAAC;IACrC,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAC7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,gBAAgB,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;CACjE;AAmCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,yBAAyB,CAsL3B"}

package/conversation/useConversationList.js

@@ -0,0 +1,200 @@
+"use client";
+import { create } from "@bufbuild/protobuf";
+import { ChannelConversationListFilter, ListChannelConversationsInputSchema, } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+import { useFetch } from "../internal/useFetch.js";
+import { CONVERSATION_LIST_POLL_INTERVAL_MS } from "./polling.js";
+const EMPTY_HEAD = { items: [], totalCount: 0, seq: 0 };
+const EMPTY_OVERLAY = { rows: new Map(), seq: 0 };
+function identityOf(conversation) {
+    return `${conversation.agentChannelId}\u0000${conversation.conversationKey}`;
+}
+/** Activity instant in epoch milliseconds, for sorted overlay inserts. */
+function activityMillisOf(conversation) {
+    const at = conversation.lastActivityAt;
+    if (!at)
+        return 0;
+    return Number(at.seconds) * 1_000 + Math.floor(at.nanos / 1_000_000);
+}
+/**
+ * Data hook for the org-wide conversation list (channel-conversations
+ * DD-004): newest activity first across every channel the caller can
+ * view, optionally narrowed to one channel and/or a server-evaluated
+ * predicate ({@link ChannelConversationListFilter}).
+ *
+ * The head page rides `useFetch` and polls; older pages accumulate via
+ * {@link UseConversationListReturn.loadMore} and are merged with head
+ * precedence — the server's offset pagination shifts under live activity,
+ * so identity dedup (head copy wins: it is the fresher read) is what
+ * keeps a moving conversation from rendering twice.
+ *
+ * Command answers enter through
+ * {@link UseConversationListReturn.applyServerState} as a short-lived
+ * OVERLAY rather than a write into the fetched state, because `useFetch`
+ * has no write fence (the reason `useConversation` is hand-rolled): a
+ * poll answer already in the microtask queue when the command answers can
+ * commit AFTER the apply, and clearing the adopted row on "any head
+ * change" would hand the inbox back to pre-command state for a full poll
+ * period. Instead every head page is stamped with the apply-sequence at
+ * fetch start, and the overlay is dropped only when a page with
+ * `seq >= overlay.seq` — one provably started after the apply — answers.
+ * Applying triggers that fetch immediately, so the overlay lives for
+ * exactly one round-trip.
+ *
+ * Two honesty guards on overlay INSERTS (rows the server has not listed):
+ * a row from another channel never enters a channel-scoped list (identity
+ * equality — the same scope the hook sends to the server), and under a
+ * server-evaluated predicate filter the overlay is update-only, because
+ * the client cannot honestly claim membership the server has not
+ * asserted (the DD-011 A-1 one-predicate discipline). Updates in place
+ * are always honest: the server listed the row.
+ */
+export function useConversationList(options) {
+    const { org, agentChannelId = "", filter = ChannelConversationListFilter.channel_conversation_list_filter_unspecified, pageSize = 50, } = options;
+    const refetchIntervalMs = options.refetchIntervalMs ?? CONVERSATION_LIST_POLL_INTERVAL_MS;
+    const stigmer = useStigmer();
+    // Monotonic count of applyServerState calls; head pages carry the
+    // value read at their fetch start (see HeadPage.seq).
+    const applySeqRef = useRef(0);
+    const fetchFn = org
+        ? async () => {
+            const seq = applySeqRef.current;
+            const result = await stigmer.agentChannel.listConversations(create(ListChannelConversationsInputSchema, {
+                org,
+                agentChannelId,
+                filter,
+                pageInfo: { num: 1, size: pageSize },
+            }));
+            return { items: result.items, totalCount: result.totalCount, seq };
+        }
+        : null;
+    const { data: head, isLoading, isRefetching, error, refetch, } = useFetch(fetchFn, [org, agentChannelId, filter, pageSize, stigmer], EMPTY_HEAD, {
+        refetchInterval: refetchIntervalMs,
+        // DD-012 D-a: returning to the tab is fresh.
+        refetchOnWindowFocus: true,
+    });
+    // Older pages, keyed by the same identity deps as the head fetch; the
+    // epoch fences in-flight loadMore answers across an identity change.
+    const [olderPages, setOlderPages] = useState([]);
+    const [loadedThroughPage, setLoadedThroughPage] = useState(1);
+    const [isLoadingMore, setIsLoadingMore] = useState(false);
+    const [loadMoreError, setLoadMoreError] = useState(null);
+    const [overlay, setOverlay] = useState(EMPTY_OVERLAY);
+    const epochRef = useRef(0);
+    useEffect(() => {
+        epochRef.current += 1;
+        setOlderPages([]);
+        setLoadedThroughPage(1);
+        setIsLoadingMore(false);
+        setLoadMoreError(null);
+        setOverlay(EMPTY_OVERLAY);
+    }, [org, agentChannelId, filter, pageSize, stigmer]);
+    const applyServerState = useCallback((fresh) => {
+        const seq = ++applySeqRef.current;
+        setOverlay((current) => {
+            const rows = new Map(current.rows);
+            rows.set(identityOf(fresh), fresh);
+            return { rows, seq };
+        });
+        // Starts the round-trip that retires the overlay; also cancels any
+        // in-flight pre-command head fetch (useFetch's cleanup semantics).
+        refetch();
+    }, [refetch]);
+    // Retire the overlay once a head page fetched after the newest apply
+    // answers — server truth has caught up. A page with an older stamp
+    // (the microtask-race case) keeps the overlay in force.
+    useEffect(() => {
+        if (overlay.rows.size === 0)
+            return;
+        if (head.seq >= overlay.seq)
+            setOverlay(EMPTY_OVERLAY);
+    }, [head, overlay]);
+    const loadMore = useCallback(() => {
+        if (!org || isLoadingMore)
+            return;
+        const epoch = epochRef.current;
+        const nextPage = loadedThroughPage + 1;
+        setIsLoadingMore(true);
+        setLoadMoreError(null);
+        stigmer.agentChannel
+            .listConversations(create(ListChannelConversationsInputSchema, {
+            org,
+            agentChannelId,
+            filter,
+            pageInfo: { num: nextPage, size: pageSize },
+        }))
+            .then((result) => {
+            if (epochRef.current !== epoch)
+                return;
+            setOlderPages((pages) => [...pages, result.items]);
+            setLoadedThroughPage(nextPage);
+            setIsLoadingMore(false);
+        }, (err) => {
+            if (epochRef.current !== epoch)
+                return;
+            setLoadMoreError(toError(err));
+            setIsLoadingMore(false);
+        });
+    }, [org, agentChannelId, filter, pageSize, stigmer, isLoadingMore, loadedThroughPage]);
+    const conversations = useMemo(() => {
+        const seen = new Set();
+        const merged = [];
+        for (const conversation of [...head.items, ...olderPages.flat()]) {
+            const identity = identityOf(conversation);
+            if (seen.has(identity))
+                continue;
+            seen.add(identity);
+            // Update-in-place is always honest: the server listed this row.
+            merged.push(overlay.rows.get(identity) ?? conversation);
+        }
+        // Overlay rows the server has not listed: sorted insert (a command
+        // answer is not a recency claim — a takeover does not advance the
+        // activity clock, so head-of-list would misorder), subject to the
+        // two honesty guards documented on the hook.
+        for (const [identity, fresh] of overlay.rows) {
+            if (seen.has(identity))
+                continue;
+            if (filter !==
+                ChannelConversationListFilter.channel_conversation_list_filter_unspecified) {
+                continue;
+            }
+            if (agentChannelId !== "" && fresh.agentChannelId !== agentChannelId) {
+                continue;
+            }
+            const at = activityMillisOf(fresh);
+            const index = merged.findIndex((c) => activityMillisOf(c) < at);
+            merged.splice(index === -1 ? merged.length : index, 0, fresh);
+            seen.add(identity);
+        }
+        return merged;
+    }, [head.items, olderPages, overlay, agentChannelId, filter]);
+    const hasMore = conversations.length < head.totalCount;
+    return useMemo(() => ({
+        conversations,
+        totalCount: head.totalCount,
+        hasMore,
+        loadMore,
+        isLoadingMore,
+        loadMoreError,
+        isLoading,
+        isRefetching,
+        error,
+        refetch,
+        applyServerState,
+    }), [
+        conversations,
+        head.totalCount,
+        hasMore,
+        loadMore,
+        isLoadingMore,
+        loadMoreError,
+        isLoading,
+        isRefetching,
+        error,
+        refetch,
+        applyServerState,
+    ]);
+}
+//# sourceMappingURL=useConversationList.js.map

package/conversation/useConversationList.js.map

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

package/conversation/useConversationParticipation.d.ts

@@ -0,0 +1,63 @@
+import type { ChannelConversation } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import type { SendChannelMessageOutput } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
+/** The four staff-facing participation commands. */
+export type ConversationCommand = "reply" | "takeOver" | "handBack" | "clearAttention";
+/** Options for {@link useConversationParticipation}. */
+export interface UseConversationParticipationOptions {
+    /** AgentChannel the conversation belongs to. */
+    readonly agentChannelId: string;
+    /** Conversation key within the channel. */
+    readonly conversationKey: string;
+    /**
+     * Receives the fresh conversation row every command answers with —
+     * wire it to {@link useConversation}'s `applyServerState` so banners
+     * and controls adopt server truth immediately. Called for reply too
+     * (via a follow-up row read): a staff reply implicitly takes over
+     * BEFORE the send, unconditionally, so control has moved even when
+     * the send itself was refused.
+     */
+    readonly onConversation?: (fresh: ChannelConversation) => void;
+}
+/** Return value of {@link useConversationParticipation}. */
+export interface UseConversationParticipationReturn {
+    /**
+     * Send a staff text reply. Resolves with the truthful outcome of the
+     * inline attempt: `accepted` (with `outboundMessageId` — the item will
+     * appear on the timeline as `ob:<that id>`), `queued`, or `refused`.
+     * A `refused` outcome WITHOUT an `outboundMessageId` left no ledger
+     * row and no timeline item will ever exist for it.
+     */
+    readonly reply: (text: string) => Promise<SendChannelMessageOutput>;
+    /**
+     * Take the conversation over: the agent goes quiet until handBack.
+     * Resolves with the fresh row — for the LOSER of a concurrent
+     * takeover too (success-with-the-winner's-state, never an error), so
+     * compare `controlledBy` against the caller rather than assuming the
+     * transition won.
+     */
+    readonly takeOver: () => Promise<ChannelConversation>;
+    /** Hand the conversation back to the agent. */
+    readonly handBack: () => Promise<ChannelConversation>;
+    /** Dismiss the needs-attention flag in place; control is untouched. */
+    readonly clearAttention: () => Promise<ChannelConversation>;
+    /** Commands currently in flight. */
+    readonly pendingCommands: ReadonlySet<ConversationCommand>;
+    /** Per-command failures, cleared when that command is retried. */
+    readonly commandErrors: ReadonlyMap<ConversationCommand, Error>;
+    /** Reset every recorded command error. */
+    readonly clearErrors: () => void;
+}
+/**
+ * Behavior hook for the participation commands on one conversation
+ * (channel-conversations DD-005/DD-007/DD-008/DD-009): reply, takeOver,
+ * handBack, clearAttention — each keyed independently so a slow reply
+ * and a takeover can be in flight at once with attributable spinners
+ * and errors.
+ *
+ * Every command re-throws its failure after recording it in
+ * {@link UseConversationParticipationReturn.commandErrors}, so callers
+ * choose the propagation (await-and-toast, or ignore and render the
+ * keyed error inline).
+ */
+export declare function useConversationParticipation(options: UseConversationParticipationOptions): UseConversationParticipationReturn;
+//# sourceMappingURL=useConversationParticipation.d.ts.map

package/conversation/useConversationParticipation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useConversationParticipation.d.ts","sourceRoot":"","sources":["../../src/conversation/useConversationParticipation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,mBAAmB,EACpB,MAAM,uEAAuE,CAAC;AAM/E,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kEAAkE,CAAC;AAKjH,oDAAoD;AACpD,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAEvF,wDAAwD;AACxD,MAAM,WAAW,mCAAmC;IAClD,gDAAgD;IAChD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;CAChE;AAED,4DAA4D;AAC5D,MAAM,WAAW,kCAAkC;IACjD;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACpE;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACtD,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACtD,uEAAuE;IACvE,QAAQ,CAAC,cAAc,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC5D,oCAAoC;IACpC,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,mBAAmB,CAAC,CAAC;IAC3D,kEAAkE;IAClE,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,mBAAmB,EAAE,KAAK,CAAC,CAAC;IAChE,0CAA0C;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,mCAAmC,GAC3C,kCAAkC,CAiGpC"}

package/conversation/useConversationParticipation.js

@@ -0,0 +1,84 @@
+"use client";
+import { create } from "@bufbuild/protobuf";
+import { ConversationControlInputSchema, GetChannelConversationInputSchema, ReplyToConversationInputSchema, } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { useCallback, useMemo } from "react";
+import { useStigmer } from "../hooks.js";
+import { useKeyedSubmission } from "../internal/useKeyedSubmission.js";
+/**
+ * Behavior hook for the participation commands on one conversation
+ * (channel-conversations DD-005/DD-007/DD-008/DD-009): reply, takeOver,
+ * handBack, clearAttention — each keyed independently so a slow reply
+ * and a takeover can be in flight at once with attributable spinners
+ * and errors.
+ *
+ * Every command re-throws its failure after recording it in
+ * {@link UseConversationParticipationReturn.commandErrors}, so callers
+ * choose the propagation (await-and-toast, or ignore and render the
+ * keyed error inline).
+ */
+export function useConversationParticipation(options) {
+    const { agentChannelId, conversationKey, onConversation } = options;
+    const stigmer = useStigmer();
+    const submission = useKeyedSubmission();
+    const { run } = submission;
+    const controlInput = useCallback(() => create(ConversationControlInputSchema, { agentChannelId, conversationKey }), [agentChannelId, conversationKey]);
+    const takeOver = useCallback(() => run("takeOver", async () => {
+        const fresh = await stigmer.agentChannel.takeOver(controlInput());
+        onConversation?.(fresh);
+        return fresh;
+    }), [run, stigmer, controlInput, onConversation]);
+    const handBack = useCallback(() => run("handBack", async () => {
+        const fresh = await stigmer.agentChannel.handBack(controlInput());
+        onConversation?.(fresh);
+        return fresh;
+    }), [run, stigmer, controlInput, onConversation]);
+    const clearAttention = useCallback(() => run("clearAttention", async () => {
+        const fresh = await stigmer.agentChannel.clearAttention(controlInput());
+        onConversation?.(fresh);
+        return fresh;
+    }), [run, stigmer, controlInput, onConversation]);
+    const reply = useCallback((text) => run("reply", async () => {
+        const output = await stigmer.agentChannel.reply(create(ReplyToConversationInputSchema, {
+            agentChannelId,
+            conversationKey,
+            payload: { kind: { case: "text", value: { body: text } } },
+        }));
+        // The implicit takeover flipped control BEFORE the send ran —
+        // even a refused reply moved it — but reply answers the send
+        // outcome, not the row. One follow-up read keeps the control
+        // banner honest without waiting a poll tick. Best-effort: a
+        // failed read only delays the banner until the next poll.
+        if (onConversation) {
+            try {
+                onConversation(await stigmer.agentChannel.getConversation(create(GetChannelConversationInputSchema, {
+                    agentChannelId,
+                    conversationKey,
+                })));
+            }
+            catch {
+                // The reply itself succeeded; the poll will catch the row up.
+            }
+        }
+        return output;
+    }), [run, stigmer, agentChannelId, conversationKey, onConversation]);
+    return useMemo(() => ({
+        reply,
+        takeOver,
+        handBack,
+        clearAttention,
+        // The submission primitive keys by string; this hook only ever
+        // submits the four command names, so the narrowing is sound.
+        pendingCommands: submission.submittingKeys,
+        commandErrors: submission.errorsByKey,
+        clearErrors: submission.clearErrors,
+    }), [
+        reply,
+        takeOver,
+        handBack,
+        clearAttention,
+        submission.submittingKeys,
+        submission.errorsByKey,
+        submission.clearErrors,
+    ]);
+}
+//# sourceMappingURL=useConversationParticipation.js.map

package/conversation/useConversationParticipation.js.map

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