llm-cli-gateway 1.0.0

package/dist/process-monitor.js

@@ -0,0 +1,146 @@
+/**
+ * On-demand process health monitoring via /proc (Linux).
+ * Gracefully degrades on non-Linux platforms.
+ */
+import { readFileSync } from "fs";
+import { noopLogger } from "./logger.js";
+/**
+ * Parse /proc/[pid]/stat safely.
+ * The `comm` field (field 2) is in parentheses and may contain spaces,
+ * so we find the LAST ')' and parse remaining fields from there.
+ */
+export function parseProcStat(content) {
+    const lastParen = content.lastIndexOf(")");
+    if (lastParen === -1)
+        return null;
+    const afterComm = content.slice(lastParen + 2); // skip ") "
+    const fields = afterComm.split(" ");
+    // fields[0] = state, fields[11] = utime (14-3), fields[12] = stime (15-3)
+    if (fields.length < 13)
+        return null;
+    return {
+        state: fields[0],
+        utime: parseInt(fields[11], 10),
+        stime: parseInt(fields[12], 10),
+    };
+}
+/**
+ * Parse VmRSS from /proc/[pid]/status.
+ * Returns RSS in kilobytes (already in kB in /proc/[pid]/status).
+ */
+export function parseVmRss(content) {
+    const match = content.match(/^VmRSS:\s+(\d+)\s+kB$/m);
+    return match ? parseInt(match[1], 10) : null;
+}
+/**
+ * Read total system CPU jiffies from /proc/stat.
+ * Used to normalize per-process CPU into a percentage.
+ */
+function getTotalCpuJiffies() {
+    try {
+        const content = readFileSync("/proc/stat", "utf-8");
+        const cpuLine = content.split("\n")[0]; // "cpu  user nice system idle ..."
+        const fields = cpuLine.split(/\s+/).slice(1).map(Number);
+        return fields.reduce((a, b) => a + b, 0);
+    }
+    catch {
+        return null;
+    }
+}
+export class ProcessMonitor {
+    logger;
+    // Previous samples for CPU delta calculation
+    prevSamples = new Map();
+    constructor(logger = noopLogger) {
+        this.logger = logger;
+    }
+    /** Clear all cached CPU samples */
+    reset() {
+        this.prevSamples.clear();
+    }
+    sampleProcess(pid) {
+        const now = new Date().toISOString();
+        // 1. Existence check
+        let alive = false;
+        try {
+            process.kill(pid, 0);
+            alive = true;
+        }
+        catch (err) {
+            if (err.code === "ESRCH") {
+                return { pid, alive: false, state: null, cpuPercent: null, memoryRssKb: null, sampledAt: now };
+            }
+            // EPERM = process exists but we can't signal it
+            if (err.code === "EPERM") {
+                alive = true;
+            }
+        }
+        // 2. Parse /proc/[pid]/stat for state + CPU ticks
+        let state = null;
+        let cpuPercent = null;
+        try {
+            const statContent = readFileSync(`/proc/${pid}/stat`, "utf-8");
+            const parsed = parseProcStat(statContent);
+            if (parsed) {
+                state = parsed.state;
+                // CPU delta calculation
+                const totalJiffies = getTotalCpuJiffies();
+                const prev = this.prevSamples.get(pid);
+                if (prev && totalJiffies !== null) {
+                    const processJiffiesDelta = (parsed.utime + parsed.stime) - (prev.utime + prev.stime);
+                    const totalJiffiesDelta = totalJiffies - prev.totalJiffies;
+                    if (totalJiffiesDelta > 0) {
+                        cpuPercent = (processJiffiesDelta / totalJiffiesDelta) * 100;
+                    }
+                }
+                // Store for next delta
+                if (totalJiffies !== null) {
+                    this.prevSamples.set(pid, {
+                        utime: parsed.utime, stime: parsed.stime,
+                        totalJiffies, timestamp: Date.now()
+                    });
+                }
+            }
+        }
+        catch {
+            // /proc not available (non-Linux) — degrade gracefully
+        }
+        // 3. Parse /proc/[pid]/status for VmRSS
+        let memoryRssKb = null;
+        try {
+            const statusContent = readFileSync(`/proc/${pid}/status`, "utf-8");
+            memoryRssKb = parseVmRss(statusContent);
+        }
+        catch {
+            // Non-Linux or process exited between checks
+        }
+        return { pid, alive, state, cpuPercent, memoryRssKb, sampledAt: now };
+    }
+    checkJobHealth(jobs) {
+        return jobs.map(job => {
+            const runningForMs = Date.now() - new Date(job.startedAt).getTime();
+            if (!job.pid) {
+                return {
+                    jobId: job.jobId, cli: job.cli, status: job.status,
+                    processHealth: null, isDead: false, isZombie: false, runningForMs
+                };
+            }
+            const health = this.sampleProcess(job.pid);
+            return {
+                jobId: job.jobId, cli: job.cli, status: job.status,
+                processHealth: health,
+                isDead: job.status === "running" && !health.alive,
+                isZombie: job.status === "running" && health.state === "Z",
+                runningForMs
+            };
+        });
+    }
+    /** Clean up stale samples for PIDs that no longer exist */
+    cleanupSamples(activePids) {
+        for (const pid of this.prevSamples.keys()) {
+            if (!activePids.has(pid)) {
+                this.prevSamples.delete(pid);
+            }
+        }
+    }
+}

package/dist/request-helpers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure, side-effect-free helpers for request argument planning.
+ * Zero I/O, zero dependencies on index-scoped collaborators.
+ */
+/** Prefix for gateway-generated session IDs. Enforces provenance structurally. */
+export declare const GATEWAY_SESSION_PREFIX = "gw-";
+export interface SessionResumeResult {
+    resumeArgs: string[];
+    effectiveSessionId: string | undefined;
+    userProvidedSession: boolean;
+}
+/**
+ * Validate that a user-provided sessionId doesn't use the reserved gateway prefix.
+ * Throws if the ID starts with "gw-" — this namespace is reserved for gateway-generated IDs.
+ */
+export declare function validateSessionId(sessionId: string): void;
+/**
+ * Pure function: determine --resume args and session provenance from request flags.
+ * Does NOT perform any session I/O — callers handle create/update separately.
+ */
+export declare function resolveSessionResumeArgs(opts: {
+    sessionId?: string;
+    resumeLatest?: boolean;
+    createNewSession?: boolean;
+}): SessionResumeResult;

package/dist/request-helpers.js

@@ -0,0 +1,32 @@
+/**
+ * Pure, side-effect-free helpers for request argument planning.
+ * Zero I/O, zero dependencies on index-scoped collaborators.
+ */
+/** Prefix for gateway-generated session IDs. Enforces provenance structurally. */
+export const GATEWAY_SESSION_PREFIX = "gw-";
+/**
+ * Validate that a user-provided sessionId doesn't use the reserved gateway prefix.
+ * Throws if the ID starts with "gw-" — this namespace is reserved for gateway-generated IDs.
+ */
+export function validateSessionId(sessionId) {
+    if (sessionId.startsWith(GATEWAY_SESSION_PREFIX)) {
+        throw new Error(`Session ID "${sessionId}" uses reserved prefix "${GATEWAY_SESSION_PREFIX}". Gateway-generated session IDs cannot be used for --resume.`);
+    }
+}
+/**
+ * Pure function: determine --resume args and session provenance from request flags.
+ * Does NOT perform any session I/O — callers handle create/update separately.
+ */
+export function resolveSessionResumeArgs(opts) {
+    if (opts.createNewSession) {
+        return { resumeArgs: [], effectiveSessionId: undefined, userProvidedSession: false };
+    }
+    if (opts.resumeLatest && !opts.sessionId) {
+        return { resumeArgs: ["--resume", "latest"], effectiveSessionId: undefined, userProvidedSession: false };
+    }
+    if (opts.sessionId) {
+        validateSessionId(opts.sessionId);
+        return { resumeArgs: ["--resume", opts.sessionId], effectiveSessionId: opts.sessionId, userProvidedSession: true };
+    }
+    return { resumeArgs: [], effectiveSessionId: undefined, userProvidedSession: false };
+}

package/dist/resources.d.ts

@@ -0,0 +1,26 @@
+import { ISessionManager } from "./session-manager.js";
+import { PerformanceMetrics } from "./metrics.js";
+export interface ResourceDefinition {
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    annotations?: {
+        audience?: ("user" | "assistant")[];
+        priority?: number;
+        lastModified?: string;
+    };
+}
+export interface ResourceContents {
+    uri: string;
+    mimeType: string;
+    text: string;
+}
+export declare class ResourceProvider {
+    private sessionManager;
+    private performanceMetrics;
+    constructor(sessionManager: ISessionManager, performanceMetrics: PerformanceMetrics);
+    listResources(): ResourceDefinition[];
+    readResource(uri: string): Promise<ResourceContents | null>;
+}

package/dist/resources.js

@@ -0,0 +1,201 @@
+import { getCliInfo } from "./model-registry.js";
+export class ResourceProvider {
+    sessionManager;
+    performanceMetrics;
+    constructor(sessionManager, performanceMetrics) {
+        this.sessionManager = sessionManager;
+        this.performanceMetrics = performanceMetrics;
+    }
+    // List all available resources
+    listResources() {
+        return [
+            {
+                uri: "sessions://all",
+                name: "All Sessions",
+                title: "📋 All Sessions",
+                description: "List of all conversation sessions across all CLIs",
+                mimeType: "application/json",
+                annotations: {
+                    audience: ["user", "assistant"],
+                    priority: 0.7,
+                    lastModified: new Date().toISOString()
+                }
+            },
+            {
+                uri: "sessions://claude",
+                name: "Claude Sessions",
+                title: "🤖 Claude Sessions",
+                description: "List of Claude conversation sessions",
+                mimeType: "application/json",
+                annotations: {
+                    audience: ["user", "assistant"],
+                    priority: 0.6
+                }
+            },
+            {
+                uri: "sessions://codex",
+                name: "Codex Sessions",
+                title: "💻 Codex Sessions",
+                description: "List of Codex conversation sessions",
+                mimeType: "application/json",
+                annotations: {
+                    audience: ["user", "assistant"],
+                    priority: 0.6
+                }
+            },
+            {
+                uri: "sessions://gemini",
+                name: "Gemini Sessions",
+                title: "✨ Gemini Sessions",
+                description: "List of Gemini conversation sessions",
+                mimeType: "application/json",
+                annotations: {
+                    audience: ["user", "assistant"],
+                    priority: 0.6
+                }
+            },
+            {
+                uri: "models://claude",
+                name: "Claude Models",
+                title: "🧠 Claude Models & Capabilities",
+                description: "Available Claude models and their capabilities",
+                mimeType: "application/json",
+                annotations: {
+                    audience: ["user", "assistant"],
+                    priority: 0.8
+                }
+            },
+            {
+                uri: "models://codex",
+                name: "Codex Models",
+                title: "🔧 Codex Models & Capabilities",
+                description: "Available Codex models and their capabilities",
+                mimeType: "application/json",
+                annotations: {
+                    audience: ["user", "assistant"],
+                    priority: 0.8
+                }
+            },
+            {
+                uri: "models://gemini",
+                name: "Gemini Models",
+                title: "🌟 Gemini Models & Capabilities",
+                description: "Available Gemini models and their capabilities",
+                mimeType: "application/json",
+                annotations: {
+                    audience: ["user", "assistant"],
+                    priority: 0.8
+                }
+            },
+            {
+                uri: "metrics://performance",
+                name: "Performance Metrics",
+                title: "📈 Performance Metrics",
+                description: "Request counts, response times, and success/failure rates",
+                mimeType: "application/json",
+                annotations: {
+                    audience: ["user", "assistant"],
+                    priority: 0.9
+                }
+            }
+        ];
+    }
+    // Read a specific resource by URI
+    async readResource(uri) {
+        // Session resources
+        if (uri === "sessions://all") {
+            const sessions = await this.sessionManager.listSessions();
+            return {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify({
+                    total: sessions.length,
+                    sessions: sessions.map((s) => ({
+                        id: s.id,
+                        cli: s.cli,
+                        description: s.description,
+                        createdAt: s.createdAt,
+                        lastUsedAt: s.lastUsedAt
+                    })),
+                    activeSessions: {
+                        claude: (await this.sessionManager.getActiveSession("claude"))?.id || null,
+                        codex: (await this.sessionManager.getActiveSession("codex"))?.id || null,
+                        gemini: (await this.sessionManager.getActiveSession("gemini"))?.id || null
+                    }
+                }, null, 2)
+            };
+        }
+        if (uri === "sessions://claude") {
+            const sessions = await this.sessionManager.listSessions("claude");
+            return {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify({
+                    cli: "claude",
+                    total: sessions.length,
+                    sessions,
+                    activeSession: (await this.sessionManager.getActiveSession("claude"))?.id || null
+                }, null, 2)
+            };
+        }
+        if (uri === "sessions://codex") {
+            const sessions = await this.sessionManager.listSessions("codex");
+            return {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify({
+                    cli: "codex",
+                    total: sessions.length,
+                    sessions,
+                    activeSession: (await this.sessionManager.getActiveSession("codex"))?.id || null
+                }, null, 2)
+            };
+        }
+        if (uri === "sessions://gemini") {
+            const sessions = await this.sessionManager.listSessions("gemini");
+            return {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify({
+                    cli: "gemini",
+                    total: sessions.length,
+                    sessions,
+                    activeSession: (await this.sessionManager.getActiveSession("gemini"))?.id || null
+                }, null, 2)
+            };
+        }
+        // Model capability resources
+        if (uri === "models://claude") {
+            const cliInfo = getCliInfo();
+            return {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify(cliInfo.claude, null, 2)
+            };
+        }
+        if (uri === "models://codex") {
+            const cliInfo = getCliInfo();
+            return {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify(cliInfo.codex, null, 2)
+            };
+        }
+        if (uri === "models://gemini") {
+            const cliInfo = getCliInfo();
+            return {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify(cliInfo.gemini, null, 2)
+            };
+        }
+        if (uri === "metrics://performance") {
+            return {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify(this.performanceMetrics.snapshot(), null, 2)
+            };
+        }
+        return null;
+    }
+}

package/dist/retry.d.ts

@@ -0,0 +1,72 @@
+/**
+ * A module for adding retry and circuit breaker logic to asynchronous operations.
+ *
+ * @module retry
+ */
+import type { Logger } from "./logger.js";
+/**
+ * Defines the possible states of the circuit breaker.
+ */
+export declare enum CircuitBreakerState {
+    /** The circuit is closed and allows operations to execute. */
+    CLOSED = "CLOSED",
+    /** The circuit is open and fails operations immediately. */
+    OPEN = "OPEN",
+    /** The circuit is half-open and allows a single trial operation. */
+    HALF_OPEN = "HALF_OPEN"
+}
+/**
+ * Represents the state and configuration of a circuit breaker.
+ */
+export interface CircuitBreaker {
+    state: CircuitBreakerState;
+    failures: number;
+    lastFailureTime: number | null;
+    readonly resetTimeout: number;
+    readonly failureThreshold: number;
+    onStateChange?: (newState: CircuitBreakerState, error?: Error) => void;
+}
+/**
+ * Configuration options for the retry logic.
+ */
+export interface RetryOptions {
+    /** The initial delay in milliseconds before the first retry. */
+    initialDelay: number;
+    /** The maximum delay in milliseconds between retries. */
+    maxDelay: number;
+    /** The exponential backoff factor. */
+    factor: number;
+    /**
+     * A function that determines if an error is transient and should be retried.
+     * @param error The error to check.
+     * @returns `true` if the error is transient, otherwise `false`.
+     */
+    isTransient: (error: any) => boolean;
+    /**
+     * A callback function executed on each retry attempt.
+     * @param error The error that caused the retry.
+     * @param attempt The current retry attempt number.
+     * @param delay The delay in milliseconds before the next attempt.
+     */
+    onRetry: (error: any, attempt: number, delay: number) => void;
+}
+/**
+ * Creates a new CircuitBreaker instance with default settings.
+ * @param options Partial options to override defaults.
+ * @returns A new CircuitBreaker instance.
+ */
+export declare function createCircuitBreaker(options?: {
+    resetTimeout?: number;
+    failureThreshold?: number;
+    onStateChange?: (newState: CircuitBreakerState, error?: Error) => void;
+}): CircuitBreaker;
+/**
+ * Wraps an asynchronous operation with retry and circuit breaker logic.
+ *
+ * @template T The return type of the operation.
+ * @param {() => Promise<T>} operation The asynchronous operation to execute.
+ * @param {CircuitBreaker} circuitBreaker The circuit breaker instance to use.
+ * @param {Partial<RetryOptions>} [retryOptions] Options for retry behavior.
+ * @returns {Promise<T>} A promise that resolves with the result of the operation.
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, circuitBreaker: CircuitBreaker, retryOptions?: Partial<RetryOptions>, logger?: Logger): Promise<T>;

package/dist/retry.js

@@ -0,0 +1,146 @@
+/**
+ * A module for adding retry and circuit breaker logic to asynchronous operations.
+ *
+ * @module retry
+ */
+/**
+ * Defines the possible states of the circuit breaker.
+ */
+export var CircuitBreakerState;
+(function (CircuitBreakerState) {
+    /** The circuit is closed and allows operations to execute. */
+    CircuitBreakerState["CLOSED"] = "CLOSED";
+    /** The circuit is open and fails operations immediately. */
+    CircuitBreakerState["OPEN"] = "OPEN";
+    /** The circuit is half-open and allows a single trial operation. */
+    CircuitBreakerState["HALF_OPEN"] = "HALF_OPEN";
+})(CircuitBreakerState || (CircuitBreakerState = {}));
+/**
+ * Default function to determine if an error is transient.
+ * Retries on timeout (exit code 124) and common network errors.
+ * Does not retry on file-not-found (ENOENT) or other errors.
+ * @param error The error object.
+ * @returns True if the error is considered transient.
+ */
+const isDefaultTransient = (error) => {
+    if (!error) {
+        return false;
+    }
+    // Shell command-related errors
+    if (error.code === 124) { // wall-clock timeout (explicit, caller-set) — transient
+        return true;
+    }
+    // Note: exit code 125 = idle timeout (stuck process) — intentionally non-transient
+    if (error.code === 'ENOENT') { // command not found
+        return false;
+    }
+    // Node.js network errors
+    const transientErrorCodes = ['ECONNRESET', 'ETIMEDOUT', 'ECONNREFUSED', 'EPIPE'];
+    if (transientErrorCodes.includes(error.code)) {
+        return true;
+    }
+    return false;
+};
+/**
+ * Creates a new CircuitBreaker instance with default settings.
+ * @param options Partial options to override defaults.
+ * @returns A new CircuitBreaker instance.
+ */
+export function createCircuitBreaker(options) {
+    return {
+        state: CircuitBreakerState.CLOSED,
+        failures: 0,
+        lastFailureTime: null,
+        resetTimeout: options?.resetTimeout ?? 60000, // 60 seconds
+        failureThreshold: options?.failureThreshold ?? 5,
+        onStateChange: options?.onStateChange,
+    };
+}
+/**
+ * Wraps an asynchronous operation with retry and circuit breaker logic.
+ *
+ * @template T The return type of the operation.
+ * @param {() => Promise<T>} operation The asynchronous operation to execute.
+ * @param {CircuitBreaker} circuitBreaker The circuit breaker instance to use.
+ * @param {Partial<RetryOptions>} [retryOptions] Options for retry behavior.
+ * @returns {Promise<T>} A promise that resolves with the result of the operation.
+ */
+export async function withRetry(operation, circuitBreaker, retryOptions, logger) {
+    const wrapError = (message, error) => {
+        const wrapped = new Error(message);
+        if (error) {
+            wrapped.cause = error;
+            if ("code" in error) {
+                wrapped.code = error.code;
+            }
+            if ("result" in error) {
+                wrapped.result = error.result;
+            }
+        }
+        return wrapped;
+    };
+    const options = {
+        initialDelay: 1000, // 1s
+        maxDelay: 30000, // 30s
+        factor: 2,
+        isTransient: isDefaultTransient,
+        onRetry: (error, attempt, delay) => {
+            logger?.debug(`[Retry] Attempt ${attempt} failed with transient error. Retrying in ${delay}ms... ${error.message}`);
+        },
+        ...retryOptions,
+    };
+    if (circuitBreaker.state === CircuitBreakerState.OPEN) {
+        const timeSinceFailure = Date.now() - (circuitBreaker.lastFailureTime ?? 0);
+        if (timeSinceFailure > circuitBreaker.resetTimeout) {
+            circuitBreaker.state = CircuitBreakerState.HALF_OPEN;
+            circuitBreaker.onStateChange?.(CircuitBreakerState.HALF_OPEN);
+        }
+        else {
+            const remaining = Math.ceil((circuitBreaker.resetTimeout - timeSinceFailure) / 1000);
+            throw wrapError(`[CircuitBreaker] Circuit is open. Failing fast. Will not try for another ${remaining}s.`);
+        }
+    }
+    const maxAttempts = circuitBreaker.failureThreshold;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const result = await operation();
+            if (circuitBreaker.failures > 0 || circuitBreaker.state === CircuitBreakerState.HALF_OPEN) {
+                const oldState = circuitBreaker.state;
+                circuitBreaker.failures = 0;
+                circuitBreaker.lastFailureTime = null;
+                circuitBreaker.state = CircuitBreakerState.CLOSED;
+                if (oldState !== CircuitBreakerState.CLOSED) {
+                    circuitBreaker.onStateChange?.(CircuitBreakerState.CLOSED);
+                }
+            }
+            return result;
+        }
+        catch (error) {
+            if (!options.isTransient(error)) {
+                throw wrapError(`[CircuitBreaker] Operation failed with non-transient error: ${error.message}`, error);
+            }
+            circuitBreaker.failures++;
+            circuitBreaker.lastFailureTime = Date.now();
+            if (circuitBreaker.state === CircuitBreakerState.HALF_OPEN) {
+                circuitBreaker.state = CircuitBreakerState.OPEN;
+                circuitBreaker.onStateChange?.(CircuitBreakerState.OPEN, error);
+                throw wrapError(`[CircuitBreaker] Circuit re-opened after failed attempt in HALF_OPEN state. Last error: ${error.message}`, error);
+            }
+            if (circuitBreaker.failures >= circuitBreaker.failureThreshold) {
+                const oldState = circuitBreaker.state;
+                circuitBreaker.state = CircuitBreakerState.OPEN;
+                if (oldState === CircuitBreakerState.CLOSED) {
+                    circuitBreaker.onStateChange?.(CircuitBreakerState.OPEN, error);
+                }
+                throw wrapError(`[CircuitBreaker] Circuit opened after ${circuitBreaker.failures} consecutive failures. Last error: ${error.message}`, error);
+            }
+            if (attempt === maxAttempts) {
+                throw error;
+            }
+            const delay = Math.min(options.initialDelay * options.factor ** (attempt - 1), options.maxDelay);
+            options.onRetry(error, attempt, delay);
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    throw new Error('[Retry] Operation failed after all retry attempts.');
+}