@lotics/app-sdk 0.100.1 → 0.101.1

package/dist/src/hooks.js

@@ -1,860 +0,0 @@
-/**
- * Typed React hooks for Lotics app data access.
- *
- * Reads come in three shapes — `useQuery` (single fetch), `useInfiniteQuery`
- * (append / load-more), and `usePaginatedQuery` (numbered pages + total) — and
- * every mutation is a `useWorkflow`; `useFileUpload` attaches files. App code
- * never writes records directly — all writes flow through declared workflows,
- * which gives the app owner a typed, audited chokepoint and means a
- * publicly-shared app exposes no anonymous direct-write path. An uploaded file
- * is inert until a workflow attaches it, so file upload keeps that same property.
- *
- * Every hook is a thin wrapper over the postMessage RPC bridge — the parent
- * does the actual API calls, results stream back through `rpc()`. The read
- * hooks cache through SWR keyed by (alias, params, …): reads dedupe and the
- * cache survives unmount/remount. Mutation / member hooks keep their own local
- * `useState` — they have nothing to share.
- */
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { DEFAULT_IMAGE_FIDELITY } from "./upload/optimize.js";
-import { useAttachmentQueue } from "./attachments.js";
-import useSWR from "swr";
-import useSWRInfinite from "swr/infinite";
-import { rpc, rpcAgentRun, rpcAgentRunContinue, postHostNotification, subscribeQueriesChanged, registerQueryAlias, notifyLocalWrite, } from "./rpc.js";
-import { initialAgentRunState, reduceAgentChunk, parseSseChunks, adoptSettledRun, pendingInteractiveCall, buildChoiceOutput, applyInteractiveAnswer, landingOf, proseOf, ABORTED, } from "./agent_stream.js";
-import { getMockRows, getMockWorkflow, hasMockFlag } from "./mock.js";
-export { buildChoiceOutput } from "./agent_stream.js";
-export function useWorkflow(alias) {
-    return useCallback(async (inputs) => {
-        // Checked per CALL, not per render: a fixture registered after mount or
-        // swapped by HMR is picked up, and an app that never runs this workflow
-        // does no work here. Mock mode needs BOTH the `?__mock=1` flag and a
-        // registered fixture, so a bundle carrying demo data cannot answer real
-        // traffic with it.
-        const mock = getMockWorkflow(alias);
-        if (mock) {
-            return typeof mock === "function" ? await mock(inputs ?? {}) : mock;
-        }
-        const result = await rpc("workflow", { alias, inputs: inputs ?? {} });
-        // A workflow is the app's only write path, so a successful one means the
-        // rows on screen are stale. Re-read now rather than waiting for the host's
-        // realtime push to say what the caller already knows — that wait is what
-        // makes a screen feel like it lagged its own button.
-        //
-        // Only on success: a refused write changed nothing, and refetching after
-        // one would replace the values the user is still looking at (and about to
-        // correct) with an identical set, for a round trip nobody asked for.
-        if (result.status !== "error")
-            notifyLocalWrite();
-        return result;
-    }, [alias]);
-}
-// Shared SWR config: surface a failed query immediately, keep the last good
-// rows (no retry loop that masks the error), and honor the focus/reconnect
-// opt-out.
-//
-// `revalidateIfStale` is LEFT AT SWR's DEFAULT (`true`): re-mounting a screen
-// renders its cached rows AND re-reads them. Pinning it `false` saved a re-query
-// per navigation and cost every screen a hand-rolled arrival refetch — where
-// forgetting is SILENT (no error, no empty state, just last visit's data until a
-// hard reload), which is not a mistake an author gets told about once and learns.
-//
-// The default costs one BACKGROUND request per re-mount of a warm key and
-// nothing visible: SWR's `isLoading` is true only on an initial load with no
-// cached data, so nothing blanks to a skeleton, and `dedupingInterval` collapses
-// a burst of navigation into one fetch.
-//
-// `useAppContext` (viewer.ts) still pins it off — the app's identity is read
-// once at boot and cannot change under the reader. `useInfiniteQuery` is the
-// one hook this does not reach; see its own note.
-function swrConfig(revalidateOnFocus) {
-    return {
-        revalidateOnFocus,
-        revalidateOnReconnect: revalidateOnFocus,
-        shouldRetryOnError: false,
-        // A query's KEY carries its params, filter and sort, so anything derived
-        // from the rows on screen re-keys the moment they change. Without this SWR
-        // answers a new key with `undefined`, `rows` falls to `[]`, and every list
-        // renders empty for a frame — unmounting each row's images, which remount
-        // blank. That is the behaviour the `loading` contract above already
-        // promises against, and what the product app sets globally for the same
-        // reason.
-        keepPreviousData: true,
-    };
-}
-/**
- * The fixture rows for this alias and this call, held STABLE across renders.
- *
- * A function fixture returns a fresh array each time it is called, and `rows` is
- * handed straight to consumers — so without memoizing, a screen that derives
- * anything from `rows` (a `useMemo`, an effect) re-runs on every render, and one
- * that sets state from them never settles. Keyed exactly the way the real read
- * is keyed, so a changed param/filter/sort re-asks the fixture and nothing else
- * does.
- */
-function useMockRows(alias, call) {
-    const key = JSON.stringify([call.params, call.filter ?? null, call.sort ?? null, call.limit ?? null]);
-    const { params, filter, sort, limit } = call;
-    return useMemo(() => getMockRows(alias, { params, filter, sort, limit }), 
-    // The KEY, not the object literal the caller rebuilt this render — a memo on
-    // the literal would be no memo at all.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [alias, key]);
-}
-/**
- * Refetch this query when the host reports that ITS tables changed — whoever
- * wrote them: another member, a workflow, the chat agent, or an external agent
- * over the CLI or MCP.
- *
- * The host names the affected aliases rather than telling every hook to
- * re-read: an app's queries usually span several tables, and a blanket refetch
- * would re-run expensive aggregates on a change to a table they never touch.
- *
- * Inert in mock mode (no host, no listener), for a mocked alias (its rows come
- * from the fixture), and for a standalone/public app (no host to push).
- * Shared by all three query hooks.
- */
-function useHostRefetch(alias, refetch, mockRows) {
-    useEffect(() => {
-        if (hasMockFlag() || mockRows)
-            return;
-        // Registered separately from the subscription because the two answer
-        // different questions: the subscription is "tell me when MY alias moved",
-        // the registration is "I am on screen, so a local write should re-read me".
-        const unregister = registerQueryAlias(alias);
-        const unsubscribe = subscribeQueriesChanged((aliases) => {
-            if (aliases.includes(alias))
-                refetch();
-        });
-        return () => {
-            unregister();
-            unsubscribe();
-        };
-    }, [alias, refetch, mockRows]);
-}
-/**
- * THE COUNT READ, defined once — used by `usePaginatedQuery` for its page total
- * and by `useCount` for a bare number.
- *
- * Both must agree on the SWR key and on the request body, byte for byte: that
- * identity is what makes a table and a badge over the same set buy ONE count
- * between them. Two hand-copied literals would hold today and diverge the first
- * time one is edited, and the failure is silent — nothing breaks, the screen
- * just quietly issues two full scans where it used to issue one. So there is one
- * definition and no opportunity to disagree.
- *
- * The key omits PAGE and SORT deliberately: a count is independent of both, so
- * page clicks and re-sorts reuse it. `active: false` yields a null key, and SWR
- * issues nothing for a null key — which is how a caller-supplied total, a
- * disabled hook and a fixture all suppress the request.
- */
-function useCountRead(alias, params, filter, active, revalidateOnFocus) {
-    const key = active
-        ? ["app-query-count", alias, params ?? {}, filter ?? null]
-        : null;
-    return useSWR(key, () => rpc("query", { alias, params: params ?? {}, filter, count: true }), swrConfig(revalidateOnFocus));
-}
-export function useQuery(alias, params, opts) {
-    const pageSize = opts?.pageSize;
-    const enabled = opts?.enabled ?? true;
-    const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
-    const sort = opts?.sort && opts.sort.length > 0 ? opts.sort : undefined;
-    const filter = opts?.filter;
-    const mockRows = useMockRows(alias, { params: params ?? {}, filter, sort, limit: pageSize });
-    // A `null` key disables the fetch (mock / disabled). SWR canonicalizes the
-    // params/sort/filter objects via its stable hash, so identical reads dedupe to
-    // one request + one cache entry that survives unmount/remount.
-    const key = mockRows || !enabled
-        ? null
-        : ["app-query", alias, params ?? {}, pageSize ?? null, sort ?? null, filter ?? null];
-    const swr = useSWR(key, () => rpc("query", {
-        alias,
-        params: params ?? {},
-        limit: pageSize,
-        offset: 0,
-        sort,
-        filter,
-    }), swrConfig(revalidateOnFocus));
-    const refetch = useCallback(() => {
-        void swr.mutate();
-    }, [swr]);
-    useHostRefetch(alias, refetch, mockRows);
-    return {
-        rows: mockRows ?? swr.data?.rows ?? [],
-        // A fixture IS the whole set, so it is never short; before the first
-        // response there is nothing to be short of.
-        truncated: mockRows || !swr.data ? false : swr.data.truncated,
-        loading: mockRows ? false : swr.isLoading,
-        isValidating: mockRows ? false : swr.isValidating,
-        error: swr.error ? swr.error.message : null,
-        refetch,
-    };
-}
-export function useFieldOptions(alias, opts) {
-    const enabled = opts?.enabled ?? true;
-    // Field config is slow-changing, so no focus/reconnect revalidation — the app
-    // calls `refetch()` after a known change. A null key defers the fetch.
-    const key = enabled ? ["app-field-options", alias] : null;
-    const swr = useSWR(key, () => rpc("field_options", { alias }), swrConfig(false));
-    const fields = useMemo(() => {
-        const raw = swr.data?.fields ?? {};
-        const out = {};
-        for (const [col, def] of Object.entries(raw)) {
-            const options = def.options ?? [];
-            const index = new Map(options.map((o) => [o.key, o]));
-            out[col] = { label: def.label, options, byKey: (k) => index.get(k) };
-        }
-        return out;
-    }, [swr.data]);
-    const refetch = useCallback(() => {
-        void swr.mutate();
-    }, [swr]);
-    return {
-        fields,
-        loading: swr.isLoading,
-        isValidating: swr.isValidating,
-        error: swr.error ? swr.error.message : null,
-        refetch,
-    };
-}
-export function useInfiniteQuery(alias, params, opts) {
-    const pageSize = opts?.pageSize ?? 30;
-    const enabled = opts?.enabled ?? true;
-    const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
-    const sort = opts?.sort && opts.sort.length > 0 ? opts.sort : undefined;
-    const filter = opts?.filter;
-    const mockRows = useMockRows(alias, { params: params ?? {}, filter, sort, limit: pageSize });
-    // Keyset (seek) pagination: each page seeks past the previous page's
-    // `next_cursor` instead of an increasing OFFSET, so deep scrolls stay O(page)
-    // and never skip/duplicate a row as the set shifts. The cursor is opaque; the
-    // server keysets a sortable key (the query's own order when `sort` is unset,
-    // else the id) and falls back to offset transparently. `loadMore`/`rows` are
-    // unchanged — the cursor is internal.
-    const getKey = (index, prev) => {
-        if (mockRows || !enabled)
-            return null;
-        // Stop once a page reports no next cursor (the end).
-        if (index > 0 && (prev == null || prev.next_cursor == null))
-            return null;
-        const cursor = index === 0 ? null : (prev?.next_cursor ?? null);
-        return ["app-query-infinite", alias, params ?? {}, pageSize, sort ?? null, filter ?? null, cursor];
-    };
-    const swr = useSWRInfinite(getKey, (key) => {
-        const cursor = key[6];
-        return rpc("query", {
-            alias,
-            params: params ?? {},
-            limit: pageSize,
-            keyset: true,
-            cursor: cursor ?? undefined,
-            sort,
-            filter,
-        });
-    }, 
-    // `revalidateFirstPage: false` — `loadMore()` fetches the next page and only
-    // that page. SWR's default re-fetches page 1 on every load-more, costing a
-    // request per scroll and reshuffling the top of the feed under a reader
-    // looking further down it (pinned by the keyset test).
-    //
-    // THE COST, stated because it is otherwise invisible: this hook does not
-    // arrival-revalidate the way the other two do. SWRInfinite decides per page
-    // and never consults `revalidateIfStale`, and neither lever that would change
-    // that is cheap — `revalidateFirstPage` pays per load-more, `revalidateOnMount`
-    // refetches EVERY loaded page. A cold key still fetches, focus/reconnect and
-    // `refetch()` still refresh; a feed that must be fresh on arrival calls
-    // `refetch()`.
-    { revalidateFirstPage: false, ...swrConfig(revalidateOnFocus) });
-    // SWRInfinite leaves an in-flight page slot `undefined` until it resolves —
-    // operate on resolved pages only so a page being appended never crashes the
-    // flatten or skews the counts.
-    const pages = (swr.data ?? []).filter((p) => p != null);
-    const rows = mockRows ?? pages.flatMap((p) => p.rows);
-    const lastPage = pages.length > 0 ? pages[pages.length - 1] : undefined;
-    // A non-null next_cursor means another page exists; null/absent = the end.
-    const hasMore = lastPage != null && lastPage.next_cursor != null;
-    const loadingMore = swr.isValidating && swr.size > pages.length;
-    const refetch = useCallback(() => {
-        void swr.mutate();
-    }, [swr]);
-    useHostRefetch(alias, refetch, mockRows);
-    const loadMore = useCallback(() => {
-        if (!hasMore || loadingMore)
-            return;
-        void swr.setSize((n) => n + 1);
-    }, [hasMore, loadingMore, swr]);
-    return {
-        rows,
-        loading: mockRows ? false : swr.isLoading,
-        isValidating: mockRows ? false : swr.isValidating,
-        error: swr.error ? swr.error.message : null,
-        refetch,
-        loadMore,
-        hasMore,
-        loadingMore,
-    };
-}
-export function usePaginatedQuery(alias, params, opts) {
-    const pageSize = opts?.pageSize ?? 25;
-    const enabled = opts?.enabled ?? true;
-    const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
-    const sort = opts?.sort && opts.sort.length > 0 ? opts.sort : undefined;
-    const filter = opts?.filter;
-    const mockRows = useMockRows(alias, { params: params ?? {}, filter, sort, limit: pageSize });
-    // `null` = the caller owns the total and it hasn't resolved; `undefined`
-    // (or omitted) = the hook counts. See `PaginatedQueryOptions.total`.
-    const suppliedTotal = opts?.total;
-    const callerOwnsTotal = suppliedTotal !== undefined;
-    // The result-set identity. When it changes, `page` derives back to 0 (not via
-    // an effect, so the stale page never fires a wasted fetch) and the count key
-    // changes (recount). `setPage` re-stamps the current identity.
-    const resetKey = JSON.stringify([params ?? {}, filter ?? null]);
-    const [pageState, setPageState] = useState({ key: resetKey, page: 0 });
-    const page = pageState.key === resetKey ? pageState.page : 0;
-    const setPage = useCallback((p) => setPageState({ key: resetKey, page: Math.max(0, p) }), [resetKey]);
-    const rowsKey = mockRows || !enabled
-        ? null
-        : ["app-query-page", alias, params ?? {}, pageSize, sort ?? null, filter ?? null, page];
-    const rowsSwr = useSWR(rowsKey, () => rpc("query", {
-        alias,
-        params: params ?? {},
-        limit: pageSize,
-        offset: page * pageSize,
-        sort,
-        filter,
-    }), swrConfig(revalidateOnFocus));
-    // Not counted when the caller supplies the total, when the hook is disabled,
-    // or under a fixture — see `useCountRead` for why the key drops page and sort.
-    const countSwr = useCountRead(alias, params, filter, !mockRows && enabled && !callerOwnsTotal, revalidateOnFocus);
-    const rows = mockRows ?? rowsSwr.data?.rows ?? [];
-    // A supplied `null` reads out as `undefined` — "not known yet" is one state
-    // to the consumer whether the hook is counting or the caller is.
-    const total = mockRows
-        ? mockRows.length
-        : callerOwnsTotal
-            ? (suppliedTotal ?? undefined)
-            : countSwr.data?.total;
-    const totalPages = total != null ? Math.max(1, Math.ceil(total / pageSize)) : undefined;
-    const hasMore = total != null ? (page + 1) * pageSize < total : rows.length === pageSize;
-    const refetch = useCallback(() => {
-        void rowsSwr.mutate();
-        void countSwr.mutate();
-    }, [rowsSwr, countSwr]);
-    useHostRefetch(alias, refetch, mockRows);
-    return {
-        rows,
-        total,
-        totalPages,
-        page,
-        pageSize,
-        hasMore,
-        setPage,
-        loading: mockRows ? false : rowsSwr.isLoading,
-        isValidating: mockRows ? false : rowsSwr.isValidating || countSwr.isValidating,
-        error: rowsSwr.error?.message ?? countSwr.error?.message ?? null,
-        refetch,
-    };
-}
-export function useCount(alias, params, opts) {
-    const enabled = opts?.enabled ?? true;
-    const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
-    const filter = opts?.filter;
-    const mockRows = useMockRows(alias, { params: params ?? {}, filter });
-    // The SAME read `usePaginatedQuery` uses for its total — one definition, so a
-    // list and a badge over one set can never drift into two scans.
-    const countSwr = useCountRead(alias, params, filter, !mockRows && enabled, revalidateOnFocus);
-    const refetch = useCallback(() => {
-        void countSwr.mutate();
-    }, [countSwr]);
-    useHostRefetch(alias, refetch, mockRows);
-    return {
-        // Under a fixture the whole set is the fixture, so its length IS the count —
-        // the same substitution every other hook makes for `rows`.
-        total: mockRows ? mockRows.length : countSwr.data?.total,
-        loading: mockRows ? false : countSwr.isLoading,
-        isValidating: mockRows ? false : countSwr.isValidating,
-        error: countSwr.error?.message ?? null,
-        refetch,
-    };
-}
-/**
- * Upload files from an app. The bytes are stored via a presigned
- * direct-to-storage upload the host mediates; the API server never proxies
- * them. Works the same in a public (anonymous) app and a member-facing one.
- *
- * ```tsx
- * const { upload, uploading } = useFileUpload();
- * const submit = useWorkflow("submitApplication");
- * const cccd = await upload(file);
- * await submit({ ...fields, cccd_file_id: cccd.id });
- * ```
- */
-export function useFileUpload() {
-    const [inFlight, setInFlight] = useState(0);
-    const [error, setError] = useState(null);
-    const upload = useCallback(async (file, options) => {
-        const fidelity = options?.fidelity ?? DEFAULT_IMAGE_FIDELITY;
-        setInFlight((n) => n + 1);
-        setError(null);
-        try {
-            const uploaded = await rpc("upload", { file, fidelity });
-            return uploaded;
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : "Upload failed";
-            setError(message);
-            throw err;
-        }
-        finally {
-            setInFlight((n) => n - 1);
-        }
-    }, []);
-    return { upload, uploading: inFlight > 0, error };
-}
-/**
- * Attachments with the optimistic-preview UX: a local object-URL preview shows
- * the INSTANT a file is added, the upload runs in the background, and the
- * stored `file_id` lands in `files` when it completes. Picking is the app's
- * (button / paste / drop) — pass the resulting `File[]` to `add`, or to
- * `attach` where a write has to wait for the ids.
- *
- * WHICH LIFECYCLE is the caller's one decision. A composer accumulates and
- * clears when it sends; a record's section passes what its row now holds as
- * `landed`, and each entry leaves the queue as the pile takes it over.
- *
- * ```tsx
- * const { files, add, remove, clear, uploading, fileIds } = useAttachments();
- * const design = useWorkflow("design");
- * // attach:  <Button icon="paperclip" onPress={() => pickFiles({ accept: "image/*" }).then(add)} />
- * // preview: map each AttachedFile to a @lotics/ui DisplayFile (snake_case → camelCase) — the
- * //          app owns this data→UI adapter; the SDK never imports @lotics/ui:
- * //   files.map((f) => (
- * //     <FileThumbnail
- * //       file={{ id: f.id, filename: f.filename, mimeType: f.mime_type, url: f.preview_url }}
- * //       uploading={f.status === "uploading"} onRemove={() => remove(f.id)} />
- * //   ))
- * // send:    design({ photo: fileIds[0] }); clear();
- * ```
- *
- * The queue is `useAttachmentQueue`, bound here to the app's own upload.
- */
-export function useAttachments(options) {
-    const { upload } = useFileUpload();
-    return useAttachmentQueue(upload, options);
-}
-/**
- * JSON-serialize the view-state snapshot — used for BOTH change-detection (a
- * fresh inline object each render must NOT re-post) and the wire payload. The
- * `data` field is app-supplied `unknown`; if it can't be JSON-serialized we drop
- * it and keep description + records, mirroring the host's own `data` cap (which
- * JSON-encodes `data` and drops it past the size limit) — a non-serializable
- * value must never crash the app's render.
- */
-function serializeAiContext(context) {
-    try {
-        return JSON.stringify(context);
-    }
-    catch {
-        return JSON.stringify({ description: context.description, records: context.records });
-    }
-}
-/**
- * Publish a slice of the CURRENT SCREEN's view state to the app's ambient chat
- * agent, so a member chatting alongside the app gets an agent that knows what
- * they are looking at — which list is filtered to what, which record is open,
- * what is typed into a form. Declarative and lifecycle-bound: mounting or
- * changing `context` pushes it to the host; unmounting, renaming the `slot`, or
- * passing `null` clears it. Independent components may publish different `slot`s
- * concurrently (a list screen + an open detail drawer); the newest value per
- * slot wins.
- *
- * **Push-only, and a SNAPSHOT of what the app already RENDERED to this member** —
- * never a channel for chat to pull app-authority data. `records` are passed as
- * raw `{ table_id, record_id }` refs (unresolved); the member's own chat agent
- * acts on them only where that member's IAM already allows. The host feeds
- * `description`/`data` into the agent's prompt as clearly-labeled DATA, never as
- * instructions.
- *
- * Host-enforced caps (exceeding them truncates/drops — never an error): `slot`
- * ≤ 50 chars; `description` ≤ 1000 chars (truncated with "…"); `records` ≤ 20;
- * `data` must JSON-serialize to ≤ 2000 chars or the `data` field is dropped (the
- * description is kept); ≤ 8 slots per app (a 9th evicts the least-recently
- * updated).
- *
- * ```tsx
- * useAiContext("orders_list", {
- *   description: `Viewing ${rows.length} orders filtered to status=open, sorted by due date.`,
- *   // `flatMap` + the guard, not `map`: the addressing columns are absent on a
- *   // GROUPED query's rows, so a ref built without checking carries `undefined`
- *   // and points the agent at nothing.
- *   records: rows.flatMap((r) =>
- *     r.__source_table_id && r.__source_record_id
- *       ? [{ table_id: r.__source_table_id, record_id: r.__source_record_id }]
- *       : [],
- *   ),
- *   data: { filter: "status=open", sort: "due_date desc" },
- * });
- * ```
- *
- * No-ops with no embedding host (standalone on the app's own origin — there is no
- * chat surface to inform) and in mock mode. Since 0.52.
- */
-export function useAiContext(slot, context) {
-    // Serialize once for both the change key and the payload. The effect re-posts
-    // only when the serialized value (or slot) actually changes, so a fresh inline
-    // object each render never spams the host. Payloads are small (host-capped),
-    // so the JSON round-trip is cheap.
-    const serialized = context === null ? null : serializeAiContext(context);
-    // Post the current value on mount and whenever it changes.
-    useEffect(() => {
-        if (hasMockFlag())
-            return;
-        const payload = serialized === null ? null : JSON.parse(serialized);
-        postHostNotification({ type: "aiContext", slot, context: payload });
-    }, [slot, serialized]);
-    // Clear the slot on unmount or slot rename ONLY — a value-only change is
-    // overwritten by the post above, with no intermediate clear.
-    useEffect(() => {
-        if (hasMockFlag())
-            return;
-        return () => postHostNotification({ type: "aiContext", slot, context: null });
-    }, [slot]);
-}
-/**
- * List the members of the app's organization — the candidate set for an
- * "assign to a member" picker. Each member is `{ id, name, email, image }`
- * (`image` = avatar URL, may be null). Resolves through the host (member-only;
- * an anonymous public visitor gets an error). Names may be empty for members
- * without a display name set — fall back to `email`.
- *
- * Gated: the app must DECLARE that it works with members — it needs a workflow
- * whose manifest declares a `member`-typed input. Passing `{ group }` restricts
- * to that group, and is only honored if some member input declares that
- * `group` — so an app can only list (and assign into) groups it declares.
- *
- * ```tsx
- * const { members } = useMembers({ group: GRP.sale });
- * // <Select variant="native" options={members.map((m) => ({
- * //   value: m.id, label: m.name || m.email || m.id, image: m.image,
- * // }))} />
- * ```
- */
-export function useMembers(opts) {
-    const group = opts?.group;
-    const [state, setState] = useState({
-        members: [],
-        loading: true,
-        error: null,
-    });
-    useEffect(() => {
-        let cancelled = false;
-        setState((s) => ({ ...s, loading: true, error: null }));
-        rpc("members", { group })
-            .then((r) => {
-            if (!cancelled)
-                setState({ members: r.members ?? [], loading: false, error: null });
-        })
-            .catch((err) => {
-            if (!cancelled)
-                setState({ members: [], loading: false, error: err.message });
-        });
-        return () => {
-            cancelled = true;
-        };
-    }, [group]);
-    return state;
-}
-export function useAgentRun(alias) {
-    const [state, setState] = useState(null);
-    const handleRef = useRef(null);
-    // The run id of the in-flight run (reported by the transport off the response
-    // header). Lets the hook poll the run to completion if the stream connection
-    // drops, and cancel it server-side on an explicit stop.
-    const runIdRef = useRef(null);
-    const inflightRef = useRef(null);
-    // Guards setState after unmount and aborts any in-flight run on unmount, so a
-    // stream never keeps writing to a dead component (or leaks the transport).
-    const mountedRef = useRef(true);
-    useEffect(() => {
-        mountedRef.current = true;
-        return () => {
-            mountedRef.current = false;
-            handleRef.current?.abort();
-        };
-    }, []);
-    // The latest state, readable synchronously (answerChoice needs the pending
-    // call + parts without waiting a render).
-    const stateRef = useRef(null);
-    const safeSetState = useCallback((s) => {
-        stateRef.current = s;
-        if (mountedRef.current)
-            setState(s);
-    }, []);
-    /**
-     * Drive ONE streaming leg (the initial run, or a continuation after an
-     * answered ask) into shared state: fold SSE chunks from `initial`, and on a
-     * cut stream fall back to the persisted row — the run is decoupled from the
-     * connection, so a truncation polls the row instead of surfacing a network
-     * error. A leg that ends `awaiting_input` resolves with `undefined`; the
-     * final leg resolves with the structured output.
-     *
-     * `revertTo` (the continuation leg): the leg's initial state is an OPTIMISTIC
-     * commit (the ask settled locally before the server accepted the answer). A
-     * request that fails before ANY chunk arrives means the server rejected it and
-     * the row never left `awaiting_input` — restore the pre-answer state so the
-     * question is answerable again, and REJECT so the app surfaces the error.
-     * Without this, a 400/409 would be misread as a mid-run connection drop,
-     * poll-adopted, and silently swallowed.
-     */
-    const streamLeg = useCallback((start, initial, revertTo) => {
-        let acc = initial;
-        let buffer = "";
-        let aborted = false;
-        let received = false;
-        safeSetState(acc);
-        // Enforce the invariant the wizard relies on: `awaiting_input` always
-        // yields an answerable pendingChoice. A polled parked row whose question
-        // cannot be rebuilt (no part in the stream, none derivable from the row)
-        // must fail loud and retryable, never sit as a silent dead end.
-        const adoptGuarded = (state, settled) => {
-            const adopted = adoptSettledRun(state, settled);
-            if (adopted.status === "awaiting_input" && !pendingInteractiveCall(adopted)) {
-                return {
-                    ...adopted,
-                    status: "error",
-                    error: "The run is waiting for an answer that could not be recovered. Run it again.",
-                };
-            }
-            return adopted;
-        };
-        const handle = start((textChunk) => {
-            if (aborted)
-                return;
-            buffer += textChunk;
-            const { chunks, rest } = parseSseChunks(buffer);
-            buffer = rest;
-            if (chunks.length === 0)
-                return;
-            received = true;
-            for (const c of chunks)
-                acc = reduceAgentChunk(acc, c);
-            safeSetState({ ...acc });
-        });
-        // Wrap abort so a stop (user or unmount) marks the run cancelled and clears
-        // the partial state back to idle — `done` resolves cleanly, never an error.
-        handleRef.current = {
-            abort: () => {
-                if (aborted)
-                    return;
-                aborted = true;
-                handle.abort();
-                safeSetState(null);
-            },
-        };
-        return handle.done
-            .then(async () => {
-            if (aborted)
-                return ABORTED;
-            // A clean stream end WITHOUT a `finish` frame is a truncation, not a
-            // completion — an edge can close a long SSE gracefully mid-run (seen
-            // in production on ~2-minute runs), swallowing the frames that carry
-            // the structured result. The run is decoupled and settles server-side
-            // regardless, so the row is the source of truth: poll it, exactly
-            // like the dropped-with-error path below. (2026-07-18: four NOXH
-            // extractions completed server-side while every client showed
-            // failure through this hole.)
-            if (acc.status === "streaming") {
-                const runId = runIdRef.current;
-                const settled = runId
-                    ? await pollAgentRunToSettle(runId, () => aborted || !mountedRef.current)
-                    : null;
-                if (aborted)
-                    return ABORTED;
-                // No settled row after the full poll window means the run's status
-                // could NOT be confirmed (an orphan the server's reaper hasn't
-                // repaired yet, or no run id ever arrived) — that is an error, never
-                // a fake "completed": a structured consumer reading a completed
-                // state with no output would render success around a missing result.
-                acc = settled
-                    ? adoptGuarded(acc, settled)
-                    : {
-                        ...acc,
-                        status: "error",
-                        error: "The run was interrupted and its result could not be confirmed. Run it again.",
-                    };
-                safeSetState(acc);
-            }
-            return landingOf(acc);
-        })
-            .catch(async (err) => {
-            if (aborted)
-                return ABORTED;
-            // The continue request itself was rejected — the server never resumed
-            // the run (400 invalid answer, 409 raced cancel/expiry, network at
-            // connect). Restore the pre-answer parked state and surface the error;
-            // this is a request failure, not a stream truncation.
-            if (revertTo && !received) {
-                safeSetState(revertTo);
-                throw err;
-            }
-            // The stream connection dropped, but the run is decoupled from it and
-            // keeps executing server-side. Poll the persisted run to completion and
-            // surface its result instead of a network error — work is never lost.
-            const runId = runIdRef.current;
-            if (runId) {
-                const settled = await pollAgentRunToSettle(runId, () => aborted || !mountedRef.current);
-                if (aborted)
-                    return ABORTED;
-                if (settled) {
-                    acc = adoptGuarded(acc, settled);
-                    safeSetState(acc);
-                }
-                if (settled)
-                    return landingOf(acc);
-            }
-            // A run failure is DATA — the landing carries it, so no consumer needs
-            // try/catch to tell "the run died" from "the run parked". Only API
-            // MISUSE still rejects (answering when nothing is pending).
-            acc = { ...acc, status: "error", error: err.message };
-            safeSetState(acc);
-            return landingOf(acc);
-        });
-    }, [safeSetState]);
-    const run = useCallback((input, opts) => {
-        // Single-flight: an extra press must not become a second paid run — the
-        // old abort-and-restart default kept the first run executing (and
-        // billing) server-side while the client went blind to it. Joining the
-        // in-flight promise makes a double-click resolve with the first run's
-        // result; `replace: true` is the explicit opt-in to abort-and-restart.
-        if (inflightRef.current && !opts.replace) {
-            return inflightRef.current;
-        }
-        handleRef.current?.abort();
-        runIdRef.current = null;
-        const inflight = streamLeg((onText) => rpcAgentRun({ alias, session_id: opts.sessionId, input: input ?? {} }, onText, (runId) => {
-            runIdRef.current = runId;
-        }), initialAgentRunState());
-        const tracked = inflight.finally(() => {
-            if (inflightRef.current === tracked)
-                inflightRef.current = null;
-        });
-        inflightRef.current = tracked;
-        return tracked;
-    }, [alias, streamLeg]);
-    // The run's pending ask — non-null exactly while it is parked on a question.
-    const pendingChoice = state ? pendingInteractiveCall(state) : null;
-    const answerChoice = useCallback((answers) => {
-        // Join first: a double-submit (the wizard's button pressed twice) must
-        // land on the in-flight continuation, not reject on the already-settled
-        // pending check below.
-        if (inflightRef.current)
-            return inflightRef.current;
-        const current = stateRef.current;
-        const runId = runIdRef.current;
-        const pending = current ? pendingInteractiveCall(current) : null;
-        if (!current || !runId || !pending) {
-            return Promise.reject(new Error("No pending question to answer."));
-        }
-        const output = buildChoiceOutput(pending.questions, answers);
-        const inflight = streamLeg((onText) => rpcAgentRunContinue({ run_id: runId, tool_call_id: pending.toolCallId, output }, onText), 
-        // The answered part settles locally (its output rides the feed's
-        // on-demand reveal) and the state re-enters streaming for the leg.
-        applyInteractiveAnswer(current, pending.toolCallId, output), 
-        // On a rejected request the leg restores this pre-answer state, so the
-        // wizard reappears and the rejection reaches the app.
-        current);
-        const tracked = inflight.finally(() => {
-            if (inflightRef.current === tracked)
-                inflightRef.current = null;
-        });
-        inflightRef.current = tracked;
-        return tracked;
-    }, [streamLeg]);
-    const abort = useCallback(() => handleRef.current?.abort(), []);
-    const cancel = useCallback(() => {
-        // Stop server-side too (saves tokens on an unwanted run), then locally.
-        // No analytics event here: the cancel RPC stamps `app_agent_runs
-        // .cancel_requested_at`, which is what separates a user's Stop from the
-        // unmount/tab-close that `abort` also serves — a client event would only
-        // duplicate a column, and would go stale the moment an app pins an old SDK.
-        const runId = runIdRef.current;
-        if (runId)
-            void rpc("agentRun.cancel", { run_id: runId }).catch(() => { });
-        handleRef.current?.abort();
-    }, []);
-    // `parts` is the source of truth; `text` (all prose concatenated) is the derived
-    // answer view.
-    const parts = state?.parts ?? EMPTY_PARTS;
-    const text = useMemo(() => proseOf(parts), [parts]);
-    return {
-        run,
-        abort,
-        cancel,
-        status: state?.status ?? "idle",
-        parts,
-        pendingChoice,
-        answerChoice,
-        text,
-        output: state?.output,
-        error: state?.error,
-    };
-}
-/** Stable empty transcript so an idle hook returns a constant `parts` reference
- *  (no new [] each render → dependents don't re-run needlessly). */
-const EMPTY_PARTS = [];
-/**
- * Bounded PAST the server-side max-run cap (20 min) plus settle grace. The
- * server guarantees a LIVE run settles by its own cap timer, so a row still
- * `running` at this deadline is an orphan (its process died mid-run) — the
- * server's reapers repair the row; the client stops polling and surfaces the
- * error. An earlier 11-minute bound gave up BEFORE the cap: a slow run that
- * lost its stream showed failure while the server later completed it — the
- * exact result-loss class this poll exists to prevent.
- */
-const POLL_DEADLINE_MS = 22 * 60_000;
-/**
- * Poll a single run until it leaves `running` — the resume path when a run's
- * stream connection drops mid-flight. Bounded just past the server-side max-run
- * cap so a hung run can never poll forever, and bails the moment the caller
- * aborts or unmounts. Returns the settled run, or null if it never settled.
- */
-async function pollAgentRunToSettle(runId, cancelled) {
-    const deadline = Date.now() + POLL_DEADLINE_MS;
-    while (Date.now() < deadline) {
-        await new Promise((r) => setTimeout(r, 2500));
-        if (cancelled())
-            return null;
-        try {
-            const { run } = await rpc("agentRun.get", { run_id: runId });
-            if (run.status !== "running")
-                return run;
-        }
-        catch {
-            // transient read failure — keep polling until the deadline
-        }
-    }
-    return null;
-}
-/**
- * The run history of a session, oldest-first — the persisted outputs the app
- * renders as a session log (NOT a chat: a flat list of past runs). Refetch
- * after a `run(...)` completes to pull in the new one.
- *
- * ```tsx
- * const { runs } = useAgentRuns(sessionId);
- * ```
- */
-export function useAgentRuns(sessionId, opts) {
-    const enabled = opts?.enabled ?? true;
-    const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
-    const key = enabled && sessionId ? ["app-agent-runs", sessionId] : null;
-    const swr = useSWR(key, () => rpc("agentRuns", { session_id: sessionId }), swrConfig(revalidateOnFocus));
-    const refetch = useCallback(() => {
-        void swr.mutate();
-    }, [swr]);
-    return {
-        runs: swr.data?.runs ?? [],
-        loading: swr.isLoading,
-        error: swr.error?.message ?? null,
-        refetch,
-    };
-}