@bivy/bivy 0.0.0 → 0.1.0-staging.2

package/dist/session/native-import.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Seeded-continuation prompt for importing a discovered provider-native
+// session (issue #156) when a true native resume isn't available — the
+// session-level sibling of session/fork.ts's cross-runtime seed path. Pure and
+// side-effect-free (no filesystem/runtime access) so it's unit-testable with
+// synthetic transcripts.
+//
+// This is deliberately a THIN, import-specific wrapper around
+// transcript-normal.ts's shared primitives rather than a copy: normalizeMessages
+// flattens the runtime's RuntimeMessage[] into portable turns exactly as fork
+// does, but the prompt wording here is honest about being an IMPORT (same
+// runtime, no resume available) rather than fork's "moved to a different
+// agent" framing — those are different user-facing claims and must not be
+// conflated.
+import { normalizeMessages } from "./transcript-normal.js";
+function truncate(text, max) {
+    const compact = String(text || "").replace(/\s+/g, " ").trim();
+    return compact.length > max ? `${compact.slice(0, Math.max(0, max - 1))}…` : compact;
+}
+/**
+ * Build the first prompt for a seeded import: a compact summary of the
+ * discovered session's recent turns, framed honestly as a best-effort
+ * continuation rather than a true resume. Bounded (recent turns + a per-turn
+ * character cap, same shape as fork's buildSeedPrompt) so this never inlines
+ * an entire transcript — the "bounded metadata only" spirit of discovery
+ * extends to what a seeded import is willing to carry into the new session.
+ */
+export function buildNativeImportSeedPrompt(transcript, opts) {
+    const recentTurns = opts.recentTurns ?? 12;
+    const perTurnChars = opts.perTurnChars ?? 700;
+    const title = opts.title || transcript.header.title || "Untitled session";
+    const recent = transcript.turns
+        .filter((t) => t.text || t.toolSummary)
+        .slice(-recentTurns)
+        .map((t) => {
+        const body = t.text || (t.toolSummary ? `[${t.toolName ?? "tool"}] ${t.toolSummary}` : "");
+        return `- ${t.role}: ${truncate(body, perTurnChars)}`;
+    })
+        .join("\n");
+    const lines = [
+        `I am continuing a ${opts.provider} session that was started outside Bivy and imported here.`,
+        `Native resume wasn't available for it, so this is a fresh session seeded with a summary of the prior conversation — not the original session itself.`,
+        `Session: ${title}`,
+        opts.cwd ? `Working directory: ${opts.cwd}` : null,
+        "",
+        "Recent conversation (most recent last):",
+        recent || "- (no prior turns were available)",
+    ].filter((line) => line !== null);
+    return lines.join("\n");
+}
+/** Convenience: normalize + seed in one call, for the common case of reading a
+ *  runtime's raw messages straight off disk. */
+export function buildNativeImportSeedFromMessages(messages, header, opts) {
+    return buildNativeImportSeedPrompt(normalizeMessages(messages, header), opts);
+}

package/dist/session/reconnect.js

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// A supervised, self-healing connection with exponential backoff + jitter — the
+// reliability layer under the sibling replication transport
+// (docs/session-replication.md, follow-up #2). Without it, warm replication is
+// only as reliable as the socket at each individual turn boundary: a relay blip
+// or a standby restart silently pauses replication until the next turn happens to
+// reconnect, and repeated failures surface nothing. This keeps exactly one live
+// connection to the standby, reconnecting on drop so the standby stays warm.
+//
+// Generic + transport-free (the connect/close and the clock are injected), so the
+// backoff/state machine unit-tests without a real socket, mirroring
+// session-event-coalescer.ts. `ReplicationService` wires a `SiblingClient` into it.
+//
+// Backoff shape: a CONNECT failure backs off (base·factor^attempt, capped, with
+// jitter); a DROP after a healthy connection resets the counter so reconnection is
+// prompt (one base delay) rather than treating a long-lived session that finally
+// dropped as if it had been flapping.
+const defaultClock = {
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (h) => clearTimeout(h),
+    random: () => Math.random(),
+};
+export class ReconnectingConnection {
+    opts;
+    conn;
+    attempt = 0; // consecutive CONNECT failures
+    timer;
+    connecting = false;
+    stopped = false;
+    waiters = [];
+    base;
+    factor;
+    max;
+    jitter;
+    clock;
+    constructor(opts) {
+        this.opts = opts;
+        this.base = opts.backoff?.baseMs ?? 1000;
+        this.factor = opts.backoff?.factor ?? 2;
+        this.max = opts.backoff?.maxMs ?? 30_000;
+        this.jitter = Math.min(1, Math.max(0, opts.backoff?.jitter ?? 0.3));
+        this.clock = opts.clock ?? defaultClock;
+    }
+    /** The live connection, or undefined while (re)connecting. */
+    current() {
+        return this.conn;
+    }
+    /** Begin connecting (idempotent). */
+    start() {
+        if (this.stopped)
+            return;
+        this.kick();
+    }
+    /**
+     * Resolve with the live connection, triggering a connect if idle and waiting up
+     * to `timeoutMs`. Resolves `undefined` if it isn't up in time — the caller skips
+     * this round while the supervisor keeps reconnecting in the background (the
+     * log-based replicator simply ships the accumulated delta on a later turn).
+     */
+    ensure(timeoutMs) {
+        if (this.conn)
+            return Promise.resolve(this.conn);
+        if (this.stopped)
+            return Promise.resolve(undefined);
+        this.start();
+        return new Promise((resolve) => {
+            const waiter = {
+                resolve,
+                timer: this.clock.setTimeout(() => {
+                    this.removeWaiter(waiter);
+                    resolve(undefined);
+                }, timeoutMs),
+            };
+            this.waiters.push(waiter);
+        });
+    }
+    /** Stop for good: cancel timers, fail waiters, and close any live connection. */
+    stop() {
+        this.stopped = true;
+        if (this.timer !== undefined) {
+            this.clock.clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        while (this.waiters.length) {
+            const w = this.waiters.pop();
+            this.clock.clearTimeout(w.timer);
+            w.resolve(undefined);
+        }
+        if (this.conn !== undefined) {
+            try {
+                this.opts.close(this.conn);
+            }
+            catch {
+                /* ignore */
+            }
+            this.conn = undefined;
+        }
+    }
+    // --- internals -----------------------------------------------------------
+    kick() {
+        if (this.stopped || this.connecting || this.conn !== undefined)
+            return;
+        this.connecting = true;
+        this.opts
+            .connect((err) => this.handleDrop(err))
+            .then((conn) => {
+            this.connecting = false;
+            if (this.stopped) {
+                try {
+                    this.opts.close(conn);
+                }
+                catch {
+                    /* ignore */
+                }
+                return;
+            }
+            this.conn = conn;
+            this.attempt = 0; // healthy again → next drop reconnects promptly
+            this.opts.onActive?.(conn);
+            this.flushWaiters(conn);
+        })
+            .catch((err) => {
+            this.connecting = false;
+            this.scheduleRetry(err);
+        });
+    }
+    handleDrop(err) {
+        // Only act on the drop of the connection we currently consider live.
+        if (this.conn === undefined)
+            return;
+        this.conn = undefined;
+        this.opts.onDrop?.(err);
+        // attempt was reset to 0 on the last successful connect, so this schedules one
+        // base-delay retry rather than an immediate hot-loop reconnect.
+        this.scheduleRetry(err);
+    }
+    scheduleRetry(err) {
+        if (this.stopped || this.timer !== undefined || this.connecting)
+            return;
+        const delay = this.delayFor(this.attempt);
+        this.attempt += 1;
+        this.opts.onRetry?.(err, delay);
+        this.timer = this.clock.setTimeout(() => {
+            this.timer = undefined;
+            this.kick();
+        }, delay);
+    }
+    delayFor(attempt) {
+        const raw = Math.min(this.max, this.base * Math.pow(this.factor, attempt));
+        // Spread ±jitter/2 around the target: with jitter=0.3 the delay is 85%–115%.
+        const spread = raw * this.jitter * (this.clock.random() - 0.5);
+        return Math.max(0, Math.round(raw + spread));
+    }
+    flushWaiters(conn) {
+        while (this.waiters.length) {
+            const w = this.waiters.pop();
+            this.clock.clearTimeout(w.timer);
+            w.resolve(conn);
+        }
+    }
+    removeWaiter(waiter) {
+        const i = this.waiters.indexOf(waiter);
+        if (i >= 0)
+            this.waiters.splice(i, 1);
+    }
+}

package/dist/session/replication-service.js

@@ -0,0 +1,236 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Daemon integration for warm session replication (docs/session-replication.md):
+// assembles the unit-tested owner/standby orchestration (replicator.ts), the git
+// checkpoint bundle (checkpoint-pack.ts), the sibling relay-client transport
+// (sibling-client.ts), and the control-plane ownership endpoints into one service
+// the node daemon drives through a handful of thin adapters (server.ts owns the
+// daemon-specific accessors, so THIS module has no server.ts coupling).
+//
+// Owner: on each turn boundary, `onTurnComplete(sessionId)` declares the standby
+// (once), gets the supervised standby connection (which reconnects on its own with
+// backoff — reconnect.ts), ships a frame, and advances the cursor on ack (retrying
+// once on a full-resync request). Standby: `handleReplicaFrame` applies an inbound
+// frame; `promote` runs the control-plane compare-and-set and materializes the
+// replica for local resume.
+//
+// Gated entirely on the node's sessionSync setting + a chosen standby, both off by
+// default — so when replication is disabled this service is inert and the daemon
+// behaves exactly as before.
+import { OwnerReplicator, StandbyApplier } from "./replicator.js";
+import { createCheckpointBundle, applyCheckpointBundle, materializeCheckpoint } from "./checkpoint-pack.js";
+import { SiblingClient } from "./sibling-client.js";
+import { ReconnectingConnection } from "./reconnect.js";
+export class ReplicationService {
+    deps;
+    owner;
+    standby;
+    // A single supervised connection to the current standby: it reconnects with
+    // backoff on drop, so replication survives relay blips / standby restarts
+    // instead of silently pausing until the next turn (follow-up #2).
+    supervisor;
+    supervisorStandbyId;
+    declared = new Set();
+    epochs = new Map();
+    constructor(deps) {
+        this.deps = deps;
+        this.owner = new OwnerReplicator({
+            readRecords: (id) => deps.readRecords(id),
+            epochOf: (id) => this.epochs.get(id) ?? 0,
+            checkpointHead: (id) => deps.checkpointHead(id),
+            bundleCheckpoint: async (id, since) => {
+                const dir = deps.repoDirFor(id);
+                return dir ? createCheckpointBundle(dir, id, since) : null;
+            },
+            runtimeSessionRef: (id) => deps.runtimeSessionRef(id),
+            worktreeSync: () => deps.settings().worktreeSync === true,
+        });
+        this.standby = new StandbyApplier({
+            persistRecords: (id, records) => deps.persistReplicaRecords(id, records),
+            applyBundle: async (id, bundle) => {
+                const dir = await deps.replicaRepoDir(id);
+                if (!dir)
+                    return { ok: false, needFull: true };
+                return applyCheckpointBundle(dir, id, bundle);
+            },
+            materialize: async (id) => {
+                const dir = await deps.replicaRepoDir(id);
+                if (dir)
+                    await materializeCheckpoint(dir, id);
+            },
+        });
+    }
+    get fetchImpl() {
+        return this.deps.fetchImpl ?? fetch;
+    }
+    ready() {
+        const s = this.deps.settings();
+        if (!s.sessionSync || !s.standbyNodeId)
+            return null;
+        const cp = this.deps.controlPlaneUrl();
+        const token = this.deps.enrollmentToken();
+        if (!cp || !token)
+            return null;
+        return { cp: cp.replace(/\/$/, ""), token, standbyId: s.standbyNodeId };
+    }
+    async cpPost(path, token, body) {
+        try {
+            const res = await this.fetchImpl(`${this.deps.controlPlaneUrl().replace(/\/$/, "")}${path}`, {
+                method: "POST",
+                headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+                body: JSON.stringify(body),
+            });
+            if (!res.ok)
+                return undefined;
+            return (await res.json());
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async cpGet(path, token) {
+        try {
+            const res = await this.fetchImpl(`${this.deps.controlPlaneUrl().replace(/\/$/, "")}${path}`, {
+                headers: { authorization: `Bearer ${token}` },
+            });
+            if (!res.ok)
+                return undefined;
+            return (await res.json());
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Time a turn will wait for the standby connection before skipping this round. */
+    static ENSURE_TIMEOUT_MS = 10_000;
+    /**
+     * The supervised connection to `standbyId`, created (and started) on demand and
+     * kept alive across turns. Switching standby tears the old one down. The
+     * supervisor owns reconnection: each attempt mints fresh credentials + a fresh
+     * `SiblingClient` and wires its close back to the supervisor's drop signal.
+     */
+    supervisorFor(standbyId) {
+        if (this.supervisor && this.supervisorStandbyId === standbyId)
+            return this.supervisor;
+        this.supervisor?.stop();
+        const sup = new ReconnectingConnection({
+            connect: async (onDrop) => {
+                const cp = this.deps.controlPlaneUrl();
+                const token = this.deps.enrollmentToken();
+                if (!cp || !token)
+                    throw new Error("control plane not configured");
+                const client = new SiblingClient({
+                    controlPlaneUrl: cp,
+                    enrollmentToken: token,
+                    siblingNodeId: standbyId,
+                    relayUrl: this.deps.relayUrl(),
+                    label: "Bivy replica",
+                    fetchImpl: this.deps.fetchImpl,
+                    onClose: () => onDrop(),
+                });
+                await client.connect();
+                return client;
+            },
+            close: (client) => client.close(),
+            onActive: () => this.deps.log?.(`replication: connected to standby ${standbyId}`),
+            onDrop: () => this.deps.log?.(`replication: standby ${standbyId} connection dropped; reconnecting`),
+            onRetry: (err, ms) => this.deps.log?.(`replication: standby ${standbyId} unreachable (${err?.message ?? err}); retrying in ${ms}ms`),
+            backoff: { baseMs: 1000, factor: 2, maxMs: 30_000, jitter: 0.3 },
+        });
+        this.supervisor = sup;
+        this.supervisorStandbyId = standbyId;
+        sup.start();
+        return sup;
+    }
+    /** Tear down the standby connection (sync disabled, or shutting down). */
+    stopSupervisor() {
+        this.supervisor?.stop();
+        this.supervisor = undefined;
+        this.supervisorStandbyId = undefined;
+    }
+    /** OWNER: called after a turn completes for a session. Ships one frame. */
+    async onTurnComplete(sessionId) {
+        const r = this.ready();
+        if (!r) {
+            // Sync turned off (or standby cleared) → drop the connection.
+            this.stopSupervisor();
+            return;
+        }
+        // Declare the standby + learn our epoch once per session.
+        if (!this.declared.has(sessionId)) {
+            const res = await this.cpPost(`/node/sessions/${encodeURIComponent(sessionId)}/standby`, r.token, { standbyNodeId: r.standbyId });
+            const ownership = res?.ownership;
+            if (ownership && typeof ownership.ownerEpoch === "number")
+                this.epochs.set(sessionId, ownership.ownerEpoch);
+            this.declared.add(sessionId);
+        }
+        // Wait briefly for the (supervised, self-reconnecting) standby connection. If
+        // it isn't up yet, skip this round — the replicator is log-based, so the next
+        // successful turn ships the accumulated delta.
+        const client = await this.supervisorFor(r.standbyId).ensure(ReplicationService.ENSURE_TIMEOUT_MS);
+        if (!client)
+            return;
+        await this.shipOnce(sessionId, client, true);
+    }
+    async shipOnce(sessionId, client, allowRetry) {
+        const frame = await this.owner.buildTurnFrame(sessionId);
+        if (!frame)
+            return;
+        try {
+            const reply = await client.request({ kind: "session.replica.frame", frame });
+            const ack = (reply.ack ?? reply);
+            const resend = this.owner.applyAck(sessionId, ack);
+            if (resend && allowRetry)
+                await this.shipOnce(sessionId, client, false);
+        }
+        catch (err) {
+            this.deps.log?.(`replication: ship failed for ${sessionId}: ${err.message}`);
+        }
+    }
+    /** STANDBY: apply an inbound replication frame and return the ack. */
+    async handleReplicaFrame(frame, ownerNodeId) {
+        const ack = await this.standby.receive(frame);
+        if (ack.status === "applied") {
+            this.deps.upsertReplicaMeta(frame.sessionId, { runtimeSessionRef: frame.runtimeSessionRef, ownerNodeId });
+        }
+        return ack;
+    }
+    /**
+     * STANDBY: promote this node to owner of a replicated session. Reads the current
+     * epoch, runs the control-plane compare-and-set, and (on success) materializes
+     * the replica working tree so the session can resume locally. Returns the new
+     * owner epoch, or undefined if the promotion lost the race.
+     */
+    async promote(sessionId, thisNodeId) {
+        const cp = this.deps.controlPlaneUrl();
+        const token = this.deps.enrollmentToken();
+        if (!cp || !token)
+            return undefined;
+        const owned = await this.cpGet(`/node/sessions/${encodeURIComponent(sessionId)}/ownership`, token);
+        const ownership = owned?.ownership;
+        const expectedEpoch = ownership && typeof ownership.ownerEpoch === "number" ? ownership.ownerEpoch : 0;
+        const res = await this.cpPost(`/node/sessions/${encodeURIComponent(sessionId)}/promote`, token, {
+            toNodeId: thisNodeId,
+            expectedEpoch,
+        });
+        const promoted = res?.ownership;
+        if (!promoted)
+            return undefined;
+        const dir = await this.deps.replicaRepoDir(sessionId);
+        if (dir)
+            await materializeCheckpoint(dir, sessionId).catch(() => { });
+        this.standby.forget(sessionId);
+        return promoted.ownerEpoch;
+    }
+    /** Tear down (session closed / node shutdown). */
+    forget(sessionId) {
+        this.owner.forget(sessionId);
+        this.standby.forget(sessionId);
+        this.declared.delete(sessionId);
+        this.epochs.delete(sessionId);
+    }
+    close() {
+        this.stopSupervisor();
+    }
+}

package/dist/session/replication.js

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Warm session replication — the transport-free DECISION core (Phase 1 of
+// docs/session-replication.md).
+//
+// The goal: a standby node continuously mirrors a session's state so that if the
+// owning node goes offline, the session can be *manually* promoted and continued
+// elsewhere WITHOUT fetching anything from the (possibly dead) owner. Both halves
+// of a session's state are already append-only, cursor-friendly logs, so warm
+// replication is "tail two logs and ship their deltas":
+//
+//   - Transcript: the per-session `EventLog` (event-log.ts) is append-only JSONL.
+//     We ship appended `LogRecord`s using the SAME count+hash cursor as the
+//     client-facing incremental sync (history-sync.ts) — self-healing on a gap.
+//   - Workspace: the Universal Agent Harness commits a git checkpoint per turn
+//     (harness/checkpoint.ts). We ship the checkpoint commit sha; the standby
+//     fetches the objects (git's own negotiation is idempotent + self-healing).
+//
+// Replication is anchored to the TURN/CHECKPOINT boundary so the two halves stay
+// mutually consistent: every replicated frame carries the transcript tail AND the
+// checkpoint that closed the same turn, and the standby applies BOTH or NEITHER.
+// Recovery point = "the last completed turn"; a crash mid-turn loses at most the
+// in-flight turn (the standby re-runs the last prompt on promotion).
+//
+// This module is the pure core — no relay, no disk, no git. Side effects (persist
+// the tail, fetch the checkpoint objects) are injected, exactly like adoption.ts
+// injects `attach`/`forget`, so the fencing/cursor/consistency logic unit-tests
+// without a daemon (test/replication.test.ts). Transport, the control-plane epoch
+// column, and the promotion command are layered on top (see the doc).
+import { historyDelta } from "../history-sync.js";
+/** A fresh, empty standby state (before the first frame). */
+export function initialReplState() {
+    return { epoch: 0, records: [], historyHash: "" };
+}
+/** The cursor a standby advertises to its owner, derived from its state. */
+export function cursorOf(state) {
+    return { count: state.records.length, historyHash: state.historyHash, checkpointCommit: state.checkpointCommit };
+}
+/**
+ * OWNER side: build the frame to send a standby, given the cursor the standby last
+ * advertised. Returns `null` when the standby is already up to date (no new records
+ * AND the same checkpoint) so the owner skips an empty send. The transcript delta
+ * reuses `historyDelta`, so a diverged/behind standby self-heals: a matching prefix
+ * yields an `append`, anything else a `full`.
+ */
+export function buildReplFrame(input) {
+    const { sessionId, epoch, records, checkpointCommit, runtimeSessionRef, cursor } = input;
+    const delta = historyDelta(records, { have: cursor?.count, haveToken: cursor?.historyHash });
+    const checkpointUnchanged = (checkpointCommit ?? undefined) === (cursor?.checkpointCommit ?? undefined);
+    // Nothing new: an append that carries no records and no newer checkpoint.
+    if (delta.mode === "append" && delta.messages.length === 0 && checkpointUnchanged)
+        return null;
+    return {
+        sessionId,
+        epoch,
+        runtimeSessionRef,
+        checkpointCommit,
+        mode: delta.mode,
+        baseCount: delta.baseCount,
+        records: delta.messages,
+        count: delta.count,
+        historyHash: delta.historyHash,
+    };
+}
+/**
+ * STANDBY side: apply one frame, mutating `state` in place ONLY after every injected
+ * side effect has succeeded (so a git/persist failure leaves the replica unchanged
+ * and the frame is safely retried). Never advances past a gap — it asks the owner to
+ * re-send instead, which `buildReplFrame` resolves to an `append` or a `full`.
+ *
+ * Fencing (the split-brain guard): a frame whose epoch is BELOW the state's is a
+ * write from an owner that has already been superseded by a promotion — rejected.
+ * A frame at or above the state's epoch is honored, and applying it adopts the
+ * (possibly higher) epoch, so a promoted owner's first frame transfers ownership.
+ */
+export async function applyReplFrame(state, frame, deps) {
+    if (frame.epoch < state.epoch)
+        return { status: "stale", ownerEpoch: state.epoch };
+    // Decide the next record list without mutating state yet.
+    let nextRecords;
+    if (frame.mode === "full") {
+        nextRecords = [...frame.records];
+    }
+    else {
+        // append — only valid when the frame continues exactly where we are.
+        if (frame.baseCount !== state.records.length) {
+            return { status: "resync", cursor: cursorOf(state) };
+        }
+        nextRecords = state.records.concat(frame.records);
+    }
+    // Git first: if it throws, we abort before touching the transcript replica.
+    const nextCheckpoint = frame.checkpointCommit ?? state.checkpointCommit;
+    if (frame.checkpointCommit && frame.checkpointCommit !== state.checkpointCommit && deps.fetchCheckpoint) {
+        await deps.fetchCheckpoint(frame.sessionId, frame.checkpointCommit);
+    }
+    await deps.persist(frame.sessionId, nextRecords);
+    // Commit the new view atomically now that all effects have landed.
+    state.records = nextRecords;
+    state.historyHash = frame.historyHash;
+    state.checkpointCommit = nextCheckpoint;
+    if (frame.runtimeSessionRef !== undefined)
+        state.runtimeSessionRef = frame.runtimeSessionRef;
+    state.epoch = Math.max(state.epoch, frame.epoch);
+    return { status: "applied", cursor: cursorOf(state) };
+}