@adonis-agora/agent 0.51.0 → 0.52.0

package/skills/agent-setup/SKILL.md

@@ -19,6 +19,8 @@ sources:
   - "DavideCarvalho/adonis-agent:packages/adonis/docs/config-reference.mdx"
   - "DavideCarvalho/adonis-agent:packages/adonis/src/define_config.ts"
   - "DavideCarvalho/adonis-agent:packages/adonis/src/stores/factory.ts"
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/react.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/react/index.ts"
 ---
 
 # Setting up @adonis-agora/agent
@@ -181,8 +183,49 @@ bring-your-own `RedisStreamClient`). Pair with `durable: true` for cross-instanc
 Source: `packages/adonis/src/stores/factory.ts` (`tokenSinks`),
 `packages/adonis/docs/streaming-and-http.mdx` ("Single-replica by default" callout).
 
+### Pattern 4 — a React chat with `@adonis-agora/agent/react`
+
+The React layer is `@dudousxd/nestjs-agent-react` re-exported (an optional peer — install it with
+`@ai-sdk/react` and `ai`), plus an `AgentProvider` that already sends the session cookie and
+shield's CSRF token. No controller, no fetch code:
+
+```tsx
+import { AgentProvider, useAgentChat } from '@adonis-agora/agent/react'
+
+export default function ChatPage() {
+  return (
+    <AgentProvider>
+      <Chat />
+    </AgentProvider>
+  )
+}
+
+function Chat() {
+  const { transcript, composer, queue } = useAgentChat({ threadId, agent: 'support' })
+  // transcript.items[].blocks — text / tools (approvals) / elicitation / ui
+  // queue.items — messages sent while a turn was running, waiting server-side
+  // composer.text / setText / submit() / canSend / files
+}
+```
+
+`useAgentChat({ threadId })` loads the thread and re-attaches to a turn still streaming on it. A send
+made mid-turn is queued (`whileRunning: 'block'` to refuse instead). `path` on the provider must
+match `config/agent.ts`'s `path`.
+
 ## Common mistakes
 
+### HIGH — calling `useAgentChat()` outside `<AgentProvider>`
+
+```tsx
+// Wrong — falls back to a bare client with no CSRF header: shield answers every POST with 403.
+function Chat() { const chat = useAgentChat() }  // no provider above
+
+// Correct — the provider reads XSRF-TOKEN (or <meta name="csrf-token">) per request.
+<AgentProvider><Chat /></AgentProvider>
+```
+
+Outside React, `createAgentClient()` from the same entry builds the client with the same defaults.
+
 ### HIGH — omitting `actorResolver` in an app that has logins
 
 ```ts

package/dist/src/react/use-agent-chat.d.ts

@@ -1,33 +0,0 @@
-import { type AgentChatClientOptions, type AgentChatRequestBody, type ChatPart } from '../client/index.js';
-/** A message in the chat transcript — the user's text, or the assistant's streamed parts. */
-export interface AgentChatMessage {
-    id: string;
-    role: 'user' | 'assistant';
-    parts: ChatPart[];
-    /** `true` while this assistant message is still receiving stream frames. */
-    streaming?: boolean;
-}
-export type AgentChatStatus = 'idle' | 'streaming' | 'error';
-export interface UseAgentChatOptions extends AgentChatClientOptions {
-    /**
-     * Builds the request body for a typed message. Defaults to `{ message }`. Override to attach
-     * `pageContext`, `agent`, `persona`, etc. The `threadId` is injected by the hook after the first
-     * turn, so a custom `buildBody` should NOT set it.
-     */
-    buildBody?: (message: string) => AgentChatRequestBody;
-}
-export interface UseAgentChatResult {
-    messages: AgentChatMessage[];
-    status: AgentChatStatus;
-    error: string | null;
-    send: (text: string) => Promise<void>;
-    cancel: () => void;
-}
-/**
- * React binding over {@link createAgentChatClient}: owns the transcript, thread id, and streaming
- * status, and drives one `AbortController` per turn. Reconnection (re-attach on a dropped stream) is
- * handled by the client — the hook just renders whatever parts it reports. Pass client options
- * (`basePath`, `fetch`, `getHeaders`, `resume`) straight through.
- */
-export declare function useAgentChat(options?: UseAgentChatOptions): UseAgentChatResult;
-//# sourceMappingURL=use-agent-chat.d.ts.map

package/dist/src/react/use-agent-chat.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-agent-chat.d.ts","sourceRoot":"","sources":["../../../src/react/use-agent-chat.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,sBAAsB,EAE3B,KAAK,oBAAoB,EACzB,KAAK,QAAQ,EAEd,MAAM,oBAAoB,CAAC;AAE5B,6FAA6F;AAC7F,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC;AAE7D,MAAM,WAAW,mBAAoB,SAAQ,sBAAsB;IACjE;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,oBAAoB,CAAC;CACvD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,MAAM,EAAE,eAAe,CAAC;IACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAQD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,kBAAkB,CA6HlF"}

package/dist/src/react/use-agent-chat.js

@@ -1,117 +0,0 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
-import { AgentChatDisconnectedError, createAgentChatClient, } from '../client/index.js';
-function randomId() {
-    return (globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`);
-}
-/**
- * React binding over {@link createAgentChatClient}: owns the transcript, thread id, and streaming
- * status, and drives one `AbortController` per turn. Reconnection (re-attach on a dropped stream) is
- * handled by the client — the hook just renders whatever parts it reports. Pass client options
- * (`basePath`, `fetch`, `getHeaders`, `resume`) straight through.
- */
-export function useAgentChat(options = {}) {
-    const { buildBody, ...clientOptions } = options;
-    const [messages, setMessages] = useState([]);
-    const [status, setStatus] = useState('idle');
-    const [error, setError] = useState(null);
-    const threadIdRef = useRef(undefined);
-    const abortRef = useRef(null);
-    const streamingIdRef = useRef(null);
-    // Keep one client instance stable across renders; the latest options ride on a ref so option
-    // changes take effect on the next send without re-creating the client.
-    const optionsRef = useRef(clientOptions);
-    optionsRef.current = clientOptions;
-    const buildBodyRef = useRef(buildBody);
-    buildBodyRef.current = buildBody;
-    const clientRef = useRef(createAgentChatClient({
-        ...clientOptions,
-        getHeaders: () => optionsRef.current.getHeaders?.() ?? {},
-    }));
-    useEffect(() => {
-        return () => {
-            abortRef.current?.abort();
-        };
-    }, []);
-    const send = useCallback(async (text) => {
-        const trimmed = text.trim();
-        if (!trimmed || streamingIdRef.current) {
-            return;
-        }
-        setError(null);
-        const userMessage = {
-            id: randomId(),
-            role: 'user',
-            parts: [{ type: 'text', text: trimmed }],
-        };
-        const assistantId = randomId();
-        setMessages((prev) => [
-            ...prev,
-            userMessage,
-            { id: assistantId, role: 'assistant', parts: [], streaming: true },
-        ]);
-        setStatus('streaming');
-        const controller = new AbortController();
-        abortRef.current = controller;
-        streamingIdRef.current = assistantId;
-        const applyParts = (parts) => setMessages((prev) => prev.map((message) => (message.id === assistantId ? { ...message, parts } : message)));
-        const stopStreaming = () => setMessages((prev) => prev.map((message) => message.id === assistantId ? { ...message, streaming: false } : message));
-        const body = {
-            ...(buildBodyRef.current?.(trimmed) ?? { message: trimmed }),
-            ...(threadIdRef.current ? { threadId: threadIdRef.current } : {}),
-        };
-        try {
-            const result = await clientRef.current.send({
-                body,
-                signal: controller.signal,
-                onParts: applyParts,
-                onThreadId: (id) => {
-                    threadIdRef.current = id;
-                },
-            });
-            if (result.queued !== undefined) {
-                // Another turn holds the thread (another tab, another device): the server queued the
-                // message. If it started at once, follow its run; otherwise there is no answer to show yet
-                // — it arrives when the turn ahead settles (a reload of the thread shows it).
-                if (result.queued.runId !== undefined) {
-                    await clientRef.current.resume(result.queued.runId, {
-                        signal: controller.signal,
-                        onParts: applyParts,
-                    });
-                }
-                else {
-                    setMessages((prev) => prev.filter((message) => message.id !== assistantId));
-                }
-            }
-            stopStreaming();
-            setStatus('idle');
-        }
-        catch (caught) {
-            if (controller.signal.aborted) {
-                return;
-            }
-            // Keep whatever streamed before the drop so the user doesn't lose a long answer.
-            if (caught instanceof AgentChatDisconnectedError && caught.parts.length > 0) {
-                applyParts(caught.parts);
-            }
-            stopStreaming();
-            setError(caught instanceof Error ? caught.message : 'Failed to reach the agent.');
-            setStatus('error');
-        }
-        finally {
-            abortRef.current = null;
-            streamingIdRef.current = null;
-        }
-    }, []);
-    const cancel = useCallback(() => {
-        abortRef.current?.abort();
-        abortRef.current = null;
-        const streamingId = streamingIdRef.current;
-        if (streamingId) {
-            setMessages((prev) => prev.map((message) => message.id === streamingId ? { ...message, streaming: false } : message));
-            streamingIdRef.current = null;
-        }
-        setStatus('idle');
-    }, []);
-    return { messages, status, error, send, cancel };
-}
-//# sourceMappingURL=use-agent-chat.js.map

package/dist/src/react/use-agent-chat.js.map

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