@adonis-agora/agent 0.61.0 → 0.62.0

package/dist/src/react/core/attachments/use-attachments.js

@@ -0,0 +1,217 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { AgentBackendUnsupportedError } from '../backend.js';
+import { useAgentConfig } from '../config/use-agent-config.js';
+import { useAgentBackend } from '../provider.js';
+import { acceptsFile, dragHasFiles, filesFromClipboard } from './files.js';
+const DEFAULT_REJECTION = {
+    type: (file) => `${file.name} is not a supported file type`,
+    size: (file) => `${file.name} is too large`,
+    count: () => 'Too many files',
+};
+let sequence = 0;
+/**
+ * Staged attachments for a composer, headless: validation (`accept`, `maxBytes`, `maxFiles`),
+ * one upload per file with progress and cancel, retry, previews, and the event handlers for a file
+ * input, a drop zone and paste — no markup, no styles. Send `refs` with the
+ * message, then `clear()`:
+ *
+ * ```ts
+ * await chat.sendMessage({ text }, { body: { attachments: files.refs } });
+ * files.clear();
+ * ```
+ */
+export function useAttachments(options = {}) {
+    const backend = useAgentBackend(options.backend);
+    // The server's limits are the defaults, so a composer never repeats (and drifts from) them.
+    const { config } = useAgentConfig({ backend });
+    const limits = config?.attachments;
+    const accept = options.accept ?? limits?.allowedContentTypes;
+    const maxBytes = options.maxBytes ?? limits?.maxBytes;
+    const maxFiles = options.maxFiles ?? limits?.maxPerMessage;
+    const effective = {
+        ...options,
+        backend,
+        ...(accept !== undefined ? { accept } : {}),
+        ...(maxBytes !== undefined ? { maxBytes } : {}),
+        ...(maxFiles !== undefined ? { maxFiles } : {}),
+    };
+    const latest = useRef(effective);
+    latest.current = effective;
+    const [items, setItems] = useState([]);
+    const itemsRef = useRef(items);
+    itemsRef.current = items;
+    const controllers = useRef(new Map());
+    const [dragDepth, setDragDepth] = useState(0);
+    const patch = useCallback((id, change) => {
+        setItems((current) => current.map((item) => (item.id === id ? { ...item, ...change } : item)));
+    }, []);
+    const start = useCallback((item) => {
+        const { upload, backend } = latest.current;
+        const run = upload ??
+            (backend.uploadAttachment !== undefined
+                ? backend.uploadAttachment.bind(backend)
+                : undefined);
+        if (run === undefined) {
+            patch(item.id, {
+                status: 'error',
+                error: new AgentBackendUnsupportedError('uploadAttachment').message,
+            });
+            return;
+        }
+        const controller = new AbortController();
+        controllers.current.set(item.id, controller);
+        run(item.file, {
+            signal: controller.signal,
+            onProgress: (fraction) => patch(item.id, { progress: Math.max(0, Math.min(1, fraction)) }),
+        }).then((attachment) => {
+            if (controller.signal.aborted)
+                return;
+            controllers.current.delete(item.id);
+            patch(item.id, { status: 'ready', progress: 1, attachment });
+        }, (error) => {
+            if (controller.signal.aborted)
+                return;
+            controllers.current.delete(item.id);
+            patch(item.id, {
+                status: 'error',
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
+    }, [patch]);
+    const add = useCallback((files) => {
+        if (files == null)
+            return;
+        const { accept, maxBytes, maxFiles, describeRejection } = latest.current;
+        const describe = (reason, file) => describeRejection?.(reason, file) ?? DEFAULT_REJECTION[reason](file);
+        let room = maxFiles === undefined
+            ? Number.POSITIVE_INFINITY
+            : maxFiles - itemsRef.current.filter((item) => item.status !== 'rejected').length;
+        const staged = [];
+        for (const file of Array.from(files)) {
+            sequence += 1;
+            const base = {
+                id: `att-${sequence}`,
+                file,
+                name: file.name,
+                size: file.size,
+                type: file.type,
+                progress: 0,
+            };
+            const reason = !acceptsFile(accept, file)
+                ? 'type'
+                : maxBytes !== undefined && file.size > maxBytes
+                    ? 'size'
+                    : room <= 0
+                        ? 'count'
+                        : undefined;
+            if (reason !== undefined) {
+                staged.push({ ...base, status: 'rejected', error: describe(reason, file) });
+                continue;
+            }
+            room -= 1;
+            const previewUrl = file.type.startsWith('image/') && typeof URL.createObjectURL === 'function'
+                ? URL.createObjectURL(file)
+                : undefined;
+            staged.push({ ...base, status: 'uploading', ...(previewUrl ? { previewUrl } : {}) });
+        }
+        if (staged.length === 0)
+            return;
+        setItems((current) => [...current, ...staged]);
+        for (const item of staged) {
+            if (item.status === 'uploading')
+                start(item);
+        }
+    }, [start]);
+    const release = useCallback((item) => {
+        if (item === undefined)
+            return;
+        controllers.current.get(item.id)?.abort();
+        controllers.current.delete(item.id);
+        if (item.previewUrl !== undefined && typeof URL.revokeObjectURL === 'function') {
+            URL.revokeObjectURL(item.previewUrl);
+        }
+    }, []);
+    const remove = useCallback((id) => {
+        release(itemsRef.current.find((item) => item.id === id));
+        setItems((current) => current.filter((item) => item.id !== id));
+    }, [release]);
+    const clear = useCallback(() => {
+        for (const item of itemsRef.current)
+            release(item);
+        setItems([]);
+    }, [release]);
+    const retry = useCallback((id) => {
+        const item = itemsRef.current.find((candidate) => candidate.id === id);
+        if (item === undefined || item.status !== 'error')
+            return;
+        const { error: _previous, ...rest } = item;
+        const again = { ...rest, status: 'uploading', progress: 0 };
+        setItems((current) => current.map((candidate) => (candidate.id === id ? again : candidate)));
+        start(again);
+    }, [start]);
+    // Unmount: cancel what is in flight and free the previews.
+    useEffect(() => () => {
+        for (const item of itemsRef.current)
+            release(item);
+    }, [release]);
+    const onPaste = useCallback((event) => {
+        const files = filesFromClipboard(event.clipboardData);
+        if (files.length === 0)
+            return;
+        event.preventDefault();
+        add(files);
+    }, [add]);
+    const dropZoneProps = useMemo(() => ({
+        onDragEnter: (event) => {
+            if (!dragHasFiles(event.dataTransfer))
+                return;
+            event.preventDefault();
+            setDragDepth((depth) => depth + 1);
+        },
+        onDragOver: (event) => {
+            // Without this the browser never fires `drop` — it opens the file instead.
+            if (dragHasFiles(event.dataTransfer))
+                event.preventDefault();
+        },
+        onDragLeave: (event) => {
+            if (!dragHasFiles(event.dataTransfer))
+                return;
+            setDragDepth((depth) => Math.max(0, depth - 1));
+        },
+        onDrop: (event) => {
+            if (!dragHasFiles(event.dataTransfer))
+                return;
+            event.preventDefault();
+            setDragDepth(0);
+            add(event.dataTransfer?.files);
+        },
+    }), [add]);
+    const inputProps = useMemo(() => ({
+        type: 'file',
+        accept: typeof accept === 'string' ? accept : accept?.join(','),
+        multiple: maxFiles === undefined || maxFiles > 1,
+        onChange: (event) => {
+            const input = event.currentTarget;
+            add(input.files);
+            // Let the same file be picked again after a remove.
+            input.value = '';
+        },
+    }), [accept, maxFiles, add]);
+    return useMemo(() => {
+        const ready = items.filter((item) => item.status === 'ready' && item.attachment !== undefined);
+        return {
+            items,
+            add,
+            remove,
+            retry,
+            clear,
+            isUploading: items.some((item) => item.status === 'uploading'),
+            refs: ready.map((item) => ({ mediaId: item.attachment.mediaId })),
+            inputProps,
+            dropZoneProps,
+            isDragging: dragDepth > 0,
+            onPaste,
+        };
+    }, [items, add, remove, retry, clear, inputProps, dropZoneProps, dragDepth, onPaste]);
+}
+//# sourceMappingURL=use-attachments.js.map

package/dist/src/react/core/attachments/use-attachments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-attachments.js","sourceRoot":"","sources":["../../../../../src/react/core/attachments/use-attachments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAG1E,OAAO,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAgG3E,MAAM,iBAAiB,GAAwD;IAC7E,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,+BAA+B;IAC3D,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,eAAe;IAC3C,KAAK,EAAE,GAAG,EAAE,CAAC,gBAAgB;CAC9B,CAAC;AAEF,IAAI,QAAQ,GAAG,CAAC,CAAC;AAEjB;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,OAAO,GAA0B,EAAE;IAChE,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,4FAA4F;IAC5F,MAAM,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,MAAM,EAAE,WAAW,CAAC;IACnC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,EAAE,mBAAmB,CAAC;IAC7D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,MAAM,EAAE,QAAQ,CAAC;IACtD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,MAAM,EAAE,aAAa,CAAC;IAC3D,MAAM,SAAS,GAAG;QAChB,GAAG,OAAO;QACV,OAAO;QACP,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC;IACF,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IACjC,MAAM,CAAC,OAAO,GAAG,SAAS,CAAC;IAC3B,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAqB,EAAE,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/B,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAC;IACzB,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,GAAG,EAA2B,CAAC,CAAC;IAC/D,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAE9C,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,EAAU,EAAE,MAAiC,EAAE,EAAE;QAC1E,QAAQ,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjG,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,KAAK,GAAG,WAAW,CACvB,CAAC,IAAsB,EAAE,EAAE;QACzB,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC;QAC3C,MAAM,GAAG,GACP,MAAM;YACN,CAAC,OAAO,CAAC,gBAAgB,KAAK,SAAS;gBACrC,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC;gBACxC,CAAC,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE;gBACb,MAAM,EAAE,OAAO;gBACf,KAAK,EAAE,IAAI,4BAA4B,CAAC,kBAAkB,CAAC,CAAC,OAAO;aACpE,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;QAC7C,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE;YACb,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,UAAU,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;SAC3F,CAAC,CAAC,IAAI,CACL,CAAC,UAAU,EAAE,EAAE;YACb,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO;gBAAE,OAAO;YACtC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACpC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;QAC/D,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACjB,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO;gBAAE,OAAO;YACtC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACpC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE;gBACb,MAAM,EAAE,OAAO;gBACf,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC9D,CAAC,CAAC;QACL,CAAC,CACF,CAAC;IACJ,CAAC,EACD,CAAC,KAAK,CAAC,CACR,CAAC;IAEF,MAAM,GAAG,GAAG,WAAW,CACrB,CAAC,KAA0D,EAAE,EAAE;QAC7D,IAAI,KAAK,IAAI,IAAI;YAAE,OAAO;QAC1B,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC;QACzE,MAAM,QAAQ,GAAG,CAAC,MAA2B,EAAE,IAAU,EAAE,EAAE,CAC3D,iBAAiB,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,iBAAiB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;QACvE,IAAI,IAAI,GACN,QAAQ,KAAK,SAAS;YACpB,CAAC,CAAC,MAAM,CAAC,iBAAiB;YAC1B,CAAC,CAAC,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,MAAM,CAAC;QACtF,MAAM,MAAM,GAAuB,EAAE,CAAC;QACtC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,KAAwB,CAAC,EAAE,CAAC;YACxD,QAAQ,IAAI,CAAC,CAAC;YACd,MAAM,IAAI,GAAG;gBACX,EAAE,EAAE,OAAO,QAAQ,EAAE;gBACrB,IAAI;gBACJ,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,QAAQ,EAAE,CAAC;aACZ,CAAC;YACF,MAAM,MAAM,GAAoC,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC;gBACxE,CAAC,CAAC,MAAM;gBACR,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,GAAG,QAAQ;oBAC9C,CAAC,CAAC,MAAM;oBACR,CAAC,CAAC,IAAI,IAAI,CAAC;wBACT,CAAC,CAAC,OAAO;wBACT,CAAC,CAAC,SAAS,CAAC;YAClB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;gBAC5E,SAAS;YACX,CAAC;YACD,IAAI,IAAI,CAAC,CAAC;YACV,MAAM,UAAU,GACd,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU;gBACzE,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC;gBAC3B,CAAC,CAAC,SAAS,CAAC;YAChB,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACvF,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAChC,QAAQ,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC;QAC/C,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;YAC1B,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW;gBAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC,EACD,CAAC,KAAK,CAAC,CACR,CAAC;IAEF,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,IAAkC,EAAE,EAAE;QACjE,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO;QAC/B,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC;QAC1C,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACpC,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU,EAAE,CAAC;YAC/E,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACvC,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,MAAM,GAAG,WAAW,CACxB,CAAC,EAAU,EAAE,EAAE;QACb,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QACzD,QAAQ,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAClE,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,OAAO;YAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QACnD,QAAQ,CAAC,EAAE,CAAC,CAAC;IACf,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAEd,MAAM,KAAK,GAAG,WAAW,CACvB,CAAC,EAAU,EAAE,EAAE;QACb,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QACvE,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,OAAO;YAAE,OAAO;QAC1D,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;QAC3C,MAAM,KAAK,GAAqB,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QAC9E,QAAQ,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAC7F,KAAK,CAAC,KAAK,CAAC,CAAC;IACf,CAAC,EACD,CAAC,KAAK,CAAC,CACR,CAAC;IAEF,2DAA2D;IAC3D,SAAS,CACP,GAAG,EAAE,CAAC,GAAG,EAAE;QACT,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,OAAO;YAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,MAAM,OAAO,GAAG,WAAW,CACzB,CAAC,KAAyB,EAAE,EAAE;QAC5B,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QACtD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC/B,KAAK,CAAC,cAAc,EAAE,CAAC;QACvB,GAAG,CAAC,KAAK,CAAC,CAAC;IACb,CAAC,EACD,CAAC,GAAG,CAAC,CACN,CAAC;IAEF,MAAM,aAAa,GAAG,OAAO,CAC3B,GAAG,EAAE,CAAC,CAAC;QACL,WAAW,EAAE,CAAC,KAAoB,EAAE,EAAE;YACpC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,YAAY,CAAC;gBAAE,OAAO;YAC9C,KAAK,CAAC,cAAc,EAAE,CAAC;YACvB,YAAY,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QACrC,CAAC;QACD,UAAU,EAAE,CAAC,KAAoB,EAAE,EAAE;YACnC,2EAA2E;YAC3E,IAAI,YAAY,CAAC,KAAK,CAAC,YAAY,CAAC;gBAAE,KAAK,CAAC,cAAc,EAAE,CAAC;QAC/D,CAAC;QACD,WAAW,EAAE,CAAC,KAAoB,EAAE,EAAE;YACpC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,YAAY,CAAC;gBAAE,OAAO;YAC9C,YAAY,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;QAClD,CAAC;QACD,MAAM,EAAE,CAAC,KAAoB,EAAE,EAAE;YAC/B,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,YAAY,CAAC;gBAAE,OAAO;YAC9C,KAAK,CAAC,cAAc,EAAE,CAAC;YACvB,YAAY,CAAC,CAAC,CAAC,CAAC;YAChB,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;QACjC,CAAC;KACF,CAAC,EACF,CAAC,GAAG,CAAC,CACN,CAAC;IAEF,MAAM,UAAU,GAAG,OAAO,CACxB,GAAG,EAAE,CAAC,CAAC;QACL,IAAI,EAAE,MAAe;QACrB,MAAM,EAAE,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC;QAC/D,QAAQ,EAAE,QAAQ,KAAK,SAAS,IAAI,QAAQ,GAAG,CAAC;QAChD,QAAQ,EAAE,CAAC,KAA0C,EAAE,EAAE;YACvD,MAAM,KAAK,GAAG,KAAK,CAAC,aAAa,CAAC;YAClC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACjB,oDAAoD;YACpD,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC;QACnB,CAAC;KACF,CAAC,EACF,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,CACxB,CAAC;IAEF,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CACxB,CAAC,IAAI,EAAgE,EAAE,CACrE,IAAI,CAAC,MAAM,KAAK,OAAO,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,CAC3D,CAAC;QACF,OAAO;YACL,KAAK;YACL,GAAG;YACH,MAAM;YACN,KAAK;YACL,KAAK;YACL,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,WAAW,CAAC;YAC9D,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC;YACjE,UAAU;YACV,aAAa;YACb,UAAU,EAAE,SAAS,GAAG,CAAC;YACzB,OAAO;SACR,CAAC;IACJ,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;AACxF,CAAC"}

package/dist/src/react/core/backend.d.ts

@@ -0,0 +1,234 @@
+import type { ActionProposal, ActionProposalMutationResult, AgentCatalogEntry, AgentClientConfig, ChatQueueState, MessageAttachment, MessageFeedback, MessageFeedbackValue, ModelCatalogView, QuotaReport, SkillCatalogEntry, ThreadDetail, ThreadSummary, ToolCatalogEntry } from '../../index.js';
+import type { HttpErrorListener } from './http-error.js';
+/**
+ * Partial update accepted by `PATCH <base>/threads/:threadId`. `defaultAgent: null` clears a
+ * previously-set default back to the module's own default; omitting it leaves the thread's
+ * current default untouched.
+ */
+export interface ThreadPatch {
+    title?: string;
+    defaultAgent?: string | null;
+    /** Pin a catalog model on the thread; `null` unpins it. */
+    model?: string | null;
+    /** Pin one of the agent's personas on the thread; `null` clears it (the agent's default applies). */
+    persona?: string | null;
+}
+/** Starting a turn: the body `POST <base>/chat` takes (see docs/stream-protocol.md). */
+export interface ChatStreamRequest {
+    /** `{ message, threadId?, agent?, persona?, model?, attachments?, pageContext?, regenerate?, … }`. */
+    body: Record<string, unknown>;
+    /** Per-request headers the AI SDK was handed for this send. */
+    headers?: Record<string, string>;
+    /** Aborted when the user stops the turn. */
+    signal?: AbortSignal;
+}
+/** Attaching to a run that is already streaming: `GET <base>/chat/:runId/stream?after=<seq>`. */
+export interface ResumeStreamRequest {
+    runId: string;
+    /**
+     * The sequence number (SSE `id:`) of the last frame the client already has. Omitted → replay
+     * from the first frame. A backend that cannot skip may ignore it: the transport also drops frames
+     * at or below it.
+     */
+    after?: number;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/**
+ * An open chat stream: the raw `text/event-stream` bytes in the stream-protocol framing, plus the
+ * identity a backend may learn before the first frame (the `X-Agent-Run-Id` / `X-Agent-Thread-Id`
+ * headers). The body's own `event: meta` frame supplies them otherwise.
+ */
+export interface ChatStreamResponse {
+    proposalDecision?: {
+        threadId: string;
+        proposalDecision: ActionProposalMutationResult | {
+            status: 'ambiguous';
+            proposalIds: string[];
+        };
+        text?: string;
+    };
+    body: ReadableStream<Uint8Array>;
+    runId?: string;
+    threadId?: string;
+    /**
+     * The server queued the message instead of starting a turn (`202`): the thread already had one
+     * running — another tab, another device. `body` is then empty; the transport reports this as a
+     * transient `data-queue` part and `useAgentChat` moves the message into `chat.queue`.
+     */
+    queued?: QueuedSendResult;
+}
+/**
+ * `POST <base>/chat` answered `202`: the message waits in the thread's queue (see
+ * docs/stream-protocol.md, "Message queue").
+ */
+export interface QueuedSendResult {
+    queued: true;
+    threadId: string;
+    /** The queued message's id — also the id of the run it will start. */
+    messageId: string;
+    /** 0-based place in the queue when it was queued. */
+    position: number;
+    queue: ChatQueueState;
+    /** Set when it started straight away (the thread was idle after all): attach to this run. */
+    runId?: string;
+    /** The run an interrupt cancelled to make room for it. */
+    interrupting?: string;
+}
+/** What `PATCH <base>/queue/:messageId` takes. */
+export interface QueuedMessageUpdate {
+    message?: string;
+    /** `[{ mediaId }]` refs replacing the message's attachments; `null` drops them. */
+    attachments?: Array<{
+        mediaId: string;
+    }> | null;
+    /** Move it to this 0-based place in the queue. */
+    position?: number;
+}
+/** What `POST <base>/messages/:id/feedback` takes. `value: null` clears the rating. */
+export interface MessageFeedbackInput {
+    value: MessageFeedbackValue | null;
+    comment?: string;
+}
+export interface UploadAttachmentOptions {
+    signal?: AbortSignal;
+    /** Called with 0..1 as the upload progresses, when the backend can observe it. */
+    onProgress?: (fraction: number) => void;
+}
+/** How {@link AgentClient} reaches the server — handed to an {@link AttachmentUploadStrategy}. */
+export interface AgentConnection {
+    /** The server's origin, trailing slash removed (`''` for same-origin). */
+    baseUrl: string;
+    /** The agent's route prefix, normalized to a leading slash (`'/agent'`), or `''`. */
+    path: string;
+    /** The client's static + per-request headers, resolved now (auth, CSRF). */
+    headers: () => Promise<Record<string, string>>;
+    credentials?: RequestCredentials;
+    fetch: typeof fetch;
+    /** The client's `onHttpError` — call it with an upload's error answer before throwing it. */
+    onHttpError?: HttpErrorListener;
+}
+/**
+ * Replaces {@link AgentClient}'s own `uploadAttachment` (`POST <path>/attachments`) — e.g.
+ * `mediaAttachments()` from `@adonis-agora/agent/react/media`, or your own storage. Gets the
+ * client's connection so it needs no configuration of its own. Resolve with the attachment your
+ * server's `AGENT_ATTACHMENT_STAGING` recognises by `mediaId`.
+ */
+export type AttachmentUploadStrategy = (file: File, options: UploadAttachmentOptions, connection: AgentConnection) => Promise<MessageAttachment>;
+/**
+ * Everything the React layer asks of a server — the seam between `useAgentChat` (and the other
+ * hooks) and whatever serves the agent. {@link AgentClient} is the default implementation, over the
+ * library's own REST routes with `fetch`. An app with its own client — a generated one, a different
+ * auth scheme (cookie session + CSRF header), a backend that is not this library at all but speaks
+ * docs/stream-protocol.md — implements this instead and passes it as `<AgentProvider backend>` (or
+ * per hook, `useAgentChat({ backend })`).
+ *
+ * The streaming, thread and cancel members are required: without them there is no chat. The rest
+ * are optional; a hook that needs one the backend does not have throws
+ * {@link AgentBackendUnsupportedError} when it is called, so a backend only implements what its
+ * server supports.
+ */
+export interface AgentBackend {
+    /** Start a turn and return its SSE stream. Throw on a non-2xx answer. */
+    openChatStream(request: ChatStreamRequest): Promise<ChatStreamResponse>;
+    /** Attach to a streaming run. Resolve `null` when nothing is streaming under that id (HTTP 404). */
+    resumeChatStream(request: ResumeStreamRequest): Promise<ChatStreamResponse | null>;
+    /** Hard-stop a run server-side. */
+    cancelStream(runId: string): Promise<unknown>;
+    listThreads(): Promise<ThreadSummary[]>;
+    getThread(id: string): Promise<ThreadDetail>;
+    updateThread(id: string, patch: ThreadPatch): Promise<unknown>;
+    deleteThread(id: string): Promise<unknown>;
+    /**
+     * Queue a message on a thread (`POST <base>/chat` with `mode: 'queue'` or `'interrupt'`), which
+     * the server answers with `202` JSON rather than a stream. What `chat.queue` sends through; a
+     * backend without it keeps the composer blocked while a turn runs.
+     */
+    enqueueMessage?(request: ChatStreamRequest): Promise<QueuedSendResult>;
+    /** `GET <base>/threads/:id/queue`. */
+    getQueue?(threadId: string): Promise<ChatQueueState>;
+    /** `PATCH <base>/queue/:messageId` — edit and/or move a waiting message. */
+    updateQueuedMessage?(messageId: string, update: QueuedMessageUpdate): Promise<ChatQueueState>;
+    /** `DELETE <base>/queue/:messageId`. */
+    removeQueuedMessage?(messageId: string): Promise<ChatQueueState>;
+    /**
+     * `POST <base>/queue/:messageId/interrupt` — run a waiting message now: it moves to the head as an
+     * interrupt and the running turn is cancelled for it. `interrupting` is the run that was
+     * cancelled; `runId` is set instead when nothing was running and the message started at once.
+     * What `chat.queue.interrupt(id)` calls.
+     */
+    interruptQueuedMessage?(messageId: string): Promise<ChatQueueState & {
+        runId?: string;
+        interrupting?: string;
+    }>;
+    /** `DELETE <base>/threads/:id/queue`. */
+    clearQueue?(threadId: string): Promise<ChatQueueState>;
+    /** `POST <base>/threads/:id/queue/resume` — `runId` when the head started. */
+    resumeQueue?(threadId: string): Promise<ChatQueueState & {
+        runId?: string;
+    }>;
+    forkFromMessage?(threadId: string, messageId: string): Promise<ThreadSummary>;
+    promoteThread?(id: string): Promise<unknown>;
+    truncateFromMessage?(threadId: string, messageId: string): Promise<unknown>;
+    listActionProposals?(input: {
+        threadId: string;
+    }): Promise<ActionProposal[]>;
+    approveActionProposal?(input: {
+        threadId: string;
+        proposalId: string;
+        remember?: boolean;
+    }): Promise<ActionProposalMutationResult>;
+    rejectActionProposal?(input: {
+        threadId: string;
+        proposalId: string;
+        reason?: string;
+    }): Promise<ActionProposalMutationResult>;
+    approveToolCall?(input: {
+        toolCallId: string;
+        remember?: boolean;
+        via?: string;
+    }): Promise<unknown>;
+    rejectToolCall?(input: {
+        toolCallId: string;
+        reason?: string;
+        via?: string;
+    }): Promise<unknown>;
+    answerToolCall?(input: {
+        toolCallId: string;
+        answers?: Record<string, string[]>;
+        via?: string;
+    }): Promise<unknown>;
+    skipToolCall?(input: {
+        toolCallId: string;
+        via?: string;
+    }): Promise<unknown>;
+    uploadAttachment?(file: File, options?: UploadAttachmentOptions): Promise<MessageAttachment>;
+    listTools?(agent?: string): Promise<ToolCatalogEntry[]>;
+    listSkills?(threadId?: string): Promise<SkillCatalogEntry[]>;
+    /** `GET <base>/quota` — every budget window, and which one blocks sends, if any. */
+    getQuota?(): Promise<QuotaReport>;
+    /** `GET <base>/models?agent=` — what a model picker offers. */
+    listModels?(agent?: string): Promise<ModelCatalogView>;
+    /** `GET <base>/agents` — what an agent picker offers. */
+    listAgents?(): Promise<AgentCatalogEntry[]>;
+    /** `GET <base>/config` — attachment limits and upload mode, and which features are on. */
+    getConfig?(): Promise<AgentClientConfig>;
+    setMessageFeedback?(messageId: string, input: MessageFeedbackInput): Promise<{
+        feedback: MessageFeedback | null;
+    }>;
+}
+/** An optional {@link AgentBackend} member the bound backend does not implement was called. */
+export declare class AgentBackendUnsupportedError extends Error {
+    readonly method: string;
+    constructor(method: string);
+}
+type OptionalMethod = {
+    [K in keyof AgentBackend]-?: undefined extends AgentBackend[K] ? K : never;
+}[keyof AgentBackend];
+/**
+ * The optional backend method `name`, bound — or a throw naming it. For hook code that has to call
+ * something a backend may not offer.
+ */
+export declare function requireBackendMethod<K extends OptionalMethod>(backend: AgentBackend, name: K): NonNullable<AgentBackend[K]>;
+export {};
+//# sourceMappingURL=backend.d.ts.map

package/dist/src/react/core/backend.d.ts.map

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

package/dist/src/react/core/backend.js

@@ -0,0 +1,21 @@
+/** An optional {@link AgentBackend} member the bound backend does not implement was called. */
+export class AgentBackendUnsupportedError extends Error {
+    method;
+    constructor(method) {
+        super(`The agent backend does not implement ${method}()`);
+        this.method = method;
+        this.name = 'AgentBackendUnsupportedError';
+    }
+}
+/**
+ * The optional backend method `name`, bound — or a throw naming it. For hook code that has to call
+ * something a backend may not offer.
+ */
+export function requireBackendMethod(backend, name) {
+    const method = backend[name];
+    if (typeof method !== 'function') {
+        throw new AgentBackendUnsupportedError(name);
+    }
+    return method.bind(backend);
+}
+//# sourceMappingURL=backend.js.map

package/dist/src/react/core/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../../../src/react/core/backend.ts"],"names":[],"mappings":"AAgPA,+FAA+F;AAC/F,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IAChC,MAAM;IAA3B,YAAqB,MAAc;QACjC,KAAK,CAAC,wCAAwC,MAAM,IAAI,CAAC,CAAC;sBADvC,MAAM;QAEzB,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AAMD;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAqB,EACrB,IAAO;IAEP,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,MAAM,IAAI,4BAA4B,CAAC,IAAI,CAAC,CAAC;IAC/C,CAAC;IACD,OAAQ,MAAwC,CAAC,IAAI,CAAC,OAAO,CAAiC,CAAC;AACjG,CAAC"}

package/dist/src/react/core/background-runs.d.ts

@@ -0,0 +1,32 @@
+import type { StoredMessage } from './client-wire.js';
+/**
+ * A sub-agent the conversation started and did not wait for. The chat is free while it works, so a
+ * client has to be able to say what is still running and to show the answer when it lands — neither
+ * of which the turn that started it can report, because that turn is over.
+ */
+export interface BackgroundRun {
+    /** The run doing the work. Also what stamps the message it eventually posts. */
+    runId: string;
+    /** The agent working on it. */
+    agent: string;
+    /** The `agent`-kind call that started it — what a UI keys its card off. */
+    toolCallId: string;
+    toolName: string;
+    /**
+     * `delivered` the moment the thread holds a message stamped with this run. A run that FAILED
+     * reads as delivered too: it posts a message saying so, which is the point — there is no third
+     * state a reader could act on differently, and "running" for ever is the state to avoid.
+     */
+    status: 'running' | 'delivered';
+    /** The message it posted, once it did. */
+    message?: StoredMessage;
+}
+/**
+ * Every sub-agent this thread started in the background, and whether each has reported back.
+ *
+ * Derived from the transcript rather than tracked in session state, so it survives a reload and a
+ * second tab: the receipt is a persisted tool result, and the answer is a persisted message stamped
+ * with the run that wrote it. Nothing here needs a live connection to be true.
+ */
+export declare function backgroundRunsFromThread(messages: readonly StoredMessage[]): BackgroundRun[];
+//# sourceMappingURL=background-runs.d.ts.map

package/dist/src/react/core/background-runs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-runs.d.ts","sourceRoot":"","sources":["../../../../src/react/core/background-runs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,EAAE,SAAS,GAAG,WAAW,CAAC;IAChC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AA0BD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,GAAG,aAAa,EAAE,CAyB5F"}

package/dist/src/react/core/background-runs.js

@@ -0,0 +1,47 @@
+function asReceipt(output) {
+    if (typeof output !== 'object' || output === null) {
+        return null;
+    }
+    const candidate = output;
+    if (candidate.detached !== true ||
+        candidate.status !== 'started' ||
+        typeof candidate.agent !== 'string' ||
+        typeof candidate.runId !== 'string') {
+        return null;
+    }
+    return { detached: true, status: 'started', agent: candidate.agent, runId: candidate.runId };
+}
+/**
+ * Every sub-agent this thread started in the background, and whether each has reported back.
+ *
+ * Derived from the transcript rather than tracked in session state, so it survives a reload and a
+ * second tab: the receipt is a persisted tool result, and the answer is a persisted message stamped
+ * with the run that wrote it. Nothing here needs a live connection to be true.
+ */
+export function backgroundRunsFromThread(messages) {
+    const byRun = new Map();
+    for (const message of messages) {
+        for (const result of message.toolResults ?? []) {
+            const receipt = asReceipt(result.output);
+            if (receipt === null || byRun.has(receipt.runId)) {
+                continue;
+            }
+            byRun.set(receipt.runId, {
+                runId: receipt.runId,
+                agent: receipt.agent,
+                toolCallId: result.id,
+                toolName: result.name,
+                status: 'running',
+            });
+        }
+    }
+    for (const message of messages) {
+        const run = message.runId === undefined ? undefined : byRun.get(message.runId);
+        if (run !== undefined) {
+            run.status = 'delivered';
+            run.message = message;
+        }
+    }
+    return [...byRun.values()];
+}
+//# sourceMappingURL=background-runs.js.map

package/dist/src/react/core/background-runs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-runs.js","sourceRoot":"","sources":["../../../../src/react/core/background-runs.ts"],"names":[],"mappings":"AAiCA,SAAS,SAAS,CAAC,MAAe;IAChC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,SAAS,GAAG,MAA0B,CAAC;IAC7C,IACE,SAAS,CAAC,QAAQ,KAAK,IAAI;QAC3B,SAAS,CAAC,MAAM,KAAK,SAAS;QAC9B,OAAO,SAAS,CAAC,KAAK,KAAK,QAAQ;QACnC,OAAO,SAAS,CAAC,KAAK,KAAK,QAAQ,EACnC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC;AAC/F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAAkC;IACzE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC/C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC;YAC/C,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACzC,IAAI,OAAO,KAAK,IAAI,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjD,SAAS;YACX,CAAC;YACD,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE;gBACvB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,UAAU,EAAE,MAAM,CAAC,EAAE;gBACrB,QAAQ,EAAE,MAAM,CAAC,IAAI;gBACrB,MAAM,EAAE,SAAS;aAClB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC/E,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,GAAG,CAAC,MAAM,GAAG,WAAW,CAAC;YACzB,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;AAC7B,CAAC"}

package/dist/src/react/core/catalog/use-agents.d.ts

@@ -0,0 +1,31 @@
+import type { AgentCatalogEntry, PersonaCatalogEntry } from '../../../index.js';
+import { type AgentBackend } from '../backend.js';
+export interface UseAgentsOptions {
+    /** Default: the enclosing `<AgentProvider>`'s. Must implement `listAgents`. */
+    backend?: AgentBackend;
+    /** `false` holds the request. Default `true`. */
+    enabled?: boolean;
+}
+export interface AgentsState {
+    /** `[]` until loaded. */
+    agents: AgentCatalogEntry[];
+    /** The agent a turn runs as when none is named. */
+    defaultAgent: string | null;
+    /**
+     * An agent's personas — the data behind a persona picker. `agent` omitted → the default agent's.
+     * `[]` for an agent that declares none (or before the list loads).
+     */
+    personasOf: (agent?: string) => PersonaCatalogEntry[];
+    /** The persona `agent` (default: the default agent) runs under when a send names none, or `null`. */
+    defaultPersonaOf: (agent?: string) => string | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * The registered agents (`GET <base>/agents`) — the data behind an agent picker, and each agent's
+ * personas behind a persona picker. Send the pick as `useAgentChat({ agent, persona })`, or pin it on
+ * a thread with `PATCH <base>/threads/:id { defaultAgent, persona }`.
+ */
+export declare function useAgents(options?: UseAgentsOptions): AgentsState;
+//# sourceMappingURL=use-agents.d.ts.map

package/dist/src/react/core/catalog/use-agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-agents.d.ts","sourceRoot":"","sources":["../../../../../src/react/core/catalog/use-agents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,KAAK,YAAY,EAAwB,MAAM,eAAe,CAAC;AAIxE,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,yBAAyB;IACzB,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,mDAAmD;IACnD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;OAGG;IACH,UAAU,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,mBAAmB,EAAE,CAAC;IACtD,qGAAqG;IACrG,gBAAgB,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACpD,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,WAAW,CA2BrE"}