@hachej/boring-ui-kit 0.1.110 → 0.2.0

package/dist/native-chat.js

@@ -0,0 +1,376 @@
+import { randomUUID } from '@hachej/boring-files/platform';
+function draft(text, attachments, version) {
+    if (typeof text !== 'string' || attachments.some(item => typeof item.id !== 'string' || !item.id || typeof item.name !== 'string'
+        || item.content.type !== 'image' || typeof item.content.data !== 'string' || typeof item.content.mimeType !== 'string'))
+        throw new TypeError('Invalid chat draft');
+    if (new Set(attachments.map(item => item.id)).size !== attachments.length)
+        throw new TypeError('Attachment identifiers must be unique');
+    return Object.freeze({ text, attachments: Object.freeze(attachments.map(item => Object.freeze({ ...item, content: Object.freeze({ ...item.content }) }))), version });
+}
+/** Local presentation/draft state over a borrowed native conversation and one owned native watch. */
+export function createNativeChatController(options) {
+    const { conversation, context } = options;
+    const historySource = options.history === false ? undefined : options.history ?? (options.source ? undefined : conversation);
+    if (historySource && historySource.id !== conversation.id)
+        throw new TypeError('History belongs to another conversation');
+    const readHistory = historySource?.entries.bind(historySource);
+    const emptyHistory = () => Object.freeze({ kind: readHistory ? 'idle' : 'disabled' });
+    const identity = Object.freeze({ runtimeId: options.identity.runtimeId, scopeId: options.identity.scopeId, principalId: options.identity.principalId });
+    if (Object.values(identity).some(value => typeof value !== 'string' || !value))
+        throw new TypeError('Explicit runtime, scope and principal identity are required');
+    let snapshot = { identity, conversationId: conversation.id, connection: { kind: 'idle' },
+        draft: draft('', [], 0), outbox: Object.freeze([]), history: emptyHistory(), send: { kind: 'idle' }, stop: 'idle', disposed: false };
+    const listeners = new Set();
+    let watch, opening, disposing;
+    const publish = (change) => {
+        snapshot = Object.freeze({ ...snapshot, ...change, ...(change.send ? { send: Object.freeze(change.send) } : {}),
+            ...(change.connection ? { connection: Object.freeze(change.connection) } : {}),
+            ...(change.history ? { history: Object.freeze(change.history) } : {}), ...(change.outbox ? { outbox: Object.freeze(change.outbox) } : {}) });
+        for (const listener of [...listeners]) {
+            try {
+                listener();
+            }
+            catch (error) {
+                queueMicrotask(() => { if (options.onListenerError)
+                    options.onListenerError(error);
+                else
+                    throw error; });
+            }
+        }
+    };
+    snapshot = Object.freeze({ ...snapshot, send: Object.freeze(snapshot.send), connection: Object.freeze(snapshot.connection) });
+    const live = () => ({ kind: options.link?.reconnecting() ? 'reconnecting' : 'connected' });
+    const open = () => snapshot.connection.kind === 'connected' || snapshot.connection.kind === 'reconnecting';
+    const unlink = options.link?.subscribe(() => {
+        if (snapshot.disposed || !watch || !open())
+            return;
+        const next = live();
+        if (next.kind !== snapshot.connection.kind)
+            publish({ connection: next });
+    });
+    let stopping, retrying;
+    let historyGeneration = 0, historyPending;
+    let historyScan;
+    const invalidateHistory = () => {
+        historyGeneration++;
+        historyPending = undefined;
+        historyScan = undefined;
+        return emptyHistory();
+    };
+    const acceptView = (view) => {
+        const previous = snapshot.view?.entries;
+        const appendOnly = !previous || previous.every((entry, index) => view.entries[index]?.id === entry.id);
+        publish({ view, ...(!appendOnly ? { history: invalidateHistory() } : {}) });
+    };
+    const stillPending = (attempt) => (snapshot.send.kind === 'unknown' || snapshot.send.kind === 'submitting') && snapshot.send.attempt.requestId === attempt.requestId;
+    const active = () => { if (snapshot.disposed)
+        throw new Error('Chat controller is disposed'); };
+    const editable = () => { active(); return snapshot.draft; };
+    // The composer is emptied when a message is sent, so a confirmation never has to clear it (text typed meanwhile is a new draft).
+    const markAdmitted = (attempt, submissionId, record) => {
+        if (!stillPending(attempt))
+            return;
+        publish({ send: { kind: 'admitted', attempt, submissionId, ...(record ? { record } : {}) } });
+    };
+    /** Messages taken from the composer that wait for the current send (`outbox` in the snapshot). */
+    const waiting = [];
+    let sending = false;
+    /** What goes back into the composer when a sent message is refused (default: the message itself). */
+    const restoreOf = new WeakMap();
+    /**
+     * Puts refused messages back into the composer, followed by every message still waiting behind them (never submitted now) and then
+     * whatever was typed since, one per line.
+     */
+    const restore = (drafts, change = {}) => {
+        const left = waiting.splice(0);
+        for (const item of left)
+            item.resolve(undefined);
+        if (snapshot.disposed)
+            return;
+        const current = snapshot.draft, back = [...drafts, ...left.map(item => item.draft)].map(item => restoreOf.get(item) ?? item);
+        const text = [...back.map(item => item.text), current.text].filter(value => value.trim()).join('\n');
+        const attachments = [...back.flatMap(item => item.attachments), ...current.attachments].filter((item, index, all) => all.findIndex(other => other.id === item.id) === index);
+        publish({ ...change, ...(left.length || snapshot.outbox.length ? { outbox: Object.freeze([]) } : {}), ...(back.length ? { draft: draft(text, attachments, current.version + 1) } : {}) });
+    };
+    function definitelyNotAdmitted(error) {
+        try {
+            return options.definitelyNotAdmitted?.(error) === true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async function submitAttempt(attempt) {
+        publish({ send: { kind: 'submitting', attempt }, ...(!stopping && snapshot.stop !== 'idle' ? { stop: 'idle' } : {}) });
+        if (snapshot.disposed)
+            return;
+        try {
+            const content = attempt.draft.attachments.length
+                ? [{ type: 'text', text: attempt.draft.text }, ...attempt.draft.attachments.map(item => ({ ...item.content }))]
+                : attempt.draft.text;
+            const submission = await conversation.submit({ type: 'input', requestId: attempt.requestId, content, whenBusy: attempt.whenBusy }, context);
+            markAdmitted(attempt, submission.id);
+            return submission;
+        }
+        catch (error) {
+            const denied = definitelyNotAdmitted(error);
+            if (!stillPending(attempt))
+                return;
+            // Refused: the message goes back into the composer. Unknown: it stays held by the attempt for `reconcile`/`retrySameRequest`.
+            if (denied)
+                restore([attempt.draft], { send: { kind: 'blocked', reason: error instanceof Error ? error.message : 'Submission was not admitted' } });
+            else
+                publish({ send: { kind: 'unknown', attempt } });
+            return undefined;
+        }
+    }
+    /** Validates and submits one message; a validation refusal puts it back into the composer. */
+    async function dispatch(item) {
+        const selected = item.draft;
+        publish({ send: { kind: 'validating', draft: selected }, ...(!stopping && snapshot.stop !== 'idle' ? { stop: 'idle' } : {}) });
+        if (snapshot.disposed)
+            return;
+        try {
+            const reason = await options.beforeSubmit?.(selected);
+            if (snapshot.disposed)
+                return;
+            if (reason !== undefined) {
+                restore([selected], { send: { kind: 'blocked', reason: typeof reason === 'string' && reason ? reason : 'Submission validation did not return success' } });
+                return;
+            }
+        }
+        catch (error) {
+            if (!snapshot.disposed)
+                restore([selected], { send: { kind: 'blocked', reason: error instanceof Error ? error.message : 'Submission validation failed' } });
+            return;
+        }
+        if (snapshot.disposed)
+            return;
+        return submitAttempt(Object.freeze({ requestId: randomUUID(), draft: selected, whenBusy: item.whenBusy }));
+    }
+    const controller = {
+        conversation,
+        getSnapshot: () => snapshot,
+        subscribe: (listener) => { if (snapshot.disposed)
+            return () => { }; listeners.add(listener); return () => { listeners.delete(listener); }; },
+        setText: (text) => { const current = editable(); publish({ draft: draft(text, current.attachments, current.version + 1) }); },
+        setAttachments: (attachments) => { const current = editable(); publish({ draft: draft(current.text, attachments, current.version + 1) }); },
+        clearHistory: () => { active(); publish({ history: invalidateHistory() }); },
+        loadEarlier: () => {
+            active();
+            if (!readHistory)
+                throw new Error('Conversation history is not enabled');
+            if (!open())
+                throw new Error('Connect before loading conversation history');
+            if (historyPending)
+                return historyPending;
+            const previous = snapshot.history;
+            if (previous.kind === 'ready' && !previous.hasMore)
+                return Promise.resolve();
+            if (!historyScan) {
+                let maxEntryId;
+                for (const entry of snapshot.view?.entries ?? [])
+                    if (maxEntryId === undefined || entry.id > maxEntryId)
+                        maxEntryId = entry.id;
+                if (maxEntryId === undefined) {
+                    publish({ history: { kind: 'ready', entries: Object.freeze([]), hasMore: false } });
+                    return Promise.resolve();
+                }
+                historyScan = { maxEntryId };
+            }
+            const scan = historyScan, generation = historyGeneration;
+            const entries = 'entries' in previous ? previous.entries : Object.freeze([]);
+            const current = () => !snapshot.disposed && historyGeneration === generation && open();
+            const pending = Promise.resolve().then(async () => {
+                try {
+                    if (!current())
+                        return;
+                    if (historySource?.id !== conversation.id)
+                        throw new Error('History conversation identity changed');
+                    const page = await readHistory({ maxEntryId: scan.maxEntryId }, 40, scan.cursor === undefined ? undefined : structuredClone(scan.cursor), context);
+                    if (!current())
+                        return;
+                    if (historySource?.id !== conversation.id)
+                        throw new Error('History conversation identity changed');
+                    if (page.items.length > 40 || !page.items.length && page.next !== undefined)
+                        throw new Error('History page did not respect its bounds');
+                    let previousId = scan.lastId;
+                    for (const entry of page.items) {
+                        if (entry.id > scan.maxEntryId || previousId !== undefined && entry.id >= previousId)
+                            throw new Error('History page did not progress in native entry order');
+                        previousId = entry.id;
+                    }
+                    const cursor = page.next === undefined ? undefined : structuredClone(page.next);
+                    historyScan = { maxEntryId: scan.maxEntryId, ...(cursor === undefined ? {} : { cursor }), ...(previousId === undefined ? {} : { lastId: previousId }) };
+                    publish({ history: { kind: 'ready', entries: Object.freeze([...page.items].reverse()), hasMore: cursor !== undefined } });
+                }
+                catch (error) {
+                    if (current())
+                        publish({ history: { kind: 'error', entries, hasMore: true, error } });
+                }
+                finally {
+                    if (historyGeneration === generation)
+                        historyPending = undefined;
+                }
+            });
+            historyPending = pending;
+            publish({ history: { kind: 'loading', entries, hasMore: true } });
+            return pending;
+        },
+        connect: () => {
+            active();
+            if (opening)
+                return opening;
+            if (watch)
+                return Promise.resolve();
+            opening = Promise.resolve().then(async () => {
+                try {
+                    const acquired = await (options.source ? options.source.open() : conversation.watch(context));
+                    if (snapshot.disposed) {
+                        await acquired.stop();
+                        return;
+                    }
+                    if (acquired.value.conversation.id !== conversation.id) {
+                        await acquired.stop();
+                        throw new Error('Chat source returned another conversation');
+                    }
+                    watch = acquired;
+                    publish({ connection: live(), view: acquired.value });
+                    acquired.start(async (view) => {
+                        if (snapshot.disposed || watch !== acquired)
+                            return;
+                        if (view.conversation.id !== conversation.id)
+                            throw new Error('Chat source changed conversation identity');
+                        acceptView(view);
+                    });
+                    void acquired.closed.then(end => {
+                        if (watch !== acquired)
+                            return;
+                        watch = undefined;
+                        publish({ connection: { kind: 'closed', end }, history: invalidateHistory() });
+                    });
+                }
+                catch (error) {
+                    if (!snapshot.disposed)
+                        publish({ connection: { kind: 'error', error } });
+                }
+                finally {
+                    opening = undefined;
+                }
+            });
+            publish({ connection: { kind: 'connecting' }, history: invalidateHistory() });
+            return opening;
+        },
+        /**
+         * Sends the composer draft (or `input`) and empties the composer at once. While another send is still being confirmed the message
+         * waits in `outbox` and is submitted, in order, after it. A refused message, and any waiting behind it, go back into the composer
+         * ahead of what was typed since; nothing is dropped or merged into another message. Resolves with the native submission, or
+         * undefined when the message was not admitted (refused, unknown, or the controller was disposed).
+         */
+        send: async (whenBusy = 'followUp', input) => {
+            active();
+            if (snapshot.send.kind === 'unknown')
+                throw new Error('Reconcile the existing submission before sending another');
+            const current = snapshot.draft;
+            const selected = input ? draft(input.text, input.attachments ?? [], 0) : current;
+            if (!selected.text.trim() && !selected.attachments.length) {
+                if (!sending)
+                    publish({ send: { kind: 'blocked', reason: 'Enter a message or attach an image' } });
+                return;
+            }
+            if (input?.restore)
+                restoreOf.set(selected, draft(input.restore.text, input.restore.attachments ?? [], 0));
+            const cleared = input ? {} : { draft: draft('', [], current.version + 1) };
+            if (sending) {
+                return new Promise(resolve => {
+                    waiting.push({ draft: selected, whenBusy, resolve });
+                    publish({ ...cleared, outbox: Object.freeze(waiting.map(item => item.draft)) });
+                });
+            }
+            sending = true;
+            publish(cleared);
+            try {
+                let next = { draft: selected, whenBusy, resolve: () => { } };
+                const first = await dispatch(next);
+                let result = first;
+                while (result && (next = waiting.shift())) {
+                    publish({ outbox: Object.freeze(waiting.map(item => item.draft)) });
+                    result = await dispatch(next);
+                    next.resolve(result);
+                }
+                return first;
+            }
+            finally {
+                sending = false;
+                // Whatever still waits (behind an unknown submission, or after disposal) was never submitted: it goes back into the composer.
+                if (waiting.length)
+                    restore([]);
+            }
+        },
+        reconcile: async () => {
+            active();
+            if (snapshot.send.kind !== 'unknown')
+                throw new Error('No unconfirmed submission to reconcile');
+            const { attempt } = snapshot.send;
+            const record = await conversation.commit(tx => tx.submissionByRequest(conversation.id, attempt.requestId), context);
+            if (record) {
+                if (record.conversationId !== conversation.id || record.requestId !== attempt.requestId || record.type !== 'input')
+                    throw new Error('Native submission lookup returned a different binding');
+                markAdmitted(attempt, record.id, record);
+            }
+            return record;
+        },
+        retrySameRequest: () => {
+            active();
+            if (retrying)
+                return retrying;
+            if (snapshot.send.kind !== 'unknown')
+                throw new Error('No unconfirmed submission to retry');
+            const { attempt } = snapshot.send;
+            retrying = Promise.resolve().then(async () => {
+                try {
+                    const reason = await options.beforeSubmit?.(attempt.draft);
+                    if (reason !== undefined)
+                        throw new Error(typeof reason === 'string' && reason ? reason : 'Submission validation did not return success');
+                    if (snapshot.disposed || !stillPending(attempt))
+                        return;
+                    return await submitAttempt(attempt);
+                }
+                finally {
+                    retrying = undefined;
+                }
+            });
+            return retrying;
+        },
+        stop: () => {
+            active();
+            if (stopping)
+                return stopping;
+            stopping = Promise.resolve().then(async () => {
+                try {
+                    await conversation.abort(context);
+                    publish({ stop: 'confirmed' });
+                }
+                catch (error) {
+                    publish({ stop: 'unconfirmed' });
+                    throw error;
+                }
+                finally {
+                    stopping = undefined;
+                }
+            });
+            publish({ stop: 'requested' });
+            return stopping;
+        },
+        dispose: () => {
+            if (disposing)
+                return disposing;
+            disposing = Promise.resolve().then(async () => { await opening; const owned = watch; watch = undefined; return owned?.stop(); });
+            unlink?.();
+            publish({ disposed: true, connection: { kind: 'closed' }, history: invalidateHistory() });
+            listeners.clear();
+            return disposing;
+        },
+    };
+    return controller;
+}

package/dist/pi.d.ts

@@ -0,0 +1,12 @@
+/** Optional native Pi presentation integration, not part of headless UI root.
+ * Preserve native asynchronous backpressure, exact operations and close reason.
+ */
+import type { ConversationWatch } from '@earendil-works/pi-durable';
+export type { ConversationView, ConversationWatch, WatchEnd } from '@earendil-works/pi-durable';
+export interface ChatSource {
+    /** Host binds authentication/native Context to the selected conversation.
+     * No new SnapshotSubscription or copied native watch lifecycle.
+     */
+    readonly open: (signal?: AbortSignal) => Promise<ConversationWatch>;
+}
+//# sourceMappingURL=pi.d.ts.map

package/dist/pi.js

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

package/dist/public-text-buffer.d.ts

@@ -0,0 +1,5 @@
+export { createTextBuffer } from './text-buffer.js';
+export type { TextBufferOptions, TextBufferSource, TextBufferState } from './text-buffer.js';
+export type TextBuffer = ReturnType<typeof import('./text-buffer.js').createTextBuffer>;
+export type { TextDraft, TextDraftKey, TextDraftRef, TextDraftStore, TextDraftOptions, TextDraftBinding, TextDraftFailure, TextDraftChoice, TextDraftChoiceSelection, TextDraftDiscovery, TextDraftCheckpoint, TextDraftRecoveryState, TextDraftCheckpointResult, TextDraftChoiceFailure, TextDraftActions } from './text-draft-types.js';
+//# sourceMappingURL=public-text-buffer.d.ts.map

package/dist/public-text-buffer.js

@@ -0,0 +1 @@
+export { createTextBuffer } from './text-buffer.js';

package/dist/remote-chat.d.ts

@@ -0,0 +1,76 @@
+import type { Context } from '@earendil-works/chord';
+import type { SubmissionRecord } from '@earendil-works/pi-durable';
+import type { ChatConversation, ChatLink } from './native-chat.js';
+/** Browser client for the `@hachej/boring-agent/chat-transport` handler. Bundles only Chord's standalone delta replay, no Pi runtime. */
+export interface RemoteChatOptions {
+    /** Handler URL. Existing query parameters (for example a conversation selector) are preserved. */
+    readonly endpoint: string | URL;
+    /** The host adds credentials here. */
+    readonly fetch: (request: Request) => Promise<Response>;
+    /** Submission status poll interval for `Submission.wait`. */
+    readonly pollMs?: number;
+    /**
+     * Release the watch stream while the page is hidden and reopen it when visible again (default true; only effective where
+     * `document.visibilityState` exists). Browsers cap concurrent HTTP/1.1 connections per host, so one idle stream per background tab
+     * can starve every other request. A reopened watch begins with a complete view, so nothing is lost. Submissions, answers and
+     * running turns are separate requests and are never affected. Pass false to keep the stream open while hidden.
+     */
+    readonly pauseWhenHidden?: boolean;
+    /**
+     * Backoff for reopening a lost watch stream: the delay doubles from `baseDelayMs` (default 1000) up to `maxDelayMs` (default
+     * 30000), each with random jitter of up to half its length. Reopening stops when the watch is stopped (controller disposed).
+     */
+    readonly reconnect?: {
+        readonly baseDelayMs?: number;
+        readonly maxDelayMs?: number;
+    };
+}
+export interface RemoteChat {
+    /** The members of the native conversation the chat controller uses, served by the remote host. Nothing else is pretended. */
+    readonly conversation: ChatConversation;
+    /** Placeholder for the controller's Context argument. The server owns the real native Context. */
+    readonly context: Context;
+    /** Answer an assistant-entry-bound question ID from the transcript. The host authenticates and resolves it. */
+    readonly answer: (callId: string, answer: string) => Promise<{
+        kind: 'answered';
+    } | {
+        kind: 'denied' | 'conflict' | 'unknown-question';
+        reason?: string;
+    }>;
+    /** Ask the host to change this conversation's model or thinking level. The host decides: a refusal carries its reason. */
+    readonly configure: (change: {
+        readonly model?: {
+            readonly provider: string;
+            readonly modelId: string;
+        };
+        readonly thinkingLevel?: string;
+    }) => Promise<{
+        kind: 'configured';
+    } | {
+        kind: 'refused';
+        reason?: string;
+    }>;
+    /** Stop a watch that the controller never claimed. Safe to call at any time; the controller's own watch is its to stop. */
+    readonly close: () => Promise<void>;
+    /** Withdraw a queued message before it runs. `already_placed` and `settled` mean it was too late. */
+    readonly withdraw: (submissionId: SubmissionRecord['id']) => Promise<'aborted' | 'already_placed' | 'settled'>;
+    /**
+     * True for a `SubmissionRefused` error: the input was definitely not admitted, so the controller shows the host's refusal as a
+     * blocked send instead of reconciling an unknown one. Spreading the remote chat into the controller options passes it.
+     */
+    readonly definitelyNotAdmitted: (error: unknown) => boolean;
+    /** Whether a lost watch stream is being reopened. Spreading the remote chat into the controller options passes it, so the controller reads `reconnecting`. */
+    readonly link: ChatLink;
+}
+/** The host refused a submitted input before it reached the conversation (status 402, `submission-refused`); `message` is the host's words. */
+export declare class SubmissionRefused extends Error {
+    readonly code = "submission-refused";
+    constructor(message: string);
+}
+/**
+ * Connect a browser to one remote native conversation. Resolves after the first view so the conversation identity is the
+ * server's. A dropped or silent stream is reopened automatically with backoff (see `reconnect` and `link`); it never means the
+ * native task stopped.
+ */
+export declare function createRemoteChat(options: RemoteChatOptions): Promise<RemoteChat>;
+//# sourceMappingURL=remote-chat.d.ts.map