@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.5

package/dist/ai/headless/use-ai-admin-config.js

@@ -0,0 +1,260 @@
+/**
+ * Load, save, key-manage and probe the deployment's AI configuration
+ * (`/api/admin/ai/*`). Issue #429, epic #419.
+ *
+ * The house hook contract, as `useStorageConfig` states it:
+ *
+ *   - SEPARATE FLAG GROUPS. `save` is the ordinary form edit and owns
+ *     `isSaving`/`saveError`. The provider KEY writes (`setKey`/`removeKey`)
+ *     act immediately, per provider, and own `keyAction`/`keyError`. `test` is
+ *     a PROBE — it saves nothing — and owns `probingProvider`/`probeError`
+ *     plus the per-provider `testResults`. Folding them together would make
+ *     the Save button spin while a key is being verified, and let a save error
+ *     and a provider diagnosis overwrite each other.
+ *   - EVERY WRITE RESOLVES `true`/`false` RATHER THAN THROWING.
+ *   - `useIsMounted()` GUARDS EVERY `setState` PAST AN `await`.
+ *
+ * ⚠ THE AI-SPECIFIC CODE IS IN `details.reason`. The API's error envelope
+ * carries the generic HTTP code at the top level (`FORBIDDEN`, `BAD_REQUEST`)
+ * and the AI taxonomy code (`AI_KEY_INVALID`, `AI_KEY_REQUIRED`, …) under
+ * `details.reason`. `toAiErrorInfo` (`services/aiErrors.ts`) — the one
+ * helper every AI surface uses — reads it there.
+ *
+ * ⚠ THE PROBE NEVER REJECTS ON A BAD ANSWER. `POST …/test` answers 200 with
+ * `success: false` for a rejected key; that lands in `testResults` like any
+ * other result. A rejection means the CALL failed and becomes `probeError`.
+ *
+ * ⚠ NO KEY IS EVER HELD HERE. `setKey` and `test` take the typed key as an
+ * argument and forward it; nothing in this hook's state can hold one, and the
+ * response that comes back is the masked `keyStatus`.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { isPlatformApiError } from '../../core/index.js';
+import { deleteAiProviderKey, getAiAdminConfig, setAiProviderKey, testAiProvider, updateAiAdminConfig, } from './client.js';
+import { toAiErrorInfo } from './errors.js';
+import { useIsMounted } from '../internal/use-is-mounted.js';
+import { useAiApi } from './use-ai-api.js';
+/** A copy of `record` with `key` removed. */
+function without(record, key) {
+    if (!(key in record))
+        return record;
+    const next = { ...record };
+    delete next[key];
+    return next;
+}
+/** 403 is named explicitly — it is the one failure an admin can act on themselves. */
+function messageFor(err, fallback) {
+    if (isPlatformApiError(err)) {
+        const reason = toAiErrorInfo(err).code;
+        if (err.status === 403 && !reason) {
+            return 'You do not have permission to manage the AI configuration';
+        }
+        switch (reason) {
+            case 'AI_KEY_INVALID':
+                return 'The provider rejected this key, so nothing was stored. Check the key and try again.';
+            case 'AI_KEY_REQUIRED':
+                return (err.message ||
+                    'The organisation-key fallback needs a stored key for every enabled provider. Save a key first.');
+            case 'AI_PROVIDER_UNAVAILABLE':
+                return 'The provider could not be reached to verify the key. Try again shortly.';
+            case 'AI_UNKNOWN_PROVIDER':
+                return err.message || 'That provider does not exist in this deployment.';
+            case 'AI_PROVIDER_NOT_REGISTERED':
+                return (err.message ||
+                    'That provider is not available in this build, so it can be switched off but not on.');
+            // #448 — the provider-specific settings (Azure OpenAI, OpenAI-compatible).
+            case 'AI_BASE_URL_REQUIRED':
+                return (err.message ||
+                    'This provider needs an endpoint before it can be enabled. Enter its base URL, then save.');
+            case 'AI_PROVIDER_SETTINGS_INVALID':
+                return (err.message ||
+                    "One of this provider's settings was refused. Check the URL (https for Azure OpenAI, no user name, password or #fragment), the API version and the deployment names.");
+            case 'AI_PROVIDER_FIELD_UNSUPPORTED':
+                return (err.message ||
+                    'This provider does not accept one of the settings sent. Reload the page and try again.');
+            default:
+                // `PUT …/key` answers 503 when the provider could not be asked to
+                // verify the key at all — nothing was stored, and retrying is the fix.
+                if (err.status === 503) {
+                    return 'The provider could not be reached to verify the key, so nothing was stored. Try again shortly.';
+                }
+                return err.message || fallback;
+        }
+    }
+    return fallback;
+}
+/**
+ * Use AI admin config.
+ *
+ * @stability experimental
+ */
+export function useAiAdminConfig(options = {}) {
+    const api = useAiApi(options.api);
+    const [config, setConfig] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [loadError, setLoadError] = useState(null);
+    const [isSaving, setIsSaving] = useState(false);
+    const [saveError, setSaveError] = useState(null);
+    const [keyAction, setKeyAction] = useState(null);
+    const [keyError, setKeyError] = useState(null);
+    const [keyWarnings, setKeyWarnings] = useState([]);
+    const [probingProvider, setProbingProvider] = useState(null);
+    const [probeError, setProbeError] = useState(null);
+    const [testResults, setTestResults] = useState({});
+    const isMounted = useIsMounted();
+    const fetchConfig = useCallback(async () => {
+        try {
+            setIsLoading(true);
+            setLoadError(null);
+            const data = await getAiAdminConfig(api);
+            if (isMounted())
+                setConfig(data);
+        }
+        catch (err) {
+            if (isMounted())
+                setLoadError(messageFor(err, 'Failed to load the AI configuration'));
+        }
+        finally {
+            if (isMounted())
+                setIsLoading(false);
+        }
+    }, [isMounted]);
+    useEffect(() => {
+        void fetchConfig();
+    }, [fetchConfig]);
+    /**
+     * THE RESPONSE IS THE NEW BASELINE, never the input: the server owns
+     * `keyStatus` and `version`, and `version` is what the NEXT save sends as
+     * `If-Match`, so two saves in a row work with no reload in between.
+     */
+    const save = useCallback(async (input) => {
+        try {
+            setIsSaving(true);
+            setSaveError(null);
+            const data = await updateAiAdminConfig(api, input, config?.version ?? 0);
+            if (isMounted())
+                setConfig(data);
+            return true;
+        }
+        catch (err) {
+            if (isPlatformApiError(err) && err.status === 409 && !toAiErrorInfo(err).code) {
+                // Somebody else saved between this page's load and this click. Every
+                // retry would 409 identically until the form is rebuilt from the
+                // current row, so reload it and say plainly the fields were replaced.
+                await fetchConfig();
+                if (isMounted()) {
+                    setSaveError('Someone else changed the AI configuration while you were editing. ' +
+                        'The form has been reloaded with the current configuration — review it and save again.');
+                }
+                return false;
+            }
+            if (isMounted())
+                setSaveError(messageFor(err, 'Failed to save the AI configuration'));
+            return false;
+        }
+        finally {
+            if (isMounted())
+                setIsSaving(false);
+        }
+    }, [config, fetchConfig, isMounted]);
+    const setKey = useCallback(async (provider, apiKey) => {
+        try {
+            setKeyAction({ provider, action: 'save' });
+            setKeyError(null);
+            setKeyWarnings([]);
+            const data = await setAiProviderKey(api, provider, apiKey);
+            if (isMounted()) {
+                setConfig(data);
+                // The last probe described a different key.
+                setTestResults((prev) => without(prev, provider));
+            }
+            return true;
+        }
+        catch (err) {
+            if (isMounted()) {
+                setKeyError({ provider, message: messageFor(err, 'Failed to save the key') });
+            }
+            return false;
+        }
+        finally {
+            if (isMounted())
+                setKeyAction(null);
+        }
+    }, [isMounted]);
+    const removeKey = useCallback(async (provider) => {
+        try {
+            setKeyAction({ provider, action: 'remove' });
+            setKeyError(null);
+            setKeyWarnings([]);
+            const data = await deleteAiProviderKey(api, provider);
+            if (isMounted()) {
+                const { warnings, ...view } = data;
+                setConfig(view);
+                setKeyWarnings(warnings);
+                setTestResults((prev) => without(prev, provider));
+            }
+            return true;
+        }
+        catch (err) {
+            if (isMounted()) {
+                setKeyError({ provider, message: messageFor(err, 'Failed to remove the key') });
+            }
+            return false;
+        }
+        finally {
+            if (isMounted())
+                setKeyAction(null);
+        }
+    }, [isMounted]);
+    const test = useCallback(async (provider, input = {}) => {
+        try {
+            setProbingProvider(provider);
+            setProbeError(null);
+            setTestResults((prev) => without(prev, provider));
+            const result = await testAiProvider(api, provider, input);
+            if (isMounted())
+                setTestResults((prev) => ({ ...prev, [provider]: result }));
+        }
+        catch (err) {
+            if (isMounted()) {
+                setProbeError({
+                    provider,
+                    message: messageFor(err, 'The provider test could not be run'),
+                });
+            }
+        }
+        finally {
+            if (isMounted())
+                setProbingProvider(null);
+        }
+    }, [isMounted]);
+    const clearSaveError = useCallback(() => setSaveError(null), []);
+    const clearKeyError = useCallback(() => setKeyError(null), []);
+    const clearKeyWarnings = useCallback(() => setKeyWarnings([]), []);
+    const clearProbeError = useCallback(() => setProbeError(null), []);
+    const clearTestResult = useCallback((provider) => setTestResults((prev) => without(prev, provider)), []);
+    return {
+        config,
+        isLoading,
+        loadError,
+        refresh: fetchConfig,
+        isSaving,
+        saveError,
+        clearSaveError,
+        save,
+        keyAction,
+        keyError,
+        clearKeyError,
+        keyWarnings,
+        clearKeyWarnings,
+        setKey,
+        removeKey,
+        probingProvider,
+        probeError,
+        clearProbeError,
+        testResults,
+        clearTestResult,
+        test,
+    };
+}
+//# sourceMappingURL=use-ai-admin-config.js.map

package/dist/ai/headless/use-ai-admin-config.js.map

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

package/dist/ai/headless/use-ai-api.d.ts

@@ -0,0 +1,22 @@
+import type { PlatformApiClient } from '../../core/index.js';
+/**
+ * The transport an AI hook calls through: `explicit` when given, else the
+ * `PlatformHostProvider`'s `api`, else a transport whose calls reject with
+ * "No platform transport is available".
+ *
+ * @param explicit - a transport to use instead (keep its identity stable).
+ * @returns the transport.
+ *
+ * @stability experimental
+ */
+export declare function useAiApi(explicit?: PlatformApiClient): PlatformApiClient;
+/**
+ * What every AI hook takes as its (last, optional) argument.
+ *
+ * @stability experimental
+ */
+export interface AiHookOptions {
+    /** The transport. Default: the `PlatformHostProvider`'s (keep its identity stable). */
+    api?: PlatformApiClient;
+}
+//# sourceMappingURL=use-ai-api.d.ts.map

package/dist/ai/headless/use-ai-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-ai-api.d.ts","sourceRoot":"","sources":["../../../src/ai/headless/use-ai-api.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAkB7D;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,CAGxE;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,uFAAuF;IACvF,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB"}

package/dist/ai/headless/use-ai-api.js

@@ -0,0 +1,31 @@
+// The transport every AI hook calls through (issue #890): the platform host's
+// `api`, or one handed to the hook. Without either, the calls reject with a
+// sentence the page can show instead of the hook throwing while it renders.
+import { useOptionalPlatformHost } from '../../core/index.js';
+const NO_TRANSPORT = 'No platform transport is available. Mount PlatformHostProvider (@marinoscar/platform-web/core).';
+function missing() {
+    return Promise.reject(new Error(NO_TRANSPORT));
+}
+/** A transport whose every call rejects; what a hook uses when no host is mounted. */
+const NO_API = Object.freeze({
+    get: missing,
+    post: missing,
+    put: missing,
+    patch: missing,
+    delete: missing,
+});
+/**
+ * The transport an AI hook calls through: `explicit` when given, else the
+ * `PlatformHostProvider`'s `api`, else a transport whose calls reject with
+ * "No platform transport is available".
+ *
+ * @param explicit - a transport to use instead (keep its identity stable).
+ * @returns the transport.
+ *
+ * @stability experimental
+ */
+export function useAiApi(explicit) {
+    const hostApi = useOptionalPlatformHost()?.api;
+    return explicit ?? hostApi ?? NO_API;
+}
+//# sourceMappingURL=use-ai-api.js.map

package/dist/ai/headless/use-ai-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-ai-api.js","sourceRoot":"","sources":["../../../src/ai/headless/use-ai-api.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4EAA4E;AAC5E,4EAA4E;AAE5E,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAG9D,MAAM,YAAY,GAChB,iGAAiG,CAAC;AAEpG,SAAS,OAAO;IACd,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,sFAAsF;AACtF,MAAM,MAAM,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC9C,GAAG,EAAE,OAAO;IACZ,IAAI,EAAE,OAAO;IACb,GAAG,EAAE,OAAO;IACZ,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,OAAO;CAChB,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,QAA4B;IACnD,MAAM,OAAO,GAAG,uBAAuB,EAAE,EAAE,GAAG,CAAC;IAC/C,OAAO,QAAQ,IAAI,OAAO,IAAI,MAAM,CAAC;AACvC,CAAC"}

package/dist/ai/headless/use-ai-capabilities.d.ts

@@ -0,0 +1,23 @@
+import type { AiCapabilitiesResponse } from './types.js';
+import type { AiHookOptions } from './use-ai-api.js';
+/**
+ * What `useAiCapabilities` returns.
+ *
+ * @stability experimental
+ */
+export interface UseAiCapabilitiesReturn extends AiCapabilitiesResponse {
+    /** Whether the first fetch is in flight. */
+    isLoading: boolean;
+    /** Why the fetch failed, or `null`. */
+    error: string | null;
+}
+/**
+ * The capability and operation vocabularies the API serves.
+ *
+ * @param options - the transport.
+ * @returns both lists (empty until loaded), loading and error state.
+ *
+ * @stability experimental
+ */
+export declare function useAiCapabilities(options?: AiHookOptions): UseAiCapabilitiesReturn;
+//# sourceMappingURL=use-ai-capabilities.d.ts.map

package/dist/ai/headless/use-ai-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-ai-capabilities.d.ts","sourceRoot":"","sources":["../../../src/ai/headless/use-ai-capabilities.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAGzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;GAIG;AACH,MAAM,WAAW,uBAAwB,SAAQ,sBAAsB;IACrE,4CAA4C;IAC5C,SAAS,EAAE,OAAO,CAAC;IACnB,uCAAuC;IACvC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,aAAkB,GAAG,uBAAuB,CAkCtF"}

package/dist/ai/headless/use-ai-capabilities.js

@@ -0,0 +1,62 @@
+/**
+ * The deployment's open capability and operation vocabularies
+ * (`GET /api/admin/ai/capabilities`, `ai_config:read`) — PP-14.17, issue #935.
+ *
+ * The admin Models page draws its capability filter and the override dialog's
+ * checkboxes from it, so a capability an app registered (`registerAiCapability`
+ * on the API) appears with its label and no web change. Fetched once per mount;
+ * the vocabularies are static for the life of the API process.
+ *
+ * It also records the labels (`registerAiCapabilityLabels`), so every chip on
+ * the page reads them. A failure is not an error state worth blocking on: the
+ * built-in capabilities are known without the API, and an app capability is
+ * drawn as its id until the labels arrive.
+ */
+import { useEffect, useState } from 'react';
+import { isPlatformApiError } from '../../core/index.js';
+import { registerAiCapabilityLabels } from './capability-labels.js';
+import { getAiCapabilities } from './client.js';
+import { useIsMounted } from '../internal/use-is-mounted.js';
+import { useAiApi } from './use-ai-api.js';
+/**
+ * The capability and operation vocabularies the API serves.
+ *
+ * @param options - the transport.
+ * @returns both lists (empty until loaded), loading and error state.
+ *
+ * @stability experimental
+ */
+export function useAiCapabilities(options = {}) {
+    const api = useAiApi(options.api);
+    const isMounted = useIsMounted();
+    const [state, setState] = useState({
+        capabilities: [],
+        operations: [],
+        isLoading: true,
+        error: null,
+    });
+    useEffect(() => {
+        let cancelled = false;
+        getAiCapabilities(api)
+            .then((data) => {
+            registerAiCapabilityLabels(data.capabilities);
+            if (!cancelled && isMounted())
+                setState({ ...data, isLoading: false, error: null });
+        })
+            .catch((err) => {
+            if (cancelled || !isMounted())
+                return;
+            setState({
+                capabilities: [],
+                operations: [],
+                isLoading: false,
+                error: isPlatformApiError(err) ? err.message : 'Failed to load the AI capabilities',
+            });
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [api, isMounted]);
+    return state;
+}
+//# sourceMappingURL=use-ai-capabilities.js.map

package/dist/ai/headless/use-ai-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-ai-capabilities.js","sourceRoot":"","sources":["../../../src/ai/headless/use-ai-capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAe3C;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAyB,EAAE;IAC3D,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IACjC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAA0B;QAC1D,YAAY,EAAE,EAAE;QAChB,UAAU,EAAE,EAAE;QACd,SAAS,EAAE,IAAI;QACf,KAAK,EAAE,IAAI;KACZ,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,SAAS,GAAG,KAAK,CAAC;QAEtB,iBAAiB,CAAC,GAAG,CAAC;aACnB,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;YACb,0BAA0B,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC9C,IAAI,CAAC,SAAS,IAAI,SAAS,EAAE;gBAAE,QAAQ,CAAC,EAAE,GAAG,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACtF,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;YACtB,IAAI,SAAS,IAAI,CAAC,SAAS,EAAE;gBAAE,OAAO;YACtC,QAAQ,CAAC;gBACP,YAAY,EAAE,EAAE;gBAChB,UAAU,EAAE,EAAE;gBACd,SAAS,EAAE,KAAK;gBAChB,KAAK,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,oCAAoC;aACpF,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEL,OAAO,GAAG,EAAE;YACV,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;IAErB,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/ai/headless/use-ai-chat.d.ts

@@ -0,0 +1,114 @@
+import { type AiInputItem, type AiOutputItem, type AiResponse, type AiResponseRequest, type AiUsage } from './types.js';
+import { type AiErrorInfo } from './errors.js';
+import type { AiHookOptions } from './use-ai-api.js';
+import { type AiChatAttachment } from './chat-attachments.js';
+/**
+ * The AI chat message status type.
+ *
+ * @stability experimental
+ */
+export type AiChatMessageStatus = 'streaming' | 'done' | 'stopped' | 'error';
+/**
+ * The AI chat message wire shape.
+ *
+ * @stability experimental
+ */
+export interface AiChatMessage {
+    /** The id. */
+    id: string;
+    /** The role. */
+    role: 'user' | 'assistant';
+    /** The text. */
+    text: string;
+    /** The status. */
+    status: AiChatMessageStatus;
+    /** Streamed reasoning summary (assistant only). */
+    reasoning?: string;
+    /** The usage. */
+    usage?: AiUsage;
+    /** Structured output, when the request asked for one and it parsed. */
+    parsed?: unknown;
+    /** Provider response id — what the NEXT turn sends as `previousResponseId`. */
+    responseId?: string;
+    /** The model. */
+    model?: string;
+    /** The error. */
+    error?: AiErrorInfo;
+    /** Set on an assistant message that came from a background run. */
+    runId?: string;
+    /**
+     * The completed response's output items (assistant only) — where hosted
+     * tool calls and web-search citations live (#442, rendered by #445).
+     */
+    output?: AiOutputItem[];
+    /** Files sent with a user message (#445). */
+    attachments?: AiChatAttachment[];
+}
+/**
+ * Everything about a turn except its prompt and the conversation linkage.
+ *
+ * @stability experimental
+ */
+export type AiChatRequestOptions = Omit<AiResponseRequest, 'input' | 'previousResponseId'> & {
+    /** `false` sends one JSON round trip instead of streaming. Default `true`. */
+    stream?: boolean;
+    /**
+     * `false` for a provider that cannot continue a conversation by
+     * `previousResponseId` (#446): the turn resends the conversation so far as
+     * `input` instead. Default `true` (chain by id).
+     */
+    chainResponses?: boolean;
+};
+/**
+ * The use AI chat return wire shape.
+ *
+ * @stability experimental
+ */
+export interface UseAiChatReturn {
+    /** The messages. */
+    messages: AiChatMessage[];
+    /** Whether streaming. */
+    isStreaming: boolean;
+    /** The id the next turn will continue from, or `null` for a fresh thread. */
+    previousResponseId: string | null;
+    /** The send. */
+    send: (prompt: string, options?: AiChatRequestOptions, attachments?: AiChatAttachment[]) => Promise<void>;
+    /** The stop. */
+    stop: () => void;
+    /** The reset. */
+    reset: () => void;
+    /** Append a finished exchange produced elsewhere (a background run). */
+    appendExchange: (prompt: string, response: AiResponse, extra?: {
+        /** The run id. */
+        runId?: string;
+        /** The attachments. */
+        attachments?: AiChatAttachment[];
+    }) => void;
+    /**
+     * The conversation so far plus this turn, as `input` items — what a turn
+     * sends to a provider that cannot chain (#446). See {@link buildHistoryInput}.
+     */
+    historyInput: (prompt: string, attachments?: readonly AiChatAttachment[]) => AiInputItem[];
+}
+/**
+ * Every completed prior exchange, then this turn, as message items (#446).
+ *
+ * An exchange is a user message and the assistant message that follows it;
+ * it is resent only when that answer finished (`done`) with text — a
+ * stopped, failed or still-streaming turn is dropped, user half included,
+ * exactly as it never advances `previousResponseId`. A user message is its
+ * text followed by one `image`/`file` part per attachment, named by
+ * `storageObjectId` (the same parts `chatTurnInput` builds, #445); the
+ * assistant's is its text.
+ 
+ *
+ * @stability experimental
+ */
+export declare function buildHistoryInput(messages: readonly AiChatMessage[], prompt: string, attachments?: readonly AiChatAttachment[]): AiInputItem[];
+/**
+ * Use AI chat.
+ *
+ * @stability experimental
+ */
+export declare function useAiChat(options?: AiHookOptions): UseAiChatReturn;
+//# sourceMappingURL=use-ai-chat.d.ts.map

package/dist/ai/headless/use-ai-chat.d.ts.map

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