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

package/dist/controller.js

@@ -0,0 +1,155 @@
+/** Prediction lifecycle only. It has no submit, agent, or execution API. */
+export class CompletionController {
+    options;
+    input = null;
+    key = '';
+    generation = 0;
+    timer;
+    expiry;
+    animation;
+    deadline;
+    abort;
+    listeners = new Set();
+    requestTimes = [];
+    disposed = false;
+    state = { status: 'idle', candidate: null, error: null, visibleCompletion: '' };
+    constructor(options) {
+        this.options = options;
+    }
+    getSnapshot = () => this.state;
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+    emit(state) {
+        this.state = { ...state, visibleCompletion: state.visibleCompletion ?? state.candidate?.completion ?? '' };
+        for (const listener of this.listeners)
+            listener();
+    }
+    event(request_id, kind) {
+        try {
+            void Promise.resolve(this.options.onEvent?.({ request_id, kind })).catch(() => { });
+        }
+        catch { /* telemetry never controls typing */ }
+    }
+    invalidate(reason) {
+        this.generation++;
+        clearTimeout(this.timer);
+        clearTimeout(this.expiry);
+        clearTimeout(this.animation);
+        clearTimeout(this.deadline);
+        this.abort?.abort(reason);
+        this.abort = undefined;
+    }
+    update(input) {
+        if (this.disposed)
+            return;
+        const nextKey = JSON.stringify(input);
+        if (nextKey === this.key)
+            return;
+        this.key = nextKey;
+        this.input = input;
+        this.invalidate();
+        this.emit({ status: 'idle', candidate: null, error: null });
+        if (input.enabled === false || !input.focused || input.composing
+            || input.selectionStart !== input.value.length || input.selectionEnd !== input.value.length)
+            return;
+        const generation = this.generation;
+        this.timer = setTimeout(() => void this.predict(generation, input), this.options.debounceMs ?? 350);
+    }
+    async predict(generation, input) {
+        this.requestTimes = this.requestTimes.filter(t => Date.now() - t < 60_000);
+        if (this.requestTimes.length >= (this.options.maxRequestsPerMinute ?? 20))
+            return;
+        this.requestTimes.push(Date.now());
+        const abort = new AbortController();
+        this.abort = abort;
+        const request = {
+            ...input.context, connection_id: input.context.connection_id ?? null, request_id: crypto.randomUUID(),
+            mode: input.value ? 'complete_draft' : 'next_prompt', draft: { text: input.value, revision: input.revision },
+        };
+        this.emit({ status: 'loading', candidate: null, error: null });
+        if (generation !== this.generation || this.disposed)
+            return;
+        const timeout = this.options.requestTimeoutMs ?? 15_000;
+        this.deadline = setTimeout(() => {
+            if (generation !== this.generation || this.disposed)
+                return;
+            this.invalidate(new DOMException('Prediction timed out', 'TimeoutError'));
+            this.emit({ status: 'unavailable', candidate: null, error: 'prediction_timeout' });
+        }, Number.isFinite(timeout) ? Math.max(1, Math.min(timeout, 30_000)) : 15_000);
+        try {
+            const candidate = await this.options.transport(request, { signal: abort.signal });
+            if (this.disposed || abort.signal.aborted || generation !== this.generation)
+                return;
+            clearTimeout(this.deadline);
+            if (!candidate || candidate.request_id !== request.request_id
+                || candidate.session_id !== request.session_id || candidate.connection_id !== request.connection_id
+                || candidate.draft_revision !== input.revision || candidate.context_revision !== request.context_revision
+                || !Number.isFinite(candidate.expires_at) || candidate.expires_at * 1000 <= Date.now()) {
+                this.emit({ status: 'idle', candidate: null, error: null });
+                return;
+            }
+            if (candidate.status !== 'suggested' || typeof candidate.completion !== 'string' || !candidate.completion.trim()) {
+                this.emit({ status: 'idle', candidate: null, error: null });
+                return;
+            }
+            if (this.options.presentation === 'typewriter') {
+                const letters = Array.from(new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(candidate.completion), part => part.segment);
+                const start = Date.now();
+                const duration = Math.min(1500, letters.length * 20);
+                const reveal = () => {
+                    if (generation !== this.generation || this.disposed)
+                        return;
+                    const count = Math.min(letters.length, Math.ceil((Date.now() - start) / duration * letters.length));
+                    this.emit({ status: 'suggested', candidate, error: null, visibleCompletion: letters.slice(0, count).join('') });
+                    if (generation !== this.generation || this.disposed)
+                        return;
+                    if (count === letters.length)
+                        this.event(candidate.request_id, 'presented');
+                    else
+                        this.animation = setTimeout(reveal, 20);
+                };
+                reveal();
+            }
+            else {
+                this.emit({ status: 'suggested', candidate, error: null });
+                this.event(candidate.request_id, 'presented');
+            }
+            if (generation !== this.generation || this.disposed)
+                return;
+            this.expiry = setTimeout(() => this.dismiss(false), Math.min(60_000, candidate.expires_at * 1000 - Date.now()));
+        }
+        catch (error) {
+            if (this.disposed || abort.signal.aborted || generation !== this.generation)
+                return;
+            clearTimeout(this.deadline);
+            this.emit({ status: 'unavailable', candidate: null,
+                error: error instanceof Error ? error.message : 'prediction_unavailable' });
+        }
+    }
+    accept() {
+        const candidate = this.state.candidate;
+        const input = this.input;
+        if (!candidate || !input || input.composing || !input.focused || input.enabled === false
+            || input.selectionStart !== input.value.length || input.selectionEnd !== input.value.length
+            || candidate.expires_at * 1000 <= Date.now()
+            || this.state.visibleCompletion !== candidate.completion)
+            return null;
+        this.invalidate();
+        this.emit({ status: 'idle', candidate: null, error: null });
+        this.event(candidate.request_id, 'accepted');
+        return { value: input.value + candidate.completion, suffix: candidate.completion, requestId: candidate.request_id };
+    }
+    dismiss(report = true) {
+        if (report && this.state.candidate)
+            this.event(this.state.candidate.request_id, 'dismissed');
+        this.invalidate();
+        this.emit({ status: 'idle', candidate: null, error: null });
+    }
+    dispose() {
+        this.disposed = true;
+        this.invalidate();
+        this.listeners.clear();
+    }
+}

package/dist/deadline.d.ts

@@ -0,0 +1,2 @@
+/** Includes response-body reads and resolves even if a custom transport ignores abort. */
+export declare function withDeadline<T>(run: (signal: AbortSignal) => Promise<T>, timeoutMs: number, parent?: AbortSignal): Promise<T>;

package/dist/deadline.js

@@ -0,0 +1,25 @@
+import { ClonePredictionError } from './http.js';
+/** Includes response-body reads and resolves even if a custom transport ignores abort. */
+export async function withDeadline(run, timeoutMs, parent) {
+    const controller = new AbortController();
+    let timer;
+    let cancel;
+    const stopped = new Promise((_, reject) => {
+        cancel = () => { controller.abort(); reject(new ClonePredictionError('prediction_cancelled', 499)); };
+        timer = setTimeout(() => {
+            const error = new ClonePredictionError('prediction_timeout', 504);
+            controller.abort(error);
+            reject(error);
+        }, timeoutMs);
+        parent?.addEventListener('abort', cancel, { once: true });
+        if (parent?.aborted)
+            cancel();
+    });
+    try {
+        return await Promise.race([stopped, controller.signal.aborted ? stopped : run(controller.signal)]);
+    }
+    finally {
+        clearTimeout(timer);
+        parent?.removeEventListener('abort', cancel);
+    }
+}

package/dist/feedback.d.ts

@@ -0,0 +1,50 @@
+import type { PredictionEvent } from './types.js';
+export type FeedbackEvent = Omit<PredictionEvent, 'user_id'>;
+export type EventTransport = (event: FeedbackEvent, options: {
+    signal: AbortSignal;
+}) => Promise<void>;
+type Observation = {
+    request_id: string;
+    kind: 'presented' | 'accepted' | 'dismissed';
+};
+export type FeedbackEvaluation = Pick<FeedbackEvent, 'rating' | 'reason' | 'guidance' | 'content_opt_in'>;
+export type FeedbackReceipt = {
+    event_id: string;
+    request_id: string;
+    kind: FeedbackEvent['kind'];
+    observed_at: number;
+    status: 'recorded' | 'failed' | 'cancelled';
+};
+/** Browser -> authenticated host proxy. No app key belongs in this transport. */
+export declare function createEventTransport(url: string, options?: {
+    fetch?: typeof fetch;
+    requestTimeoutMs?: number;
+    maxConcurrentRequests?: number;
+}): EventTransport;
+/** Attribution is local. Text collection is off unless explicitly enabled. */
+export declare class FeedbackTracker {
+    private readonly deliver;
+    private readonly options;
+    private accepted;
+    private scope;
+    constructor(deliver: (event: FeedbackEvent, options: {
+        signal: AbortSignal;
+    }) => unknown, options?: {
+        collectSubmittedText?: boolean;
+        onDelivery?: (receipt: FeedbackReceipt) => unknown;
+    });
+    private emit;
+    observe(event: Observation, before: string): void;
+    input(value: string): void;
+    /** Call only AFTER the host successfully accepts the user's explicit send. */
+    submitted(value: string): 'human' | 'accepted_prediction' | 'edited_prediction';
+    /** An explicit quality decision, separate from Escape, blur and expiry. */
+    rejected(requestId: string, evaluation?: FeedbackEvaluation): string;
+    feedback(requestId: string, evaluation: FeedbackEvaluation): string;
+    private evaluate;
+    /** Caller must observe the actual downstream task result; SDK does not infer it. */
+    outcome(requestId: string, result: 'succeeded' | 'failed'): string;
+    /** Account/thread/connection changes cancel outstanding old-scope delivery. */
+    reset(): void;
+}
+export {};

package/dist/feedback.js

@@ -0,0 +1,118 @@
+import { ClonePredictionError, readResponse } from './http.js';
+import { withDeadline } from './deadline.js';
+/** Browser -> authenticated host proxy. No app key belongs in this transport. */
+export function createEventTransport(url, options = {}) {
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const timeout = options.requestTimeoutMs ?? 2000;
+    const limit = options.maxConcurrentRequests ?? 4;
+    if (!Number.isFinite(timeout) || timeout < 1 || timeout > 30_000 || !Number.isInteger(limit) || limit < 1 || limit > 32) {
+        throw new Error('Invalid feedback transport limits');
+    }
+    let inFlight = 0;
+    return async (event, { signal }) => {
+        if (inFlight >= limit)
+            throw new ClonePredictionError('event_capacity_exceeded', 503);
+        // Serialize once: every retry has exactly the same ID and body.
+        const body = JSON.stringify(event);
+        inFlight++;
+        try {
+            for (let attempt = 0;; attempt++) {
+                try {
+                    await withDeadline(async (boundedSignal) => {
+                        const response = await fetcher(url, { method: 'POST', credentials: 'same-origin', signal: boundedSignal,
+                            headers: { 'Content-Type': 'application/json' }, body });
+                        const result = await readResponse(response);
+                        if (result.status !== 'recorded')
+                            throw new ClonePredictionError('invalid_event_response', 502);
+                    }, timeout, signal);
+                    return;
+                }
+                catch (error) {
+                    const transient = error instanceof TypeError || error instanceof ClonePredictionError
+                        && (error.status === 429 || error.status >= 500) && !error.code.startsWith('invalid_');
+                    if (signal.aborted || !transient || attempt >= 2)
+                        throw error;
+                    await withDeadline(() => new Promise(resolve => setTimeout(resolve, 100 * (attempt + 1))), 1000, signal);
+                }
+            }
+        }
+        finally {
+            inFlight--;
+        }
+    };
+}
+/** Attribution is local. Text collection is off unless explicitly enabled. */
+export class FeedbackTracker {
+    deliver;
+    options;
+    accepted = null;
+    scope = new AbortController();
+    constructor(deliver, options = {}) {
+        this.deliver = deliver;
+        this.options = options;
+    }
+    emit(request_id, kind, values = {}) {
+        const event = { ...values, event_id: crypto.randomUUID(), request_id, kind };
+        const signal = this.scope.signal;
+        const observed_at = Date.now();
+        const receipt = (status) => {
+            try {
+                void Promise.resolve(this.options.onDelivery?.({ event_id: event.event_id, request_id, kind, observed_at, status })).catch(() => { });
+            }
+            catch { /* diagnostics never control typing */ }
+        };
+        try {
+            void Promise.resolve(this.deliver(event, { signal })).then(() => receipt(signal.aborted ? 'cancelled' : 'recorded'), () => receipt(signal.aborted ? 'cancelled' : 'failed'));
+        }
+        catch {
+            receipt(signal.aborted ? 'cancelled' : 'failed');
+        }
+        return event.event_id;
+    }
+    observe(event, before) {
+        if (event.kind === 'accepted')
+            this.accepted = { requestId: event.request_id, before, inserted: null, edited: false };
+        this.emit(event.request_id, event.kind);
+    }
+    input(value) {
+        const accepted = this.accepted;
+        if (!accepted)
+            return;
+        if (accepted.inserted === null) {
+            accepted.inserted = value;
+            return;
+        }
+        if (!value.trim() || value === accepted.before) {
+            this.accepted = null;
+            return;
+        }
+        if (value !== accepted.inserted && !accepted.edited) {
+            accepted.edited = true;
+            this.emit(accepted.requestId, 'edited');
+        }
+    }
+    /** Call only AFTER the host successfully accepts the user's explicit send. */
+    submitted(value) {
+        const accepted = this.accepted;
+        this.accepted = null;
+        if (!accepted || accepted.inserted === null || !value.trim() || value === accepted.before)
+            return 'human';
+        const origin = value === accepted.inserted ? 'accepted_prediction' : 'edited_prediction';
+        this.emit(accepted.requestId, 'submitted', { submission_origin: origin,
+            ...(origin === 'edited_prediction' && this.options.collectSubmittedText && Array.from(value).length <= 4000
+                ? { final_text: value, content_opt_in: true } : {}) });
+        return origin;
+    }
+    /** An explicit quality decision, separate from Escape, blur and expiry. */
+    rejected(requestId, evaluation = {}) { return this.evaluate(requestId, 'rejected', evaluation); }
+    feedback(requestId, evaluation) { return this.evaluate(requestId, 'feedback', evaluation); }
+    evaluate(requestId, kind, evaluation) {
+        if (evaluation.guidance && !evaluation.content_opt_in)
+            throw new Error('Feedback guidance requires content_opt_in');
+        return this.emit(requestId, kind, evaluation);
+    }
+    /** Caller must observe the actual downstream task result; SDK does not infer it. */
+    outcome(requestId, result) { return this.emit(requestId, 'outcome', { outcome: result }); }
+    /** Account/thread/connection changes cancel outstanding old-scope delivery. */
+    reset() { this.accepted = null; this.scope.abort(); this.scope = new AbortController(); }
+}