crewly 1.13.0 → 1.14.0

package/dist/cli/backend/src/services/session/runtime-pid-registry.service.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Runtime PID Registry
+ *
+ * Tracks the OS process ids of spawned agent-runtime PTY sessions so orphaned
+ * runtime processes can be reaped after a NON-graceful backend death (crash,
+ * OOM-kill, external `kill -9`, or the shutdown force-exit `SIGKILL`-self firing
+ * mid-cleanup). Normal teardown (`killSession`/`forceDestroyAll`) already reaps
+ * children; the gap this closes is the cross-restart one — a fresh backend has
+ * no record of the previous run's children, so they live on indefinitely
+ * (issue #715: ~7 stray `gemini --yolo` on Irissair since Feb).
+ *
+ * Safety is the whole point. The startup reaper:
+ *   1. only ever touches PIDs THIS backend recorded (never a broad `pkill`),
+ *   2. re-reads each live PID's command line and kills it ONLY if it still
+ *      matches the recorded spawn signature — so a PID reused by an unrelated
+ *      process after a crash is left untouched.
+ *
+ * @module services/session/runtime-pid-registry.service
+ */
+/** Registry file name under the Crewly home. */
+export declare const RUNTIME_PID_FILE = "runtime-pids.json";
+/**
+ * Read the live command line for a pid, cross-platform, or null if the process
+ * does not exist / is unreadable.
+ *
+ * - Linux: `/proc/<pid>/cmdline` (NUL-separated argv).
+ * - Other (macOS/BSD): `ps -o command= -p <pid>`.
+ *
+ * @param pid - Process id to inspect.
+ * @returns The normalised command line, or null.
+ */
+export declare function readProcessCmdline(pid: number): string | null;
+/** Whether a pid is currently alive (signal 0 probe). */
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * Persistent, identity-verified registry of spawned runtime PIDs.
+ *
+ * Records are written on session spawn and removed on clean teardown; whatever
+ * remains at the next boot is a candidate orphan from a non-graceful death.
+ */
+export interface RuntimePidRegistryOptions {
+    /** Override the registry file location (tests). */
+    filePath?: string;
+    /** Override how a pid's live command line is read (tests). */
+    cmdlineReader?: (pid: number) => string | null;
+}
+export declare class RuntimePidRegistry {
+    private static instance;
+    private readonly filePath;
+    private readonly cmdlineReader;
+    private readonly logger;
+    private constructor();
+    static getInstance(): RuntimePidRegistry;
+    /** Reset for tests (optionally pointing at a temp file + stub cmdline reader). */
+    static resetForTesting(options?: RuntimePidRegistryOptions): RuntimePidRegistry;
+    private read;
+    private write;
+    /**
+     * Record a freshly spawned runtime process.
+     *
+     * @param pid - PTY child pid.
+     * @param sessionName - Owning session.
+     * @param command - Spawn executable.
+     * @param args - Spawn args.
+     */
+    record(pid: number, sessionName: string, command: string, args?: string[]): void;
+    /**
+     * Drop the record for a session we have torn down ourselves (so it is not a
+     * reap candidate next boot).
+     *
+     * @param sessionName - Session whose record to remove.
+     */
+    remove(sessionName: string): void;
+    /** Clear all records (graceful shutdown reaped everything itself). */
+    clear(): void;
+    /**
+     * Reap orphaned runtime processes left by a previous, non-graceful backend
+     * exit. Call ONCE at boot, before sessions are restored. Kills a recorded pid
+     * only if it is still alive AND its live command line still matches the
+     * recorded signature (guards against PID reuse). Clears the registry after.
+     *
+     * @returns The number of orphan processes reaped.
+     */
+    reapOrphans(): number;
+}
+//# sourceMappingURL=runtime-pid-registry.service.d.ts.map

package/dist/cli/backend/src/services/session/runtime-pid-registry.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-pid-registry.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/session/runtime-pid-registry.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAoBH,gDAAgD;AAChD,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAOpD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAyB7D;AAED,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAS/C;AAED;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAChD;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmC;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiC;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,OAAO;IAMP,MAAM,CAAC,WAAW,IAAI,kBAAkB;IAKxC,kFAAkF;IAClF,MAAM,CAAC,eAAe,CAAC,OAAO,GAAE,yBAA8B,GAAG,kBAAkB;IAKnF,OAAO,CAAC,IAAI;IAWZ,OAAO,CAAC,KAAK;IAWb;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,IAAI;IAQpF;;;;;OAKG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAMjC,sEAAsE;IACtE,KAAK,IAAI,IAAI;IAIb;;;;;;;OAOG;IACH,WAAW,IAAI,MAAM;CAgDtB"}

package/dist/cli/backend/src/services/session/runtime-pid-registry.service.js

@@ -0,0 +1,214 @@
+/**
+ * Runtime PID Registry
+ *
+ * Tracks the OS process ids of spawned agent-runtime PTY sessions so orphaned
+ * runtime processes can be reaped after a NON-graceful backend death (crash,
+ * OOM-kill, external `kill -9`, or the shutdown force-exit `SIGKILL`-self firing
+ * mid-cleanup). Normal teardown (`killSession`/`forceDestroyAll`) already reaps
+ * children; the gap this closes is the cross-restart one — a fresh backend has
+ * no record of the previous run's children, so they live on indefinitely
+ * (issue #715: ~7 stray `gemini --yolo` on Irissair since Feb).
+ *
+ * Safety is the whole point. The startup reaper:
+ *   1. only ever touches PIDs THIS backend recorded (never a broad `pkill`),
+ *   2. re-reads each live PID's command line and kills it ONLY if it still
+ *      matches the recorded spawn signature — so a PID reused by an unrelated
+ *      process after a crash is left untouched.
+ *
+ * @module services/session/runtime-pid-registry.service
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { execFileSync } from 'child_process';
+import * as path from 'path';
+import { LoggerService } from '../core/logger.service.js';
+import { getCrewlyHomePath } from '../core/crewly-home.utils.js';
+/** Registry file name under the Crewly home. */
+export const RUNTIME_PID_FILE = 'runtime-pids.json';
+/** Collapse whitespace + trim so signatures compare stably across `/proc` and `ps`. */
+function normalizeCmdline(s) {
+    return s.replace(/\s+/g, ' ').trim();
+}
+/**
+ * Read the live command line for a pid, cross-platform, or null if the process
+ * does not exist / is unreadable.
+ *
+ * - Linux: `/proc/<pid>/cmdline` (NUL-separated argv).
+ * - Other (macOS/BSD): `ps -o command= -p <pid>`.
+ *
+ * @param pid - Process id to inspect.
+ * @returns The normalised command line, or null.
+ */
+export function readProcessCmdline(pid) {
+    // Linux fast path — read argv directly from /proc.
+    const procPath = `/proc/${pid}/cmdline`;
+    if (existsSync(procPath)) {
+        try {
+            const raw = readFileSync(procPath);
+            // argv is NUL-separated, trailing NUL.
+            const cmd = raw.toString('utf8').replace(/\0/g, ' ');
+            return normalizeCmdline(cmd) || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    // Portable fallback (macOS): ask `ps`.
+    try {
+        const out = execFileSync('ps', ['-o', 'command=', '-p', String(pid)], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const cmd = normalizeCmdline(out);
+        return cmd || null;
+    }
+    catch {
+        // Non-zero exit = no such process.
+        return null;
+    }
+}
+/** Whether a pid is currently alive (signal 0 probe). */
+export function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 1)
+        return false; // never touch pid 0/1
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM = exists but not ours to signal → treat as alive (don't reap).
+        return err.code === 'EPERM';
+    }
+}
+export class RuntimePidRegistry {
+    static instance = null;
+    filePath;
+    cmdlineReader;
+    logger;
+    constructor(options = {}) {
+        this.filePath = options.filePath ?? path.join(getCrewlyHomePath(), RUNTIME_PID_FILE);
+        this.cmdlineReader = options.cmdlineReader ?? readProcessCmdline;
+        this.logger = LoggerService.getInstance().createComponentLogger('RuntimePidRegistry');
+    }
+    static getInstance() {
+        if (!this.instance)
+            this.instance = new RuntimePidRegistry();
+        return this.instance;
+    }
+    /** Reset for tests (optionally pointing at a temp file + stub cmdline reader). */
+    static resetForTesting(options = {}) {
+        this.instance = new RuntimePidRegistry(options);
+        return this.instance;
+    }
+    read() {
+        if (!existsSync(this.filePath))
+            return [];
+        try {
+            const parsed = JSON.parse(readFileSync(this.filePath, 'utf8'));
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            // Corrupt file — treat as empty (and it gets rewritten on next mutation).
+            return [];
+        }
+    }
+    write(records) {
+        try {
+            mkdirSync(path.dirname(this.filePath), { recursive: true });
+            writeFileSync(this.filePath, JSON.stringify(records, null, 2), 'utf8');
+        }
+        catch (err) {
+            this.logger.warn('Failed to persist runtime PID registry (non-fatal)', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /**
+     * Record a freshly spawned runtime process.
+     *
+     * @param pid - PTY child pid.
+     * @param sessionName - Owning session.
+     * @param command - Spawn executable.
+     * @param args - Spawn args.
+     */
+    record(pid, sessionName, command, args = []) {
+        if (!Number.isInteger(pid) || pid <= 1)
+            return;
+        const signature = normalizeCmdline([command, ...args].join(' '));
+        const records = this.read().filter((r) => r.sessionName !== sessionName && r.pid !== pid);
+        records.push({ pid, sessionName, signature, spawnedAt: new Date().toISOString() });
+        this.write(records);
+    }
+    /**
+     * Drop the record for a session we have torn down ourselves (so it is not a
+     * reap candidate next boot).
+     *
+     * @param sessionName - Session whose record to remove.
+     */
+    remove(sessionName) {
+        const records = this.read();
+        const next = records.filter((r) => r.sessionName !== sessionName);
+        if (next.length !== records.length)
+            this.write(next);
+    }
+    /** Clear all records (graceful shutdown reaped everything itself). */
+    clear() {
+        this.write([]);
+    }
+    /**
+     * Reap orphaned runtime processes left by a previous, non-graceful backend
+     * exit. Call ONCE at boot, before sessions are restored. Kills a recorded pid
+     * only if it is still alive AND its live command line still matches the
+     * recorded signature (guards against PID reuse). Clears the registry after.
+     *
+     * @returns The number of orphan processes reaped.
+     */
+    reapOrphans() {
+        const records = this.read();
+        if (records.length === 0)
+            return 0;
+        let reaped = 0;
+        for (const rec of records) {
+            if (!isPidAlive(rec.pid))
+                continue;
+            const liveCmdline = this.cmdlineReader(rec.pid);
+            if (!liveCmdline || !liveCmdline.includes(rec.signature)) {
+                // Either unreadable, or the PID was reused by an unrelated process —
+                // do NOT kill. Log so a surprising mismatch is observable.
+                this.logger.warn('Skipping recorded PID — not a matching runtime (reused or changed)', {
+                    pid: rec.pid,
+                    sessionName: rec.sessionName,
+                    expected: rec.signature,
+                    live: liveCmdline ?? '(gone)',
+                });
+                continue;
+            }
+            // Verified orphan — SIGKILL the process and its group.
+            this.logger.error('Reaping orphaned runtime process from a previous backend run', {
+                pid: rec.pid,
+                sessionName: rec.sessionName,
+                signature: rec.signature,
+                spawnedAt: rec.spawnedAt,
+            });
+            try {
+                process.kill(rec.pid, 'SIGKILL');
+            }
+            catch {
+                /* already gone between the probe and now */
+            }
+            try {
+                process.kill(-rec.pid, 'SIGKILL'); // process group
+            }
+            catch {
+                /* no group / already gone */
+            }
+            reaped++;
+        }
+        // Whatever was recorded belongs to a prior run — this run records fresh.
+        this.clear();
+        if (reaped > 0) {
+            this.logger.warn('Orphan runtime reaper finished', { reaped, scanned: records.length });
+        }
+        return reaped;
+    }
+}
+//# sourceMappingURL=runtime-pid-registry.service.js.map

package/dist/cli/backend/src/services/session/runtime-pid-registry.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-pid-registry.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/session/runtime-pid-registry.service.ts"],"names":[],"mappings":"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"}

package/dist/cli/backend/src/services/session/session-backend.factory.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Session Backend Factory Module
+ *
+ * Provides factory functions for creating and accessing session backend instances.
+ * Uses a singleton pattern to ensure only one backend instance is active at a time.
+ *
+ * @module session-backend.factory
+ */
+import { ISessionBackend, SessionBackendType } from './session-backend.interface.js';
+/**
+ * Create a new session backend instance.
+ *
+ * This function creates a new backend instance based on the specified type.
+ * If a backend already exists and is of a different type, the existing
+ * backend will be destroyed before creating the new one.
+ *
+ * @param type - Type of backend to create. Defaults to 'pty'.
+ * @returns The created session backend instance
+ * @throws Error if the backend type is not supported or creation fails
+ *
+ * @example
+ * ```typescript
+ * // Create a PTY backend (default)
+ * const backend = await createSessionBackend();
+ *
+ * // Create a specific backend type
+ * const ptyBackend = await createSessionBackend('pty');
+ * ```
+ */
+export declare function createSessionBackend(type?: SessionBackendType): Promise<ISessionBackend>;
+/**
+ * Get the singleton session backend instance.
+ *
+ * Returns the currently active session backend instance, or creates a new
+ * PTY backend if none exists.
+ *
+ * @returns The session backend instance
+ * @throws Error if no backend exists and creation fails
+ *
+ * @example
+ * ```typescript
+ * const backend = await getSessionBackend();
+ * const session = await backend.createSession('my-session', options);
+ * ```
+ */
+export declare function getSessionBackend(): Promise<ISessionBackend>;
+/**
+ * Get the singleton session backend instance synchronously.
+ *
+ * Returns the currently active session backend instance, or null if none exists.
+ * This is useful for checking if a backend has been initialized without
+ * triggering creation.
+ *
+ * @returns The session backend instance if it exists, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const backend = getSessionBackendSync();
+ * if (backend) {
+ *   console.log('Backend is initialized');
+ * } else {
+ *   console.log('No backend initialized yet');
+ * }
+ * ```
+ */
+export declare function getSessionBackendSync(): ISessionBackend | null;
+/**
+ * Get the type of the currently active backend.
+ *
+ * @returns The backend type if one is active, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const type = getSessionBackendType();
+ * console.log('Current backend type:', type ?? 'none');
+ * ```
+ */
+export declare function getSessionBackendType(): SessionBackendType | null;
+/**
+ * Destroy the current session backend and release resources.
+ *
+ * This function destroys the singleton backend instance, killing all
+ * active sessions and releasing any held resources.
+ *
+ * @returns Promise that resolves when destruction is complete
+ *
+ * @example
+ * ```typescript
+ * await destroySessionBackend();
+ * console.log('Backend destroyed');
+ * ```
+ */
+export declare function destroySessionBackend(): Promise<void>;
+/**
+ * Check if a session backend is currently initialized.
+ *
+ * @returns true if a backend exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isSessionBackendInitialized()) {
+ *   console.log('Backend is ready');
+ * }
+ * ```
+ */
+export declare function isSessionBackendInitialized(): boolean;
+/**
+ * Reset the factory state (for testing purposes).
+ *
+ * This function resets the internal factory state without destroying
+ * the backend. Use with caution - this is primarily for testing.
+ *
+ * @internal
+ */
+export declare function resetSessionBackendFactory(): void;
+/**
+ * Set the session backend instance (for testing purposes).
+ *
+ * This function allows injecting a mock backend for testing.
+ * Use with caution - this is primarily for testing.
+ *
+ * @param backend - The backend instance to set
+ * @param type - The type of the backend
+ * @internal
+ */
+export declare function setSessionBackendForTesting(backend: ISessionBackend | null, type: SessionBackendType | null): void;
+//# sourceMappingURL=session-backend.factory.d.ts.map

package/dist/cli/backend/src/services/session/session-backend.factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-backend.factory.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/session/session-backend.factory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACN,eAAe,EACf,kBAAkB,EAClB,MAAM,gCAAgC,CAAC;AA2BxC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,oBAAoB,CACzC,IAAI,GAAE,kBAA0B,GAC9B,OAAO,CAAC,eAAe,CAAC,CAwD1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,eAAe,CAAC,CAKlE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,GAAG,IAAI,CAE9D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,IAAI,kBAAkB,GAAG,IAAI,CAEjE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAY3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,IAAI,OAAO,CAErD;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAIjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAC1C,OAAO,EAAE,eAAe,GAAG,IAAI,EAC/B,IAAI,EAAE,kBAAkB,GAAG,IAAI,GAC7B,IAAI,CAGN"}

package/dist/cli/backend/src/services/session/session-backend.factory.js

@@ -0,0 +1,226 @@
+/**
+ * Session Backend Factory Module
+ *
+ * Provides factory functions for creating and accessing session backend instances.
+ * Uses a singleton pattern to ensure only one backend instance is active at a time.
+ *
+ * @module session-backend.factory
+ */
+import { LoggerService } from '../core/logger.service.js';
+import { PtySessionBackend } from './pty/index.js';
+/**
+ * Singleton instance of the session backend
+ */
+let sessionBackendInstance = null;
+/**
+ * Type of the currently active backend
+ */
+let currentBackendType = null;
+/**
+ * Promise-based mutex to prevent race conditions during async initialization.
+ * If a creation is in progress, subsequent calls wait for it to complete.
+ */
+let creationPromise = null;
+/**
+ * Logger for factory operations
+ */
+const getLogger = () => {
+    return LoggerService.getInstance().createComponentLogger('SessionBackendFactory');
+};
+/**
+ * Create a new session backend instance.
+ *
+ * This function creates a new backend instance based on the specified type.
+ * If a backend already exists and is of a different type, the existing
+ * backend will be destroyed before creating the new one.
+ *
+ * @param type - Type of backend to create. Defaults to 'pty'.
+ * @returns The created session backend instance
+ * @throws Error if the backend type is not supported or creation fails
+ *
+ * @example
+ * ```typescript
+ * // Create a PTY backend (default)
+ * const backend = await createSessionBackend();
+ *
+ * // Create a specific backend type
+ * const ptyBackend = await createSessionBackend('pty');
+ * ```
+ */
+export async function createSessionBackend(type = 'pty') {
+    const logger = getLogger();
+    // Return existing instance if it matches the requested type
+    if (sessionBackendInstance && currentBackendType === type) {
+        logger.debug('Returning existing session backend instance', { type });
+        return sessionBackendInstance;
+    }
+    // If a creation is already in progress, wait for it
+    if (creationPromise) {
+        logger.debug('Waiting for in-progress backend creation', { type });
+        return creationPromise;
+    }
+    // Create the backend with mutex protection
+    creationPromise = (async () => {
+        try {
+            // Double-check after acquiring the "lock"
+            if (sessionBackendInstance && currentBackendType === type) {
+                return sessionBackendInstance;
+            }
+            // If we have an existing instance of a different type, destroy it first
+            if (sessionBackendInstance && currentBackendType !== type) {
+                logger.info('Destroying existing backend to switch types', {
+                    oldType: currentBackendType,
+                    newType: type,
+                });
+                await sessionBackendInstance.destroy();
+                sessionBackendInstance = null;
+                currentBackendType = null;
+            }
+            logger.info('Creating new session backend', { type });
+            switch (type) {
+                case 'pty': {
+                    sessionBackendInstance = new PtySessionBackend();
+                    currentBackendType = 'pty';
+                    logger.info('PTY session backend created');
+                    return sessionBackendInstance;
+                }
+                default: {
+                    const exhaustiveCheck = type;
+                    throw new Error(`Unsupported session backend type: ${exhaustiveCheck}`);
+                }
+            }
+        }
+        finally {
+            // Clear the promise after completion (success or failure)
+            creationPromise = null;
+        }
+    })();
+    return creationPromise;
+}
+/**
+ * Get the singleton session backend instance.
+ *
+ * Returns the currently active session backend instance, or creates a new
+ * PTY backend if none exists.
+ *
+ * @returns The session backend instance
+ * @throws Error if no backend exists and creation fails
+ *
+ * @example
+ * ```typescript
+ * const backend = await getSessionBackend();
+ * const session = await backend.createSession('my-session', options);
+ * ```
+ */
+export async function getSessionBackend() {
+    if (!sessionBackendInstance) {
+        return await createSessionBackend('pty');
+    }
+    return sessionBackendInstance;
+}
+/**
+ * Get the singleton session backend instance synchronously.
+ *
+ * Returns the currently active session backend instance, or null if none exists.
+ * This is useful for checking if a backend has been initialized without
+ * triggering creation.
+ *
+ * @returns The session backend instance if it exists, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const backend = getSessionBackendSync();
+ * if (backend) {
+ *   console.log('Backend is initialized');
+ * } else {
+ *   console.log('No backend initialized yet');
+ * }
+ * ```
+ */
+export function getSessionBackendSync() {
+    return sessionBackendInstance;
+}
+/**
+ * Get the type of the currently active backend.
+ *
+ * @returns The backend type if one is active, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const type = getSessionBackendType();
+ * console.log('Current backend type:', type ?? 'none');
+ * ```
+ */
+export function getSessionBackendType() {
+    return currentBackendType;
+}
+/**
+ * Destroy the current session backend and release resources.
+ *
+ * This function destroys the singleton backend instance, killing all
+ * active sessions and releasing any held resources.
+ *
+ * @returns Promise that resolves when destruction is complete
+ *
+ * @example
+ * ```typescript
+ * await destroySessionBackend();
+ * console.log('Backend destroyed');
+ * ```
+ */
+export async function destroySessionBackend() {
+    const logger = getLogger();
+    if (sessionBackendInstance) {
+        logger.info('Destroying session backend', { type: currentBackendType });
+        await sessionBackendInstance.destroy();
+        sessionBackendInstance = null;
+        currentBackendType = null;
+        logger.info('Session backend destroyed');
+    }
+    else {
+        logger.debug('No session backend to destroy');
+    }
+}
+/**
+ * Check if a session backend is currently initialized.
+ *
+ * @returns true if a backend exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isSessionBackendInitialized()) {
+ *   console.log('Backend is ready');
+ * }
+ * ```
+ */
+export function isSessionBackendInitialized() {
+    return sessionBackendInstance !== null;
+}
+/**
+ * Reset the factory state (for testing purposes).
+ *
+ * This function resets the internal factory state without destroying
+ * the backend. Use with caution - this is primarily for testing.
+ *
+ * @internal
+ */
+export function resetSessionBackendFactory() {
+    sessionBackendInstance = null;
+    currentBackendType = null;
+    creationPromise = null;
+}
+/**
+ * Set the session backend instance (for testing purposes).
+ *
+ * This function allows injecting a mock backend for testing.
+ * Use with caution - this is primarily for testing.
+ *
+ * @param backend - The backend instance to set
+ * @param type - The type of the backend
+ * @internal
+ */
+export function setSessionBackendForTesting(backend, type) {
+    sessionBackendInstance = backend;
+    currentBackendType = type;
+}
+//# sourceMappingURL=session-backend.factory.js.map

package/dist/cli/backend/src/services/session/session-backend.factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-backend.factory.js","sourceRoot":"","sources":["../../../../../../backend/src/services/session/session-backend.factory.ts"],"names":[],"mappings":"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"}