@beeuni/sdk 0.1.0

package/dist/core/session-sync/session-sync-controller.js

@@ -0,0 +1,440 @@
+import { SandboxNotReadyError, isSandboxNotReadyError } from '../http/runtime-errors.js';
+import { isAbortError } from '../http/abort-error.js';
+import { ApiError } from '../http/api/errors.js';
+const DEFAULT_READ_TIMEOUT_MS = 120_000;
+class SessionSyncReadTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Session history read did not settle within ${timeoutMs}ms`);
+        this.name = 'SessionSyncReadTimeoutError';
+    }
+}
+const TAIL_RETRY_BASE_MS = 1_000;
+const TAIL_RETRY_MAX_MS = 15_000;
+export const SESSION_SYNC_PAGE_SIZE = 100;
+export const SESSION_SYNC_TAIL_PAGE_SIZE = 50;
+export const MAX_TURN_BACKFILL_PAGES = 10;
+export function createHttpSessionSyncPageLoader(options) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const baseUrl = options.baseUrl.replace(/\/$/, '');
+    return async ({ limit, before }, signal) => {
+        const query = new URLSearchParams({ limit: String(limit) });
+        if (before)
+            query.set('before', before);
+        const token = await options.getToken?.();
+        const response = await fetchImpl(`${baseUrl}/session/${encodeURIComponent(options.sessionId)}/message?${query}`, {
+            headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+            ...(signal ? { signal } : {}),
+        });
+        if (!response.ok) {
+            if (response.status === 503) {
+                throw new SandboxNotReadyError(`session ${response.status}`);
+            }
+            throw new ApiError(`Session synchronization failed: ${response.status}`, { status: response.status });
+        }
+        return {
+            messages: (await response.json()),
+            nextCursor: response.headers.get('x-next-cursor') || undefined,
+        };
+    };
+}
+export function loadHttpSessionHistory(options) {
+    return loadCompleteSessionHistory(createHttpSessionSyncPageLoader(options));
+}
+export function createHttpSessionSyncController(options) {
+    return new SessionSyncController({
+        ...options,
+        loadPage: createHttpSessionSyncPageLoader(options),
+    });
+}
+export async function loadCompleteSessionHistory(loadPage) {
+    const pages = [];
+    const cursors = new Set();
+    let before;
+    do {
+        const page = await loadPage({
+            limit: SESSION_SYNC_PAGE_SIZE,
+            ...(before ? { before } : {}),
+        });
+        pages.push(page.messages);
+        before = page.nextCursor;
+        if (before && cursors.has(before)) {
+            throw new Error(`Session history cursor repeated: ${before}`);
+        }
+        if (before)
+            cursors.add(before);
+    } while (before);
+    const ordered = [];
+    const seen = new Set();
+    for (let index = pages.length - 1; index >= 0; index--) {
+        for (const message of pages[index]) {
+            if (seen.has(message.info.id))
+                continue;
+            seen.add(message.info.id);
+            ordered.push(message);
+        }
+    }
+    return ordered;
+}
+const defaultScheduler = {
+    now: Date.now,
+    setInterval: (handler, intervalMs) => setInterval(handler, intervalMs),
+    clearInterval: (handle) => clearInterval(handle),
+    setTimeout: (handler, timeoutMs) => setTimeout(handler, timeoutMs),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+export class SessionSyncController {
+    options;
+    scheduler;
+    livenessIntervalMs;
+    verifyIntervalMs;
+    readTimeoutMs;
+    lastTailReadAt;
+    retryAttempt = 0;
+    tailUnavailable = false;
+    tailRetryTimer;
+    snapshot = {
+        freshness: 'idle',
+        hasOlder: false,
+        isLoadingOlder: false,
+    };
+    nextCursor;
+    knownUserMessageIds = new Set();
+    olderHistoryStarted = false;
+    tailRequest;
+    turnEndPending = false;
+    olderRequest;
+    livenessTimer;
+    livenessBusy = false;
+    streamReliable = false;
+    lastActivityAt;
+    listeners = new Set();
+    destroyed = false;
+    abortController = new AbortController();
+    constructor(options) {
+        this.options = options;
+        this.scheduler = options.scheduler ?? defaultScheduler;
+        this.livenessIntervalMs = options.livenessIntervalMs ?? 10_000;
+        this.verifyIntervalMs = options.verifyIntervalMs ?? 30_000;
+        this.readTimeoutMs = options.readTimeoutMs ?? DEFAULT_READ_TIMEOUT_MS;
+        this.lastActivityAt = this.scheduler.now();
+        this.lastTailReadAt = this.scheduler.now();
+    }
+    getSnapshot = () => this.snapshot;
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+    start() {
+        if (this.snapshot.freshness === 'fresh')
+            return Promise.resolve();
+        return this.reconcile('initial');
+    }
+    reconcile(reason = 'manual') {
+        if (this.destroyed)
+            return Promise.resolve();
+        if (this.tailRequest)
+            return this.tailRequest;
+        this.update({
+            freshness: this.snapshot.freshness === 'idle' || this.snapshot.freshness === 'loading'
+                ? 'loading'
+                : 'stale',
+        });
+        this.tailRequest = this.loadTail(reason).finally(() => {
+            this.tailRequest = undefined;
+        });
+        return this.tailRequest;
+    }
+    loadOlder = () => {
+        if (this.destroyed || !this.nextCursor)
+            return Promise.resolve();
+        if (this.olderRequest)
+            return this.olderRequest;
+        const before = this.nextCursor;
+        this.update({ isLoadingOlder: true });
+        this.olderRequest = this.loadCompleteOlderTurn(before)
+            .then((page) => {
+            if (this.destroyed)
+                return;
+            this.rememberUserMessages(page.messages);
+            this.options.hydrate(page.messages);
+            this.olderHistoryStarted = true;
+            this.setCursor(page.nextCursor);
+        })
+            .finally(() => {
+            this.olderRequest = undefined;
+            this.update({ isLoadingOlder: false });
+        });
+        return this.olderRequest;
+    };
+    noteActivity() {
+        this.lastActivityAt = this.scheduler.now();
+        if (this.snapshot.freshness !== 'fresh') {
+            this.update({ freshness: 'fresh' });
+        }
+    }
+    setStreamReliable(reliable) {
+        this.streamReliable = reliable;
+    }
+    setBusy(isBusy, watchIdle = false) {
+        const turnEnded = this.livenessBusy && !isBusy;
+        this.livenessBusy = isBusy;
+        if (!isBusy && !watchIdle) {
+            this.stopLivenessTimer();
+            if (turnEnded && !this.destroyed)
+                this.reconcileTurnEnd();
+            return;
+        }
+        if (turnEnded && !this.destroyed)
+            this.reconcileTurnEnd();
+        if (this.livenessTimer !== undefined)
+            return;
+        this.lastActivityAt = this.scheduler.now();
+        this.livenessTimer = this.scheduler.setInterval(() => void this.checkLiveness(), this.livenessIntervalMs);
+    }
+    destroy() {
+        this.destroyed = true;
+        this.stopLivenessTimer();
+        if (this.tailRetryTimer !== undefined) {
+            this.cancelTimer(this.tailRetryTimer);
+            this.tailRetryTimer = undefined;
+        }
+        this.abortController.abort();
+        this.listeners.clear();
+    }
+    reconcileTurnEnd() {
+        if (!this.tailRequest) {
+            void this.reconcile('turn-end');
+            return;
+        }
+        if (this.turnEndPending)
+            return;
+        this.turnEndPending = true;
+        void this.tailRequest.finally(() => {
+            this.turnEndPending = false;
+            if (!this.destroyed)
+                void this.reconcile('turn-end');
+        });
+    }
+    async loadTail(reason) {
+        this.lastTailReadAt = this.scheduler.now();
+        try {
+            const page = await this.loadPage('tail', reason);
+            if (this.destroyed)
+                return;
+            this.rememberUserMessages(page.messages);
+            this.options.hydrate(page.messages);
+            if (!this.olderHistoryStarted) {
+                this.setCursor(page.nextCursor);
+            }
+            this.update({ freshness: 'fresh' });
+            this.options.markLoaded();
+            this.retryAttempt = 0;
+            this.tailUnavailable = false;
+        }
+        catch (error) {
+            if (this.destroyed)
+                return;
+            if (this.abortController.signal.aborted)
+                return;
+            const timedOut = error instanceof SessionSyncReadTimeoutError;
+            if (!timedOut && isAbortError(error))
+                return;
+            if (!timedOut) {
+                this.update({ freshness: isSandboxNotReadyError(error) ? 'loading' : 'error' });
+            }
+            if (error instanceof ApiError && (error.status === 404 || error.status === 410)) {
+                this.tailUnavailable = true;
+                this.cancelTimer(this.tailRetryTimer);
+                this.tailRetryTimer = undefined;
+                return;
+            }
+            this.scheduleTailRetry(reason);
+        }
+    }
+    scheduleTailRetry(reason) {
+        if (this.destroyed || this.tailRetryTimer !== undefined)
+            return;
+        const delay = Math.min(TAIL_RETRY_BASE_MS * 2 ** this.retryAttempt, TAIL_RETRY_MAX_MS);
+        this.retryAttempt += 1;
+        this.tailRetryTimer = this.startTimer(() => {
+            this.tailRetryTimer = undefined;
+            if (this.destroyed)
+                return;
+            void this.reconcile(reason);
+        }, delay);
+    }
+    async loadPage(operation, reason, before) {
+        const startedAt = this.scheduler.now();
+        try {
+            const page = await this.boundedRead((signal) => this.options.loadPage({
+                limit: operation === 'tail' ? SESSION_SYNC_TAIL_PAGE_SIZE : SESSION_SYNC_PAGE_SIZE,
+                ...(before ? { before } : {}),
+            }, signal));
+            this.options.onTelemetry?.({
+                operation,
+                reason,
+                durationMs: this.scheduler.now() - startedAt,
+                messageCount: page.messages.length,
+                succeeded: true,
+            });
+            return page;
+        }
+        catch (error) {
+            this.options.onTelemetry?.({
+                operation,
+                reason,
+                durationMs: this.scheduler.now() - startedAt,
+                messageCount: 0,
+                succeeded: false,
+            });
+            throw error;
+        }
+    }
+    boundedRead(read) {
+        const lifetime = this.abortController.signal;
+        const controller = new AbortController();
+        const onLifetimeAbort = () => controller.abort(lifetime.reason);
+        if (lifetime.aborted)
+            controller.abort(lifetime.reason);
+        else
+            lifetime.addEventListener('abort', onLifetimeAbort, { once: true });
+        let timer;
+        const deadline = new Promise((_resolve, reject) => {
+            timer = this.startTimer(() => {
+                const error = new SessionSyncReadTimeoutError(this.readTimeoutMs);
+                reject(error);
+                controller.abort(error);
+            }, this.readTimeoutMs);
+        });
+        let readPromise;
+        try {
+            readPromise = read(controller.signal);
+        }
+        catch (error) {
+            readPromise = Promise.reject(error);
+        }
+        return Promise.race([readPromise, deadline]).finally(() => {
+            this.cancelTimer(timer);
+            lifetime.removeEventListener('abort', onLifetimeAbort);
+        });
+    }
+    async loadCompleteOlderTurn(before) {
+        const firstPage = await this.loadPage('older', 'manual', before);
+        return this.loadCompleteTurn(firstPage, 'older', 'manual', before, (partialPage) => {
+            this.rememberUserMessages(partialPage.messages);
+            this.options.hydrate(partialPage.messages);
+            this.setCursor(partialPage.nextCursor);
+        });
+    }
+    async loadCompleteTurn(firstPage, operation, reason, initialCursor, onPage) {
+        const messages = [...firstPage.messages];
+        const knownUserMessageIds = new Set(this.knownUserMessageIds);
+        const seenCursors = new Set(initialCursor ? [initialCursor] : []);
+        let cursor = firstPage.nextCursor;
+        let pagesRead = 0;
+        for (const message of firstPage.messages) {
+            if (message.info.role === 'user') {
+                knownUserMessageIds.add(message.info.id);
+            }
+        }
+        while (cursor &&
+            pagesRead < MAX_TURN_BACKFILL_PAGES &&
+            messages.some((message) => message.info.role === 'assistant' &&
+                Boolean(message.info.parentID) &&
+                !knownUserMessageIds.has(message.info.parentID))) {
+            if (seenCursors.has(cursor)) {
+                throw new Error(`Session history cursor repeated: ${cursor}`);
+            }
+            seenCursors.add(cursor);
+            let page;
+            try {
+                page = await this.loadPage(operation, reason, cursor);
+            }
+            catch (error) {
+                onPage?.({ messages: [...messages], nextCursor: cursor });
+                throw error;
+            }
+            if (this.destroyed)
+                return { messages, nextCursor: cursor };
+            pagesRead += 1;
+            messages.unshift(...page.messages);
+            for (const message of page.messages) {
+                if (message.info.role === 'user') {
+                    knownUserMessageIds.add(message.info.id);
+                }
+            }
+            cursor = page.nextCursor;
+            onPage?.({ messages: [...messages], nextCursor: cursor });
+        }
+        return { messages, nextCursor: cursor };
+    }
+    rememberUserMessages(messages) {
+        for (const message of messages) {
+            if (message.info.role === 'user') {
+                this.knownUserMessageIds.add(message.info.id);
+            }
+        }
+    }
+    async checkLiveness() {
+        if (this.destroyed || this.tailUnavailable || this.streamReliable)
+            return;
+        const nowMs = this.scheduler.now();
+        const quiet = nowMs - this.lastActivityAt > this.livenessIntervalMs;
+        const verifyDue = nowMs - this.lastTailReadAt >= this.verifyIntervalMs;
+        if (!(this.livenessBusy && quiet) && !verifyDue)
+            return;
+        await this.raceDeadline(this.reconcile('poll'), this.livenessIntervalMs);
+        this.lastActivityAt = this.scheduler.now();
+    }
+    raceDeadline(work, timeoutMs) {
+        return new Promise((resolve) => {
+            let handle;
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.cancelTimer(handle);
+                resolve();
+            };
+            handle = this.startTimer(finish, timeoutMs);
+            void work.then(finish, finish);
+        });
+    }
+    setCursor(cursor) {
+        this.nextCursor = cursor;
+        this.update({ hasOlder: Boolean(cursor) });
+    }
+    stopLivenessTimer() {
+        if (this.livenessTimer === undefined)
+            return;
+        this.scheduler.clearInterval(this.livenessTimer);
+        this.livenessTimer = undefined;
+    }
+    startTimer(handler, delayMs) {
+        return this.scheduler.setTimeout
+            ? this.scheduler.setTimeout(handler, delayMs)
+            : setTimeout(handler, delayMs);
+    }
+    cancelTimer(handle) {
+        if (handle === undefined)
+            return;
+        if (this.scheduler.clearTimeout) {
+            this.scheduler.clearTimeout(handle);
+        }
+        else {
+            clearTimeout(handle);
+        }
+    }
+    update(next) {
+        const snapshot = { ...this.snapshot, ...next };
+        if (snapshot.freshness === this.snapshot.freshness &&
+            snapshot.hasOlder === this.snapshot.hasOlder &&
+            snapshot.isLoadingOlder === this.snapshot.isLoadingOlder) {
+            return;
+        }
+        this.snapshot = snapshot;
+        for (const listener of this.listeners)
+            listener();
+    }
+}

package/dist/core/stream/chat-events.d.ts

@@ -0,0 +1,96 @@
+import type { Message, Part, QuestionAnswer, SessionStatus, Todo } from '../runtime/client.js';
+import type { RuntimeEvent } from './event-stream.js';
+export interface BeeuniChatEventMessageUpdated {
+    type: 'message.updated';
+    sessionID: string;
+    message: Message;
+}
+export interface BeeuniChatEventMessageRemoved {
+    type: 'message.removed';
+    sessionID: string;
+    messageID: string;
+}
+export interface BeeuniChatEventPartUpdated {
+    type: 'message.part.updated';
+    sessionID: string;
+    part: Part;
+}
+export interface BeeuniChatEventPartRemoved {
+    type: 'message.part.removed';
+    sessionID: string;
+    messageID: string;
+    partID: string;
+}
+export interface BeeuniChatEventSessionStatus {
+    type: 'session.status';
+    sessionID: string;
+    status: SessionStatus;
+}
+export interface BeeuniChatEventSessionIdle {
+    type: 'session.idle';
+    sessionID: string;
+}
+export interface BeeuniChatEventSessionError {
+    type: 'session.error';
+    sessionID?: string;
+    error?: unknown;
+}
+export interface BeeuniChatQuestionOption {
+    label: string;
+    description: string;
+}
+export interface BeeuniChatQuestionInfo {
+    question: string;
+    header: string;
+    options: BeeuniChatQuestionOption[];
+    multiple?: boolean;
+    custom?: boolean;
+}
+export interface BeeuniChatToolRef {
+    messageID: string;
+    callID: string;
+}
+export interface BeeuniChatEventQuestionAsked {
+    type: 'question.asked';
+    sessionID: string;
+    requestID: string;
+    questions: BeeuniChatQuestionInfo[];
+    tool?: BeeuniChatToolRef;
+}
+export interface BeeuniChatEventQuestionAnswered {
+    type: 'question.answered';
+    sessionID: string;
+    requestID: string;
+    outcome: 'replied' | 'rejected';
+    answers?: QuestionAnswer[];
+}
+export interface BeeuniChatEventPermissionAsked {
+    type: 'permission.asked';
+    sessionID: string;
+    requestID: string;
+    permission: string;
+    patterns: string[];
+    tool?: BeeuniChatToolRef;
+}
+export interface BeeuniChatEventPermissionReplied {
+    type: 'permission.replied';
+    sessionID: string;
+    requestID: string;
+    reply: 'once' | 'always' | 'reject';
+}
+export interface BeeuniChatEventTodoUpdated {
+    type: 'todo.updated';
+    sessionID: string;
+    todos: Todo[];
+}
+export interface BeeuniChatEventConnection {
+    type: 'connection';
+    status: 'connected';
+}
+export interface BeeuniChatEventHeartbeatGap {
+    type: 'heartbeat-gap';
+    gapMs: number;
+}
+export type BeeuniChatEvent = BeeuniChatEventMessageUpdated | BeeuniChatEventMessageRemoved | BeeuniChatEventPartUpdated | BeeuniChatEventPartRemoved | BeeuniChatEventSessionStatus | BeeuniChatEventSessionIdle | BeeuniChatEventSessionError | BeeuniChatEventQuestionAsked | BeeuniChatEventQuestionAnswered | BeeuniChatEventPermissionAsked | BeeuniChatEventPermissionReplied | BeeuniChatEventTodoUpdated | BeeuniChatEventConnection | BeeuniChatEventHeartbeatGap;
+export declare function heartbeatGapEvent(gapMs: number): BeeuniChatEventHeartbeatGap;
+export declare function narrowChatEvent(event: RuntimeEvent): BeeuniChatEvent | null;

package/dist/core/stream/chat-events.js

@@ -0,0 +1,95 @@
+export function heartbeatGapEvent(gapMs) {
+    return { type: 'heartbeat-gap', gapMs };
+}
+export function narrowChatEvent(event) {
+    switch (event.type) {
+        case 'message.updated':
+            return {
+                type: 'message.updated',
+                sessionID: event.properties.sessionID,
+                message: event.properties.info,
+            };
+        case 'message.removed':
+            return {
+                type: 'message.removed',
+                sessionID: event.properties.sessionID,
+                messageID: event.properties.messageID,
+            };
+        case 'message.part.updated':
+            return {
+                type: 'message.part.updated',
+                sessionID: event.properties.sessionID,
+                part: event.properties.part,
+            };
+        case 'message.part.removed':
+            return {
+                type: 'message.part.removed',
+                sessionID: event.properties.sessionID,
+                messageID: event.properties.messageID,
+                partID: event.properties.partID,
+            };
+        case 'session.status':
+            return {
+                type: 'session.status',
+                sessionID: event.properties.sessionID,
+                status: event.properties.status,
+            };
+        case 'session.idle':
+            return { type: 'session.idle', sessionID: event.properties.sessionID };
+        case 'session.error':
+            return {
+                type: 'session.error',
+                sessionID: event.properties.sessionID,
+                error: event.properties.error,
+            };
+        case 'question.asked':
+            return {
+                type: 'question.asked',
+                sessionID: event.properties.sessionID,
+                requestID: event.properties.id,
+                questions: event.properties.questions,
+                tool: event.properties.tool,
+            };
+        case 'question.replied':
+            return {
+                type: 'question.answered',
+                sessionID: event.properties.sessionID,
+                requestID: event.properties.requestID,
+                outcome: 'replied',
+                answers: event.properties.answers,
+            };
+        case 'question.rejected':
+            return {
+                type: 'question.answered',
+                sessionID: event.properties.sessionID,
+                requestID: event.properties.requestID,
+                outcome: 'rejected',
+            };
+        case 'permission.asked':
+            return {
+                type: 'permission.asked',
+                sessionID: event.properties.sessionID,
+                requestID: event.properties.id,
+                permission: event.properties.permission,
+                patterns: event.properties.patterns,
+                tool: event.properties.tool,
+            };
+        case 'permission.replied':
+            return {
+                type: 'permission.replied',
+                sessionID: event.properties.sessionID,
+                requestID: event.properties.requestID,
+                reply: event.properties.reply,
+            };
+        case 'todo.updated':
+            return {
+                type: 'todo.updated',
+                sessionID: event.properties.sessionID,
+                todos: event.properties.todos,
+            };
+        case 'server.connected':
+            return { type: 'connection', status: 'connected' };
+        default:
+            return null;
+    }
+}

package/dist/core/stream/event-stream.d.ts

@@ -0,0 +1,52 @@
+import type { Event as OpenCodeSdkEvent } from '../runtime/runtime-types.js';
+export type RuntimeEvent = OpenCodeSdkEvent | {
+    id: string;
+    type: 'lsp.client.diagnostics';
+    properties: {
+        serverID: string;
+        path: string;
+    };
+};
+export interface EventStreamClient {
+    global: {
+        event: (opts: {
+            signal: AbortSignal;
+            sseDefaultRetryDelay?: number;
+            sseMaxRetryDelay?: number;
+            sseMaxRetryAttempts?: number;
+        }) => Promise<{
+            stream: AsyncIterable<unknown>;
+        }>;
+    };
+}
+export type EventStreamTimerHandle = ReturnType<typeof setTimeout>;
+export interface EventStreamTimers {
+    now: () => number;
+    setTimeout: (handler: () => void, timeoutMs?: number) => EventStreamTimerHandle;
+    clearTimeout: (handle: EventStreamTimerHandle | undefined) => void;
+    random?: () => number;
+}
+export interface OpenEventStreamOptions {
+    url?: string;
+    client?: EventStreamClient;
+    onEvent: (event: RuntimeEvent) => void;
+    onGapRehydrate?: (gapMs: number) => void;
+    signal?: AbortSignal;
+    connectTimeoutMs?: number;
+    heartbeatTimeoutMs?: number;
+    maxConsecutiveHardFailures?: number;
+    onParked?: (reason: EventStreamParkedInfo) => void;
+    onConnectionChange?: (state: EventStreamConnectionState) => void;
+    timers?: EventStreamTimers;
+}
+export type EventStreamConnectionState = 'connecting' | 'open' | 'lost';
+export interface EventStreamParkedInfo {
+    consecutiveFailures: number;
+    lastError: unknown;
+}
+export interface EventStreamHandle {
+    close: () => void;
+}
+export declare function openEventStream(opts: OpenEventStreamOptions): EventStreamHandle;
+export { heartbeatGapEvent, narrowChatEvent, type BeeuniChatEvent, type BeeuniChatEventConnection, type BeeuniChatEventHeartbeatGap, type BeeuniChatEventMessageRemoved, type BeeuniChatEventMessageUpdated, type BeeuniChatEventPartRemoved, type BeeuniChatEventPartUpdated, type BeeuniChatEventPermissionAsked, type BeeuniChatEventPermissionReplied, type BeeuniChatEventQuestionAnswered, type BeeuniChatEventQuestionAsked, type BeeuniChatEventSessionError, type BeeuniChatEventSessionIdle, type BeeuniChatEventSessionStatus, type BeeuniChatEventTodoUpdated, type BeeuniChatQuestionInfo, type BeeuniChatQuestionOption, type BeeuniChatToolRef, } from './chat-events.js';
+export type OpenCodeEvent = RuntimeEvent;