@adonis-agora/agent 0.61.0 → 0.62.0

package/dist/src/react/core/catalog/use-agents.js

@@ -0,0 +1,28 @@
+import { useCallback, useMemo } from 'react';
+import { requireBackendMethod } from '../backend.js';
+import { useAgentBackend } from '../provider.js';
+import { useResource } from './use-resource.js';
+/**
+ * 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 function useAgents(options = {}) {
+    const { enabled = true } = options;
+    const backend = useAgentBackend(options.backend);
+    const { data, isLoading, error, refresh } = useResource(() => requireBackendMethod(backend, 'listAgents')(), '', enabled);
+    const find = useCallback((name) => (data ?? []).find((agent) => name === undefined ? agent.isDefault === true : agent.name === name), [data]);
+    return useMemo(() => {
+        const agents = data ?? [];
+        return {
+            agents,
+            defaultAgent: agents.find((agent) => agent.isDefault === true)?.name ?? null,
+            personasOf: (agent) => find(agent)?.personas ?? [],
+            defaultPersonaOf: (agent) => find(agent)?.defaultPersona ?? null,
+            isLoading,
+            error,
+            refresh,
+        };
+    }, [data, find, isLoading, error, refresh]);
+}
+//# sourceMappingURL=use-agents.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-agents.js","sourceRoot":"","sources":["../../../../../src/react/core/catalog/use-agents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAE7C,OAAO,EAAqB,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA0BhD;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,OAAO,GAAqB,EAAE;IACtD,MAAM,EAAE,OAAO,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACnC,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,WAAW,CACrD,GAAG,EAAE,CAAC,oBAAoB,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,EACnD,EAAE,EACF,OAAO,CACR,CAAC;IACF,MAAM,IAAI,GAAG,WAAW,CACtB,CAAC,IAAa,EAAiC,EAAE,CAC/C,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAC1B,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CACpE,EACH,CAAC,IAAI,CAAC,CACP,CAAC;IACF,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,MAAM,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QAC1B,OAAO;YACL,MAAM;YACN,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC,EAAE,IAAI,IAAI,IAAI;YAC5E,UAAU,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,QAAQ,IAAI,EAAE;YAC3D,gBAAgB,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,cAAc,IAAI,IAAI;YACzE,SAAS;YACT,KAAK;YACL,OAAO;SACR,CAAC;IACJ,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AAC9C,CAAC"}

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

@@ -0,0 +1,41 @@
+import type { ModelCatalogEntry, ModelCatalogLock, ModelCatalogView } from '../../../spi/model-catalog.js';
+import { type AgentBackend } from '../backend.js';
+export interface UseModelsOptions {
+    /** Default: the enclosing `<AgentProvider>`'s. Must implement `listModels`. */
+    backend?: AgentBackend;
+    /** The agent to list models for; omitted → the default agent. */
+    agent?: string;
+    /** `false` holds the request. Default `true`. */
+    enabled?: boolean;
+}
+/** A catalog entry with the provider it sits under, for a flat list or a search. */
+export interface ModelOption extends ModelCatalogEntry {
+    providerId: string;
+    providerLabel: string;
+}
+export interface ModelsState {
+    /** Grouped as the server sent them. `[]` until loaded. */
+    providers: ModelCatalogView['providers'];
+    /** Every model, flattened in provider order. */
+    models: ModelOption[];
+    /** The model a turn runs on when none is picked, or `null` when the provider decides. */
+    defaultModel: string | null;
+    /**
+     * The agent always runs on one model (`{ model, reason? }`), or `null`. A picker shows it
+     * read-only: the server runs every turn on it and refuses any other.
+     */
+    locked: ModelCatalogLock | null;
+    /** The entry for `id`, or `undefined`. */
+    find: (id: string | null | undefined) => ModelOption | undefined;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * The models this caller may pick (`GET <base>/models?agent=`), with badges and availability — the
+ * data behind a model picker. Headless: render the options however you like, then send the pick
+ * as `useAgentChat({ model })` or `sendMessage(msg, { body: { model } })` (that turn only), or
+ * pin it on the thread with `chat.models.pinToThread(id)`.
+ */
+export declare function useModels(options?: UseModelsOptions): ModelsState;
+//# sourceMappingURL=use-models.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-models.d.ts","sourceRoot":"","sources":["../../../../../src/react/core/catalog/use-models.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,KAAK,YAAY,EAAwB,MAAM,eAAe,CAAC;AAIxE,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,oFAAoF;AACpF,MAAM,WAAW,WAAY,SAAQ,iBAAiB;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,gDAAgD;IAChD,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,yFAAyF;IACzF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;OAGG;IACH,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAChC,0CAA0C;IAC1C,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,KAAK,WAAW,GAAG,SAAS,CAAC;IACjE,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,WAAW,CA6BrE"}

package/dist/src/react/core/catalog/use-models.js

@@ -0,0 +1,35 @@
+import { useMemo } from 'react';
+import { requireBackendMethod } from '../backend.js';
+import { useAgentBackend } from '../provider.js';
+import { useResource } from './use-resource.js';
+/**
+ * The models this caller may pick (`GET <base>/models?agent=`), with badges and availability — the
+ * data behind a model picker. Headless: render the options however you like, then send the pick
+ * as `useAgentChat({ model })` or `sendMessage(msg, { body: { model } })` (that turn only), or
+ * pin it on the thread with `chat.models.pinToThread(id)`.
+ */
+export function useModels(options = {}) {
+    const { agent, enabled = true } = options;
+    const backend = useAgentBackend(options.backend);
+    const { data, isLoading, error, refresh } = useResource(() => requireBackendMethod(backend, 'listModels')(agent), `${agent ?? ''}`, enabled);
+    return useMemo(() => {
+        const providers = data?.providers ?? [];
+        const models = providers.flatMap((provider) => provider.models.map((model) => ({
+            ...model,
+            providerId: provider.id,
+            providerLabel: provider.label,
+        })));
+        const byId = new Map(models.map((model) => [model.id, model]));
+        return {
+            providers,
+            models,
+            defaultModel: data?.default ?? null,
+            locked: data?.locked ?? null,
+            find: (id) => (id == null ? undefined : byId.get(id)),
+            isLoading,
+            error,
+            refresh,
+        };
+    }, [data, isLoading, error, refresh]);
+}
+//# sourceMappingURL=use-models.js.map

package/dist/src/react/core/catalog/use-models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-models.js","sourceRoot":"","sources":["../../../../../src/react/core/catalog/use-models.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAMhC,OAAO,EAAqB,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAoChD;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,OAAO,GAAqB,EAAE;IACtD,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAC1C,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,WAAW,CACrD,GAAG,EAAE,CAAC,oBAAoB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,KAAK,CAAC,EACxD,GAAG,KAAK,IAAI,EAAE,EAAE,EAChB,OAAO,CACR,CAAC;IACF,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,MAAM,SAAS,GAAG,IAAI,EAAE,SAAS,IAAI,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAC5C,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAC9B,GAAG,KAAK;YACR,UAAU,EAAE,QAAQ,CAAC,EAAE;YACvB,aAAa,EAAE,QAAQ,CAAC,KAAK;SAC9B,CAAC,CAAC,CACJ,CAAC;QACF,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;QAC/D,OAAO;YACL,SAAS;YACT,MAAM;YACN,YAAY,EAAE,IAAI,EAAE,OAAO,IAAI,IAAI;YACnC,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,IAAI;YAC5B,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACrD,SAAS;YACT,KAAK;YACL,OAAO;SACR,CAAC;IACJ,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AACxC,CAAC"}

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

@@ -0,0 +1,12 @@
+export interface ResourceState<T> {
+    data: T | undefined;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * One read, re-run when `key` changes, with only the newest response allowed to land. The shared
+ * shape behind `useModels` / `useAgents`.
+ */
+export declare function useResource<T>(load: () => Promise<T>, key: string, enabled: boolean): ResourceState<T>;
+//# sourceMappingURL=use-resource.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-resource.d.ts","sourceRoot":"","sources":["../../../../../src/react/core/catalog/use-resource.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,OAAO,GACf,aAAa,CAAC,CAAC,CAAC,CA+BlB"}

package/dist/src/react/core/catalog/use-resource.js

@@ -0,0 +1,41 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * One read, re-run when `key` changes, with only the newest response allowed to land. The shared
+ * shape behind `useModels` / `useAgents`.
+ */
+export function useResource(load, key, enabled) {
+    const [data, setData] = useState(undefined);
+    const [isLoading, setIsLoading] = useState(enabled);
+    const [error, setError] = useState(null);
+    const loadRef = useRef(load);
+    loadRef.current = load;
+    const generation = useRef(0);
+    const refresh = useCallback(async () => {
+        const mine = ++generation.current;
+        setIsLoading(true);
+        try {
+            const value = await loadRef.current();
+            if (mine !== generation.current)
+                return;
+            setData(value);
+            setError(null);
+        }
+        catch (caught) {
+            if (mine !== generation.current)
+                return;
+            setError(caught instanceof Error ? caught : new Error(String(caught)));
+        }
+        finally {
+            if (mine === generation.current)
+                setIsLoading(false);
+        }
+    }, []);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: `key` names what `load` reads
+    useEffect(() => {
+        if (!enabled)
+            return;
+        void refresh();
+    }, [enabled, key, refresh]);
+    return { data, isLoading, error, refresh };
+}
+//# sourceMappingURL=use-resource.js.map

package/dist/src/react/core/catalog/use-resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-resource.js","sourceRoot":"","sources":["../../../../../src/react/core/catalog/use-resource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AASjE;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,IAAsB,EACtB,GAAW,EACX,OAAgB;IAEhB,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAgB,SAAS,CAAC,CAAC;IAC3D,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IACpD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IACvB,MAAM,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAE7B,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,IAAmB,EAAE;QACpD,MAAM,IAAI,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC;QAClC,YAAY,CAAC,IAAI,CAAC,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;YACtC,IAAI,IAAI,KAAK,UAAU,CAAC,OAAO;gBAAE,OAAO;YACxC,OAAO,CAAC,KAAK,CAAC,CAAC;YACf,QAAQ,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;QAAC,OAAO,MAAM,EAAE,CAAC;YAChB,IAAI,IAAI,KAAK,UAAU,CAAC,OAAO;gBAAE,OAAO;YACxC,QAAQ,CAAC,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACzE,CAAC;gBAAS,CAAC;YACT,IAAI,IAAI,KAAK,UAAU,CAAC,OAAO;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QACvD,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,yFAAyF;IACzF,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,KAAK,OAAO,EAAE,CAAC;IACjB,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;IAE5B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC7C,CAAC"}

package/dist/src/react/core/client-wire.d.ts

@@ -0,0 +1,14 @@
+import type { StoredMessage as DomainStoredMessage, AgentStreamEvent as DomainStreamEvent, ToolCallRequest as DomainToolCallRequest } from '../../index.js';
+/** Optional protocol fields accepted from compatible custom backends; no persistence is implied. */
+export interface ToolCallRequest extends DomainToolCallRequest {
+    parentId?: string;
+}
+export interface StoredMessage extends Omit<DomainStoredMessage, 'toolCalls'> {
+    toolCalls?: ToolCallRequest[];
+    metadata?: Record<string, unknown>;
+}
+export type AgentStreamEvent = DomainStreamEvent | {
+    kind: 'message-metadata';
+    metadata: Record<string, unknown>;
+};
+//# sourceMappingURL=client-wire.d.ts.map

package/dist/src/react/core/client-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-wire.d.ts","sourceRoot":"","sources":["../../../../src/react/core/client-wire.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,IAAI,mBAAmB,EACpC,gBAAgB,IAAI,iBAAiB,EACrC,eAAe,IAAI,qBAAqB,EACzC,MAAM,gBAAgB,CAAC;AAExB,oGAAoG;AACpG,MAAM,WAAW,eAAgB,SAAQ,qBAAqB;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC;IAC3E,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AACD,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC"}

package/dist/src/react/core/client-wire.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client-wire.js.map

package/dist/src/react/core/client-wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-wire.js","sourceRoot":"","sources":["../../../../src/react/core/client-wire.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,222 @@
+import type { ActionProposal, ActionProposalMutationResult, AgentCatalogEntry, AgentClientConfig, ChatQueueState, MessageAttachment, MessageFeedback, ModelCatalogView, QuotaReport, SkillCatalogEntry, ThreadDetail, ThreadSummary, ToolCatalogEntry } from '../../index.js';
+import type { AgentBackend, AttachmentUploadStrategy, ChatStreamRequest, ChatStreamResponse, MessageFeedbackInput, QueuedMessageUpdate, QueuedSendResult, ResumeStreamRequest, ThreadPatch, UploadAttachmentOptions } from './backend.js';
+import { type AgentRequestError, type ErrorAnswer, type HttpErrorListener } from './http-error.js';
+export type { ThreadPatch } from './backend.js';
+export type { AgentRequestError, HttpErrorListener } from './http-error.js';
+/**
+ * Thrown by {@link AgentClient} on a non-2xx response. Carries the HTTP `status` so callers can
+ * branch (e.g. 403 → "not your thread", 429 → quota) instead of string-matching a generic Error,
+ * and what the server said: `message` is the body's `message` when it sent one (so a hook that
+ * shows `error.message` shows the server's words), `code` its machine-readable `code`, and `body`
+ * the whole answer, parsed when it is JSON.
+ */
+export declare class AgentHttpError extends Error implements AgentRequestError {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    /** The answer's body: parsed JSON, else its text; `undefined` when empty. */
+    readonly body: unknown;
+    /** The body's `code` (`quota_exceeded`, …), when the server sent one. */
+    readonly code: string | undefined;
+    constructor(status: number, method: string, path: string, statusText: string, answer?: ErrorAnswer);
+    /** Read a refused `response`'s body into an error. */
+    static from(response: Response, method: string, path: string): Promise<AgentHttpError>;
+}
+export interface CancelResult {
+    aborted: boolean;
+}
+export interface OkResult {
+    ok: boolean;
+}
+export interface AgentClientOptions {
+    /**
+     * The server's origin, e.g. `https://api.example.com`. Defaults to `''` (same origin). The
+     * agent's route prefix is {@link AgentClientOptions.path}, not part of this.
+     */
+    baseUrl?: string;
+    /**
+     * The agent's route prefix — `AgentModule`'s `path`, with any global prefix in front
+     * (`'api/agent'`). Leading/trailing slashes are optional. Defaults to `'agent'`.
+     */
+    path?: string;
+    /** Static headers merged into every request. */
+    headers?: Record<string, string>;
+    /**
+     * Resolved per request — for short-lived bearer tokens, or a CSRF header read from a cookie
+     * (`{ 'X-XSRF-TOKEN': readCookie('XSRF-TOKEN') }`), which has to be read at request time because
+     * the server may rotate it.
+     */
+    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    /**
+     * Forwarded to fetch so cookie auth works. Same-origin requests send cookies by default; set
+     * `'include'` when the API lives on another origin (and have it answer with credentialed CORS).
+     */
+    credentials?: RequestCredentials;
+    /** Injectable for tests / non-browser runtimes. */
+    fetch?: typeof fetch;
+    /**
+     * Called with every error answer (an {@link AgentHttpError}, or a `MediaUploadError` from a
+     * `mediaAttachments()` upload) right before it is thrown — the place for app-wide reactions such
+     * as "401 → sign in again". The error still reaches the caller. Not called for the `404` a
+     * resume answers when nothing is streaming, which is an answer, not a failure.
+     */
+    onHttpError?: HttpErrorListener;
+    /** Attachment uploads. */
+    attachments?: {
+        /**
+         * How `uploadAttachment` uploads. Omitted → `POST <path>/attachments` (multipart). Pass
+         * `mediaAttachments()` from `@adonis-agora/agent/react/media` for resumable uploads through
+         * @adonis-agora/media, or your own {@link AttachmentUploadStrategy}.
+         */
+        upload?: AttachmentUploadStrategy;
+    };
+}
+/** `'/api/agent'` from `'api/agent'`, `'/api/agent/'`, …; `''` for an empty path. */
+export declare function normalizeAgentPath(path: string | undefined): string;
+/**
+ * Framework-agnostic REST client for the Adonis agent endpoints — the default {@link AgentBackend}.
+ * Used by `useAgentChat`, but standalone-usable (vanilla fetch, no React).
+ */
+export declare class AgentClient implements AgentBackend {
+    private readonly options;
+    constructor(options?: AgentClientOptions);
+    /** `POST <path>/chat` → the turn's SSE stream. Throws {@link AgentHttpError} on a non-2xx. */
+    openChatStream(request: ChatStreamRequest): Promise<ChatStreamResponse>;
+    /**
+     * `POST <path>/chat` for a message that should wait in the thread's queue — the body carries
+     * `mode: 'queue'` (or `'interrupt'`), which the server always answers with `202` JSON.
+     */
+    enqueueMessage(request: ChatStreamRequest): Promise<QueuedSendResult>;
+    /** `GET <path>/threads/:id/queue` — the thread's waiting messages, and whether it drains. */
+    getQueue(threadId: string): Promise<ChatQueueState>;
+    /** `PATCH <path>/queue/:messageId` — change a waiting message's text/attachments, or move it. */
+    updateQueuedMessage(messageId: string, update: QueuedMessageUpdate): Promise<ChatQueueState>;
+    /** `DELETE <path>/queue/:messageId`. */
+    removeQueuedMessage(messageId: string): Promise<ChatQueueState>;
+    /**
+     * `POST <path>/queue/:messageId/interrupt` — run a waiting message now, cancelling the running
+     * turn for it. `runId` when nothing was running and it started; else `interrupting`.
+     */
+    interruptQueuedMessage(messageId: string): Promise<ChatQueueState & {
+        runId?: string;
+        interrupting?: string;
+    }>;
+    /** `DELETE <path>/threads/:id/queue` — drop every waiting message. */
+    clearQueue(threadId: string): Promise<ChatQueueState>;
+    /** `POST <path>/threads/:id/queue/resume` — lift a pause; `runId` when the head started. */
+    resumeQueue(threadId: string): Promise<ChatQueueState & {
+        runId?: string;
+    }>;
+    /**
+     * `GET <path>/chat/:runId/stream[?after=<seq>]` → the run's SSE stream, or `null` when nothing is
+     * streaming under that id (404).
+     */
+    resumeChatStream(request: ResumeStreamRequest): Promise<ChatStreamResponse | null>;
+    /**
+     * Rate a message (`'up'`/`'down'`, optional comment) or clear its rating (`value: null`). Answers
+     * the stored rating.
+     */
+    setMessageFeedback(messageId: string, input: MessageFeedbackInput): Promise<{
+        feedback: MessageFeedback | null;
+    }>;
+    listThreads(): Promise<ThreadSummary[]>;
+    /**
+     * The skills this caller can invoke right now, scope-resolved — the same list, built by the same
+     * call, that the model is offered, so what a user can type after a `/` and what the agent can
+     * reach cannot drift apart. `threadId` reaches the host's own resolver, which may scope a skill to
+     * one conversation; omitted, the server reads it as a brand-new thread.
+     */
+    listSkills(threadId?: string): Promise<SkillCatalogEntry[]>;
+    /**
+     * The tools this caller can reach through `agent` (the default agent when omitted), each with the
+     * server-declared `presentation` a chat narrates it by — the same list the model is offered.
+     * Prefer {@link useToolCatalog}, which fetches it once and shares it.
+     */
+    listTools(agent?: string): Promise<ToolCatalogEntry[]>;
+    getThread(id: string): Promise<ThreadDetail>;
+    deleteThread(id: string): Promise<void>;
+    forkFromMessage(threadId: string, messageId: string): Promise<ThreadSummary>;
+    /** General `PATCH <path>/threads/:threadId` — title and/or the thread's pinned default agent. */
+    updateThread(id: string, patch: ThreadPatch): Promise<OkResult>;
+    /**
+     * Uploads a file (image/PDF) for a vision-capable model turn. Multipart, field name `file` —
+     * mirrors the backend's `POST <path>/attachments`. The returned {@link MessageAttachment} is
+     * what a caller then rides on `sendMessage({ text }, { body: { attachments: [...] } })`.
+     */
+    uploadAttachment(file: File, options?: UploadAttachmentOptions): Promise<MessageAttachment>;
+    private uploadWithProgress;
+    promoteThread(id: string): Promise<OkResult>;
+    truncateFromMessage(threadId: string, messageId: string): Promise<OkResult>;
+    /** `GET <path>/models?agent=` — the models this caller may pick, grouped by provider. */
+    listModels(agent?: string): Promise<ModelCatalogView>;
+    /** `GET <path>/agents` — the registered agents, the default one flagged. */
+    listAgents(): Promise<AgentCatalogEntry[]>;
+    /** `GET <path>/config` — attachment limits and upload mode, and which features are on. */
+    getConfig(): Promise<AgentClientConfig>;
+    /** `GET <path>/quota` — the caller's budget windows and the one blocking sends, if any. */
+    getQuota(): Promise<QuotaReport>;
+    cancelStream(runId: string): Promise<CancelResult>;
+    /**
+     * `remember` approves later calls of the same tool in the same thread; `via` names the surface
+     * the decision came through (the server records `'web'` when omitted).
+     */
+    listActionProposals({ threadId }: {
+        threadId: string;
+    }): Promise<ActionProposal[]>;
+    approveActionProposal({ threadId, proposalId, remember, }: {
+        threadId: string;
+        proposalId: string;
+        remember?: boolean;
+    }): Promise<ActionProposalMutationResult>;
+    rejectActionProposal({ threadId, proposalId, reason, }: {
+        threadId: string;
+        proposalId: string;
+        reason?: string;
+    }): Promise<ActionProposalMutationResult>;
+    approveToolCall(input: {
+        toolCallId: string;
+        remember?: boolean;
+        via?: string;
+    }): Promise<void>;
+    rejectToolCall(input: {
+        toolCallId: string;
+        reason?: string;
+        via?: string;
+    }): Promise<void>;
+    /**
+     * Settle a parked question set. `answers` is questionId → chosen option values; a question left
+     * out takes the pre-picked default the request carried, resolved server-side against the request
+     * the run already holds. Omit the whole object and the user has confirmed every pre-picked
+     * answer — which is the point of the surface, so it is a valid submission rather than a blank.
+     * `via` names the surface the answer came through (the server records `'web'` when omitted).
+     */
+    answerToolCall(input: {
+        toolCallId: string;
+        answers?: Record<string, string[]>;
+        via?: string;
+    }): Promise<void>;
+    /**
+     * Decline to answer and let the agent proceed on its own pre-picked values. Lands on the same
+     * values a confirmation would, and persists differently on purpose — only one of them is
+     * evidence the user chose them.
+     */
+    skipToolCall(input: {
+        toolCallId: string;
+        via?: string;
+    }): Promise<void>;
+    private fetchImpl;
+    /** This client's connection, for an {@link AttachmentUploadStrategy}. */
+    private connection;
+    private baseUrl;
+    private agentPath;
+    /** Origin + agent path: what every route hangs off. */
+    private root;
+    private resolveHeaders;
+    private credentials;
+    private request;
+    private requestResponse;
+    /** The error for a refused `response`, already reported to `onHttpError`. */
+    private failure;
+    private handleResponse;
+}
+//# sourceMappingURL=client.d.ts.map

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

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