@adonis-agora/agent 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @adonis-agora/agent
 
+## 0.13.0
+
+### Minor Changes
+
+- [`b684986`](https://github.com/DavideCarvalho/adonis-agent/commit/b68498606a02e82dc92d01a7aa139eb6ba752bee) - Add a framework-agnostic browser client and a React hook for the chat SSE endpoints.
+
+  Consuming the agent's SSE envelope (`POST /agent/chat` → `event: meta` / `data: {delta}` / `event: component` / `event: done`) and reconnecting a dropped stream used to be re-implemented by hand in every app. Two new entry points move that logic into the package, next to the server that emits the envelope:
+
+  - **`@adonis-agora/agent/client`** — zero-dependency, isomorphic. `createAgentChatClient({ basePath, fetch, getHeaders, resume })` returns `send()` / `resume()` that post a turn, parse the envelope, capture the run id, and — when the connection drops before `done` — re-attach to `GET /agent/chat/:runId/stream` (which replays the whole stream from the start and follows live) with backoff, until the run finishes or the retry budget is exhausted. The run is durable and keeps executing server-side across the drop, so no tokens are lost. Also exports the parsing primitives (`parseSseEvent`, `decodeFrame`, `foldPart`, `readSseStream`) and `AgentChatDisconnectedError` (which carries the partial parts).
+  - **`@adonis-agora/agent/react`** — `useAgentChat({ ...clientOptions, buildBody })` returning `{ messages, status, error, send, cancel }`, a thin state wrapper over the client. `react` is a new optional peer dependency.
+
 ## 0.12.0
 
 ### Minor Changes

package/dist/src/client/chat-client.d.ts

@@ -0,0 +1,90 @@
+import { type ChatFrame, type ChatPart } from './sse.js';
+/**
+ * Body of `POST /agent/chat` (shape accepted by the provider → `AgentService.chat`). `message` is
+ * required; everything else is optional context. `pageContext` reaches the tools' ctx (not the model
+ * prompt) and is rebuilt from each turn's input, so send it on every message, not just the first.
+ */
+export interface AgentChatRequestBody {
+    message: string;
+    threadId?: string;
+    agent?: string;
+    persona?: string;
+    pageContext?: {
+        kind?: string;
+        [key: string]: unknown;
+    };
+    attachments?: unknown[];
+}
+/** Options for {@link createAgentChatClient}. */
+export interface AgentChatClientOptions {
+    /**
+     * Base path the provider mounted its routes under (`POST {basePath}/chat`,
+     * `GET {basePath}/chat/:runId/stream`). Defaults to `/agent`.
+     */
+    basePath?: string;
+    /** `fetch` implementation to use. Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /**
+     * Extra headers merged into every request — e.g. an anti-CSRF token (`{ 'X-XSRF-TOKEN': ... }`).
+     * Called per request so a rotating token is always read fresh.
+     */
+    getHeaders?: () => Record<string, string>;
+    /** Reconnection policy for a dropped stream, or `false` to disable and fail on the first drop. */
+    resume?: AgentChatResumeOptions | false;
+}
+/** Reconnection policy: how many times to re-attach, and the backoff before each attempt. */
+export interface AgentChatResumeOptions {
+    /** Max consecutive re-attach attempts before giving up. Defaults to 6. */
+    maxAttempts?: number;
+    /** Backoff before attempt `n` (1-based), in ms. Defaults to `min(400 * n, 3000)`. */
+    backoffMs?: (attempt: number) => number;
+}
+/** Callbacks fired while a stream is consumed. All optional. */
+export interface AgentChatHandlers {
+    /** The assistant message's parts so far, rebuilt on every frame (safe to render directly). */
+    onParts?: (parts: ChatPart[]) => void;
+    /** Each decoded renderable/control frame, in wire order. */
+    onFrame?: (frame: ChatFrame) => void;
+    /** The run id, as soon as it is known (response header, then the `meta` frame). */
+    onRunId?: (runId: string) => void;
+    /** The thread id, as soon as it is known. */
+    onThreadId?: (threadId: string) => void;
+}
+/** Arguments to {@link AgentChatClient.send}. */
+export interface AgentChatSendOptions extends AgentChatHandlers {
+    body: AgentChatRequestBody;
+    signal?: AbortSignal;
+}
+/** The settled result of a completed chat turn. */
+export interface AgentChatResult {
+    runId?: string;
+    threadId?: string;
+    parts: ChatPart[];
+}
+/**
+ * Thrown when a run's stream dropped and could not be resumed within the retry budget. Carries the
+ * partial parts received so far (and the ids) so a consumer can keep what streamed and surface a
+ * "couldn't finish, try again" state instead of losing the message.
+ */
+export declare class AgentChatDisconnectedError extends Error {
+    readonly runId: string | undefined;
+    readonly threadId: string | undefined;
+    readonly parts: ChatPart[];
+    constructor(runId: string | undefined, threadId: string | undefined, parts: ChatPart[]);
+}
+/**
+ * A framework-agnostic client for the agent chat SSE endpoints. `send` posts a turn and streams the
+ * reply; if the connection drops before the run finishes, it re-attaches to
+ * `GET {basePath}/chat/:runId/stream` — which replays the whole stream from the start and follows live
+ * — with backoff, until the run emits `done` or the retry budget is exhausted. The run itself is
+ * durable and keeps executing server-side across the drop, so no tokens are lost.
+ */
+export interface AgentChatClient {
+    send(options: AgentChatSendOptions): Promise<AgentChatResult>;
+    /** Re-attach to an already-started run (e.g. after a fresh page load) and stream it to completion. */
+    resume(runId: string, options?: AgentChatHandlers & {
+        signal?: AbortSignal;
+    }): Promise<AgentChatResult>;
+}
+export declare function createAgentChatClient(options?: AgentChatClientOptions): AgentChatClient;
+//# sourceMappingURL=chat-client.d.ts.map

package/dist/src/client/chat-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-client.d.ts","sourceRoot":"","sources":["../../../src/client/chat-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAwC,MAAM,UAAU,CAAC;AAE/F;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACxD,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;CACzB;AAED,iDAAiD;AACjD,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,kGAAkG;IAClG,MAAM,CAAC,EAAE,sBAAsB,GAAG,KAAK,CAAC;CACzC;AAED,6FAA6F;AAC7F,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACzC;AAED,gEAAgE;AAChE,MAAM,WAAW,iBAAiB;IAChC,8FAA8F;IAC9F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,IAAI,CAAC;IACtC,4DAA4D;IAC5D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACrC,mFAAmF;IACnF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,6CAA6C;IAC7C,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,iDAAiD;AACjD,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,IAAI,EAAE,oBAAoB,CAAC;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC;gBACf,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE;CAOvF;AAiCD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC9D,sGAAsG;IACtG,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,iBAAiB,GAAG;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACrD,OAAO,CAAC,eAAe,CAAC,CAAC;CAC7B;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,sBAA2B,GAAG,eAAe,CAmL3F"}

package/dist/src/client/chat-client.js

@@ -0,0 +1,204 @@
+import { decodeFrame, foldPart, readSseStream } from './sse.js';
+/**
+ * Thrown when a run's stream dropped and could not be resumed within the retry budget. Carries the
+ * partial parts received so far (and the ids) so a consumer can keep what streamed and surface a
+ * "couldn't finish, try again" state instead of losing the message.
+ */
+export class AgentChatDisconnectedError extends Error {
+    runId;
+    threadId;
+    parts;
+    constructor(runId, threadId, parts) {
+        super('The agent stream dropped and could not be resumed.');
+        this.name = 'AgentChatDisconnectedError';
+        this.runId = runId;
+        this.threadId = threadId;
+        this.parts = parts;
+    }
+}
+const DEFAULT_MAX_ATTEMPTS = 6;
+function defaultBackoff(attempt) {
+    return Math.min(400 * attempt, 3000);
+}
+/** An `AbortError`-shaped error without depending on `DOMException` (kept Node/browser portable). */
+function abortError() {
+    const error = new Error('Aborted');
+    error.name = 'AbortError';
+    return error;
+}
+function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortError());
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(abortError());
+        }, { once: true });
+    });
+}
+export function createAgentChatClient(options = {}) {
+    const basePath = (options.basePath ?? '/agent').replace(/\/$/, '');
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const resumeCfg = options.resume;
+    const maxAttempts = resumeCfg === false ? 0 : (resumeCfg?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
+    const backoff = (resumeCfg === false ? undefined : resumeCfg?.backoffMs) ?? defaultBackoff;
+    function headers(base) {
+        return { ...base, ...(options.getHeaders?.() ?? {}) };
+    }
+    /**
+     * Drains one SSE stream, folding renderable frames into a fresh parts array (a re-attach replays
+     * from the start, so rebuilding from `[]` yields the complete message without duplicating). Returns
+     * whether the stream ended with `done` (the run finished) vs. was cut short.
+     */
+    async function consume(body, sink) {
+        let parts = [];
+        for await (const event of readSseStream(body)) {
+            const frame = decodeFrame(event);
+            if (!frame) {
+                continue;
+            }
+            sink.handlers.onFrame?.(frame);
+            if (frame.type === 'done') {
+                return true;
+            }
+            if (frame.type === 'meta') {
+                if (frame.runId) {
+                    sink.handlers.onRunId?.(frame.runId);
+                }
+                if (frame.threadId) {
+                    sink.handlers.onThreadId?.(frame.threadId);
+                }
+                continue;
+            }
+            parts = foldPart(parts, frame);
+            sink.onParts(parts);
+        }
+        return false;
+    }
+    /**
+     * Runs the re-attach loop from a known `runId` until the run emits `done` or the retry budget is
+     * exhausted. Shared by `send` (after the POST drops) and `resume` (from a cold start).
+     */
+    async function reattach(runId, signal, sink) {
+        let attempt = 0;
+        let sawDone = false;
+        while (!sawDone && !signal?.aborted && attempt < maxAttempts) {
+            attempt += 1;
+            await delay(backoff(attempt), signal);
+            try {
+                const response = await fetchImpl(`${basePath}/chat/${runId}/stream`, {
+                    method: 'GET',
+                    credentials: 'include',
+                    ...(signal ? { signal } : {}),
+                    headers: headers({ Accept: 'text/event-stream' }),
+                });
+                if (!response.ok || !response.body) {
+                    continue;
+                }
+                attempt = 0; // Reconnected: reset the budget; only the next drop counts again.
+                sawDone = await consume(response.body, sink);
+            }
+            catch (error) {
+                if (signal?.aborted) {
+                    throw error;
+                }
+                // Dropped again — loop retries until the budget is spent.
+            }
+        }
+        return sawDone;
+    }
+    async function send(sendOptions) {
+        const { body, signal } = sendOptions;
+        let runId;
+        let threadId;
+        let lastParts = [];
+        const handlers = {
+            ...sendOptions,
+            onRunId: (id) => {
+                runId = id;
+                sendOptions.onRunId?.(id);
+            },
+            onThreadId: (id) => {
+                threadId = id;
+                sendOptions.onThreadId?.(id);
+            },
+        };
+        const onParts = (parts) => {
+            lastParts = parts;
+            sendOptions.onParts?.(parts);
+        };
+        const sink = { onParts, handlers };
+        const response = await fetchImpl(`${basePath}/chat`, {
+            method: 'POST',
+            credentials: 'include',
+            ...(signal ? { signal } : {}),
+            headers: headers({ 'Content-Type': 'application/json', Accept: 'text/event-stream' }),
+            body: JSON.stringify(body),
+        });
+        if (!response.ok || !response.body) {
+            throw new Error(`Failed to start agent chat (HTTP ${response.status}).`);
+        }
+        // The provider sets these before any byte; capture the runId now so a mid-stream drop (before the
+        // `meta` frame) can still re-attach.
+        const headerRunId = response.headers.get('X-Agent-Run-Id');
+        if (headerRunId) {
+            runId = headerRunId;
+            sendOptions.onRunId?.(headerRunId);
+        }
+        const headerThreadId = response.headers.get('X-Agent-Thread-Id');
+        if (headerThreadId) {
+            threadId = headerThreadId;
+            sendOptions.onThreadId?.(headerThreadId);
+        }
+        let sawDone;
+        try {
+            sawDone = await consume(response.body, sink);
+        }
+        catch (error) {
+            if (signal?.aborted) {
+                throw error;
+            }
+            sawDone = false; // Fall through to the re-attach loop instead of surfacing the drop as an error.
+        }
+        if (!sawDone && runId) {
+            sawDone = await reattach(runId, signal, sink);
+        }
+        if (!sawDone) {
+            throw new AgentChatDisconnectedError(runId, threadId, lastParts);
+        }
+        return {
+            parts: lastParts,
+            ...(runId !== undefined ? { runId } : {}),
+            ...(threadId !== undefined ? { threadId } : {}),
+        };
+    }
+    async function resume(runId, resumeOptions = {}) {
+        let threadId;
+        let lastParts = [];
+        const handlers = {
+            ...resumeOptions,
+            onThreadId: (id) => {
+                threadId = id;
+                resumeOptions.onThreadId?.(id);
+            },
+        };
+        const onParts = (parts) => {
+            lastParts = parts;
+            resumeOptions.onParts?.(parts);
+        };
+        const sawDone = await reattach(runId, resumeOptions.signal, { onParts, handlers });
+        if (!sawDone) {
+            throw new AgentChatDisconnectedError(runId, threadId, lastParts);
+        }
+        return {
+            runId,
+            parts: lastParts,
+            ...(threadId !== undefined ? { threadId } : {}),
+        };
+    }
+    return { send, resume };
+}
+//# sourceMappingURL=chat-client.js.map

package/dist/src/client/chat-client.js.map

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

package/dist/src/client/index.d.ts

@@ -0,0 +1,3 @@
+export { type ChatFrame, type ChatPart, type SseEvent, decodeFrame, foldPart, parseSseEvent, readSseStream, } from './sse.js';
+export { type AgentChatClient, type AgentChatClientOptions, type AgentChatHandlers, type AgentChatRequestBody, type AgentChatResult, type AgentChatResumeOptions, type AgentChatSendOptions, AgentChatDisconnectedError, createAgentChatClient, } from './chat-client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,WAAW,EACX,QAAQ,EACR,aAAa,EACb,aAAa,GACd,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/src/client/index.js

@@ -0,0 +1,3 @@
+export { decodeFrame, foldPart, parseSseEvent, readSseStream, } from './sse.js';
+export { AgentChatDisconnectedError, createAgentChatClient, } from './chat-client.js';
+//# sourceMappingURL=index.js.map

package/dist/src/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,WAAW,EACX,QAAQ,EACR,aAAa,EACb,aAAa,GACd,MAAM,UAAU,CAAC;AAClB,OAAO,EAQL,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/src/client/sse.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Client-side counterpart to {@link import('../sse.js').frameToSse}: parses the provider's SSE
+ * envelope back into typed frames the browser can render. Kept framework-agnostic (no React, no
+ * Adonis) so any consumer — a React hook, a Vue composable, a plain fetch loop — decodes the wire
+ * format the same way, and so the envelope stays owned by the package that emits it.
+ *
+ * Wire format (see `frameToSse` + the provider's `#pipe`):
+ * - `event: meta\ndata: {runId,threadId}`   — sent once, first, before any token
+ * - `data: {"delta":"..."}`                  — a text chunk (default event, no `event:` line)
+ * - `event: component\ndata: {name,data}`    — a rendered component
+ * - `event: done\ndata: {}`                  — the run's stream finished
+ */
+/** A rendered part of an assistant message: streamed text, or a named component with its props. */
+export type ChatPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'component';
+    name: string;
+    data: unknown;
+};
+/** A decoded stream frame — the typed form of one SSE event. */
+export type ChatFrame = {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'component';
+    name: string;
+    data: unknown;
+} | {
+    type: 'meta';
+    runId?: string;
+    threadId?: string;
+} | {
+    type: 'done';
+};
+/** One raw SSE event: the `event:` name (default `message`) and the joined `data:` payload. */
+export interface SseEvent {
+    event: string;
+    data: string;
+}
+/**
+ * Parses one raw SSE frame (the text between `\n\n` separators, without them) into `{event, data}`.
+ * A frame with no `data:` line (e.g. a `:` keep-alive comment) returns `null`.
+ */
+export declare function parseSseEvent(frame: string): SseEvent | null;
+/**
+ * Decodes a parsed {@link SseEvent} into a typed {@link ChatFrame}, or `null` when the payload is
+ * malformed (non-JSON, or missing required fields) so callers can skip it without crashing.
+ */
+export declare function decodeFrame(event: SseEvent): ChatFrame | null;
+/**
+ * Folds a renderable {@link ChatFrame} (text or component) into the message's parts, concatenating
+ * consecutive text deltas into the trailing text part and appending components in order. `meta`/`done`
+ * frames are control frames and are ignored here. Returns a new array (never mutates the input).
+ */
+export declare function foldPart(parts: ChatPart[], frame: ChatFrame): ChatPart[];
+/**
+ * Reads a byte {@link ReadableStream} (a `fetch` `response.body`) as a sequence of raw SSE events,
+ * splitting on the `\n\n` frame separator and buffering partial frames across chunks. Yields only
+ * frames that carry a `data:` payload (keep-alives are dropped).
+ */
+export declare function readSseStream(body: ReadableStream<Uint8Array>): AsyncGenerator<SseEvent>;
+//# sourceMappingURL=sse.d.ts.map

package/dist/src/client/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../../src/client/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,mGAAmG;AACnG,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEvD,gEAAgE;AAChE,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB,+FAA+F;AAC/F,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAc5D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,IAAI,CAsC7D;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,SAAS,GAAG,QAAQ,EAAE,CAYxE;AAED;;;;GAIG;AACH,wBAAuB,aAAa,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,cAAc,CAAC,QAAQ,CAAC,CAyB/F"}

package/dist/src/client/sse.js

@@ -0,0 +1,129 @@
+/**
+ * Client-side counterpart to {@link import('../sse.js').frameToSse}: parses the provider's SSE
+ * envelope back into typed frames the browser can render. Kept framework-agnostic (no React, no
+ * Adonis) so any consumer — a React hook, a Vue composable, a plain fetch loop — decodes the wire
+ * format the same way, and so the envelope stays owned by the package that emits it.
+ *
+ * Wire format (see `frameToSse` + the provider's `#pipe`):
+ * - `event: meta\ndata: {runId,threadId}`   — sent once, first, before any token
+ * - `data: {"delta":"..."}`                  — a text chunk (default event, no `event:` line)
+ * - `event: component\ndata: {name,data}`    — a rendered component
+ * - `event: done\ndata: {}`                  — the run's stream finished
+ */
+/**
+ * Parses one raw SSE frame (the text between `\n\n` separators, without them) into `{event, data}`.
+ * A frame with no `data:` line (e.g. a `:` keep-alive comment) returns `null`.
+ */
+export function parseSseEvent(frame) {
+    let event = 'message';
+    const dataLines = [];
+    for (const line of frame.split('\n')) {
+        if (line.startsWith('event:')) {
+            event = line.slice('event:'.length).trim();
+        }
+        else if (line.startsWith('data:')) {
+            dataLines.push(line.slice('data:'.length).trim());
+        }
+    }
+    if (dataLines.length === 0) {
+        return null;
+    }
+    return { event, data: dataLines.join('\n') };
+}
+/**
+ * Decodes a parsed {@link SseEvent} into a typed {@link ChatFrame}, or `null` when the payload is
+ * malformed (non-JSON, or missing required fields) so callers can skip it without crashing.
+ */
+export function decodeFrame(event) {
+    if (event.event === 'done') {
+        return { type: 'done' };
+    }
+    if (event.event === 'meta') {
+        try {
+            const parsed = JSON.parse(event.data);
+            return {
+                type: 'meta',
+                ...(typeof parsed?.runId === 'string' ? { runId: parsed.runId } : {}),
+                ...(typeof parsed?.threadId === 'string' ? { threadId: parsed.threadId } : {}),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    if (event.event === 'component') {
+        try {
+            const parsed = JSON.parse(event.data);
+            if (typeof parsed?.name !== 'string') {
+                return null;
+            }
+            return { type: 'component', name: parsed.name, data: parsed.data };
+        }
+        catch {
+            return null;
+        }
+    }
+    // Default event: a text delta.
+    try {
+        const parsed = JSON.parse(event.data);
+        const delta = parsed?.delta;
+        if (typeof delta !== 'string' || delta.length === 0) {
+            return null;
+        }
+        return { type: 'text', delta };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Folds a renderable {@link ChatFrame} (text or component) into the message's parts, concatenating
+ * consecutive text deltas into the trailing text part and appending components in order. `meta`/`done`
+ * frames are control frames and are ignored here. Returns a new array (never mutates the input).
+ */
+export function foldPart(parts, frame) {
+    if (frame.type === 'component') {
+        return [...parts, { type: 'component', name: frame.name, data: frame.data }];
+    }
+    if (frame.type === 'text') {
+        const last = parts[parts.length - 1];
+        if (last && last.type === 'text') {
+            return [...parts.slice(0, -1), { type: 'text', text: last.text + frame.delta }];
+        }
+        return [...parts, { type: 'text', text: frame.delta }];
+    }
+    return parts;
+}
+/**
+ * Reads a byte {@link ReadableStream} (a `fetch` `response.body`) as a sequence of raw SSE events,
+ * splitting on the `\n\n` frame separator and buffering partial frames across chunks. Yields only
+ * frames that carry a `data:` payload (keep-alives are dropped).
+ */
+export async function* readSseStream(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done) {
+                break;
+            }
+            buffer += decoder.decode(value, { stream: true });
+            let separatorIndex = buffer.indexOf('\n\n');
+            while (separatorIndex !== -1) {
+                const frame = buffer.slice(0, separatorIndex);
+                buffer = buffer.slice(separatorIndex + 2);
+                const parsed = parseSseEvent(frame);
+                if (parsed) {
+                    yield parsed;
+                }
+                separatorIndex = buffer.indexOf('\n\n');
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+//# sourceMappingURL=sse.js.map

package/dist/src/client/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../../src/client/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAoBH;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,KAAK,GAAG,SAAS,CAAC;IACtB,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QAC7C,CAAC;aAAM,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAe;IACzC,IAAI,KAAK,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;QAC3B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC1B,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAA4C,CAAC;YACjF,OAAO;gBACL,IAAI,EAAE,MAAM;gBACZ,GAAG,CAAC,OAAO,MAAM,EAAE,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACrE,GAAG,CAAC,OAAO,MAAM,EAAE,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC/E,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAuC,CAAC;YAC5E,IAAI,OAAO,MAAM,EAAE,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACrC,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,+BAA+B;IAC/B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAA+B,CAAC;QACpE,MAAM,KAAK,GAAG,MAAM,EAAE,KAAK,CAAC;QAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAiB,EAAE,KAAgB;IAC1D,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC/B,OAAO,CAAC,GAAG,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACrC,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACjC,OAAO,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QAClF,CAAC;QACD,OAAO,CAAC,GAAG,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,aAAa,CAAC,IAAgC;IACnE,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,CAAC;QACH,SAAS,CAAC;YACR,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI,EAAE,CAAC;gBACT,MAAM;YACR,CAAC;YACD,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAClD,IAAI,cAAc,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC5C,OAAO,cAAc,KAAK,CAAC,CAAC,EAAE,CAAC;gBAC7B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;gBAC9C,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC;gBAC1C,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;gBACpC,IAAI,MAAM,EAAE,CAAC;oBACX,MAAM,MAAM,CAAC;gBACf,CAAC;gBACD,cAAc,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,WAAW,EAAE,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.12.0";
+export declare const VERSION = "0.13.0";
 export * from './types.js';
 export * from './spi/tool.js';
 export * from './base-tool.js';

package/dist/src/index.js

@@ -1,4 +1,4 @@
-export const VERSION = '0.12.0';
+export const VERSION = '0.13.0';
 export * from './types.js';
 export * from './spi/tool.js';
 export * from './base-tool.js';

package/dist/src/react/index.d.ts

@@ -0,0 +1,2 @@
+export { type AgentChatMessage, type AgentChatStatus, type UseAgentChatOptions, type UseAgentChatResult, useAgentChat, } from './use-agent-chat.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,YAAY,GACb,MAAM,qBAAqB,CAAC"}

package/dist/src/react/index.js

@@ -0,0 +1,2 @@
+export { useAgentChat, } from './use-agent-chat.js';
+//# sourceMappingURL=index.js.map

package/dist/src/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,YAAY,GACb,MAAM,qBAAqB,CAAC"}

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

@@ -0,0 +1,33 @@
+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

@@ -0,0 +1 @@
+{"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,CAgHlF"}

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

@@ -0,0 +1,103 @@
+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 {
+            await clientRef.current.send({
+                body,
+                signal: controller.signal,
+                onParts: applyParts,
+                onThreadId: (id) => {
+                    threadIdRef.current = id;
+                },
+            });
+            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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/agent",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {
@@ -77,6 +77,16 @@
       "types": "./dist/src/telescope/index.d.ts",
       "import": "./dist/src/telescope/index.js",
       "default": "./dist/src/telescope/index.js"
+    },
+    "./client": {
+      "types": "./dist/src/client/index.d.ts",
+      "import": "./dist/src/client/index.js",
+      "default": "./dist/src/client/index.js"
+    },
+    "./react": {
+      "types": "./dist/src/react/index.d.ts",
+      "import": "./dist/src/react/index.js",
+      "default": "./dist/src/react/index.js"
     }
   },
   "files": [
@@ -99,9 +109,13 @@
     "@adonisjs/redis": "^9.2.0",
     "ai": "^7.0.0",
     "node-sql-parser": "^5.3.0",
+    "react": "^18.0.0 || ^19.0.0",
     "zod": "^3.23.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
     "node-sql-parser": {
       "optional": true
     },
@@ -142,10 +156,12 @@
     "@adonisjs/core": "^7.3.0",
     "@adonisjs/lucid": "^22.4.0",
     "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
     "ai": "^7.0.0",
     "better-sqlite3": "^11.0.0",
     "luxon": "^3.4.0",
     "node-sql-parser": "^5.3.0",
+    "react": "^19.0.0",
     "typescript": "^5.4.0",
     "vitest": "^3.0.0",
     "zod": "^3.25.0"