@clone-ai/prompt-prediction 0.7.0-bootstrap.0 → 0.7.0

package/dist/generated/api-types.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/dist/http.d.ts

@@ -0,0 +1,8 @@
+/** A safe service error code and HTTP status, without request or response bodies. */
+export declare class ClonePredictionError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, status: number);
+}
+/** Decode the object-shaped API envelope. Do not swallow aborted body reads. */
+export declare function readResponse(response: Response): Promise<unknown>;

package/dist/http.js

@@ -0,0 +1,35 @@
+/** A safe service error code and HTTP status, without request or response bodies. */
+export class ClonePredictionError extends Error {
+    code;
+    status;
+    constructor(code, status) {
+        super(code);
+        this.code = code;
+        this.status = status;
+        this.name = 'ClonePredictionError';
+    }
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Decode the object-shaped API envelope. Do not swallow aborted body reads. */
+export async function readResponse(response) {
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+    }
+    if (!response.ok) {
+        const detail = isObject(body) && isObject(body.detail) ? body.detail : undefined;
+        // Only structured error codes may cross into host UI/logs, never arbitrary text.
+        const code = typeof detail?.code === 'string' && /^[a-z][a-z0-9_]{0,127}$/.test(detail.code)
+            ? detail.code : 'prediction_request_failed';
+        throw new ClonePredictionError(code, response.status);
+    }
+    if (!isObject(body))
+        throw new ClonePredictionError('invalid_response', 502);
+    return body;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { CompletionController } from './controller.js';
+export { CloneModeController } from './clone-mode.js';
+export type { CloneModeInput, CloneModeState, CloneModeOptions } from './clone-mode.js';
+export { createPredictionTransport, ClonePredictionError } from './transport.js';
+export { FeedbackTracker, createEventTransport } from './feedback.js';
+export type { FeedbackEvent, FeedbackEvaluation, FeedbackReceipt, EventTransport } from './feedback.js';
+export type { PredictionMetric } from './transport.js';
+export type { CompletionInput, CompletionState, CompletionOptions, AcceptedCompletion } from './controller.js';
+export type { PredictionInput, PredictionOutput, CompletionRequest, PredictionTransport, PredictionEvent } from './types.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { CompletionController } from './controller.js';
+export { CloneModeController } from './clone-mode.js';
+export { createPredictionTransport, ClonePredictionError } from './transport.js';
+export { FeedbackTracker, createEventTransport } from './feedback.js';

package/dist/react.d.ts

@@ -0,0 +1,50 @@
+import type { KeyboardEvent, TextareaHTMLAttributes } from 'react';
+import type { CloneModeInput, CloneModeOptions } from './clone-mode.js';
+import type { CompletionOptions } from './controller.js';
+import type { CompletionRequest, PredictionTransport } from './types.js';
+export interface TabCompletionOptions {
+    value: string;
+    onValueChange: (value: string) => void;
+    context: Omit<CompletionRequest, 'draft' | 'mode' | 'request_id'>;
+    transport: PredictionTransport;
+    enabled?: boolean;
+    debounceMs?: number;
+    maxRequestsPerMinute?: number;
+    requestTimeoutMs?: number;
+    presentation?: 'instant' | 'typewriter';
+    onEvent?: CompletionOptions['onEvent'];
+}
+/** Opt-in only. Render the returned candidate and a visible Stop action before starting. */
+export declare function useCloneMode(options: CloneModeOptions & {
+    input: CloneModeInput;
+}): {
+    state: import("./clone-mode.js").CloneModeState;
+    start: (limits?: {
+        maxTurns?: number;
+        maxDurationMs?: number;
+    }) => boolean;
+    stop: () => void;
+    turnCompleted: () => boolean;
+};
+export declare function useTabCompletion(options: TabCompletionOptions): {
+    inputProps: {
+        ref: import("react").RefObject<HTMLTextAreaElement | null>;
+        value: string;
+        onKeyDown: (event: KeyboardEvent<HTMLTextAreaElement>) => void;
+        onChange: (event: React.ChangeEvent<HTMLTextAreaElement>) => void;
+        onCompositionStart: () => void;
+        onCompositionEnd: () => void;
+        onFocus: () => void;
+        onBlur: () => void;
+        onSelect: () => void;
+    };
+    inputRef: import("react").RefObject<HTMLTextAreaElement | null>;
+    completion: string;
+    state: import("./controller.js").CompletionState;
+    canAccept: boolean;
+    accept: () => boolean;
+    dismiss: () => void;
+};
+export type TabCompletionInputProps = TabCompletionOptions & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'defaultValue' | 'onChange'>;
+/** Drop-in textarea; the parent owns form submission and every explicit send. */
+export declare function TabCompletionInput(props: TabCompletionInputProps): import("react/jsx-runtime").JSX.Element;

package/dist/react.js

@@ -0,0 +1,147 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from 'react';
+import { CompletionController } from './controller.js';
+import { CloneModeController } from './clone-mode.js';
+/** Opt-in only. Render the returned candidate and a visible Stop action before starting. */
+export function useCloneMode(options) {
+    const current = useRef(options);
+    current.current = options;
+    const controller = useMemo(() => new CloneModeController({
+        transport: (request, settings) => current.current.transport(request, settings),
+        onSubmit: (text, metadata) => current.current.onSubmit(text, metadata),
+        get reviewMs() { return current.current.reviewMs; },
+        get requestTimeoutMs() { return current.current.requestTimeoutMs; },
+    }), []);
+    const state = useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+    const settings = useRef({ reviewMs: options.reviewMs, requestTimeoutMs: options.requestTimeoutMs });
+    const key = JSON.stringify(options.input);
+    useLayoutEffect(() => {
+        const changed = !Object.is(settings.current.reviewMs, options.reviewMs)
+            || !Object.is(settings.current.requestTimeoutMs, options.requestTimeoutMs);
+        settings.current = { reviewMs: options.reviewMs, requestTimeoutMs: options.requestTimeoutMs };
+        // Keep the controller's pending-send guard until the host receipt settles.
+        if (changed && !['off', 'stopped'].includes(controller.getSnapshot().status))
+            controller.stop('settings_changed');
+        controller.update(current.current.input);
+    }, [controller, key, options.reviewMs, options.requestTimeoutMs]);
+    useEffect(() => {
+        const stopActive = (reason) => {
+            if (!['off', 'stopped'].includes(controller.getSnapshot().status))
+                controller.stop(reason);
+        };
+        const visibility = () => { if (document.hidden)
+            stopActive('page_hidden'); };
+        document.addEventListener('visibilitychange', visibility);
+        return () => { document.removeEventListener('visibilitychange', visibility); stopActive('unmounted'); };
+    }, [controller]);
+    return { state,
+        start: (limits) => {
+            controller.update(current.current.input);
+            return !document.hidden && controller.start(limits);
+        },
+        stop: () => controller.stop(),
+        turnCompleted: () => { controller.update(current.current.input); return controller.turnCompleted(); }, };
+}
+export function useTabCompletion(options) {
+    const current = useRef(options);
+    current.current = options;
+    const inputRef = useRef(null);
+    const composing = useRef(false);
+    const [interaction, rerender] = useState(0);
+    const revision = useRef({ value: options.value, number: 0 });
+    if (revision.current.value !== options.value) {
+        revision.current = { value: options.value, number: revision.current.number + 1 };
+    }
+    const controller = useMemo(() => new CompletionController({
+        transport: (request, settings) => current.current.transport(request, settings),
+        onEvent: event => current.current.onEvent?.(event),
+        debounceMs: options.debounceMs, maxRequestsPerMinute: options.maxRequestsPerMinute,
+        requestTimeoutMs: options.requestTimeoutMs, presentation: options.presentation,
+    }), [options.debounceMs, options.maxRequestsPerMinute, options.requestTimeoutMs, options.presentation]);
+    const state = useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+    const snapshot = useCallback(() => {
+        const node = inputRef.current;
+        return {
+            value: current.current.value, revision: revision.current.number, context: current.current.context,
+            enabled: current.current.enabled, focused: !!node && node.ownerDocument.activeElement === node,
+            composing: composing.current, selectionStart: node?.selectionStart ?? 0, selectionEnd: node?.selectionEnd ?? 0,
+        };
+    }, []);
+    const key = JSON.stringify({ value: options.value, context: options.context, enabled: options.enabled, interaction });
+    useLayoutEffect(() => { controller.update(snapshot()); }, [controller, snapshot, key]);
+    // dismiss cancels all work without poisoning React StrictMode's effect replay.
+    useEffect(() => () => controller.dismiss(false), [controller]);
+    const accept = useCallback(() => {
+        controller.update(snapshot());
+        const accepted = controller.accept();
+        const node = inputRef.current;
+        if (!accepted || !node)
+            return false;
+        // Native insertion preserves Chromium's Undo stack. React state assignment
+        // alone is insufficient. Other hosts can use the controller's accepted value.
+        const document = node.ownerDocument;
+        let inserted = false;
+        try {
+            inserted = document.execCommand('insertText', false, accepted.suffix);
+        }
+        catch { /* fallback below */ }
+        if (!inserted && node.value !== accepted.value) {
+            node.setRangeText(accepted.suffix, node.selectionStart, node.selectionEnd, 'end');
+        }
+        current.current.onValueChange(node.value);
+        rerender(n => n + 1);
+        return true;
+    }, [controller, snapshot]);
+    const onKeyDown = useCallback((event) => {
+        if (composing.current || event.nativeEvent.isComposing || event.keyCode === 229)
+            return;
+        controller.update(snapshot());
+        if (event.key === 'Tab' && !event.shiftKey && !event.ctrlKey && !event.altKey && !event.metaKey && accept()) {
+            event.preventDefault();
+            event.stopPropagation();
+        }
+        else if (event.key === 'Escape' && controller.getSnapshot().candidate) {
+            controller.dismiss();
+            event.preventDefault();
+            event.stopPropagation();
+        }
+    }, [controller, snapshot, accept]);
+    const inputProps = {
+        ref: inputRef, value: options.value, onKeyDown,
+        onChange: (event) => {
+            current.current.onValueChange(event.currentTarget.value);
+            controller.dismiss(false);
+        },
+        onCompositionStart: () => { composing.current = true; controller.update(snapshot()); },
+        onCompositionEnd: () => { composing.current = false; rerender(n => n + 1); },
+        onFocus: () => rerender(n => n + 1),
+        onBlur: () => { controller.dismiss(false); rerender(n => n + 1); },
+        onSelect: () => { controller.update(snapshot()); rerender(n => n + 1); },
+    };
+    return { inputProps, inputRef, completion: state.visibleCompletion, state,
+        canAccept: !!state.candidate && state.visibleCompletion === state.candidate.completion,
+        accept, dismiss: () => controller.dismiss() };
+}
+/** Drop-in textarea; the parent owns form submission and every explicit send. */
+export function TabCompletionInput(props) {
+    const { value, onValueChange, context, transport, enabled, debounceMs, maxRequestsPerMinute, requestTimeoutMs, presentation, onEvent, style, onKeyDown, onFocus, onBlur, onSelect, onCompositionStart, onCompositionEnd, onScroll, ...textarea } = props;
+    const completion = useTabCompletion({ value, onValueChange, context, transport,
+        enabled: enabled !== false && !textarea.disabled && !textarea.readOnly, debounceMs, maxRequestsPerMinute, requestTimeoutMs, presentation, onEvent });
+    const ghostRef = useRef(null);
+    const id = useId();
+    const shared = { boxSizing: 'border-box', width: '100%', padding: 12, margin: 0,
+        font: 'inherit', lineHeight: '1.5', letterSpacing: 'inherit', whiteSpace: 'pre-wrap', overflowWrap: 'break-word',
+        border: '1px solid transparent', borderRadius: 8, ...style };
+    return _jsxs("div", { style: { position: 'relative', width: '100%' }, children: [_jsxs("div", { ref: ghostRef, "aria-hidden": "true", "data-clone-suggestion": "", style: { ...shared,
+                    position: 'absolute', inset: 0, zIndex: 1, pointerEvents: 'none', overflow: 'hidden', color: 'transparent',
+                    background: 'transparent', borderColor: 'transparent' }, children: [value, _jsx("span", { style: { color: '#737982' }, children: completion.completion })] }), _jsx("textarea", { ...textarea, ...completion.inputProps, style: { ...shared, position: 'relative',
+                    background: 'transparent', resize: 'vertical', borderColor: '#9ca3af', ...style }, "aria-describedby": [textarea['aria-describedby'], completion.completion ? id : ''].filter(Boolean).join(' ') || undefined, onKeyDown: event => { completion.inputProps.onKeyDown(event); if (!event.defaultPrevented)
+                    onKeyDown?.(event); }, onFocus: event => { completion.inputProps.onFocus(); onFocus?.(event); }, onBlur: event => { completion.inputProps.onBlur(); onBlur?.(event); }, onSelect: event => { completion.inputProps.onSelect(); onSelect?.(event); }, onCompositionStart: event => { completion.inputProps.onCompositionStart(); onCompositionStart?.(event); }, onCompositionEnd: event => { completion.inputProps.onCompositionEnd(); onCompositionEnd?.(event); }, onScroll: event => {
+                    if (ghostRef.current) {
+                        ghostRef.current.scrollTop = event.currentTarget.scrollTop;
+                        ghostRef.current.scrollLeft = event.currentTarget.scrollLeft;
+                    }
+                    onScroll?.(event);
+                } }), completion.completion && _jsxs("span", { id: id, style: { position: 'absolute', width: 1, height: 1, overflow: 'hidden', clipPath: 'inset(50%)' }, children: ["Suggestion: ", completion.completion, ". ", completion.canAccept ? 'Press Tab to accept, Escape to dismiss.' : 'Loading suggestion. Escape to dismiss.'] })] });
+}

package/dist/server.d.ts

@@ -0,0 +1,33 @@
+import type { components } from './generated/api-types.js';
+import type { CompletionRequest, PredictionOutput, PredictionEvent } from './types.js';
+export interface ConnectionFlow {
+    requestId: string;
+    state: string;
+    codeVerifier: string;
+    redirectUri: string;
+    userId: string;
+}
+export declare class CloneClient {
+    #private;
+    constructor(options: {
+        apiKey: string;
+        baseUrl: string;
+        fetch?: typeof fetch;
+        requestTimeoutMs?: number;
+        maxConcurrentRequests?: number;
+    });
+    private call;
+    predict(userId: string, request: CompletionRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<PredictionOutput>;
+    recordEvent(userId: string, event: Omit<PredictionEvent, 'user_id'>): Promise<components['schemas']['EventOutput']>;
+    clearFeedback(userId: string): Promise<components['schemas']['FeedbackClearOutput']>;
+    cancel(userId: string, requestId: string): Promise<components['schemas']['CancelOutput']>;
+    revoke(userId: string, connectionId: string): Promise<components['schemas']['RevokeOutput']>;
+    usage(): Promise<components['schemas']['UsageOutput']>;
+    connect(userId: string, redirectUri: string): Promise<{
+        authorizeUrl: string;
+        flow: ConnectionFlow;
+    }>;
+    exchange(flow: ConnectionFlow, callback: URLSearchParams, authenticatedUserId: string): Promise<components['schemas']['ConnectionExchangeOutput']>;
+}

package/dist/server.js

@@ -0,0 +1,93 @@
+import { ClonePredictionError, readResponse } from './http.js';
+import { withDeadline } from './deadline.js';
+export class CloneClient {
+    #key;
+    #base;
+    #fetch;
+    #timeout;
+    #limit;
+    #inFlight = 0;
+    constructor(options) {
+        if (typeof window !== 'undefined')
+            throw new Error('CloneClient must only run on your server');
+        const url = new URL(options.baseUrl);
+        if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1'].includes(url.hostname))) {
+            throw new Error('Clone API must use HTTPS (loopback HTTP is development only)');
+        }
+        if (url.username || url.password || url.search || url.hash)
+            throw new Error('Invalid Clone API URL');
+        if (!options.apiKey.startsWith('clnp_'))
+            throw new Error('An app-scoped Clone API key is required');
+        this.#key = options.apiKey;
+        this.#base = options.baseUrl.replace(/\/$/, '');
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#timeout = options.requestTimeoutMs ?? 15_000;
+        this.#limit = options.maxConcurrentRequests ?? 16;
+        if (!Number.isFinite(this.#timeout) || this.#timeout < 1 || this.#timeout > 30_000
+            || !Number.isInteger(this.#limit) || this.#limit < 1 || this.#limit > 1000)
+            throw new Error('Invalid Clone request limits');
+    }
+    async call(path, body, signal) {
+        if (this.#inFlight >= this.#limit)
+            throw new ClonePredictionError('client_capacity_exceeded', 503);
+        this.#inFlight++;
+        try {
+            return await withDeadline(async (boundedSignal) => {
+                const response = await this.#fetch(this.#base + '/v1' + path, {
+                    method: body === undefined ? 'GET' : 'POST', signal: boundedSignal,
+                    headers: { Authorization: 'Bearer ' + this.#key, 'Content-Type': 'application/json' },
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                });
+                return await readResponse(response);
+            }, this.#timeout, signal);
+        }
+        finally {
+            this.#inFlight--;
+        }
+    }
+    predict(userId, request, options = {}) {
+        // The authenticated server identity always overwrites any untrusted body user_id.
+        return this.call('/predictions', { ...request, user_id: userId }, options.signal);
+    }
+    recordEvent(userId, event) {
+        return this.call('/prediction-events', { ...event, user_id: userId });
+    }
+    clearFeedback(userId) {
+        return this.call('/prediction-feedback/clear', { user_id: userId });
+    }
+    cancel(userId, requestId) {
+        return this.call('/predictions/' + encodeURIComponent(requestId) + '/cancel', { user_id: userId });
+    }
+    revoke(userId, connectionId) {
+        return this.call('/connections/' + encodeURIComponent(connectionId) + '/revoke', { user_id: userId });
+    }
+    usage() {
+        return this.call('/usage');
+    }
+    async connect(userId, redirectUri) {
+        const codeVerifier = randomToken();
+        const state = randomToken();
+        const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(codeVerifier));
+        const codeChallenge = base64url(new Uint8Array(hash));
+        const body = {
+            user_id: userId, redirect_uri: redirectUri, state, code_challenge: codeChallenge,
+        };
+        const result = await this.call('/connections', body);
+        return { authorizeUrl: result.authorize_url,
+            flow: { requestId: result.request_id, state, codeVerifier, redirectUri, userId } };
+    }
+    exchange(flow, callback, authenticatedUserId) {
+        if (flow.userId !== authenticatedUserId || callback.get('state') !== flow.state
+            || callback.get('request_id') !== flow.requestId || !callback.get('code')) {
+            throw new ClonePredictionError('invalid_connect_callback', 400);
+        }
+        return this.call('/connections/exchange', {
+            request_id: flow.requestId, user_id: authenticatedUserId, redirect_uri: flow.redirectUri,
+            code_verifier: flow.codeVerifier, code: callback.get('code'),
+        });
+    }
+}
+function base64url(bytes) {
+    return btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function randomToken() { return base64url(crypto.getRandomValues(new Uint8Array(48))); }

package/dist/transport.d.ts

@@ -0,0 +1,15 @@
+import type { PredictionTransport } from './types.js';
+export { ClonePredictionError } from './http.js';
+/** Host-owned diagnostics. Contains no text, user identifiers or credentials. */
+export interface PredictionMetric {
+    durationMs: number;
+    status: number;
+    outcome: 'suggested' | 'abstained' | 'failed' | 'cancelled';
+    code?: string;
+}
+/** Call your own authenticated backend. Never put a Clone app key in a browser. */
+export declare function createPredictionTransport(endpoint: string, options?: {
+    fetch?: typeof fetch;
+    headers?: () => Record<string, string>;
+    onMetric?: (metric: PredictionMetric) => void | Promise<void>;
+}): PredictionTransport;

package/dist/transport.js

@@ -0,0 +1,42 @@
+import { readResponse } from './http.js';
+import { ClonePredictionError } from './http.js';
+export { ClonePredictionError } from './http.js';
+/** Call your own authenticated backend. Never put a Clone app key in a browser. */
+export function createPredictionTransport(endpoint, options = {}) {
+    const request = options.fetch ?? globalThis.fetch;
+    return async (input, { signal }) => {
+        const started = performance.now();
+        let status = 0;
+        let outcome = 'failed';
+        let code;
+        try {
+            const response = await request(endpoint, {
+                method: 'POST', credentials: 'same-origin', signal,
+                headers: { 'Content-Type': 'application/json', ...options.headers?.() },
+                body: JSON.stringify(input),
+            });
+            status = response.status;
+            const output = await readResponse(response);
+            if (output.status !== 'suggested' && output.status !== 'abstained')
+                throw new ClonePredictionError('invalid_response', 502);
+            outcome = output.status === 'abstained' ? 'abstained' : 'suggested';
+            return output;
+        }
+        catch (error) {
+            const timedOut = signal.aborted && (signal.reason instanceof DOMException && signal.reason.name === 'TimeoutError'
+                || signal.reason instanceof ClonePredictionError && signal.reason.code === 'prediction_timeout');
+            if (!timedOut && (signal.aborted || error instanceof DOMException && error.name === 'AbortError'))
+                outcome = 'cancelled';
+            code = timedOut ? 'prediction_timeout' : error instanceof ClonePredictionError ? error.code
+                : outcome === 'cancelled' ? 'cancelled' : 'network_error';
+            throw error;
+        }
+        finally {
+            try {
+                void Promise.resolve(options.onMetric?.({ durationMs: Math.max(0, performance.now() - started),
+                    status, outcome, ...(code ? { code } : {}) })).catch(() => { });
+            }
+            catch { /* Diagnostics never interfere with prediction, input or send. */ }
+        }
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,8 @@
+import type { components } from './generated/api-types.js';
+export type PredictionInput = components['schemas']['PredictionInput'];
+export type PredictionOutput = components['schemas']['PredictionOutput'];
+export type CompletionRequest = Omit<PredictionInput, 'user_id'>;
+export type PredictionEvent = components['schemas']['EventInput'];
+export type PredictionTransport = (request: CompletionRequest, options: {
+    signal: AbortSignal;
+}) => Promise<PredictionOutput>;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/docs/agent-integration.md

@@ -0,0 +1,122 @@
+# Instructions for the customer's integration agent
+
+Implement next-prompt prediction and Tab Completion in the existing customer composer using product context by default, preserving its submission behavior. No Clone end-user account, consent screen or callback is required for this basic path. Offer Clone personalization separately in settings only if desired. Read `README.md`, exported types and `openapi.json`. Do not infer that the customer uses assistant-ui just because the optional adapter exists.
+
+Begin with [start.md](start.md), which covers agent-led self-service app registration and callback updates. This guide supplies the detailed implementation contract for SDK 0.7.0. Verify installed types; 0.3.1 has no typewriter option or Clone mode.
+
+## Prerequisites
+
+- The public `@clone-ai/prompt-prediction@0.7.0` npm package, Node 22.13+, React 18 or 19. Follow the [installation instructions](releases.md#download-and-install). Checksum-verified GitHub archives are also available.
+- A Clone app key (`clnp_...`) for the chosen production or sandbox app and its API base URL. Use an isolated sandbox app for synthetic integration tests. Only optional personalization needs an exact registered HTTPS callback (HTTP loopback is local/test only). The agent obtains these through self-service onboarding; the customer need not prepare them in advance.
+- An existing authenticated customer session and server-side session storage.
+- Only for optional personalization: a Clone test account with selected profile/Goal context already synced. Basic verification needs no Clone test account. Local-only unsynced content is unavailable.
+- When credentials or the customer's auth/session interface are missing, identify that dependency; do not fabricate them or claim a connected test passed.
+
+The app key is required for API verification; a callback and Clone account are required only for optional personalized verification. Missing credentials do not prevent inspection, preparation or deterministic tests. Production installation follows verified company card setup; an explicitly selected sandbox does not require a card. If account access is absent, use [browser/computer-use onboarding](browser-onboarding.md) and request only an authentication or required-consent handoff when needed. If offering personalization, derive and register the callback using the [self-service onboarding procedure](start.md#1-register-your-app-and-settings). The hosted API origin is `https://api.clone.is` unless Clone specifies another environment. No additional service credentials are required for predictions.
+
+## Server integration
+
+Import `CloneClient` and `ConnectionFlow` from `@clone-ai/prompt-prediction/server`. Create the client once in a server-only module:
+
+```ts
+const clone = new CloneClient({ apiKey: process.env.CLONE_APP_KEY!, baseUrl: process.env.CLONE_API_URL! });
+```
+
+Implement the basic routes in your existing authenticated backend. Check your normal CSRF/origin requirements on mutations. Limit body size to 300 KB. Never log request bodies, app keys or completion text. Derive `userId` from the customer's authenticated server session, never from browser input. The app key isolates the customer app; the server identity isolates its users.
+
+| Customer route | Implementation |
+|---|---|
+| POST `/api/clone/predict` | Read typed `CompletionRequest`, call `clone.predict(session.user.id, body, {signal})`. With no optional personalization configured, require `connection_id` to be absent/null. Preserve status and safe `{detail:{code}}` errors. Forward disconnect cancellation. |
+| POST `/api/clone/events` | Read `{event_id, request_id, kind}` and call `clone.recordEvent(session.user.id, body)`. Preserve the same event ID on retries. Do not include message text. Events do not change billing and do not require a Clone connection. |
+
+Basic requests omit `connection_id` or set it to null. Supply recent `messages`, selected `artifact` text and, optionally, up to 4,000 characters of `user_preferences` from the product's own permitted data for this user. Update `context_revision` on preference changes. Basic predictions use the context in that request and do not require a Clone end-user account. Its response has `connection_id: null`, `profile_revision: ""`, and `grant_revision: 0`.
+
+### Optional Clone personalization
+
+Add the following routes only when offering Connect Clone. Place it in optional settings, not in front of the composer. Store connection and flow by the **current authenticated user**, never process-globally.
+
+| Customer route | Implementation |
+|---|---|
+| POST `/api/clone/connect` | `clone.connect(session.user.id, registeredCallbackUrl)`. Keep the returned `flow` in the server session for ten minutes; send only `authorizeUrl` to the browser. |
+| GET your callback | Load and atomically consume the unexpired `flow` from the same session, call `clone.exchange(flow, new URL(request.url).searchParams, session.user.id)`, and persist `connection_id` by user. Reject reused flow; redirect to a clean URL. Set `Cache-Control: no-store` and `Referrer-Policy: no-referrer`. |
+| GET `/api/clone/state` | Return only this user's saved optional connection ID or null. |
+| POST `/api/clone/disconnect` | Clear the client candidate immediately, revoke this user's saved connection through `clone.revoke`, and remove it from server storage after success. New requests can then use product context. Resolve an uncertain revoke with current state before reporting successful disconnection. |
+
+For prediction, match any supplied connection ID to the server session's saved connection before forwarding. Never accept another user's connection from the browser. A request with an explicitly invalid, expired, revoked or stale connection must fail rather than silently switch to basic mode. Clear the unusable connection/candidate; the host can enter basic mode for subsequent newly initiated requests. Do not automatically retry failed personalized work without its connection, create a second billed request, or reuse a request ID across modes.
+
+`CloneClient` overwrites any body `user_id` with the server identity. It does not implement your authentication, CSRF checks, connection storage or session expiry. `ConnectionFlow` contains a PKCE verifier and must stay server-side. Do not embed it in a URL or browser localStorage. See `examples/react/vite.config.ts` in the source bundle for an executable **loopback fixture** backend; its fixed identity and in-memory storage are intentionally unsuitable for production.
+
+Next.js App Router: import the server client only in Route Handlers/server modules; keep the React wrapper in a file beginning `'use client'`. Vite: use the existing server or framework middleware; Vite alone is not an authenticated production backend. Do not move the key into client configuration to get a demo working.
+
+## React integration
+
+Prefer `useTabCompletion({value,onValueChange,context,transport})` if preserving the existing textarea. Attach all `inputProps`, including its ref and composition/select handlers, to the **same native textarea**. Compose host keyboard handlers after the SDK handler, and stop when `event.defaultPrevented`. Render `completion` through your existing ghost-text affordance. For a new textarea use `TabCompletionInput`, which supplies the overlay and accessible description.
+
+For assistant-ui 0.15.21, replace only `ComposerPrimitive.Input` with `CloneComposerInput` from `/assistant-ui` under your existing `ComposerPrimitive.Root` and runtime. Keep `ComposerPrimitive.Send`. Tab never sends; the adapter supports explicit Enter and Shift+Enter newline. Custom Enter behavior can call `preventDefault` in its `onKeyDown` prop. The adapter does not provide assistant-ui mention/upload plugins or autosizing; keep a custom composer through the headless adapter if those are required.
+
+Use `createPredictionTransport('/api/clone/predict')` from the root entry. It uses same-origin credentials and `AbortSignal`; it never retries silently. Keep `session_id` stable for one customer thread. Increment `context_revision` whenever messages, artifact selection/revision, mode or relevant preferences change. Update `connection_id` on account switch/reconnect and clear it on logout/revoke. Draft revisions are maintained by the React hook.
+
+Pass the actual conversation through `context.messages`, including the latest explicitly submitted text and real assistant responses. The example keeps the latest 30 turns and increments the conversation revision on submission, independently of the artifact revision. `ComposerEvents.submitted(text)` returns the submission origin (`human`, `accepted_prediction` or `edited_prediction`) for that message. Preserve the latest correction within the API envelope; do not invent an assistant response or relabel accepted generated text as human-authored. An empty composer immediately after a user sends a message may legitimately receive no suggestion while the host agent is still working.
+
+Debounce defaults to 350 ms; one active client request; default maximum 20 attempts/minute per controller. Eligibility: focused, writable textarea, caret at the end, no selection, no active IME. Tab accepts; Escape dismisses and stops propagation; without a candidate Tab retains normal focus traversal. Stale/aborted/mismatched/expired results are ignored. No Clone connection means product-context prediction remains available. Set `enabled={false}` on host logout; change the session identity/context on host account switches before re-enabling. Omitted connection IDs no longer disable prediction in 0.2.1. Native insertion preserves Chromium Undo; verify the host/browser combination before claiming support.
+
+## Optional automatic sending
+
+Ask whether the customer wants to expose Clone mode separately from manual Tab completion. Use the [Clone mode contract](clone-mode.md), keep it off by default, and show the end user the scope, turn/time limits, full candidate and Stop control. Start only on an explicit user action. Supply the normal authenticated host send callback, bind account/thread/connection identity, stop on typing/IME/hide/logout/context change/error, and call `turnCompleted()` only after the host agent completes and new context is supplied. Submitted messages use `origin: "agent"`, never human acceptance. Unknown send outcomes are not retried. The executable local example is `?clone-mode=1`.
+
+## Observation events
+
+Wire `onEvent` for `presented`, `accepted` and `dismissed`. The host records `edited` only after the user changes an accepted draft, and `submitted` only from its existing successful submission callback. Never send a message to obtain telemetry. The executable example includes `examples/react/composer-events.ts`: observe the pre-insertion value when `accepted` arrives, feed native input changes (and controlled `onValueChange`) to the tracker, and call `submitted(text)` once the host accepts an explicit send. Reset attribution on account, connection, thread or artifact-context changes. The assistant-ui example uses the same input observer and its runtime `onNew` callback.
+
+Use the bubbling `onInput` observer shown in the example. Updating observation state in `onInputCapture` can restore a controlled textarea's old value before its `onChange` handler receives the edit. Test the exact text after the first character typed following Tab, including a space or punctuation, and verify that submitted text reaches the next prediction request.
+
+The example distinguishes the SDK insertion from a later edit, removes attribution after clearing or Undo back to the original draft, and associates a submission with the most recently accepted suggestion. It does not measure how much suggested text remains or every suggestion used in a draft. `presented` means the controller offered a candidate; it does not prove the user read it. Adapt these observation boundaries explicitly if your editor behaves differently. No draft or completion text is included in the transmitted `{event_id, request_id, kind}`.
+
+Telemetry is best effort and must not block input or send. The example shows local `pending`/`recorded`/`failed` delivery receipts; fixture receipts are labelled separately. SDK 0.7.0 uses bounded retries with the same event ID/body; it does not persist a durable retry queue. Reset the tracker on account/context changes to abort old-scope delivery. Report failed/missing deliveries instead of treating them as zero engagement. Verify acceptance without send, edited submission, Undo followed by an unrelated manual send, context change, telemetry failure, duplicate delivery, and unchanged billable usage. These event records alone do not establish coverage, usefulness, suggestion quality or human acceptance.
+
+## Suggestion rendering contract
+
+The prediction endpoint returns one complete JSON object, not SSE or token deltas. `createPredictionTransport` waits for that response, the controller validates it, and the controller validates the complete candidate. By default `useTabCompletion` exposes the full `completion` immediately and `TabCompletionInput` renders it as ghost text. With `presentation: "typewriter"`, the hook exposes a visible prefix until the animation completes; `canAccept` remains false until then. The complete candidate remains in `state.candidate`. This is the default for both empty-composer next prompts and draft completions.
+
+Do not add per-character timers, progressively slice `completion`, or route it through an assistant-message streaming renderer by default. A typewriter animation is an optional presentation choice, not evidence that the API streams. In 0.7.0 set `presentation: "typewriter"` only when the customer's stated preference or an AskUserQuestion answer calls for it; do not ask again for a choice already supplied. The entire candidate must be visible before offering Tab acceptance; never accept only a partial string or send unseen text. Cancel any animation on edits, selection/context changes, dismissal, or expiry. Ordinary manual sending must stay available throughout.
+
+Verify the installed package version and lockfile, inspect the actual composer adapter, and check the response format before attributing progressive display to the SDK or customer code. A recording alone cannot establish which layer produced an effect. Return evidence that the default renderer shows a complete candidate, Tab inserts it exactly once without sending, and only the host's explicit-send action submits it.
+
+## Errors and retry
+
+### Keep the host composer independent of Clone availability
+
+Prediction is optional background work. Never await it in the host's input, attachment, Undo, Enter or send-button path, and never disable the composer while it is loading or unavailable. On Clone network failure, HTTP error, invalid response or abstention, show no candidate and retain the current draft, selection, attachments and normal explicit-send behavior. Keep infrastructure errors in developer diagnostics, not in a blocking end-user dialog.
+
+Do not gate composer mounting, page loading, or the host's send endpoint on Clone health. Keep prediction requests separate from the customer's core send/agent path and bound their backend concurrency so stalled prediction calls cannot exhaust shared request capacity. A Clone outage disables the enhancement; it must not disable the product's composer. This integration contract must be tested in the customer's actual app, not inferred from the SDK demo.
+
+The controller and server client default to a 15-second prediction deadline (`requestTimeoutMs`, at most 30 seconds). Reuse one server `CloneClient` with `maxConcurrentRequests` (default 16) to bound local in-flight calls. Apply suitable host request-body limits, propagate disconnect cancellation, and retain the SDK's stale-result checks. A request that never resolves must still leave typing, editing, focus traversal and sending usable. Recovery must not submit a draft or accept an old candidate. Avoid automatic retry loops and never generate a new paid request merely to hide an unknown transport outcome.
+
+Verify this in the actual host composer by returning 503, 429 and 402 from the Clone proxy, failing its network request, returning malformed JSON, and leaving a request pending. For each case: type and edit text, confirm no stale ghost text, verify candidate-free Tab moves focus, and send the exact draft once through the existing Enter/button flow. Check Undo and IME independently. Restore the prediction route and verify a fresh suggestion can be accepted without sending. These local failure cases do not prove production capacity or a live customer outage test.
+
+| Code / status | Action |
+|---|---|
+| `prediction_in_progress` / 409 | Same ID is in flight; retry the exact body later, never duplicate generation. |
+| `idempotency_conflict` / 409 | Bug: same request ID with different body/user. Fix identity/revision mapping. |
+| `prediction_replay_expired` / 410 | Result recovery window ended. Do not automatically generate a new paid request. |
+| `connection_revoked`, `connection_not_found` / 403 or 404 | Clear the invalid connection/candidate. Resume product-context mode for subsequent user activity; keep reconnect optional. |
+| `context_changed_reconnect` / 409 | Clear the stale personalized candidate. Use product context for subsequent user activity or let the user reconnect and review changed sources. |
+| `sandbox_exhausted`, `monthly_cap_reached` / 402 | Disable predictions, keep normal typing/send; customer must explicitly change plan/cap. |
+| `rate_limited` / 429 | Back off; keep normal input. |
+| `context_too_large`, `latest_message_too_large` / 413 | Reduce artifact summary/selected context; never silently erase latest human correction. |
+| service 502/503/504 | Hide candidate and keep typing. Retry same ID to resolve unknown settlement; terminal failed ID never executes again. |
+| `invalid_response` / 502 | The SDK could not decode an object-shaped JSON response. Keep normal input and inspect the backend; do not retry with a new ID automatically. |
+
+New IDs mean new possible billable work. Retry with the same ID/body if the transport outcome is unknown. Results can be recovered for one hour but accepted for only 60 seconds. Avoid client retry loops on terminal errors. Send errors from Clone through your backend unchanged; network errors should not block your composer.
+
+## Acceptance evidence to return
+
+Use Playwright in the customer's app. Save commit/version, commands, screenshots and network receipts with secrets/text redacted. Cover both nonempty draft and empty next-prompt. Assert displayed suggestion → Tab inserts exactly once → send count unchanged → user's Enter/button sends exactly once. Verify Undo, Escape, candidate-free Tab focus, repeated Tab, Shift+Tab, selection, composition start/end, late response, typing during request, thread/artifact change, logout/reconnect, 402/429/service failure. Browser-dispatched composition events are contract tests, not native OS IME evidence. Do not require additional human real-use sessions or manual QA to finish automated integration. Mark native behavior as unverified if there is no existing evidence for that host/browser.
+
+First verify basic mode without any Clone user session, callback or connection: both draft completion and empty next-prompt must work, events must be attributed only to the authenticated customer user, and quota/cancellation must apply normally. Then, if optional personalization is implemented, verify switching in both directions clears candidates and drops late responses; an explicitly bad connection must fail without an implicit fallback request. Verify connected scope: approved synced profile/Goal only; no unrelated source included; wrong app/user connection rejected; revoke during generation produces no candidate. API tests cover these boundaries, but customer code must also clear local state on account changes. Revocation blocks future/in-flight/replayed server results; an already delivered candidate can exist until the host clears it or its 60-second expiry.
+
+Report installation, fixture interaction, live API call, real customer app, human acceptance and usefulness **separately**. Missing app credentials or service access is an explicit unverified item, not a passing mock. Return observed latency, API usage and charges, including failed/cancelled attempts where receipts exist, and missing-cost count. Do not claim customer adoption, superiority or savings from fixture success.
+
+## Feedback memory
+
+Use the packaged [FeedbackTracker](feedback.md) for host attribution and bounded delivery. Only opt-in edited successful submissions and explicit evaluations enter scoped API memory; ordinary observations do not automatically train preferences.