@bubblebrain-ai/bubble 0.0.63 → 0.0.65

package/dist/sdk/replay-event-log.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A small append-only event log for SDK streams. Producers never wait for a
+ * consumer, and consumers can attach again with their last seen sequence.
+ */
+export declare class ReplayEventLog<T> {
+    private readonly retention;
+    private readonly entries;
+    private nextIndex;
+    private firstIndex;
+    private readonly readers;
+    private signal;
+    private closed;
+    private failure;
+    constructor(retention?: number);
+    get length(): number;
+    get retainedCount(): number;
+    append(value: T): void;
+    close(error?: unknown): void;
+    iterate(options?: {
+        from?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<T>;
+    private readFrom;
+    private prune;
+    private wake;
+}

package/dist/sdk/replay-event-log.js

@@ -0,0 +1,122 @@
+/**
+ * A small append-only event log for SDK streams. Producers never wait for a
+ * consumer, and consumers can attach again with their last seen sequence.
+ */
+export class ReplayEventLog {
+    retention;
+    entries = new Map();
+    nextIndex = 0;
+    firstIndex = 0;
+    readers = new Map();
+    signal = deferredSignal();
+    closed = false;
+    failure;
+    constructor(retention = Infinity) {
+        this.retention = retention;
+        if (retention !== Infinity && (!Number.isSafeInteger(retention) || retention < 1))
+            throw new Error('Invalid event retention');
+    }
+    get length() {
+        return this.nextIndex;
+    }
+    get retainedCount() { return this.entries.size; }
+    append(value) {
+        if (this.closed)
+            return;
+        this.entries.set(this.nextIndex++, value);
+        this.prune();
+        this.wake();
+    }
+    close(error) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.failure = error;
+        this.wake();
+    }
+    iterate(options = {}) {
+        const start = Math.max(0, options.from ?? 0);
+        const reader = {};
+        const cancelled = new AbortController();
+        const signal = options.signal ? AbortSignal.any([options.signal, cancelled.signal]) : cancelled.signal;
+        const release = () => { this.readers.delete(reader); this.prune(); };
+        // Reserve the cursor when subscribing, before a synchronous producer can
+        // prune events and before the consumer calls next(). close/return also
+        // release subscriptions which were never advanced.
+        if (!signal.aborted)
+            this.readers.set(reader, start);
+        signal.addEventListener('abort', release, { once: true });
+        const cleanup = () => { signal.removeEventListener('abort', release); release(); };
+        const iterator = this.readFrom(start, reader, signal, cleanup);
+        const finish = iterator.return.bind(iterator);
+        const fail = iterator.throw.bind(iterator);
+        iterator.return = async (value) => { cancelled.abort(); cleanup(); return finish(value); };
+        iterator.throw = async (error) => { cancelled.abort(); cleanup(); return fail(error); };
+        return iterator;
+    }
+    async *readFrom(start, reader, abortSignal, cleanup) {
+        let index = start;
+        try {
+            while (true) {
+                while (index < this.nextIndex) {
+                    if (abortSignal.aborted)
+                        return;
+                    if (index < this.firstIndex) {
+                        throw new Error('Replay cursor expired; restore persisted history and subscribe from the latest sequence.');
+                    }
+                    const value = this.entries.get(index);
+                    this.readers.set(reader, ++index);
+                    this.prune();
+                    yield value;
+                }
+                if (this.closed) {
+                    if (this.failure !== undefined)
+                        throw this.failure;
+                    return;
+                }
+                if (abortSignal.aborted)
+                    return;
+                const currentSignal = this.signal.promise;
+                await waitForSignal(currentSignal, abortSignal);
+            }
+        }
+        finally {
+            cleanup();
+        }
+    }
+    prune() {
+        if (this.retention === Infinity)
+            return;
+        let before = this.nextIndex - this.retention;
+        for (const index of this.readers.values())
+            before = Math.min(before, index);
+        while (this.firstIndex < before)
+            this.entries.delete(this.firstIndex++);
+    }
+    wake() {
+        const previous = this.signal;
+        this.signal = deferredSignal();
+        previous.resolve();
+    }
+}
+function deferredSignal() {
+    let resolve;
+    const promise = new Promise((done) => {
+        resolve = done;
+    });
+    return { promise, resolve };
+}
+function waitForSignal(signal, abortSignal) {
+    if (!abortSignal)
+        return signal;
+    if (abortSignal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const done = () => {
+            abortSignal.removeEventListener("abort", done);
+            resolve();
+        };
+        abortSignal.addEventListener("abort", done, { once: true });
+        signal.then(done);
+    });
+}

package/dist/sdk/session-turn-coordinator.d.ts

@@ -0,0 +1,45 @@
+export type SessionTurnPhase = "queued" | "reserved" | "starting" | "active" | "stopping" | "settled";
+export interface SessionTurnQueueState {
+    active: boolean;
+    queued: number;
+    phase: Exclude<SessionTurnPhase, "queued" | "settled"> | "idle" | "deleted";
+}
+export interface SessionTurnReservation {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly signal: AbortSignal;
+    readonly phase: SessionTurnPhase;
+    readonly completion: Promise<void>;
+    waitForStart(): Promise<void>;
+    markActive(): void;
+    cancel(error?: Error): void;
+    finish(): void;
+}
+/**
+ * One synchronous state machine owns the complete per-session turn lifecycle.
+ * A reservation and its AbortController are created when runTurn() is called,
+ * before its async iterator is consumed, so stop/delete never have a handoff
+ * window in which a turn is invisible.
+ */
+export declare class SessionTurnCoordinator {
+    private readonly sessions;
+    private readonly deletedSessions;
+    private readonly turnIdPrefix;
+    private nextTurnId;
+    reserve(sessionId: string, signal?: AbortSignal): SessionTurnReservation;
+    getCurrent(sessionId: string): SessionTurnReservation | undefined;
+    getState(sessionId: string): SessionTurnQueueState;
+    stop(sessionId: string, message?: string): number;
+    stopCurrent(sessionId: string, message?: string): number;
+    clearQueue(sessionId: string, message?: string): number;
+    delete(sessionId: string): Promise<void>;
+    isDeleted(sessionId: string): boolean;
+    revive(sessionId: string): void;
+    private reservationFor;
+    private cancelTurn;
+    private finishTurn;
+    private settleDetached;
+    private promoteNext;
+    private deleteEmptySession;
+    private detachExternalAbort;
+}

package/dist/sdk/session-turn-coordinator.js

@@ -0,0 +1,227 @@
+import { AgentAbortError, throwIfAborted } from "../agent/abort-errors.js";
+import { randomUUID } from "node:crypto";
+/**
+ * One synchronous state machine owns the complete per-session turn lifecycle.
+ * A reservation and its AbortController are created when runTurn() is called,
+ * before its async iterator is consumed, so stop/delete never have a handoff
+ * window in which a turn is invisible.
+ */
+export class SessionTurnCoordinator {
+    sessions = new Map();
+    deletedSessions = new Set();
+    turnIdPrefix = `sdk-turn-${randomUUID().slice(0, 6)}`;
+    nextTurnId = 0;
+    reserve(sessionId, signal) {
+        if (this.deletedSessions.has(sessionId)) {
+            throw new Error(`Session is deleted: ${sessionId}`);
+        }
+        throwIfAborted(signal);
+        const turn = {
+            id: `${this.turnIdPrefix}-${++this.nextTurnId}`,
+            sessionId,
+            phase: "queued",
+            abort: new AbortController(),
+            start: deferred(),
+            completion: deferred(),
+            externalSignal: signal,
+        };
+        // A reservation can legally be stopped before its iterator is consumed.
+        // Keep that rejected start promise observed until waitForStart() reads it.
+        void turn.start.promise.catch(() => undefined);
+        let session = this.sessions.get(sessionId);
+        if (!session) {
+            session = { queued: [] };
+            this.sessions.set(sessionId, session);
+        }
+        if (!session.current) {
+            session.current = turn;
+            turn.phase = "reserved";
+            turn.start.resolve(undefined);
+        }
+        else {
+            session.queued.push(turn);
+        }
+        if (signal) {
+            turn.onExternalAbort = () => {
+                this.cancelTurn(turn, abortReason(signal, "SDK turn cancelled."));
+            };
+            signal.addEventListener("abort", turn.onExternalAbort, { once: true });
+        }
+        return this.reservationFor(turn);
+    }
+    getCurrent(sessionId) {
+        const turn = this.sessions.get(sessionId)?.current;
+        return turn ? this.reservationFor(turn) : undefined;
+    }
+    getState(sessionId) {
+        if (this.deletedSessions.has(sessionId)) {
+            return { active: false, queued: 0, phase: "deleted" };
+        }
+        const session = this.sessions.get(sessionId);
+        const currentPhase = session?.current?.phase;
+        return {
+            active: Boolean(session?.current),
+            queued: session?.queued.length ?? 0,
+            phase: currentPhase && currentPhase !== "queued" && currentPhase !== "settled"
+                ? currentPhase
+                : "idle",
+        };
+    }
+    stop(sessionId, message = "SDK turn stopped.") {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return 0;
+        const turns = [session.current, ...session.queued].filter((turn) => Boolean(turn));
+        for (const turn of turns)
+            this.cancelTurn(turn, new AgentAbortError(message));
+        return turns.length;
+    }
+    stopCurrent(sessionId, message = "SDK turn stopped.") {
+        const current = this.sessions.get(sessionId)?.current;
+        if (!current)
+            return 0;
+        this.cancelTurn(current, new AgentAbortError(message));
+        return 1;
+    }
+    clearQueue(sessionId, message = "Queued SDK turn cancelled.") {
+        const queued = [...(this.sessions.get(sessionId)?.queued ?? [])];
+        for (const turn of queued)
+            this.cancelTurn(turn, new AgentAbortError(message));
+        return queued.length;
+    }
+    async delete(sessionId) {
+        this.deletedSessions.add(sessionId);
+        const session = this.sessions.get(sessionId);
+        const turns = session
+            ? [session.current, ...session.queued].filter((turn) => Boolean(turn))
+            : [];
+        for (const turn of turns) {
+            this.cancelTurn(turn, new AgentAbortError("SDK session deleted."));
+        }
+        await Promise.all(turns.map((turn) => turn.completion.promise));
+    }
+    isDeleted(sessionId) {
+        return this.deletedSessions.has(sessionId);
+    }
+    revive(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session?.current || session?.queued.length) {
+            throw new Error(`Cannot recreate session while turns are still settling: ${sessionId}`);
+        }
+        this.deletedSessions.delete(sessionId);
+    }
+    reservationFor(turn) {
+        return {
+            id: turn.id,
+            sessionId: turn.sessionId,
+            signal: turn.abort.signal,
+            get phase() {
+                return turn.phase;
+            },
+            completion: turn.completion.promise,
+            waitForStart: async () => {
+                await turn.start.promise;
+                if (turn.phase === "settled")
+                    throw turn.terminalError ?? new AgentAbortError("SDK turn cancelled.");
+                if (turn.phase === "reserved")
+                    turn.phase = "starting";
+                throwIfAborted(turn.abort.signal);
+            },
+            markActive: () => {
+                throwIfAborted(turn.abort.signal);
+                if (turn.phase === "starting")
+                    turn.phase = "active";
+            },
+            cancel: (error = new AgentAbortError("SDK turn cancelled.")) => {
+                this.cancelTurn(turn, error);
+            },
+            finish: () => this.finishTurn(turn),
+        };
+    }
+    cancelTurn(turn, error) {
+        if (turn.phase === "settled")
+            return;
+        turn.terminalError = error;
+        turn.abort.abort(error);
+        const session = this.sessions.get(turn.sessionId);
+        if (!session) {
+            this.settleDetached(turn);
+            return;
+        }
+        if (turn.phase === "queued") {
+            const index = session.queued.indexOf(turn);
+            if (index >= 0)
+                session.queued.splice(index, 1);
+            this.settleDetached(turn);
+            this.deleteEmptySession(turn.sessionId, session);
+            return;
+        }
+        if (turn.phase === "reserved") {
+            if (session.current === turn)
+                session.current = undefined;
+            this.settleDetached(turn);
+            this.promoteNext(turn.sessionId, session);
+            return;
+        }
+        turn.phase = "stopping";
+    }
+    finishTurn(turn) {
+        if (turn.phase === "settled")
+            return;
+        const session = this.sessions.get(turn.sessionId);
+        if (session?.current === turn)
+            session.current = undefined;
+        this.settleDetached(turn);
+        if (session)
+            this.promoteNext(turn.sessionId, session);
+    }
+    settleDetached(turn) {
+        this.detachExternalAbort(turn);
+        const error = turn.terminalError;
+        turn.phase = "settled";
+        if (error)
+            turn.start.reject(error);
+        turn.completion.resolve(undefined);
+    }
+    promoteNext(sessionId, session) {
+        if (this.deletedSessions.has(sessionId)) {
+            for (const queued of [...session.queued]) {
+                this.cancelTurn(queued, new AgentAbortError("SDK session deleted."));
+            }
+            this.deleteEmptySession(sessionId, session);
+            return;
+        }
+        while (!session.current && session.queued.length > 0) {
+            const next = session.queued.shift();
+            if (!next || next.phase === "settled")
+                continue;
+            session.current = next;
+            next.phase = "reserved";
+            next.start.resolve(undefined);
+        }
+        this.deleteEmptySession(sessionId, session);
+    }
+    deleteEmptySession(sessionId, session) {
+        if (!session.current && session.queued.length === 0)
+            this.sessions.delete(sessionId);
+    }
+    detachExternalAbort(turn) {
+        if (turn.externalSignal && turn.onExternalAbort) {
+            turn.externalSignal.removeEventListener("abort", turn.onExternalAbort);
+        }
+    }
+}
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((onResolve, onReject) => {
+        resolve = onResolve;
+        reject = onReject;
+    });
+    return { promise, resolve, reject };
+}
+function abortReason(signal, fallback) {
+    if (signal.reason instanceof Error)
+        return signal.reason;
+    return new AgentAbortError(typeof signal.reason === "string" ? signal.reason : fallback);
+}

package/dist/session-context-fence.d.ts

@@ -0,0 +1,16 @@
+import type { SessionManager } from "./session.js";
+/** The revision of a host's resident history, not the manager's refreshed log.
+ * Reads and audit/metadata refreshes never legitimize a foreign conversation.
+ * Local clear/rewind/manual compaction replace history explicitly; other local
+ * writes advance the fence only when they extend the host's existing snapshot.
+ */
+export declare class SessionContextFence {
+    private readonly session;
+    private revision;
+    private readonly unsubscribe;
+    constructor(session: SessionManager);
+    getRevision(): string;
+    /** Call only alongside replacing the host's resident messages. */
+    reloadHistory(): import("./types.js").Message[];
+    dispose(): void;
+}

package/dist/session-context-fence.js

@@ -0,0 +1,26 @@
+/** The revision of a host's resident history, not the manager's refreshed log.
+ * Reads and audit/metadata refreshes never legitimize a foreign conversation.
+ * Local clear/rewind/manual compaction replace history explicitly; other local
+ * writes advance the fence only when they extend the host's existing snapshot.
+ */
+export class SessionContextFence {
+    session;
+    revision;
+    unsubscribe;
+    constructor(session) {
+        this.session = session;
+        this.revision = session.getRevision();
+        this.unsubscribe = session.subscribeContextCommits((previous, revision, replacement) => {
+            if (replacement || previous === this.revision)
+                this.revision = revision;
+        });
+    }
+    getRevision() { return this.revision; }
+    /** Call only alongside replacing the host's resident messages. */
+    reloadHistory() {
+        const messages = this.session.getMessages();
+        this.revision = this.session.getRevision();
+        return messages;
+    }
+    dispose() { this.unsubscribe(); }
+}

package/dist/session-log.d.ts

@@ -0,0 +1,25 @@
+import type { Message } from "./types.js";
+import type { SessionLogEntry, SessionMarkerKind, SessionMetadata, SessionProviderErrorEntry } from "./session-types.js";
+import type { SanitizedProviderError } from "./provider-error-record.js";
+/** Records that change conversational context or its execution state.
+ * Keep this shared by revision hashing and checkpoint receipt supersession.
+ * Unknown/new markers are conservative: only known diagnostics are excluded.
+ */
+export declare function affectsContextRevision(entry: SessionLogEntry): boolean;
+export declare class SessionLog {
+    private entries;
+    private nextId;
+    private contextRevision;
+    private allocateId;
+    appendEntries(entries: SessionLogEntry[]): void;
+    getRevision(): string;
+    load(lines: string[]): void;
+    replace(entries: SessionLogEntry[]): void;
+    list(): SessionLogEntry[];
+    getMetadata(): SessionMetadata;
+    setMetadata(metadata: SessionMetadata): SessionLogEntry[];
+    appendMessage(message: Message): SessionLogEntry[];
+    appendMarker(kind: SessionMarkerKind, value: string): SessionLogEntry;
+    appendProviderError(error: SanitizedProviderError): SessionProviderErrorEntry;
+    toMessages(): Message[];
+}