@agent-native/core 0.211.0 → 0.212.0-nightly-20261021010049

package/dist/client/sharing/useShareVisibilityTransition.js

@@ -0,0 +1,224 @@
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore, } from "react";
+import { useOrg } from "../org/hooks.js";
+import { extractShareErrorMessage } from "./share-controller-helpers.js";
+/**
+ * Whether moving to `to` shows more of the resource to more people than `from`
+ * does and so needs an explicit confirmation. Public -> organization narrows
+ * access and Public stays confirmation-free, so only private -> organization
+ * asks.
+ */
+export function visibilityNeedsConfirmation(from, to) {
+    return from === "private" && to === "org";
+}
+/**
+ * Why a requested visibility change was never saved: `ignored` when the
+ * request was refused up front (closed surface, no manage rights, a save
+ * already running) and `dropped` when it was held for confirmation and then
+ * cancelled or invalidated.
+ */
+export class ShareVisibilityNotSavedError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason === "dropped"
+            ? "The visibility change was not confirmed."
+            : "The visibility change was not applied.");
+        this.name = "ShareVisibilityNotSavedError";
+        this.reason = reason;
+    }
+}
+function notSaved(reason) {
+    const rejected = Promise.reject(new ShareVisibilityNotSavedError(reason));
+    // Callers that fire and forget must not raise an unhandled rejection; one
+    // that awaits the returned promise still sees it.
+    rejected.catch(() => undefined);
+    return rejected;
+}
+// A surface can unmount while its server write keeps running. Keep the lock
+// for that write's lifetime across all sharing surfaces in this browser session.
+const inflightSaves = new Map();
+const saveListeners = new Set();
+function subscribeToSaves(listener) {
+    saveListeners.add(listener);
+    return () => {
+        saveListeners.delete(listener);
+    };
+}
+function notifySaves() {
+    for (const listener of saveListeners)
+        listener();
+}
+export function useShareVisibilityTransition(options) {
+    const { resourceType, resourceId, current, canManage, active } = options;
+    const resourceKey = `${resourceType}:${resourceId}`;
+    const [pending, setPendingState] = useState(null);
+    const [confirming, setSubmittingState] = useState(false);
+    const inflight = useSyncExternalStore(subscribeToSaves, () => inflightSaves.get(resourceKey), () => undefined);
+    const submitting = confirming || inflight !== undefined;
+    const [error, setError] = useState(null);
+    const pendingRef = useRef(null);
+    // Closing the surface drops its UI state, but cannot cancel a server write.
+    const confirmingRef = useRef(new Map());
+    // Bumped whenever the pending request is dropped, so a save that finishes
+    // afterwards cannot touch the next request's state.
+    const generationRef = useRef(0);
+    const latestRef = useRef({ ...options, resourceKey });
+    latestRef.current = { ...options, resourceKey };
+    const org = useOrg({
+        enabled: active && canManage && pending !== null && options.orgId !== null,
+    });
+    const organizationName = readOrganizationName(org.data, options.orgId);
+    const reset = useCallback(() => {
+        generationRef.current += 1;
+        // A save that is already running settles the request itself.
+        const state = pendingRef.current;
+        if (state && confirmingRef.current.get(state.resourceKey) !== state) {
+            state.settle.reject(new ShareVisibilityNotSavedError("dropped"));
+        }
+        pendingRef.current = null;
+        setPendingState(null);
+        setSubmittingState(false);
+        setError(null);
+    }, []);
+    useEffect(() => reset, [reset]);
+    useEffect(() => {
+        reset();
+    }, [reset, resourceKey]);
+    useEffect(() => {
+        if (!active || !canManage)
+            reset();
+    }, [active, canManage, reset]);
+    // The saved value moved under the dialog (another tab, a refetch), so the
+    // change it describes is no longer the one it would make. While a save is
+    // running `current` is the optimistic value, which is expected to differ.
+    useEffect(() => {
+        if (pending && !submitting && pending.from !== current)
+            reset();
+    }, [current, pending, reset, submitting]);
+    const track = useCallback((key, target, promise) => {
+        const entry = { target, promise };
+        inflightSaves.set(key, entry);
+        notifySaves();
+        const clear = () => {
+            if (inflightSaves.get(key) === entry) {
+                inflightSaves.delete(key);
+                notifySaves();
+            }
+        };
+        promise.then(clear, clear);
+    }, []);
+    const request = useCallback((next) => {
+        const latest = latestRef.current;
+        const inflight = inflightSaves.get(latest.resourceKey);
+        if (inflight?.target === next)
+            return inflight.promise;
+        if (inflight)
+            return notSaved("ignored");
+        if (next === latest.current) {
+            return Promise.resolve();
+        }
+        if (!latest.canManage || !latest.active) {
+            return notSaved("ignored");
+        }
+        if (!visibilityNeedsConfirmation(latest.current, next)) {
+            reset();
+            const generation = generationRef.current;
+            const saved = latest.apply(next);
+            track(latest.resourceKey, next, saved);
+            saved.catch((failure) => {
+                // Only the newest intent on this resource reports to the shared
+                // error state. An older failure, or one from a resource the surface
+                // has left, still rejects for its caller but must not show here.
+                // The generation moves in an effect, so the resource is also checked
+                // against the live value.
+                if (generation === generationRef.current &&
+                    latestRef.current.resourceKey === latest.resourceKey) {
+                    latest.onDirectError(failure);
+                }
+            });
+            return saved;
+        }
+        // A held request replaces any earlier one, which is dropped.
+        reset();
+        const held = new Promise((resolve, reject) => {
+            const state = {
+                from: latest.current,
+                to: next,
+                resourceKey: latest.resourceKey,
+                settle: { resolve, reject },
+            };
+            pendingRef.current = state;
+            setPendingState(state);
+            setError(null);
+        });
+        held.catch(() => undefined);
+        return held;
+    }, [reset, track]);
+    const confirm = useCallback(async () => {
+        const state = pendingRef.current;
+        if (!state ||
+            confirmingRef.current.has(state.resourceKey) ||
+            inflightSaves.has(state.resourceKey))
+            return;
+        const latest = latestRef.current;
+        // The effects that drop a stale request run after render; a click can
+        // land before them, so the request is checked against the live values.
+        if (state.resourceKey !== latest.resourceKey ||
+            !latest.canManage ||
+            !latest.active ||
+            state.from !== latest.current) {
+            reset();
+            return;
+        }
+        const generation = generationRef.current;
+        confirmingRef.current.set(state.resourceKey, state);
+        setSubmittingState(true);
+        setError(null);
+        try {
+            const applying = latest.apply(state.to);
+            track(state.resourceKey, state.to, applying);
+            await applying;
+            state.settle.resolve();
+            if (generation !== generationRef.current)
+                return;
+            pendingRef.current = null;
+            setPendingState(null);
+        }
+        catch (failure) {
+            if (generation !== generationRef.current) {
+                state.settle.reject(new ShareVisibilityNotSavedError("dropped"));
+                return;
+            }
+            setError(extractShareErrorMessage(failure));
+        }
+        finally {
+            confirmingRef.current.delete(state.resourceKey);
+            if (generation === generationRef.current) {
+                setSubmittingState(false);
+            }
+        }
+    }, [reset, track]);
+    const cancel = useCallback(() => {
+        const state = pendingRef.current;
+        if (state && confirmingRef.current.has(state.resourceKey))
+            return;
+        reset();
+    }, [reset]);
+    return {
+        pending: pending ? { from: pending.from, to: pending.to } : null,
+        organizationName,
+        submitting,
+        error,
+        request,
+        confirm,
+        cancel,
+    };
+}
+function readOrganizationName(org, resourceOrgId) {
+    if (!org || !resourceOrgId)
+        return null;
+    const name = org.orgId === resourceOrgId
+        ? org.orgName
+        : org.orgs?.find((summary) => summary.orgId === resourceOrgId)?.orgName;
+    const trimmed = typeof name === "string" ? name.trim() : "";
+    return trimmed || null;
+}

package/dist/client/use-chat-thread-list.d.ts

@@ -0,0 +1,40 @@
+import { type ChatThreadOwnership, type ChatThreadListRow, type ChatThreadScope } from "./use-chat-threads.js";
+export interface UseChatThreadListOptions {
+    /** Which list this is. Narrowed on the server before paging. */
+    ownership: ChatThreadOwnership;
+    /** Rows per page, an integer from 1 to 200. Defaults to 50. Anything else throws `ChatThreadListConfigError`. */
+    pageSize?: number;
+    scope?: ChatThreadScope | null;
+    includeExternal?: boolean;
+    /** Search text. Empty lists the whole set. */
+    query?: string;
+    /** When false nothing is fetched and the list is empty. Defaults to true. */
+    enabled?: boolean;
+    /** Listen for thread update events and refresh loaded rows. Defaults to true. Does not affect initial or manual refreshes. */
+    refreshOnThreadUpdates?: boolean;
+    apiUrl?: string;
+}
+export interface UseChatThreadListResult {
+    threads: ChatThreadListRow[];
+    /** True until the first page of the current list settles. */
+    loading: boolean;
+    loadingMore: boolean;
+    /** The last request failed; `threads` keeps whatever was already loaded. */
+    error: Error | null;
+    /** The server has rows past the ones loaded. */
+    hasMore: boolean;
+    loadMore: () => Promise<void>;
+    refresh: () => Promise<void>;
+}
+/** `pageSize` is not an integer between 1 and the server's page cap. */
+export declare class ChatThreadListConfigError extends Error {
+    constructor(pageSize: unknown);
+}
+/**
+ * One paginated chat history list (`mine`, `shared`, or `all`). Each list pages
+ * independently, so a long Shared list never waits on My chats. It refetches
+ * by default when a thread mutation in this tab calls `notifyChatThreadsUpdated`,
+ * keeping every row already loaded, however many server pages that spans,
+ * rather than collapsing to the first page.
+ */
+export declare function useChatThreadList(options: UseChatThreadListOptions): UseChatThreadListResult;

package/dist/client/use-chat-thread-list.js

@@ -0,0 +1,210 @@
+import { useCallback, useEffect, useLayoutEffect, useState } from "react";
+import { agentNativePath } from "./api-path.js";
+import { CHAT_THREADS_MAX_PAGE_SIZE, CHAT_THREADS_UPDATED_EVENT, ChatThreadListError, fetchChatThreadListPage, } from "./use-chat-threads.js";
+const DEFAULT_PAGE_SIZE = 50;
+/** `pageSize` is not an integer between 1 and the server's page cap. */
+export class ChatThreadListConfigError extends Error {
+    constructor(pageSize) {
+        super(`useChatThreadList pageSize must be an integer from 1 to ${CHAT_THREADS_MAX_PAGE_SIZE}, got ${String(pageSize)}.`);
+        this.name = "ChatThreadListConfigError";
+    }
+}
+function resolvePageSize(pageSize) {
+    if (pageSize === undefined)
+        return DEFAULT_PAGE_SIZE;
+    if (!Number.isInteger(pageSize) ||
+        pageSize < 1 ||
+        pageSize > CHAT_THREADS_MAX_PAGE_SIZE) {
+        throw new ChatThreadListConfigError(pageSize);
+    }
+    return pageSize;
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function createListState(identity, enabled) {
+    return {
+        identity,
+        session: {
+            active: false,
+            requestId: 0,
+            inFlight: null,
+            // Deduped rows can be fewer than the server rows consumed.
+            nextOffset: 0,
+            hasMore: false,
+        },
+        threads: [],
+        loading: enabled,
+        loadingMore: false,
+        error: null,
+        hasMore: false,
+    };
+}
+/**
+ * One paginated chat history list (`mine`, `shared`, or `all`). Each list pages
+ * independently, so a long Shared list never waits on My chats. It refetches
+ * by default when a thread mutation in this tab calls `notifyChatThreadsUpdated`,
+ * keeping every row already loaded, however many server pages that spans,
+ * rather than collapsing to the first page.
+ */
+export function useChatThreadList(options) {
+    const { ownership, includeExternal = false, enabled = true, refreshOnThreadUpdates = true, } = options;
+    const apiUrl = options.apiUrl ?? agentNativePath("/_agent-native/agent-chat");
+    const pageSize = resolvePageSize(options.pageSize);
+    const query = options.query?.trim() ?? "";
+    const scopeType = options.scope?.type ?? null;
+    const scopeId = options.scope?.id ?? null;
+    const identity = JSON.stringify([
+        apiUrl,
+        ownership,
+        query,
+        scopeType,
+        scopeId,
+        pageSize,
+        includeExternal,
+        enabled,
+    ]);
+    const [stored, setState] = useState(() => createListState(identity, enabled));
+    // Reset during render: consumers must never observe the preceding list,
+    // including during their layout effects before passive cleanup runs.
+    const state = stored.identity === identity ? stored : createListState(identity, enabled);
+    if (state !== stored)
+        setState(state);
+    const { session } = state;
+    const update = useCallback((patch) => {
+        setState((previous) => previous.session === session ? { ...previous, ...patch } : previous);
+    }, [session]);
+    useLayoutEffect(() => {
+        session.active = true;
+        return () => {
+            session.active = false;
+            session.requestId += 1;
+            session.inFlight = null;
+        };
+    }, [session]);
+    const request = useCallback((page) => fetchChatThreadListPage({
+        apiUrl,
+        offset: page.offset,
+        limit: page.limit,
+        query,
+        ownership,
+        includeExternal,
+        scope: scopeType && scopeId ? { type: scopeType, id: scopeId } : null,
+    }).then((result) => {
+        if (result.hasMore === undefined) {
+            throw new ChatThreadListError("Chat history response did not say whether more threads exist.");
+        }
+        // A page that claims more rows exist but returned none would be
+        // requested again from the same offset forever.
+        if (result.hasMore && result.threads.length === 0) {
+            throw new ChatThreadListError("Chat history response reported more threads but returned none.");
+        }
+        return { threads: result.threads, hasMore: result.hasMore };
+    }), [apiUrl, includeExternal, ownership, query, scopeId, scopeType]);
+    // Reload the first `window` server rows, one capped page at a time, and swap
+    // them in only once every page has arrived. A failure part-way leaves the
+    // rows and offset already on screen untouched.
+    const replace = useCallback(async (window) => {
+        if (!session.active)
+            return;
+        const requestId = ++session.requestId;
+        const isCurrent = () => session.active && requestId === session.requestId;
+        session.inFlight = "replace";
+        update({ loadingMore: false });
+        try {
+            const rows = new Map();
+            let consumed = 0;
+            let more = true;
+            while (more && consumed < window) {
+                const page = await request({
+                    offset: consumed,
+                    limit: Math.min(CHAT_THREADS_MAX_PAGE_SIZE, window - consumed),
+                });
+                if (!isCurrent())
+                    return;
+                for (const thread of page.threads) {
+                    if (!rows.has(thread.id))
+                        rows.set(thread.id, thread);
+                }
+                consumed += page.threads.length;
+                more = page.hasMore;
+            }
+            session.nextOffset = consumed;
+            session.hasMore = more;
+            update({ threads: [...rows.values()], hasMore: more, error: null });
+        }
+        catch (failure) {
+            if (!isCurrent())
+                return;
+            update({ error: asError(failure) });
+        }
+        finally {
+            if (isCurrent()) {
+                session.inFlight = null;
+                update({ loading: false });
+            }
+        }
+    }, [request, session, update]);
+    const refresh = useCallback(async () => {
+        if (!enabled)
+            return;
+        // Reload every row already on screen so a mutation does not collapse a
+        // list the person has paged through.
+        await replace(Math.max(pageSize, session.nextOffset));
+    }, [enabled, pageSize, replace, session]);
+    const loadMore = useCallback(async () => {
+        if (!session.active || session.inFlight || !session.hasMore)
+            return;
+        const requestId = session.requestId;
+        const isCurrent = () => session.active && requestId === session.requestId;
+        session.inFlight = "append";
+        update({ loadingMore: true });
+        try {
+            const page = await request({
+                offset: session.nextOffset,
+                limit: pageSize,
+            });
+            if (!isCurrent())
+                return;
+            session.nextOffset += page.threads.length;
+            session.hasMore = page.hasMore;
+            setState((previous) => {
+                if (previous.session !== session)
+                    return previous;
+                const known = new Set(previous.threads.map((thread) => thread.id));
+                return {
+                    ...previous,
+                    threads: [
+                        ...previous.threads,
+                        ...page.threads.filter((thread) => !known.has(thread.id)),
+                    ],
+                    hasMore: page.hasMore,
+                    error: null,
+                };
+            });
+        }
+        catch (failure) {
+            if (!isCurrent())
+                return;
+            update({ error: asError(failure) });
+        }
+        finally {
+            if (isCurrent()) {
+                session.inFlight = null;
+                update({ loadingMore: false });
+            }
+        }
+    }, [pageSize, request, session, update]);
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+    useEffect(() => {
+        if (!enabled || !refreshOnThreadUpdates || typeof window === "undefined")
+            return;
+        const onUpdated = () => void refresh();
+        window.addEventListener(CHAT_THREADS_UPDATED_EVENT, onUpdated);
+        return () => window.removeEventListener(CHAT_THREADS_UPDATED_EVENT, onUpdated);
+    }, [enabled, refresh, refreshOnThreadUpdates]);
+    const { threads, loading, loadingMore, error, hasMore } = state;
+    return { threads, loading, loadingMore, error, hasMore, loadMore, refresh };
+}

package/dist/client/use-chat-threads.d.ts

@@ -6,6 +6,14 @@ export interface ChatThreadScope {
     context?: string;
     contextVersion?: string;
 }
+/** Which of the caller's lists a thread belongs to; `mine` is ownership alone. */
+export type ChatThreadOwnership = "all" | "mine" | "shared";
+/**
+ * Why the caller can see a thread. A direct per-user grant outranks
+ * organization access when both apply.
+ */
+export type ChatThreadAccessBasis = "owner" | "direct" | "organization";
+export type ChatThreadVisibility = "private" | "org" | "public";
 export interface ChatThreadSummary {
     id: string;
     title: string;
@@ -17,6 +25,14 @@ export interface ChatThreadSummary {
     source?: ChatThreadSource | null;
     pinnedAt?: number | null;
     archivedAt?: number | null;
+    /**
+     * Server-supplied on listed threads. Absent on optimistic local drafts,
+     * which the caller owns by definition.
+     */
+    ownerEmail?: string;
+    accessBasis?: ChatThreadAccessBasis;
+    visibility?: ChatThreadVisibility;
+    orgId?: string | null;
 }
 export interface ChatThreadSource {
     platform?: string;
@@ -61,8 +77,59 @@ export interface UseChatThreadsOptions {
     routeThreadId?: string | null;
     includeExternal?: boolean;
     isolateHistoryByScope?: boolean;
+    /** Narrows the history list and search. Defaults to `all`. */
+    ownership?: ChatThreadOwnership;
 }
+export declare const CHAT_THREADS_UPDATED_EVENT = "agent-chat:threads-updated";
+/** The server caps one page here; larger requests are silently shortened. */
+export declare const CHAT_THREADS_MAX_PAGE_SIZE = 200;
+/** The thread list endpoint answered with a failure status or a malformed body. */
+export declare class ChatThreadListError extends Error {
+    readonly status: number | null;
+    constructor(message: string, status?: number | null);
+}
+export interface ChatThreadListPageRequest {
+    apiUrl?: string;
+    /** Non-negative safe integer. Undefined uses the server default. */
+    offset?: number;
+    /** Positive safe integer. Undefined uses the server default. The server caps pages at 200 rows. */
+    limit?: number;
+    /** Switches the endpoint to search; ownership still narrows before paging. */
+    query?: string;
+    ownership?: ChatThreadOwnership;
+    includeExternal?: boolean;
+    scope?: ChatThreadScope | null;
+}
+/** A listed thread as the server returns it: ownership metadata always present. */
+export type ChatThreadListRow = ChatThreadSummary & {
+    ownerEmail: string;
+    accessBasis: ChatThreadAccessBasis;
+    visibility: ChatThreadVisibility;
+};
+export interface ChatThreadListPage {
+    threads: ChatThreadListRow[];
+    /** `undefined` when the server did not report it. */
+    hasMore: boolean | undefined;
+}
+/**
+ * One page of the thread list or search, for the ownership-aware lists. Throws
+ * `ChatThreadListError` for a non-2xx response, a body that is not a thread
+ * list, or a row missing `ownerEmail` / `accessBasis` / `visibility` or sitting
+ * on the wrong side of `ownership`, so callers cannot mistake a failed page
+ * for an empty one. Invalid explicit pagination arguments reject with
+ * `TypeError` before a request is sent.
+ *
+ * The server caps each page at 200 rows. Advance offsets by the actual number
+ * of returned rows and use `hasMore`, rather than the requested limit.
+ */
+export declare function fetchChatThreadListPage(request?: ChatThreadListPageRequest): Promise<ChatThreadListPage>;
 export declare function appendChatThreadScopeParams(params: URLSearchParams, scope?: ChatThreadScope | null): void;
+/**
+ * Tell every mounted chat history list the thread set or its sharing changed,
+ * so they refetch. Anything that mutates a thread outside `useChatThreads`
+ * (a share grant, a visibility change) must call this.
+ */
+export declare function notifyChatThreadsUpdated(): void;
 export declare function useChatThreads(apiUrl?: string, storageKey?: string, scope?: ChatThreadScope | null, options?: UseChatThreadsOptions): {
     threads: ChatThreadSummary[];
     activeThreadId: string | null;