@adonis-agora/agent 0.61.0 → 0.62.0

package/dist/src/react/core/presentation/tool-activity.js

@@ -0,0 +1,165 @@
+import { getToolName } from 'ai';
+import { fillTemplate, phraseFor } from './phrasing.js';
+import { resolveResultView } from './result-view.js';
+/** Whether the stream classified this call as an `action` (it parks for approval before it runs). */
+export function isActionCall(part) {
+    const metadata = part.toolMetadata;
+    return (typeof metadata === 'object' &&
+        metadata !== null &&
+        metadata.toolKind === 'action');
+}
+export function toolCallState(part) {
+    const output = 'output' in part ? part.output : undefined;
+    if (output !== null &&
+        typeof output === 'object' &&
+        'proposalId' in output &&
+        'executed' in output &&
+        output.executed === false)
+        return {
+            status: 'awaiting-approval',
+            isSettled: false,
+            isFailed: false,
+            isDenied: false,
+            output,
+            error: null,
+        };
+    const errorText = 'errorText' in part ? part.errorText : undefined;
+    const outputError = output !== null && typeof output === 'object' && 'error' in output
+        ? String(output.error)
+        : undefined;
+    const isDenied = part.state === 'output-denied';
+    const isFailed = part.state === 'output-error' || (outputError !== undefined && !isDenied);
+    const isSettled = part.state === 'output-available' || part.state === 'output-error' || isDenied;
+    const isAwaiting = part.state === 'approval-requested' || (part.state === 'input-available' && isActionCall(part));
+    const status = isDenied
+        ? 'denied'
+        : isFailed
+            ? 'failed'
+            : isSettled
+                ? 'done'
+                : isAwaiting
+                    ? 'awaiting-approval'
+                    : 'running';
+    return {
+        status,
+        isSettled,
+        isFailed,
+        isDenied,
+        output,
+        error: errorText ?? outputError ?? null,
+    };
+}
+/**
+ * Which failed calls the model went on to correct, by call id: a call that failed and was followed,
+ * in the same run, by a SUCCESS of the same tool. The operator wants to know a retry happened, not
+ * to read every attempt. A failed read is not corrected by a successful query.
+ */
+export function correctedCallIds(parts) {
+    const corrected = new Set();
+    const lastSuccessByTool = new Map();
+    parts.forEach((part, index) => {
+        if (part.state === 'output-available' && !toolCallState(part).isFailed) {
+            lastSuccessByTool.set(getToolName(part), index);
+        }
+    });
+    parts.forEach((part, index) => {
+        const successAt = lastSuccessByTool.get(getToolName(part));
+        if (successAt !== undefined && index < successAt && toolCallState(part).isFailed) {
+            corrected.add(part.toolCallId);
+        }
+    });
+    return corrected;
+}
+export function describeToolCall(part, catalog, options = {}) {
+    const presentation = catalog?.[getToolName(part)];
+    const state = toolCallState(part);
+    const input = part.input;
+    const confirm = presentation?.confirm;
+    return {
+        status: state.status,
+        phrase: phraseFor(presentation, input, state.isSettled, options.fallback),
+        label: presentation?.label ?? null,
+        icon: presentation?.icon ?? null,
+        tone: presentation?.tone ?? 'neutral',
+        detail: presentation?.detail ?? null,
+        confirm: options.confirmation !== undefined
+            ? {
+                title: options.confirmation.title,
+                verb: options.confirmation.verb,
+                detail: options.confirmation.detail ?? null,
+            }
+            : confirm === undefined
+                ? null
+                : {
+                    title: fillTemplate(confirm.title, input),
+                    verb: confirm.verb,
+                    detail: confirm.detail !== undefined ? fillTemplate(confirm.detail, input) : null,
+                },
+        result: state.status === 'done'
+            ? resolveResultView(state.output, presentation?.result, {
+                ...(options.inferResult !== undefined ? { infer: options.inferResult } : {}),
+            })
+            : null,
+        error: state.error,
+        presentation: presentation ?? null,
+    };
+}
+const STATUS_WEIGHT = {
+    running: 4,
+    queued: 4,
+    executing: 4,
+    succeeded: 0,
+    'awaiting-approval': 3,
+    failed: 2,
+    denied: 1,
+    done: 0,
+};
+function descendants(call) {
+    return call.children.flatMap((child) => [child, ...descendants(child)]);
+}
+function leaves(call) {
+    return call.children.length === 0 ? [call] : call.children.flatMap(leaves);
+}
+/**
+ * Fold a tool run into activity groups, in order of first appearance. Pass `block.roots` (the
+ * transcript's call tree) so nesting is honoured; a flat `block.calls` works too and simply has
+ * nothing nested.
+ */
+export function groupToolActivity(calls, options = {}) {
+    const expanded = options.expandNested === true ? calls.flatMap(leaves) : [...calls];
+    const corrected = options.hideCorrected === true
+        ? correctedCallIds(expanded.map((call) => call.part))
+        : new Set();
+    const groups = new Map();
+    for (const call of expanded) {
+        if (corrected.has(call.toolCallId))
+            continue;
+        const presentation = options.catalog?.[call.name];
+        const key = options.keyOf?.(call, presentation) ?? presentation?.label ?? call.name;
+        const status = call.description.status;
+        const phrase = phraseFor(presentation, call.part.input, status !== 'running' && status !== 'awaiting-approval', options.fallback);
+        const inner = options.expandNested === true ? 0 : descendants(call).length;
+        const existing = groups.get(key);
+        if (existing === undefined) {
+            groups.set(key, {
+                key,
+                label: presentation?.label ?? null,
+                icon: presentation?.icon ?? null,
+                status,
+                count: 1,
+                phrase,
+                calls: [call],
+                innerCount: inner,
+            });
+            continue;
+        }
+        existing.count += 1;
+        existing.calls.push(call);
+        existing.phrase = phrase;
+        existing.innerCount += inner;
+        if (STATUS_WEIGHT[status] > STATUS_WEIGHT[existing.status])
+            existing.status = status;
+    }
+    return [...groups.values()];
+}
+//# sourceMappingURL=tool-activity.js.map

package/dist/src/react/core/presentation/tool-activity.js.map

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

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

@@ -0,0 +1,39 @@
+import type { ToolCatalogEntry } from '../../../index.js';
+import { ALL_AGENTS } from '../../../tool-presentation.js';
+export { ALL_AGENTS };
+import { type AgentBackend } from '../backend.js';
+import { type ToolCatalog } from './phrasing.js';
+/** What the catalog needs of a backend. */
+type ToolsBackend = Pick<AgentBackend, 'listTools'>;
+export interface UseToolCatalogOptions {
+    /**
+     * The backend to ask. Default: the enclosing `<AgentProvider>`'s. Must be STABLE across renders
+     * (the shared copy is keyed by it): a backend constructed inline refetches every render.
+     */
+    backend?: ToolsBackend;
+    /**
+     * The agent whose tools to list. Omitted → the server's default agent. {@link ALL_AGENTS} (`'*'`)
+     * → every tool the actor reaches through any agent, each once — for an app with several agents
+     * whose conversations one surface shows.
+     */
+    agent?: string;
+    /** `false` holds the request (e.g. until the user is signed in). Default `true`. */
+    enabled?: boolean;
+}
+export interface ToolCatalogState {
+    /** Tool name → presentation, for the tools that declared one. `{}` until loaded. */
+    catalog: ToolCatalog;
+    /** Everything `GET <base>/tools` returned, kinds included. */
+    entries: ToolCatalogEntry[];
+    isLoading: boolean;
+    error: Error | null;
+    /** Drop the shared copy and ask again. */
+    refresh: () => void;
+}
+/**
+ * The server-declared presentation of the tools this actor can reach (`GET <base>/tools`), for
+ * `phraseFor`, `describeToolCall` and `groupToolActivity` — or pass `catalog` to
+ * `useChatTranscript({ toolCatalog })` and read the phrases off the transcript's calls.
+ */
+export declare function useToolCatalog(options?: UseToolCatalogOptions): ToolCatalogState;
+//# sourceMappingURL=use-tool-catalog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-tool-catalog.d.ts","sourceRoot":"","sources":["../../../../../src/react/core/presentation/use-tool-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAE3D,OAAO,EAAE,UAAU,EAAE,CAAC;AAGtB,OAAO,EAAE,KAAK,YAAY,EAAgC,MAAM,eAAe,CAAC;AAEhF,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,eAAe,CAAC;AAElE,2CAA2C;AAC3C,KAAK,YAAY,GAAG,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;AAEpD,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,oFAAoF;IACpF,OAAO,EAAE,WAAW,CAAC;IACrB,8DAA8D;IAC9D,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AA8BD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,gBAAgB,CAyCpF"}

package/dist/src/react/core/presentation/use-tool-catalog.js

@@ -0,0 +1,77 @@
+import { ALL_AGENTS } from '../../../tool-presentation.js';
+export { ALL_AGENTS };
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { AgentBackendUnsupportedError } from '../backend.js';
+import { useAgentBackend } from '../provider.js';
+import { toolCatalogFrom } from './phrasing.js';
+/**
+ * One request per backend + agent for the whole page: the catalog is a deployment-time constant, so
+ * every component that narrates a tool call can call this hook and share the answer instead of
+ * putting a request between a tool starting and the sentence that describes it. A failed request
+ * is not cached, so the next mount retries.
+ */
+const shared = new WeakMap();
+function load(client, agent) {
+    let byAgent = shared.get(client);
+    if (byAgent === undefined) {
+        byAgent = new Map();
+        shared.set(client, byAgent);
+    }
+    const key = agent ?? '';
+    const cached = byAgent.get(key);
+    if (cached !== undefined)
+        return cached;
+    if (client.listTools === undefined) {
+        return Promise.reject(new AgentBackendUnsupportedError('listTools'));
+    }
+    const request = client.listTools(agent).catch((error) => {
+        byAgent.delete(key);
+        throw error;
+    });
+    byAgent.set(key, request);
+    return request;
+}
+/**
+ * The server-declared presentation of the tools this actor can reach (`GET <base>/tools`), for
+ * `phraseFor`, `describeToolCall` and `groupToolActivity` — or pass `catalog` to
+ * `useChatTranscript({ toolCatalog })` and read the phrases off the transcript's calls.
+ */
+export function useToolCatalog(options = {}) {
+    const { agent, enabled = true } = options;
+    const client = useAgentBackend(options.backend);
+    const [entries, setEntries] = useState([]);
+    const [isLoading, setLoading] = useState(enabled);
+    const [error, setError] = useState(null);
+    const [generation, setGeneration] = useState(0);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: `generation` is the refresh trigger
+    useEffect(() => {
+        if (!enabled) {
+            setLoading(false);
+            return;
+        }
+        let cancelled = false;
+        setLoading(true);
+        load(client, agent).then((loaded) => {
+            if (cancelled)
+                return;
+            setEntries(Array.isArray(loaded) ? loaded : []);
+            setError(null);
+            setLoading(false);
+        }, (failure) => {
+            if (cancelled)
+                return;
+            setError(failure instanceof Error ? failure : new Error(String(failure)));
+            setLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [client, agent, enabled, generation]);
+    const refresh = useCallback(() => {
+        shared.get(client)?.delete(agent ?? '');
+        setGeneration((current) => current + 1);
+    }, [client, agent]);
+    const catalog = useMemo(() => toolCatalogFrom(entries), [entries]);
+    return { catalog, entries, isLoading, error, refresh };
+}
+//# sourceMappingURL=use-tool-catalog.js.map

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

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

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

@@ -0,0 +1,68 @@
+import { type ReactNode } from 'react';
+import type { UiCapabilities } from '../../genui/index.js';
+import type { AgentBackend, AttachmentUploadStrategy } from './backend.js';
+import { type GenuiProviderValue } from './genui/generative-ui.js';
+import type { HttpErrorListener } from './http-error.js';
+export interface AgentProviderProps {
+    /** Advertise exact supported component versions; omission keeps legacy support, [] is text only. */
+    uiCapabilities?: UiCapabilities;
+    /**
+     * A backend of your own — see {@link AgentBackend}. Omitted → an {@link AgentClient} over this
+     * library's REST routes, built from the connection props below (which are ignored when a backend
+     * is given). Must be stable across renders.
+     */
+    backend?: AgentBackend;
+    /** The server's origin, e.g. `https://api.example.com`. Default `''` (same origin). */
+    baseUrl?: string;
+    /** `AgentModule`'s `path`, global prefix included (`'api/agent'`). Default `'agent'`. */
+    path?: string;
+    /** Static headers on every request. */
+    headers?: Record<string, string>;
+    /**
+     * Read at every request — a short-lived bearer token, or a CSRF header read from a cookie
+     * (`{ 'X-XSRF-TOKEN': readCookie('XSRF-TOKEN') }`).
+     */
+    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** `'include'` when the API is on another origin and authenticates by cookie. */
+    credentials?: RequestCredentials;
+    /** Injectable for tests / non-browser runtimes. */
+    fetch?: typeof fetch;
+    /**
+     * Every error answer of the built-in client (an `AgentHttpError`, or a `MediaUploadError` from
+     * `mediaAttachments()`), right before it is thrown — for app-wide reactions such as "401 → sign
+     * in again". Read at call time, so it may change between renders.
+     */
+    onHttpError?: HttpErrorListener;
+    /** Attachment uploads of the built-in client. */
+    attachments?: {
+        /** e.g. `mediaAttachments()` from `@adonis-agora/agent/react/media`. */
+        upload?: AttachmentUploadStrategy;
+    };
+    /**
+     * Set generative UI up here — the same settings `<GenuiProvider>` takes (registry, catalog,
+     * resolver, fallback, …). Every message then draws pushed components with them.
+     */
+    genui?: GenuiProviderValue;
+    children?: ReactNode;
+}
+/**
+ * The agent connection, once, at the app root. Every hook below it — `useAgentChat`, `useThreads`,
+ * `useModels`, `useAgents`, `useQuota`, `useToolCatalog`, `useMessageFeedback`, `useAttachments` —
+ * talks to it unless handed a `backend` of its own.
+ *
+ * ```tsx
+ * <AgentProvider baseUrl="https://api.example.com" credentials="include">
+ *   <App />
+ * </AgentProvider>
+ * ```
+ *
+ * Without a provider every hook shares one same-origin client on `/agent`.
+ */
+export declare function AgentProvider({ backend, uiCapabilities, baseUrl, path, headers, getHeaders, credentials, fetch, onHttpError, attachments, genui, children, }: AgentProviderProps): import("react").JSX.Element;
+/**
+ * The backend a hook talks to: `own` when given, else the enclosing {@link AgentProvider}'s, else a
+ * shared same-origin client on `/agent`. For your own hooks over the same connection.
+ */
+export declare function useAgentBackend<B extends AgentBackend = AgentBackend>(own?: B): B;
+export declare function useAgentUiCapabilities(): UiCapabilities | undefined;
+//# sourceMappingURL=provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../../src/react/core/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,SAAS,EAA+B,MAAM,OAAO,CAAC;AAClF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAG3E,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAClF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAOzD,MAAM,WAAW,kBAAkB;IACjC,oGAAoG;IACpG,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5E,iFAAiF;IACjF,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,mDAAmD;IACnD,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,iDAAiD;IACjD,WAAW,CAAC,EAAE;QACZ,wEAAwE;QACxE,MAAM,CAAC,EAAE,wBAAwB,CAAC;KACnC,CAAC;IACF;;;OAGG;IACH,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,EAC5B,OAAO,EACP,cAAc,EACd,OAAO,EACP,IAAI,EACJ,OAAO,EACP,UAAU,EACV,WAAW,EACX,KAAK,EACL,WAAW,EACX,WAAW,EACX,KAAK,EACL,QAAQ,GACT,EAAE,kBAAkB,+BA8BpB;AAUD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAGjF;AAKD,wBAAgB,sBAAsB,IAAI,cAAc,GAAG,SAAS,CAEnE"}

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

@@ -0,0 +1,61 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext, useMemo, useRef } from 'react';
+import { AgentClient } from './client.js';
+import { sharedContext } from './components/ambient-ui.js';
+import { GenuiProvider } from './genui/generative-ui.js';
+// Shared by key, like the genui contexts: `/media` and `/genui` are separate bundles.
+const AgentBackendContext = sharedContext('@adonis-agora/agent/react:agent-backend');
+/**
+ * The agent connection, once, at the app root. Every hook below it — `useAgentChat`, `useThreads`,
+ * `useModels`, `useAgents`, `useQuota`, `useToolCatalog`, `useMessageFeedback`, `useAttachments` —
+ * talks to it unless handed a `backend` of its own.
+ *
+ * ```tsx
+ * <AgentProvider baseUrl="https://api.example.com" credentials="include">
+ *   <App />
+ * </AgentProvider>
+ * ```
+ *
+ * Without a provider every hook shares one same-origin client on `/agent`.
+ */
+export function AgentProvider({ backend, uiCapabilities, baseUrl, path, headers, getHeaders, credentials, fetch, onHttpError, attachments, genui, children, }) {
+    // Headers are read per request, so a re-render with new ones reaches the same client.
+    const latestHeaders = useRef({ headers, getHeaders, onHttpError });
+    latestHeaders.current = { headers, getHeaders, onHttpError };
+    const upload = attachments?.upload;
+    const value = useMemo(() => backend ??
+        new AgentClient({
+            ...(baseUrl !== undefined ? { baseUrl } : {}),
+            ...(path !== undefined ? { path } : {}),
+            ...(credentials !== undefined ? { credentials } : {}),
+            ...(fetch !== undefined ? { fetch } : {}),
+            ...(upload !== undefined ? { attachments: { upload } } : {}),
+            onHttpError: (error) => latestHeaders.current.onHttpError?.(error),
+            getHeaders: async () => {
+                const current = latestHeaders.current;
+                const dynamic = (await current.getHeaders?.()) ?? {};
+                return { ...current.headers, ...dynamic };
+            },
+        }), [backend, baseUrl, path, credentials, fetch, upload]);
+    const content = genui !== undefined ? _jsx(GenuiProvider, { ...genui, children: children }) : children;
+    return (_jsx(AgentUiCapabilitiesContext.Provider, { value: uiCapabilities ?? null, children: _jsx(AgentBackendContext.Provider, { value: value, children: content }) }));
+}
+let fallback;
+/** The client every hook uses outside an {@link AgentProvider}: same origin, `/agent`. */
+function defaultBackend() {
+    fallback ??= new AgentClient();
+    return fallback;
+}
+/**
+ * The backend a hook talks to: `own` when given, else the enclosing {@link AgentProvider}'s, else a
+ * shared same-origin client on `/agent`. For your own hooks over the same connection.
+ */
+export function useAgentBackend(own) {
+    const provided = useContext(AgentBackendContext);
+    return (own ?? provided ?? defaultBackend());
+}
+const AgentUiCapabilitiesContext = sharedContext('@adonis-agora/agent/react:ui-capabilities');
+export function useAgentUiCapabilities() {
+    return useContext(AgentUiCapabilitiesContext) ?? undefined;
+}
+//# sourceMappingURL=provider.js.map

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

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

package/dist/src/react/core/queue/model.d.ts

@@ -0,0 +1,73 @@
+import type { MessageAttachment, QueuePause } from '../../../index.js';
+import type { MessageFile } from '../attachments/files.js';
+/**
+ * What the composer (and `sendMessage`) does with a message sent while a turn is still running:
+ *  - `'queue'` (default) — it waits in the thread's queue and runs when the turn settles.
+ *  - `'interrupt'` — the running turn is cancelled and this message runs next.
+ *  - `'block'` — the composer refuses it (`blockedBy: 'busy'`), as before queues existed.
+ */
+export type WhileRunning = 'queue' | 'interrupt' | 'block';
+/**
+ * A per-call answer to "a turn is still running" — `composer.submit({ mode })`,
+ * `sendMessage(message, { mode })`. It overrides the chat's `whileRunning` for that one send
+ * (including `'block'`), and means nothing when no turn is running: the message is simply sent.
+ */
+export interface SendWhileRunning {
+    /** `'queue'` — wait for the running turn. `'interrupt'` — cancel it and run this next. */
+    mode?: 'queue' | 'interrupt';
+}
+/** A message waiting in the thread's queue, as the chat shows it. */
+export interface QueuedChatMessage {
+    /** The server's id once it is queued; a local id while `state` is `'sending'`. */
+    id: string;
+    text: string;
+    /** The uploaded attachments as they were queued — what a re-send carries. */
+    attachments: MessageAttachment[];
+    /**
+     * The same attachments as {@link MessageFile}s — the shape `messageFiles()` gives for a sent
+     * message, so one renderer draws the files of a waiting message and of a sent one.
+     */
+    files: MessageFile[];
+    /**
+     * `'sending'` — on its way to the server (it has no server id yet, so it cannot be edited).
+     * `'queued'` — waiting its turn.
+     */
+    state: 'sending' | 'queued';
+    /** Queued by an interrupt: it runs as soon as the cancelled turn settles. */
+    interrupt: boolean;
+    createdAt: string;
+}
+/** `chat.queue` — the thread's queue of waiting messages, and what can be done to it. */
+export interface ChatQueue {
+    /** Waiting messages, in the order they will run. */
+    items: QueuedChatMessage[];
+    /** Why the queue stopped draining (a failed turn, a Stop, the quota), or `null`. */
+    paused: QueuePause | null;
+    /** The backend can queue (`enqueueMessage`). Without it sends made mid-turn are refused. */
+    isSupported: boolean;
+    /**
+     * Queue `text` (with already-uploaded `attachments`) on this chat's thread. `mode: 'interrupt'`
+     * cancels the running turn and runs it next. Starts at once when nothing is running.
+     */
+    add: (text: string, options?: {
+        attachments?: MessageAttachment[];
+        mode?: 'queue' | 'interrupt';
+    }) => Promise<void>;
+    remove: (id: string) => Promise<void>;
+    /**
+     * Run a waiting message now: it moves to the head as an interrupt and the running turn is
+     * cancelled for it (with nothing running, it starts at once). One server call — the message keeps
+     * its id and never leaves the queue, unlike a `remove` followed by an `add`. Needs a backend with
+     * `interruptQueuedMessage`.
+     */
+    interrupt: (id: string) => Promise<void>;
+    edit: (id: string, text: string) => Promise<void>;
+    /** Move a waiting message to `index` (0 → next). */
+    move: (id: string, index: number) => Promise<void>;
+    clear: () => Promise<void>;
+    /** Lift a pause; the head starts when nothing is running. */
+    resume: () => Promise<void>;
+    /** The last queue operation that failed, or `null`. */
+    error: Error | null;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/src/react/core/queue/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../../../src/react/core/queue/model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,WAAW,GAAG,OAAO,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0FAA0F;IAC1F,IAAI,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;CAC9B;AAED,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC;;;OAGG;IACH,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB;;;OAGG;IACH,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B,6EAA6E;IAC7E,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,yFAAyF;AACzF,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,oFAAoF;IACpF,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC1B,4FAA4F;IAC5F,WAAW,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,GAAG,EAAE,CACH,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,GAAG,WAAW,CAAA;KAAE,KAC1E,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;;;;;OAKG;IACH,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,oDAAoD;IACpD,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,6DAA6D;IAC7D,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,uDAAuD;IACvD,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB"}

package/dist/src/react/core/queue/model.js

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

package/dist/src/react/core/queue/model.js.map

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

package/dist/src/react/core/quota/use-quota.d.ts

@@ -0,0 +1,35 @@
+import { type QuotaBlock, type QuotaReport, type QuotaWarning, type QuotaWindow } from '../../../spi/quota-provider.js';
+import { type AgentBackend } from '../backend.js';
+export interface UseQuotaOptions {
+    /** Default: the enclosing `<AgentProvider>`'s. Must implement `getQuota`. */
+    backend?: AgentBackend;
+    /** `false` holds the request. Default `true`. */
+    enabled?: boolean;
+    /** Re-read every `pollMs` ms as well. Default: only on mount, after runs, and on `refresh`. */
+    pollMs?: number;
+}
+export interface QuotaState {
+    /** The full report, once loaded. */
+    report: QuotaReport | undefined;
+    windows: QuotaWindow[];
+    /** The `day` / `month` windows, when the server reports them. */
+    day: QuotaWindow | undefined;
+    month: QuotaWindow | undefined;
+    /** The window that blocks sends, or `null` — pass it to `useAgentChat({ blocked })`. */
+    blocked: QuotaBlock | null;
+    /**
+     * The soft limit: the fullest window past its `warnAt` (`{ period, ratio, reason? }`), or `null`.
+     * The server's `warning`, else derived from the windows; never set while `blocked`.
+     */
+    warning: QuotaWarning | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * The caller's budget (`GET <base>/quota`): every window's usage against its ceilings, and which
+ * one — if any — blocks sends. Re-read after every run a chat on the same backend settles, so a
+ * meter moves with the conversation. Headless: draw the meter yourself.
+ */
+export declare function useQuota(options?: UseQuotaOptions): QuotaState;
+//# sourceMappingURL=use-quota.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-quota.d.ts","sourceRoot":"","sources":["../../../../../src/react/core/quota/use-quota.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,WAAW,EAEjB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,KAAK,YAAY,EAAwB,MAAM,eAAe,CAAC;AAKxE,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+FAA+F;IAC/F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,oCAAoC;IACpC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,iEAAiE;IACjE,GAAG,EAAE,WAAW,GAAG,SAAS,CAAC;IAC7B,KAAK,EAAE,WAAW,GAAG,SAAS,CAAC;IAC/B,wFAAwF;IACxF,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B;;;OAGG;IACH,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7B,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,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,UAAU,CAuClE"}

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

@@ -0,0 +1,47 @@
+import { useEffect, useMemo } from 'react';
+import { quotaWarning, } from '../../../spi/quota-provider.js';
+import { requireBackendMethod } from '../backend.js';
+import { useResource } from '../catalog/use-resource.js';
+import { useAgentBackend } from '../provider.js';
+import { onThreadsEvent } from '../threads/threads-events.js';
+/**
+ * The caller's budget (`GET <base>/quota`): every window's usage against its ceilings, and which
+ * one — if any — blocks sends. Re-read after every run a chat on the same backend settles, so a
+ * meter moves with the conversation. Headless: draw the meter yourself.
+ */
+export function useQuota(options = {}) {
+    const { enabled = true, pollMs } = options;
+    const backend = useAgentBackend(options.backend);
+    const { data, isLoading, error, refresh } = useResource(() => requireBackendMethod(backend, 'getQuota')(), '', enabled);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        return onThreadsEvent(backend, (event) => {
+            if (event.type === 'changed')
+                void refresh();
+        });
+    }, [backend, enabled, refresh]);
+    useEffect(() => {
+        if (!enabled || pollMs === undefined || pollMs <= 0)
+            return;
+        const timer = setInterval(() => void refresh(), pollMs);
+        return () => clearInterval(timer);
+    }, [enabled, pollMs, refresh]);
+    return useMemo(() => {
+        const windows = data?.windows ?? [];
+        return {
+            report: data,
+            windows,
+            day: windows.find((window) => window.period === 'day'),
+            month: windows.find((window) => window.period === 'month'),
+            blocked: data?.blocked ?? null,
+            warning: data === undefined || data.blocked !== undefined
+                ? null
+                : (data.warning ?? quotaWarning(windows) ?? null),
+            isLoading,
+            error,
+            refresh,
+        };
+    }, [data, isLoading, error, refresh]);
+}
+//# sourceMappingURL=use-quota.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-quota.js","sourceRoot":"","sources":["../../../../../src/react/core/quota/use-quota.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,EAKL,YAAY,GACb,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAqB,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AA8B9D;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAO,GAAoB,EAAE;IACpD,MAAM,EAAE,OAAO,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC3C,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,UAAU,CAAC,EAAE,EACjD,EAAE,EACF,OAAO,CACR,CAAC;IAEF,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,OAAO,cAAc,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YACvC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;gBAAE,KAAK,OAAO,EAAE,CAAC;QAC/C,CAAC,CAAC,CAAC;IACL,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IAEhC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,OAAO,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,IAAI,CAAC;YAAE,OAAO;QAC5D,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;QACxD,OAAO,GAAG,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAE/B,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC;QACpC,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,OAAO;YACP,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,KAAK,KAAK,CAAC;YACtD,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,KAAK,OAAO,CAAC;YAC1D,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,IAAI;YAC9B,OAAO,EACL,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;gBAC9C,CAAC,CAAC,IAAI;gBACN,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,IAAI,IAAI,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"}