@beeuni/sdk 0.1.0

package/dist/core/session/control-stream.d.ts

@@ -0,0 +1,62 @@
+import type { SessionPrompt } from '../rest/projects-client/sessions.js';
+import type { RuntimeEvent } from '../stream/event-stream.js';
+export interface SessionControlQueue {
+    known: boolean;
+    prompts: SessionPrompt[];
+    held: boolean;
+    observed_at?: string;
+}
+export interface SessionControlFrame {
+    type: string;
+    cseq: number;
+    cepoch: string;
+    at: number;
+    payload: unknown;
+}
+export interface SessionRuntimeStatus {
+    state: 'up' | 'down';
+    reason: string | null;
+}
+export interface SessionControlStreamTiming {
+    backoffMs?: readonly number[];
+    livenessMs?: number;
+}
+export interface SessionControlStreamOptions {
+    projectId: string;
+    sessionId: string;
+    runtime?: boolean;
+    tabId?: string;
+    onQueue?: (queue: SessionControlQueue) => void;
+    onControl?: (frame: SessionControlFrame) => void;
+    onRuntimeEvent?: (event: RuntimeEvent) => void;
+    onRuntimeStatus?: (status: SessionRuntimeStatus) => void;
+    onRuntimeHealth?: (health: Record<string, unknown>) => void;
+    onRuntimeResync?: () => void;
+    onHeartbeat?: () => void;
+    onConnectionChange?: (connected: boolean) => void;
+    timing?: SessionControlStreamTiming;
+}
+export type SessionStreamOptions = SessionControlStreamOptions;
+export interface SessionControlStreamHandle {
+    connected: () => boolean;
+    lastQueue: () => SessionControlQueue | null;
+    lastControl: (type: string) => SessionControlFrame | null;
+    close: () => void;
+}
+export declare function openSessionStream(options: SessionControlStreamOptions): SessionControlStreamHandle;
+export declare const openSessionControlStream: typeof openSessionStream;
+export declare function sessionStreamConnected(projectId: string, sessionId: string): boolean;
+export declare function subscribeSessionStreamConnections(listener: () => void): () => void;
+export declare function __resetSessionControlStreamsForTests(): void;
+export interface SessionStreamEventClient {
+    global: {
+        event: (options: {
+            signal: AbortSignal;
+        }) => Promise<{
+            stream: AsyncIterable<unknown>;
+        }>;
+    };
+}
+export declare function sessionStreamEventClient(projectId: string, sessionId: string, hooks?: {
+    onResync?: () => void;
+}): SessionStreamEventClient;

package/dist/core/session/control-stream.js

@@ -0,0 +1,329 @@
+import { platformConfig } from '../http/config.js';
+import { platformEventTransport } from '../stream/platform-event-transport.js';
+const BACKOFF_MS = [1_000, 2_000, 5_000, 10_000, 20_000, 30_000];
+const LIVENESS_MS = 45_000;
+const streams = new Map();
+export function openSessionStream(options) {
+    const key = `${options.projectId}/${options.sessionId}`;
+    let shared = streams.get(key);
+    if (!shared) {
+        shared = {
+            subscribers: new Set(),
+            connected: false,
+            lastQueue: null,
+            latest: new Map(),
+            lastStatus: null,
+            lastHealth: null,
+            runtimeRefs: 0,
+            connectedWithRuntime: false,
+            tabId: null,
+            authoritative: false,
+            reconnectNow: false,
+            attempt: null,
+            abort: new AbortController(),
+        };
+        streams.set(key, shared);
+    }
+    const target = shared;
+    const opening = target.subscribers.size === 0 && !target.attempt;
+    target.subscribers.add(options);
+    let reconnect = false;
+    if (options.runtime) {
+        target.runtimeRefs += 1;
+        if (!target.connectedWithRuntime)
+            reconnect = true;
+    }
+    if (options.tabId && target.tabId !== options.tabId) {
+        target.tabId = options.tabId;
+        reconnect = true;
+    }
+    if (reconnect && !opening && target.attempt) {
+        target.reconnectNow = true;
+        target.attempt.abort();
+    }
+    if (opening)
+        void run(options, target);
+    if (target.connected)
+        options.onConnectionChange?.(true);
+    for (const frame of [...target.latest.values()].sort((a, b) => a.cseq - b.cseq)) {
+        safely(() => options.onControl?.(frame));
+    }
+    if (target.lastQueue)
+        safely(() => options.onQueue?.(target.lastQueue));
+    if (options.runtime && target.lastStatus)
+        safely(() => options.onRuntimeStatus?.(target.lastStatus));
+    if (options.runtime && target.lastHealth)
+        safely(() => options.onRuntimeHealth?.(target.lastHealth));
+    let closed = false;
+    return {
+        connected: () => target.connected,
+        lastQueue: () => target.lastQueue,
+        lastControl: (type) => target.latest.get(type) ?? null,
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            target.subscribers.delete(options);
+            if (options.runtime)
+                target.runtimeRefs -= 1;
+            if (target.subscribers.size > 0)
+                return;
+            target.abort.abort();
+            if (streams.get(key) === target)
+                streams.delete(key);
+            if (target.connected) {
+                target.connected = false;
+                for (const listener of [...connectionListeners])
+                    safely(listener);
+            }
+        },
+    };
+}
+export const openSessionControlStream = openSessionStream;
+export function sessionStreamConnected(projectId, sessionId) {
+    const shared = streams.get(`${projectId}/${sessionId}`);
+    return shared?.connected === true && shared.authoritative;
+}
+const connectionListeners = new Set();
+export function subscribeSessionStreamConnections(listener) {
+    connectionListeners.add(listener);
+    return () => {
+        connectionListeners.delete(listener);
+    };
+}
+function safely(fn) {
+    try {
+        fn();
+    }
+    catch {
+    }
+}
+function each(shared, fn) {
+    for (const subscriber of [...shared.subscribers])
+        safely(() => fn(subscriber));
+}
+function setConnected(shared, connected) {
+    if (shared.connected === connected)
+        return;
+    shared.connected = connected;
+    each(shared, (subscriber) => subscriber.onConnectionChange?.(connected));
+    for (const listener of [...connectionListeners])
+        safely(listener);
+}
+async function run(options, shared) {
+    const backoff = options.timing?.backoffMs ?? BACKOFF_MS;
+    const livenessMs = options.timing?.livenessMs ?? LIVENESS_MS;
+    const stop = shared.abort.signal;
+    let cseq = null;
+    let cepoch = null;
+    let seq = null;
+    let epoch = null;
+    let failures = 0;
+    while (!stop.aborted) {
+        const attempt = new AbortController();
+        shared.attempt = attempt;
+        const end = () => attempt.abort();
+        stop.addEventListener('abort', end);
+        let watchdog;
+        const arm = () => {
+            clearTimeout(watchdog);
+            watchdog = setTimeout(end, livenessMs);
+        };
+        arm();
+        const withRuntime = shared.runtimeRefs > 0;
+        shared.connectedWithRuntime = withRuntime;
+        try {
+            const url = new URL(`${platformConfig().backendUrl.replace(/\/$/, '')}/projects/${encodeURIComponent(options.projectId)}/sessions/${encodeURIComponent(options.sessionId)}/events`);
+            if (!withRuntime)
+                url.searchParams.set('channels', 'control');
+            if (shared.tabId)
+                url.searchParams.set('tab_id', shared.tabId);
+            if (withRuntime && seq !== null && epoch) {
+                url.searchParams.set('since', String(seq));
+                url.searchParams.set('epoch', epoch);
+            }
+            if (cseq !== null && cepoch) {
+                url.searchParams.set('since_control', String(cseq));
+                url.searchParams.set('cepoch', cepoch);
+            }
+            const messages = platformEventTransport({
+                url: url.href,
+                headers: new Headers({ Accept: 'text/event-stream' }),
+                signal: attempt.signal,
+            });
+            for await (const message of messages) {
+                if (attempt.signal.aborted)
+                    break;
+                arm();
+                if (message.data === undefined)
+                    continue;
+                let frame;
+                try {
+                    frame = JSON.parse(message.data);
+                }
+                catch {
+                    continue;
+                }
+                failures = 0;
+                setConnected(shared, true);
+                const type = typeof frame.type === 'string' ? frame.type : '';
+                if (frame.channel === 'runtime') {
+                    if (type === 'beeuni.resync') {
+                        seq = null;
+                        epoch = typeof frame.epoch === 'string' ? frame.epoch : null;
+                        each(shared, (subscriber) => subscriber.onRuntimeResync?.());
+                        continue;
+                    }
+                    if (typeof frame.epoch === 'string')
+                        epoch = frame.epoch;
+                    if (typeof frame.seq === 'number')
+                        seq = frame.seq;
+                    if (!type || type.startsWith('beeuni.') || typeof frame.seq !== 'number')
+                        continue;
+                    const event = {
+                        id: `${epoch ?? ''}:${frame.seq}`,
+                        type,
+                        properties: frame.payload,
+                    };
+                    each(shared, (subscriber) => {
+                        if (subscriber.runtime)
+                            subscriber.onRuntimeEvent?.(event);
+                    });
+                    continue;
+                }
+                if (type === 'beeuni.stream.heartbeat') {
+                    each(shared, (subscriber) => subscriber.onHeartbeat?.());
+                    continue;
+                }
+                if (type === 'beeuni.runtime.status') {
+                    const status = {
+                        state: frame.state === 'up' ? 'up' : 'down',
+                        reason: typeof frame.reason === 'string' ? frame.reason : null,
+                    };
+                    shared.lastStatus = status;
+                    each(shared, (subscriber) => {
+                        if (subscriber.runtime)
+                            subscriber.onRuntimeStatus?.(status);
+                    });
+                    continue;
+                }
+                if (type === 'beeuni.runtime.health') {
+                    const health = (frame.health ?? null);
+                    if (!health)
+                        continue;
+                    shared.lastHealth = health;
+                    each(shared, (subscriber) => {
+                        if (subscriber.runtime)
+                            subscriber.onRuntimeHealth?.(health);
+                    });
+                    continue;
+                }
+                if (type === 'beeuni.control.resync') {
+                    cseq = null;
+                    cepoch = typeof frame.cepoch === 'string' ? frame.cepoch : null;
+                    continue;
+                }
+                if (frame.channel !== 'control' || typeof frame.cseq !== 'number')
+                    continue;
+                cseq = frame.cseq;
+                cepoch = typeof frame.cepoch === 'string' ? frame.cepoch : cepoch;
+                const control = {
+                    type,
+                    cseq: frame.cseq,
+                    cepoch: cepoch ?? '',
+                    at: typeof frame.at === 'number' ? frame.at : Date.now(),
+                    payload: frame.payload,
+                };
+                shared.latest.set(type, control);
+                if (type === 'beeuni.control.session' && !shared.authoritative) {
+                    shared.authoritative = true;
+                    for (const listener of [...connectionListeners])
+                        safely(listener);
+                }
+                each(shared, (subscriber) => subscriber.onControl?.(control));
+                const payload = frame.payload;
+                if (type === 'beeuni.control.queue' && payload?.known && Array.isArray(payload.prompts)) {
+                    shared.lastQueue = payload;
+                    each(shared, (subscriber) => subscriber.onQueue?.(payload));
+                }
+            }
+        }
+        catch {
+        }
+        finally {
+            clearTimeout(watchdog);
+            stop.removeEventListener('abort', end);
+        }
+        if (stop.aborted)
+            break;
+        if (shared.reconnectNow) {
+            shared.reconnectNow = false;
+            continue;
+        }
+        setConnected(shared, false);
+        const delay = backoff[Math.min(failures, backoff.length - 1)] ?? 1_000;
+        failures += 1;
+        await new Promise((resolve) => {
+            const timer = setTimeout(done, delay);
+            function done() {
+                clearTimeout(timer);
+                stop.removeEventListener('abort', done);
+                resolve();
+            }
+            stop.addEventListener('abort', done);
+        });
+    }
+}
+export function __resetSessionControlStreamsForTests() {
+    for (const shared of streams.values())
+        shared.abort.abort();
+    streams.clear();
+}
+const eventClients = new Map();
+export function sessionStreamEventClient(projectId, sessionId, hooks = {}) {
+    const key = `${projectId}/${sessionId}`;
+    if (!hooks.onResync) {
+        const cached = eventClients.get(key);
+        if (cached)
+            return cached;
+    }
+    async function* iterate(signal) {
+        const queue = [];
+        let wake = () => { };
+        const handle = openSessionStream({
+            projectId,
+            sessionId,
+            runtime: true,
+            onRuntimeEvent: (event) => {
+                queue.push(event);
+                wake();
+            },
+            onRuntimeResync: () => hooks.onResync?.(),
+        });
+        const onAbort = () => wake();
+        signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            while (!signal.aborted) {
+                if (queue.length === 0) {
+                    await new Promise((resolve) => {
+                        wake = resolve;
+                    });
+                    continue;
+                }
+                yield queue.shift();
+            }
+        }
+        finally {
+            signal.removeEventListener('abort', onAbort);
+            handle.close();
+        }
+    }
+    const client = {
+        global: {
+            event: async ({ signal }) => ({ stream: iterate(signal) }),
+        },
+    };
+    if (!hooks.onResync)
+        eventClients.set(key, client);
+    return client;
+}

package/dist/core/session/current-runtime.d.ts

@@ -0,0 +1,14 @@
+export interface CurrentRuntimeState {
+    url: string | null;
+    sandboxId: string | null;
+    dbSandboxId: string | null;
+    version: number;
+}
+export declare const currentRuntimeStore: {
+    getState(): CurrentRuntimeState;
+    subscribe(listener: () => void): () => void;
+};
+export declare function setCurrentRuntime(url: string | null, sandboxId?: string | null, dbSandboxId?: string | null): void;
+export declare function getCurrentRuntimeUrl(): string | null;
+export declare function getCurrentRuntimeSandboxId(): string | null;
+export declare function getCurrentRuntimeDbSandboxId(): string | null;

package/dist/core/session/current-runtime.js

@@ -0,0 +1,34 @@
+let state = {
+    url: null,
+    sandboxId: null,
+    dbSandboxId: null,
+    version: 0,
+};
+const listeners = new Set();
+export const currentRuntimeStore = {
+    getState() {
+        return state;
+    },
+    subscribe(listener) {
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+        };
+    },
+};
+export function setCurrentRuntime(url, sandboxId = null, dbSandboxId = null) {
+    if (state.url === url && state.sandboxId === sandboxId && state.dbSandboxId === dbSandboxId)
+        return;
+    state = { url, sandboxId, dbSandboxId, version: state.version + 1 };
+    for (const listener of listeners)
+        listener();
+}
+export function getCurrentRuntimeUrl() {
+    return state.url;
+}
+export function getCurrentRuntimeSandboxId() {
+    return state.sandboxId;
+}
+export function getCurrentRuntimeDbSandboxId() {
+    return state.dbSandboxId;
+}

package/dist/core/session/health.d.ts

@@ -0,0 +1,41 @@
+export type SessionHealthResponse = {
+    status?: string;
+    runtimeReady?: boolean;
+    version?: string;
+    harness?: {
+        id: string;
+        version: string | null;
+        state: string;
+        ready: boolean;
+        error: string | null;
+        session: {
+            id: string | null;
+            required: boolean;
+        };
+        turn: {
+            in_flight: boolean | null;
+            end: string | null;
+            orphaned_prompt: boolean;
+        } | null;
+        details: Record<string, unknown>;
+    };
+    opencode?: string | boolean;
+    boot_error?: string | null;
+    reason?: string | null;
+    message?: string | null;
+    capabilities?: string[];
+};
+export type RuntimeCapability = 'session.rewind' | 'session.compact' | 'session.commands' | 'session.fork' | 'session.subagents' | 'session.mcp' | 'session.todo' | 'session.shell' | 'session.attach' | 'session.config';
+export declare function runtimeSupports(capabilities: readonly string[] | null | undefined, capability: RuntimeCapability): boolean;
+export type ProxyHop = 'control_plane' | 'provider_ingress' | 'daemon' | 'upstream_port';
+export declare function parseProxyHop(value: unknown): ProxyHop | null;
+export interface SessionHealthResult {
+    status: number;
+    ok: boolean;
+    health: SessionHealthResponse | null;
+    body: string;
+    hop: ProxyHop | null;
+    upstreamStatus: number | null;
+}
+export declare function isRuntimeReady(health: SessionHealthResponse | null): boolean;
+export declare function getSessionHealth(runtimeUrl?: string | null, init?: RequestInit): Promise<SessionHealthResult>;

package/dist/core/session/health.js

@@ -0,0 +1,53 @@
+import { authenticatedFetch } from '../http/auth.js';
+import { getActiveRuntimeUrl } from './server-store/active.js';
+export function runtimeSupports(capabilities, capability) {
+    if (!capabilities?.some((entry) => entry.startsWith('session.')))
+        return true;
+    return capabilities.includes(capability);
+}
+const PROXY_HOPS = [
+    'control_plane',
+    'provider_ingress',
+    'daemon',
+    'upstream_port',
+];
+export function parseProxyHop(value) {
+    return typeof value === 'string' && PROXY_HOPS.includes(value) ? value : null;
+}
+export function isRuntimeReady(health) {
+    if (!health)
+        return false;
+    if (health.runtimeReady !== undefined)
+        return health.runtimeReady === true;
+    if (health.harness)
+        return health.harness.ready === true;
+    if (health.opencode !== undefined)
+        return health.opencode === 'ok' || health.opencode === true;
+    return (health.status !== 'starting' &&
+        health.status !== 'down' &&
+        health.status !== 'error');
+}
+export async function getSessionHealth(runtimeUrl, init) {
+    const url = (runtimeUrl === undefined ? getActiveRuntimeUrl() : runtimeUrl) || null;
+    if (!url)
+        return { status: 0, ok: false, health: null, body: '', hop: null, upstreamStatus: null };
+    const res = await authenticatedFetch(`${url}/beeuni/health`, { method: 'GET', ...init }, { retryOnAuthError: false });
+    const body = await res.text().catch(() => '');
+    let parsed = null;
+    try {
+        parsed = body ? JSON.parse(body) : null;
+    }
+    catch {
+        parsed = null;
+    }
+    const health = parsed;
+    const hop = parseProxyHop(res.headers.get('X-Beeuni-Proxy-Hop')) ?? parseProxyHop(parsed?.hop);
+    const headerUpstream = Number(res.headers.get('X-Beeuni-Upstream-Status'));
+    const bodyUpstream = parsed?.upstream_status;
+    const upstreamStatus = Number.isFinite(headerUpstream) && headerUpstream > 0
+        ? headerUpstream
+        : typeof bodyUpstream === 'number'
+            ? bodyUpstream
+            : null;
+    return { status: res.status, ok: res.ok, health, body, hop, upstreamStatus };
+}

package/dist/core/session/host-signals.d.ts

@@ -0,0 +1,3 @@
+export type HostSignal = 'visible' | 'online' | 'retry';
+export declare function notifyHostSignal(signal: HostSignal): void;
+export declare function onHostSignal(listener: (signal: HostSignal) => void): () => void;

package/dist/core/session/host-signals.js

@@ -0,0 +1,16 @@
+const listeners = new Set();
+export function notifyHostSignal(signal) {
+    for (const listener of [...listeners]) {
+        try {
+            listener(signal);
+        }
+        catch {
+        }
+    }
+}
+export function onHostSignal(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}

package/dist/core/session/index.d.ts

@@ -0,0 +1,15 @@
+export * from './url.js';
+export * from './health.js';
+export * from './preview.js';
+export * from './preview-auth.js';
+export * from './preview-probe.js';
+export * from './presentation.js';
+export * from './connection.js';
+export * from './working.js';
+export * from './turn-end-cause.js';
+export * from './compaction.js';
+export * from './wake-escalation.js';
+export * from './status-vocabulary.js';
+export type { PendingInteractions, RuntimeVerbs, TranscriptPage } from './runtime-verbs.js';
+export * from './runtime-sessions.js';
+export { notifyHostSignal, type HostSignal } from './host-signals.js';

package/dist/core/session/index.js

@@ -0,0 +1,14 @@
+export * from './url.js';
+export * from './health.js';
+export * from './preview.js';
+export * from './preview-auth.js';
+export * from './preview-probe.js';
+export * from './presentation.js';
+export * from './connection.js';
+export * from './working.js';
+export * from './turn-end-cause.js';
+export * from './compaction.js';
+export * from './wake-escalation.js';
+export * from './status-vocabulary.js';
+export * from './runtime-sessions.js';
+export { notifyHostSignal } from './host-signals.js';

package/dist/core/session/message-queue.d.ts

@@ -0,0 +1,43 @@
+export interface QueuedMessageInput<TFile = unknown, TMention = unknown> {
+    id: string;
+    clientMessageId: string;
+    text: string;
+    files?: TFile[];
+    mentions?: TMention[];
+    agent?: string | null;
+    model?: {
+        providerID: string;
+        modelID: string;
+    } | null;
+    variant?: string | null;
+    command?: {
+        name: string;
+        split?: {
+            before: string;
+            after: string;
+        };
+    };
+    createdAt: number;
+}
+export interface QueuedMessage<TFile = unknown, TMention = unknown> extends QueuedMessageInput<TFile, TMention> {
+    attempts: number;
+    lastError?: string;
+}
+export interface SessionQueue<TFile = unknown, TMention = unknown> {
+    pending: QueuedMessage<TFile, TMention>[];
+    failed: QueuedMessage<TFile, TMention>[];
+    inFlightId: string | null;
+    inFlightIds?: string[];
+}
+export declare function createSessionQueue<TFile = unknown, TMention = unknown>(): SessionQueue<TFile, TMention>;
+export declare function enqueue<TFile, TMention>(state: SessionQueue<TFile, TMention>, input: QueuedMessageInput<TFile, TMention>): SessionQueue<TFile, TMention>;
+export declare function claimNext<TFile, TMention>(state: SessionQueue<TFile, TMention>): {
+    state: SessionQueue<TFile, TMention>;
+    claimed?: QueuedMessage<TFile, TMention>;
+};
+export declare function completeInFlight<TFile, TMention>(state: SessionQueue<TFile, TMention>): SessionQueue<TFile, TMention>;
+export declare function failInFlight<TFile, TMention>(state: SessionQueue<TFile, TMention>, error: string): SessionQueue<TFile, TMention>;
+export declare function retryFailed<TFile, TMention>(state: SessionQueue<TFile, TMention>, id: string): SessionQueue<TFile, TMention>;
+export declare function removeQueued<TFile, TMention>(state: SessionQueue<TFile, TMention>, id: string): SessionQueue<TFile, TMention>;
+export declare function editQueued<TFile, TMention>(state: SessionQueue<TFile, TMention>, id: string, text: string): SessionQueue<TFile, TMention>;
+export declare function reorderQueued<TFile, TMention>(state: SessionQueue<TFile, TMention>, id: string, toIndex: number): SessionQueue<TFile, TMention>;