@pellux/goodvibes-sdk 0.38.0 → 1.0.0

package/dist/platform/runtime/session-spine/client.js

@@ -0,0 +1,449 @@
+/**
+ * client.ts — the SDK session-spine surface client.
+ *
+ * The in-process coordinator that mirrors a surface's OWN session identity
+ * (create / resume / heartbeat / close) into the daemon-hosted session spine.
+ * It sits NEXT TO a surface's local session truth, never replacing it: the local
+ * store stays the offline read-model; this client mirrors identity to the daemon
+ * and buffers ops when the daemon is unreachable.
+ *
+ * This is the ONE core extracted from two near-twin implementations — the TUI's
+ * typed-client version (`goodvibes-tui` src/runtime/session-spine-client.ts) and
+ * the agent's raw-REST version (`goodvibes-agent` src/runtime/session-spine-client.ts).
+ * The union of their behaviors is the spec; their differences are parameterized:
+ *
+ *  - TRANSPORT is injected. The core builds a canonical
+ *    {@link RegisterSharedSessionInput} and hands it to an injected
+ *    {@link SpineTransport}; the adapter performs the real wire call (a typed SDK
+ *    sessions client, or a hand-rolled version-tolerant REST mirror) and folds its
+ *    result into a {@link SpineResult}. The core NEVER assumes a typed client
+ *    exists — that is exactly why the agent, which compiles against a pinned npm
+ *    SDK that may predate `sessions.register`, can still use this core.
+ *  - ACTIVATION MODE is optional. Construct WITH a `transport` for
+ *    live-immediately mode (the agent — live for the whole process lifetime), or
+ *    WITHOUT one for dormant-until-`activate()` mode (the TUI — activated once its
+ *    bootstrap adopts a compatible external daemon, deactivated when the mode is
+ *    lost).
+ *  - PARTICIPANT identity, origin `kind`, queue bound and heartbeat window are
+ *    options with the verified defaults.
+ *
+ * Discipline (load-bearing for the interactive-latency budget):
+ *  - Every public method (register / reopen / heartbeat / close /
+ *    foldLegacyRecords) is fire-and-forget: it returns `void` SYNCHRONOUSLY and
+ *    never throws into the caller, even when the wire call rejects. Session
+ *    start/resume/heartbeat never block the render or turn path.
+ *  - Before a transport is attached every op is queued, never dropped-on-the-floor
+ *    and never attempted over a transport that does not exist. Attaching flushes
+ *    the backlog.
+ *  - Offline ops go into a bounded ring (drop-oldest); flush is idempotent because
+ *    register is an upsert.
+ *  - Heartbeat is debounced/coalesced to at most one wire call per window and omits
+ *    the title so it never renames a titled session.
+ *  - A timer-driven keepalive fires the heartbeat on a fixed cadence INDEPENDENT of
+ *    render/turn activity, so a live-but-idle surface keeps its participant
+ *    lastSeenAt fresh and never falls outside the daemon's freshness/reaper windows.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { logger } from '../../utils/logger.js';
+/**
+ * The canonical TUI participant (TRANSPORT axis). Pass as the `participant` option
+ * when the surface is the operator terminal UI.
+ */
+export const TUI_SPINE_PARTICIPANT = {
+    surfaceKind: 'tui',
+    surfaceId: 'surface:tui',
+    displayName: 'Terminal UI',
+};
+/**
+ * The canonical agent participant (TRANSPORT axis). `surfaceKind` stays 'service';
+ * the record origin `kind` ('agent') is stamped by the REST mirror server-side, not
+ * here — so the agent leaves `recordKind` unset.
+ */
+export const AGENT_SPINE_PARTICIPANT = {
+    surfaceKind: 'service',
+    surfaceId: 'surface:goodvibes-agent',
+    displayName: 'GoodVibes Agent',
+};
+const DEFAULT_QUEUE_LIMIT = 128;
+const DEFAULT_HEARTBEAT_MIN_INTERVAL_MS = 45_000;
+export class SessionSpineClient {
+    participant;
+    recordKind;
+    probeImpl;
+    now;
+    queueLimit;
+    heartbeatMinIntervalMs;
+    log;
+    transport = null;
+    reachability = 'unknown';
+    records = new Map();
+    queue = [];
+    lastHeartbeatAt = 0;
+    heartbeatTimer = null;
+    flushing = false;
+    /** The most recently registered/reopened session — the keepalive heartbeat target. */
+    lastSessionId = null;
+    /**
+     * Timer-driven keepalive: fires the heartbeat on a fixed cadence INDEPENDENT of
+     * render/turn activity, so a live-but-render-silent surface keeps its participant
+     * lastSeenAt fresh. Each tick is just a heartbeat() call, so it rides the SAME
+     * bounded offline-queue/reconnect handling as every other op — no new retry loop,
+     * no faster-than-cadence attempts against a dead daemon.
+     */
+    keepaliveTimer = null;
+    constructor(options) {
+        this.participant = options.participant;
+        this.recordKind = options.recordKind;
+        this.probeImpl = options.probe;
+        this.now = options.now ?? (() => Date.now());
+        this.queueLimit = Math.max(1, options.queueLimit ?? DEFAULT_QUEUE_LIMIT);
+        this.heartbeatMinIntervalMs = Math.max(0, options.heartbeatMinIntervalMs ?? DEFAULT_HEARTBEAT_MIN_INTERVAL_MS);
+        this.log = options.log ?? logger;
+        // Live-immediately mode: a transport supplied at construction starts the
+        // keepalive now and is live for the whole process lifetime (no activate step).
+        if (options.transport) {
+            this.transport = options.transport;
+            this.startKeepalive();
+        }
+    }
+    /** Honest reachability: 'unknown' until a wire call resolves, then online/offline. */
+    status() {
+        return this.reachability;
+    }
+    /** Whether a transport is currently attached. */
+    get active() {
+        return this.transport !== null;
+    }
+    /** Current bounded offline-queue depth (for diagnostics / tests). */
+    get pendingOps() {
+        return this.queue.length;
+    }
+    /** The session the keepalive heartbeat currently targets (diagnostics/tests). */
+    get keepaliveSessionId() {
+        return this.lastSessionId;
+    }
+    /**
+     * The CANONICAL "which wire rows are mine" set: every sessionId this client
+     * has register()/reopen()'d and not yet close()'d, regardless of whatever id
+     * a caller's own local store separately uses for the same conceptual
+     * session. register()/reopen() send exactly the `sessionId` the caller
+     * passes in — this client never assumes that string also matches a local
+     * broker's own idea of the session's id. A cross-surface read facade (the
+     * SDK's SessionUnionCache) uses this to recognize its own wire mirror by
+     * the id ACTUALLY SENT, not by hoping a local reader's id happens to agree.
+     */
+    get mirroredSessionIds() {
+        return new Set(this.records.keys());
+    }
+    /**
+     * DORMANT-MODE activation: attach the transport once a compatible external daemon
+     * has been adopted. Flushes anything queued while dormant, starts the keepalive.
+     * Reachability stays 'unknown' until the first wire call resolves.
+     */
+    activate(transport) {
+        this.transport = transport;
+        this.log.info('session spine activated — mirroring session identity to the adopted external daemon', {});
+        this.startKeepalive();
+        void this.flush();
+    }
+    /**
+     * Detach the transport (daemon mode resolved to non-external, or was lost). Ops
+     * continue to be queued (bounded, drop-oldest) rather than dropped.
+     */
+    deactivate(reason) {
+        if (this.transport === null)
+            return;
+        this.transport = null;
+        this.reachability = 'unknown';
+        this.stopKeepalive();
+        this.log.info('session spine deactivated', { reason });
+    }
+    /** CREATE: fire-and-forget initial registration (title stamped once). */
+    register(record) {
+        this.cacheHeartbeatRecord(record);
+        this.dispatchRegister(this.buildInput(record, { includeTitle: true }));
+    }
+    /** RESUME: fire-and-forget reopen (reopen:true, no title) — the only reopen path. */
+    reopen(record) {
+        this.cacheHeartbeatRecord(record);
+        this.dispatchRegister(this.buildInput(record, { includeTitle: false, reopen: true }));
+    }
+    /**
+     * HEARTBEAT: debounced re-register, coalesced to one wire call per window, no title,
+     * no reopen. Safe to call on every turn/render tick — internally a no-op unless the
+     * window has elapsed.
+     */
+    heartbeat(sessionId) {
+        const cached = this.records.get(sessionId);
+        if (!cached)
+            return;
+        const now = this.now();
+        if (now - this.lastHeartbeatAt >= this.heartbeatMinIntervalMs) {
+            this.lastHeartbeatAt = now;
+            this.dispatchRegister(this.withFreshLastSeen(cached));
+            return;
+        }
+        if (this.heartbeatTimer)
+            return; // already a trailing beat scheduled -> coalesced
+        const delay = Math.max(0, this.heartbeatMinIntervalMs - (now - this.lastHeartbeatAt));
+        this.heartbeatTimer = setTimeout(() => {
+            this.heartbeatTimer = null;
+            this.lastHeartbeatAt = this.now();
+            const rec = this.records.get(sessionId);
+            if (rec)
+                this.dispatchRegister(this.withFreshLastSeen(rec));
+        }, delay);
+        this.heartbeatTimer.unref?.();
+    }
+    /** CLOSE: best-effort, fire-and-forget; tolerate a racing daemon stop. */
+    close(sessionId) {
+        this.records.delete(sessionId);
+        if (!this.transport) {
+            this.enqueue({ type: 'close', sessionId });
+            return;
+        }
+        void this.runClose(sessionId);
+    }
+    /**
+     * LEGACY FOLD: register each per-project record; a record whose id is in `closedIds`
+     * is registered then closed so a locally-closed session STAYS closed in the daemon
+     * (honest history). Idempotent — register is an upsert; closing an already-closed
+     * record is a no-op.
+     */
+    foldLegacyRecords(records, closedIds) {
+        for (const record of records) {
+            this.enqueue({ type: 'register', sessionId: record.sessionId, input: this.buildInput(record, { includeTitle: true }) });
+            if (closedIds.has(record.sessionId)) {
+                this.enqueue({ type: 'close', sessionId: record.sessionId });
+            }
+        }
+        void this.flush();
+    }
+    /** Reachability probe — runs OFF the interactive path (deferred startup). Flushes on
+     * success. A no-op returning the current status when no `probe` option was supplied. */
+    async probeReachability() {
+        if (!this.probeImpl)
+            return this.reachability;
+        let reachable = false;
+        try {
+            reachable = await this.probeImpl();
+        }
+        catch {
+            reachable = false;
+        }
+        if (reachable) {
+            this.reachability = 'online';
+            await this.flush();
+        }
+        else {
+            this.reachability = 'offline';
+        }
+        return this.reachability;
+    }
+    /** Clears the pending heartbeat + keepalive timers; call on shutdown. */
+    dispose() {
+        if (this.heartbeatTimer) {
+            clearTimeout(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        this.stopKeepalive();
+    }
+    startKeepalive() {
+        if (this.keepaliveTimer !== null || this.heartbeatMinIntervalMs <= 0)
+            return;
+        this.keepaliveTimer = setInterval(() => {
+            if (this.lastSessionId)
+                this.heartbeat(this.lastSessionId);
+        }, this.heartbeatMinIntervalMs);
+        this.keepaliveTimer.unref?.();
+    }
+    stopKeepalive() {
+        if (this.keepaliveTimer !== null) {
+            clearInterval(this.keepaliveTimer);
+            this.keepaliveTimer = null;
+        }
+    }
+    cacheHeartbeatRecord(record) {
+        // Cache the title-less form so heartbeats never rename a titled session.
+        this.records.set(record.sessionId, this.buildInput(record, { includeTitle: false }));
+        // Track the newest session as the keepalive-heartbeat target.
+        this.lastSessionId = record.sessionId;
+    }
+    buildInput(record, opts) {
+        const participant = {
+            ...this.participant,
+            ...(record.userId ? { userId: record.userId } : {}),
+            lastSeenAt: this.now(),
+        };
+        return {
+            sessionId: record.sessionId,
+            ...(this.recordKind ? { kind: this.recordKind } : {}),
+            project: record.project,
+            ...(opts.includeTitle && record.title ? { title: record.title } : {}),
+            participant,
+            ...(opts.reopen ? { reopen: true } : {}),
+        };
+    }
+    withFreshLastSeen(input) {
+        return { ...input, participant: { ...input.participant, lastSeenAt: this.now() } };
+    }
+    dispatchRegister(input) {
+        if (!this.transport) {
+            this.enqueue({ type: 'register', sessionId: input.sessionId, input });
+            return;
+        }
+        void this.runRegister(input);
+    }
+    async runRegister(input) {
+        const transport = this.transport;
+        if (!transport) {
+            this.enqueue({ type: 'register', sessionId: input.sessionId, input });
+            return;
+        }
+        try {
+            const result = await transport.register(input);
+            if (result.outcome === 'ok') {
+                this.reachability = 'online';
+                await this.flush();
+            }
+            else if (result.outcome === 'offline') {
+                this.reachability = 'offline';
+                this.enqueue({ type: 'register', sessionId: input.sessionId, input });
+            }
+            else {
+                // Durable reject: honest local-only. Never claim online; do not queue (this is
+                // not a transient connectivity fault, so it must not retry-forever).
+                this.log.debug('session spine register not applied', { error: result.error });
+            }
+        }
+        catch (error) {
+            // Fire-and-forget contract: absorb everything. An unexpected transport throw is
+            // treated as transient offline and queued for reconnect replay.
+            this.reachability = 'offline';
+            this.enqueue({ type: 'register', sessionId: input.sessionId, input });
+            this.log.debug('session spine register threw — queued for reconnect', { error: errorMessage(error) });
+        }
+    }
+    async runClose(sessionId) {
+        const transport = this.transport;
+        if (!transport) {
+            this.enqueue({ type: 'close', sessionId });
+            return;
+        }
+        try {
+            const result = await transport.close(sessionId);
+            if (result.outcome === 'ok') {
+                this.reachability = 'online';
+            }
+            else if (result.outcome === 'offline') {
+                this.reachability = 'offline';
+                this.enqueue({ type: 'close', sessionId });
+            }
+            else {
+                this.log.debug('session spine close not applied', { error: result.error });
+            }
+        }
+        catch (error) {
+            this.reachability = 'offline';
+            this.enqueue({ type: 'close', sessionId });
+            this.log.debug('session spine close threw — queued for reconnect', { error: errorMessage(error) });
+        }
+    }
+    enqueue(op) {
+        if (this.queue.length >= this.queueLimit)
+            this.queue.shift(); // drop-oldest
+        this.queue.push(op);
+    }
+    async flush() {
+        if (this.flushing || this.queue.length === 0)
+            return;
+        const transport = this.transport;
+        if (!transport)
+            return;
+        this.flushing = true;
+        try {
+            const pending = this.queue.splice(0, this.queue.length);
+            for (const op of pending) {
+                try {
+                    let result;
+                    if (op.type === 'register') {
+                        if (!op.input)
+                            continue;
+                        result = await transport.register(op.input);
+                    }
+                    else {
+                        result = await transport.close(op.sessionId);
+                    }
+                    if (result.outcome === 'ok') {
+                        this.reachability = 'online';
+                    }
+                    else if (result.outcome === 'offline') {
+                        this.reachability = 'offline';
+                        this.enqueue(op);
+                    }
+                    else {
+                        this.log.debug('session spine flush op not applied', { error: result.error });
+                    }
+                }
+                catch (error) {
+                    this.reachability = 'offline';
+                    this.enqueue(op);
+                    this.log.debug('session spine flush op threw — re-queued', { error: errorMessage(error) });
+                }
+            }
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Reads a surface's OWN project-scoped control-plane sessions.json and folds each
+ * record into the daemon via the client (register upsert; closed records also
+ * closed). Writes a marker file so subsequent runs are a no-op. Register is
+ * idempotent, so even a marker-less re-run is safe. Only folds the store for the
+ * project it is invoked from — the per-project discovery scope is documented, not
+ * silently "complete" across every project a surface has ever run in.
+ */
+export function foldLegacySpineStore(client, options) {
+    const log = options.log ?? logger;
+    if (existsSync(options.markerPath))
+        return { folded: 0, skipped: true };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(options.storePath, 'utf-8'));
+    }
+    catch {
+        // No store (or unreadable) -> nothing to fold; do not write a marker so a later
+        // run with a real store still folds.
+        return { folded: 0, skipped: false };
+    }
+    const sessions = isRecord(raw) && isRecord(raw.sessions) ? raw.sessions : {};
+    const records = [];
+    const closedIds = new Set();
+    for (const [key, value] of Object.entries(sessions)) {
+        if (!isRecord(value))
+            continue;
+        const sessionId = typeof value.id === 'string' && value.id.trim().length > 0 ? value.id : key;
+        const title = typeof value.title === 'string' ? value.title : undefined;
+        records.push({ sessionId, project: options.project, ...(title ? { title } : {}) });
+        if (value.status === 'closed')
+            closedIds.add(sessionId);
+    }
+    client.foldLegacyRecords(records, closedIds);
+    try {
+        mkdirSync(dirname(options.markerPath), { recursive: true });
+        writeFileSync(options.markerPath, JSON.stringify({ migratedAt: (options.now ?? Date.now)(), count: records.length, source: options.storePath }, null, 2));
+    }
+    catch (err) {
+        log.debug('session spine legacy fold marker write failed', { err });
+    }
+    return { folded: records.length, skipped: false };
+}

package/dist/platform/runtime/session-spine/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @pellux/goodvibes-sdk/platform/runtime/session-spine
+ *
+ * The ONE session-spine surface client extracted from the near-twin TUI and agent
+ * implementations, plus the cross-surface session read facade (union cache). Both
+ * are consumed by two-plus surfaces (TUI, agent, and — in waiting — webui / PWA),
+ * which is why they live here per the SDK-boundary rule (machinery needed by 2+
+ * surfaces => SDK). See docs/decisions/2026-07-05-session-spine-sdk-extraction.md.
+ */
+export { SessionSpineClient, foldLegacySpineStore, TUI_SPINE_PARTICIPANT, AGENT_SPINE_PARTICIPANT, type SpineReachability, type SpineOutcome, type SpineResult, type SpineTransport, type SessionSpineRecord, type SessionSpineClientOptions, type FoldLegacySpineStoreOptions, type FoldLegacySpineStoreResult, } from './client.js';
+export { SessionUnionCache, deriveSpineFooterStatus, type LocalSessionReader, type WireSessionReader, type SessionUnionMode, type CrossSurfaceView, type SessionReadFacade, type SessionUnionCacheOptions, } from './union-cache.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/platform/runtime/session-spine/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/session-spine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,GAChC,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,GAC9B,MAAM,kBAAkB,CAAC"}

package/dist/platform/runtime/session-spine/index.js

@@ -0,0 +1,11 @@
+/**
+ * @pellux/goodvibes-sdk/platform/runtime/session-spine
+ *
+ * The ONE session-spine surface client extracted from the near-twin TUI and agent
+ * implementations, plus the cross-surface session read facade (union cache). Both
+ * are consumed by two-plus surfaces (TUI, agent, and — in waiting — webui / PWA),
+ * which is why they live here per the SDK-boundary rule (machinery needed by 2+
+ * surfaces => SDK). See docs/decisions/2026-07-05-session-spine-sdk-extraction.md.
+ */
+export { SessionSpineClient, foldLegacySpineStore, TUI_SPINE_PARTICIPANT, AGENT_SPINE_PARTICIPANT, } from './client.js';
+export { SessionUnionCache, deriveSpineFooterStatus, } from './union-cache.js';