llm-cli-gateway 1.17.3 → 1.17.5

package/dist/retry.js

@@ -1,72 +1,35 @@
-/**
- * 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
+        resetTimeout: options?.resetTimeout ?? 60000,
         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);
@@ -82,8 +45,8 @@ export async function withRetry(operation, circuitBreaker, retryOptions, logger)
         return wrapped;
     };
     const options = {
-        initialDelay: 1000, // 1s
-        maxDelay: 30000, // 30s
+        initialDelay: 1000,
+        maxDelay: 30000,
         factor: 2,
         isTransient: isDefaultTransient,
         onRetry: (error, attempt, delay) => {

package/dist/session-manager-pg.d.ts

@@ -1,48 +1,16 @@
 import type { Pool } from "pg";
 import { Session, CliType } from "./session-manager.js";
 export type { Logger } from "./logger.js";
-/**
- * PostgreSQL-backed session manager. PostgreSQL is the source of truth and
- * the only required service for this backend.
- */
 export declare class PostgreSQLSessionManager {
     private pool;
     constructor(pool: Pool);
-    /**
-     * Create a new session.
-     */
     createSession(cli: CliType, description?: string, sessionId?: string): Promise<Session>;
-    /**
-     * Get session by ID.
-     */
     getSession(sessionId: string): Promise<Session | null>;
-    /**
-     * List all sessions, optionally filtered by CLI.
-     */
     listSessions(cli?: CliType): Promise<Session[]>;
-    /**
-     * Delete a session.
-     */
     deleteSession(sessionId: string): Promise<boolean>;
-    /**
-     * Set active session for a CLI. The row-level update is serialized by
-     * PostgreSQL and the session FK keeps stale IDs from being recorded.
-     */
     setActiveSession(cli: CliType, sessionId: string | null): Promise<boolean>;
-    /**
-     * Get active session for a CLI.
-     */
     getActiveSession(cli: CliType): Promise<Session | null>;
-    /**
-     * Update session usage timestamp.
-     */
     updateSessionUsage(sessionId: string): Promise<void>;
-    /**
-     * Update session metadata using PostgreSQL's atomic JSONB merge.
-     */
     updateSessionMetadata(sessionId: string, metadata: Record<string, any>): Promise<boolean>;
-    /**
-     * Clear all sessions, optionally filtered by CLI.
-     */
     clearAllSessions(cli?: CliType): Promise<number>;
 }

package/dist/session-manager-pg.js

@@ -6,18 +6,11 @@ const DEFAULT_SESSION_DESCRIPTIONS = {
     grok: "Grok Session",
     mistral: "Mistral Session",
 };
-/**
- * PostgreSQL-backed session manager. PostgreSQL is the source of truth and
- * the only required service for this backend.
- */
 export class PostgreSQLSessionManager {
     pool;
     constructor(pool) {
         this.pool = pool;
     }
-    /**
-     * Create a new session.
-     */
     async createSession(cli, description, sessionId) {
         const id = sessionId || randomUUID();
         const sessionDescription = description ?? DEFAULT_SESSION_DESCRIPTIONS[cli];
@@ -47,18 +40,12 @@ export class PostgreSQLSessionManager {
             client.release();
         }
     }
-    /**
-     * Get session by ID.
-     */
     async getSession(sessionId) {
         const result = await this.pool.query(`SELECT id, cli, description, metadata, created_at AS "createdAt", last_used_at AS "lastUsedAt"
        FROM sessions
        WHERE id = $1`, [sessionId]);
         return result.rows[0] ?? null;
     }
-    /**
-     * List all sessions, optionally filtered by CLI.
-     */
     async listSessions(cli) {
         const query = cli
             ? `SELECT id, cli, description, metadata, created_at AS "createdAt", last_used_at AS "lastUsedAt"
@@ -73,9 +60,6 @@ export class PostgreSQLSessionManager {
             : await this.pool.query(query);
         return result.rows;
     }
-    /**
-     * Delete a session.
-     */
     async deleteSession(sessionId) {
         const session = await this.getSession(sessionId);
         if (!session) {
@@ -84,10 +68,6 @@ export class PostgreSQLSessionManager {
         const result = await this.pool.query("DELETE FROM sessions WHERE id = $1", [sessionId]);
         return result.rowCount !== 0;
     }
-    /**
-     * Set active session for a CLI. The row-level update is serialized by
-     * PostgreSQL and the session FK keeps stale IDs from being recorded.
-     */
     async setActiveSession(cli, sessionId) {
         if (sessionId !== null) {
             const session = await this.getSession(sessionId);
@@ -101,9 +81,6 @@ export class PostgreSQLSessionManager {
        ON CONFLICT (cli) DO UPDATE SET session_id = $2, updated_at = $3`, [cli, sessionId, now]);
         return true;
     }
-    /**
-     * Get active session for a CLI.
-     */
     async getActiveSession(cli) {
         const result = await this.pool.query("SELECT session_id FROM active_sessions WHERE cli = $1", [cli]);
         const sessionId = result.rows[0]?.session_id;
@@ -112,16 +89,10 @@ export class PostgreSQLSessionManager {
         }
         return await this.getSession(sessionId);
     }
-    /**
-     * Update session usage timestamp.
-     */
     async updateSessionUsage(sessionId) {
         const now = new Date().toISOString();
         await this.pool.query("UPDATE sessions SET last_used_at = $1 WHERE id = $2", [now, sessionId]);
     }
-    /**
-     * Update session metadata using PostgreSQL's atomic JSONB merge.
-     */
     async updateSessionMetadata(sessionId, metadata) {
         const result = await this.pool.query(`UPDATE sessions
        SET metadata = COALESCE(metadata, '{}'::jsonb) || $1::jsonb
@@ -129,9 +100,6 @@ export class PostgreSQLSessionManager {
        RETURNING id`, [JSON.stringify(metadata), sessionId]);
         return result.rowCount !== 0;
     }
-    /**
-     * Clear all sessions, optionally filtered by CLI.
-     */
     async clearAllSessions(cli) {
         const query = cli ? "DELETE FROM sessions WHERE cli = $1" : "DELETE FROM sessions";
         const result = cli ? await this.pool.query(query, [cli]) : await this.pool.query(query);

package/dist/session-manager.d.ts

@@ -15,15 +15,6 @@ export interface SessionStorage {
     sessions: Record<string, Session>;
     activeSession: Record<CliType, string | null>;
 }
-/**
- * Slice λ: callback invoked before a session record is removed (whether via
- * explicit `deleteSession`, TTL eviction, or `clearAllSessions`). Used to
- * tear down per-session resources owned by the gateway — currently git
- * worktrees registered on `session.metadata.worktreePath`. The hook
- * receives the path; promise failures are logged but do not block session
- * removal (gateway-owned-lifecycle invariant: `session_delete` must always
- * succeed for the caller).
- */
 export type SessionCleanupHook = (session: Session) => void | Promise<void>;
 export declare class FileSessionManager {
     private storagePath;
@@ -52,11 +43,6 @@ export declare class FileSessionManager {
     clearAllSessions(cli?: CliType): number;
 }
 export declare const SessionManager: typeof FileSessionManager;
-/**
- * Session manager interface supporting both sync (file) and async (PostgreSQL) backends.
- * Methods return T | Promise<T> so both backends satisfy the contract.
- * Callers must always use `await` for uniform handling.
- */
 export interface ISessionManager {
     createSession(cli: CliType, description?: string, sessionId?: string): Session | Promise<Session>;
     getSession(sessionId: string): Session | null | Promise<Session | null>;
@@ -68,13 +54,6 @@ export interface ISessionManager {
     updateSessionMetadata(sessionId: string, metadata: Record<string, any>): boolean | Promise<boolean>;
     clearAllSessions(cli?: CliType): number | Promise<number>;
 }
-/**
- * Factory function to create session manager
- * Returns PostgreSQLSessionManager if config present, otherwise FileSessionManager
- * @param config - Configuration object
- * @param db - Optional pre-existing DatabaseConnection (avoids creating duplicate connections)
- * @param logger - Logger instance for structured logging
- */
 export declare function createSessionManager(config?: Config, db?: DatabaseConnection, logger?: Logger, opts?: {
     cleanupHook?: SessionCleanupHook;
 }): Promise<ISessionManager>;

package/dist/session-manager.js

@@ -45,7 +45,7 @@ export class FileSessionManager {
     isExpired(session) {
         const ts = new Date(session.lastUsedAt).getTime();
         if (!Number.isFinite(ts))
-            return true; // malformed → expired
+            return true;
         return Date.now() - ts > this.sessionTtlMs;
     }
     evictExpiredSessions() {
@@ -77,7 +77,6 @@ export class FileSessionManager {
                 this.storage = JSON.parse(data);
             }
             catch {
-                // If file is corrupted, start fresh
                 this.storage = { sessions: {}, activeSession: createEmptyActiveSessions() };
             }
         }
@@ -113,7 +112,6 @@ export class FileSessionManager {
             description: sessionDescription,
         };
         this.storage.sessions[id] = session;
-        // Set as active session if none exists for this CLI
         if (!this.storage.activeSession[cli]) {
             this.storage.activeSession[cli] = id;
         }
@@ -145,7 +143,6 @@ export class FileSessionManager {
         const session = this.storage.sessions[sessionId];
         this.invokeCleanupHook(session);
         delete this.storage.sessions[sessionId];
-        // If this was the active session, clear it
         if (this.storage.activeSession[session.cli] === sessionId) {
             this.storage.activeSession[session.cli] = null;
         }
@@ -220,20 +217,10 @@ export class FileSessionManager {
         return sessionsToDelete.length;
     }
 }
-// Maintain backward compatibility
 export const SessionManager = FileSessionManager;
-/**
- * Factory function to create session manager
- * Returns PostgreSQLSessionManager if config present, otherwise FileSessionManager
- * @param config - Configuration object
- * @param db - Optional pre-existing DatabaseConnection (avoids creating duplicate connections)
- * @param logger - Logger instance for structured logging
- */
 export async function createSessionManager(config, db, logger, opts) {
     if (config?.database) {
-        // Import dynamically to avoid loading pg if not needed.
         const { PostgreSQLSessionManager } = await import("./session-manager-pg.js");
-        // Use provided db connection or create new one
         if (!db) {
             const { createDatabaseConnection } = await import("./db.js");
             db = await createDatabaseConnection(config, logger);
@@ -241,7 +228,6 @@ export async function createSessionManager(config, db, logger, opts) {
         return new PostgreSQLSessionManager(db.getPool());
     }
     else {
-        // Use file-based storage with TTL from config
         const sessionTtlMs = config?.sessionTtl
             ? config.sessionTtl * 1000
             : DEFAULT_SESSION_TTL_SECONDS * 1000;

package/dist/stream-json-parser.d.ts

@@ -1,9 +1,3 @@
-/**
- * NDJSON parser for Claude `--output-format stream-json --include-partial-messages`.
- *
- * Each line of stdout is a complete JSON object. This parser extracts the
- * final result text, cost, usage, and metadata from the stream.
- */
 export interface StreamJsonUsage {
     inputTokens: number;
     outputTokens: number;
@@ -20,16 +14,4 @@ export interface StreamJsonResult {
     isError: boolean;
     numTurns: number | null;
 }
-/**
- * Parse completed NDJSON stdout from `claude --output-format stream-json --include-partial-messages`.
- *
- * Parsing strategy:
- * 1. Split by newlines, filter empty lines
- * 2. JSON.parse each line, skip malformed lines
- * 3. Find the `type=result` event — contains final text, cost, usage
- * 4. Fall back to the last `type=assistant` event if no result event
- * 5. Extract `model` from `type=system` (init) event
- *
- * No rawEvents stored — the stdout buffer is already in memory.
- */
 export declare function parseStreamJson(stdout: string): StreamJsonResult;

package/dist/stream-json-parser.js

@@ -1,9 +1,3 @@
-/**
- * NDJSON parser for Claude `--output-format stream-json --include-partial-messages`.
- *
- * Each line of stdout is a complete JSON object. This parser extracts the
- * final result text, cost, usage, and metadata from the stream.
- */
 function stringOrNull(value) {
     return typeof value === "string" ? value : null;
 }
@@ -13,18 +7,6 @@ function numberOrNull(value) {
 function numberOrZero(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
-/**
- * Parse completed NDJSON stdout from `claude --output-format stream-json --include-partial-messages`.
- *
- * Parsing strategy:
- * 1. Split by newlines, filter empty lines
- * 2. JSON.parse each line, skip malformed lines
- * 3. Find the `type=result` event — contains final text, cost, usage
- * 4. Fall back to the last `type=assistant` event if no result event
- * 5. Extract `model` from `type=system` (init) event
- *
- * No rawEvents stored — the stdout buffer is already in memory.
- */
 export function parseStreamJson(stdout) {
     const lines = stdout.split("\n").filter(line => line.trim().length > 0);
     let resultEvent = null;
@@ -36,7 +18,6 @@ export function parseStreamJson(stdout) {
             parsed = JSON.parse(line);
         }
         catch {
-            // Skip malformed lines
             continue;
         }
         if (!parsed || typeof parsed !== "object") {
@@ -52,7 +33,6 @@ export function parseStreamJson(stdout) {
             systemEvent = parsed;
         }
     }
-    // Extract from result event (preferred)
     if (resultEvent) {
         const usage = resultEvent.usage
             ? {
@@ -73,7 +53,6 @@ export function parseStreamJson(stdout) {
             numTurns: numberOrNull(resultEvent.num_turns),
         };
     }
-    // Fallback: extract text from assistant event
     if (assistantEvent) {
         const message = assistantEvent.message;
         let text = "";
@@ -97,7 +76,6 @@ export function parseStreamJson(stdout) {
             numTurns: null,
         };
     }
-    // No result or assistant event found — return empty
     return {
         text: "",
         costUsd: null,

package/dist/upstream-contracts.d.ts

@@ -1,11 +1,4 @@
 import type { CliType } from "./session-manager.js";
-/**
- * `optional` (slice κ): consumes the next token as the flag's value
- * ONLY if that token does not start with `-`. Used for Claude's
- * `-p`/`--print`, which is a no-arg switch in claude-code 2.x but
- * also doubles as the legacy `-p <prompt>` positional shorthand that
- * the gateway has emitted since v0.x.
- */
 export type CliFlagArity = "none" | "one" | "optional" | "variadic";
 export interface CliFlagContract {
     arity: CliFlagArity;
@@ -13,41 +6,12 @@ export interface CliFlagContract {
     pattern?: RegExp;
     description: string;
 }
-/**
- * Pure upstream-tracking metadata for a provider CLI.
- *
- * IMPORTANT — non-duplication invariant: nothing here encodes mechanical
- * behaviour. Flags, output modes, session/resume rules, permission modes,
- * forbidden flags, env contracts, and positional limits live ONLY in the
- * surrounding {@link CliContract} and are validated ONLY by
- * {@link validateUpstreamCliArgs} / {@link validateUpstreamCliEnv}. The fields
- * below are descriptive pointers used by the upstream changelog scanner
- * (`scripts/upstream-scan.mjs`) and surfaced in the contract report — they
- * never drive argv/env enforcement.
- *
- * `docs/upstream/provider-sources.dag.toml` mirrors `sourceUrls` and
- * `watchCategories` for the scanner's offline scan plan; a unit test
- * (`upstream-sources.test.ts`) asserts the TOML stays in sync with these
- * fields so the two cannot drift. The TypeScript values here are authoritative;
- * the TOML is scanner input only and is never consulted for contract
- * enforcement.
- */
 export interface CliUpstreamMetadata {
-    /** Canonical changelog / release-notes URLs the scanner retrieves with --live. */
     sourceUrls: readonly string[];
-    /** Distribution package identifier (npm package name, PyPI project, …). */
     packageName?: string;
-    /** Source repository URL, when distinct from the changelog source. */
     repo?: string;
-    /** Human-facing install / getting-started docs. */
     installDocsUrl?: string;
-    /** Distribution channel the gateway expects the CLI to ship through. */
     releaseChannel?: "npm" | "pypi" | "github-release" | "vendor";
-    /**
-     * Contract surfaces worth watching in upstream release notes (e.g. "flags",
-     * "output-formats", "session-resume"). Descriptive labels for the scanner and
-     * report ONLY — never a validation input.
-     */
     watchCategories: readonly string[];
 }
 export interface CliContract {
@@ -68,7 +32,6 @@ export interface CliContract {
     resumeMaxPositionals?: number;
     resumeOnlyFlags?: readonly string[];
     resumeForbiddenFlags?: readonly string[];
-    /** Non-mechanical upstream-tracking metadata. See {@link CliUpstreamMetadata}. */
     upstreamMetadata?: CliUpstreamMetadata;
 }
 export interface CliContractFixture {
@@ -93,19 +56,6 @@ export declare function validateUpstreamCliArgs(cli: CliType, args: readonly str
 export declare function assertUpstreamCliArgs(cli: CliType, args: readonly string[]): void;
 export declare function validateUpstreamCliEnv(cli: CliType, env: Record<string, string> | undefined): ContractValidationResult;
 export declare function assertUpstreamCliEnv(cli: CliType, env: Record<string, string> | undefined): void;
-/**
- * Best-effort, advisory-only extraction of long-form flags from raw --help text.
- * Returns a sorted array of unique `--foo-bar` style flags discovered in the output.
- *
- * Heuristics:
- * - Matches common option declaration lines emitted by clap, yargs, commander, custom TUIs, etc.
- * - Lowercases for stable comparison against our contract keys.
- * - Intentionally conservative: ignores obvious noise (URLs, prose in descriptions).
- *
- * This powers the bidirectional drift detector (extra flags the installed binary
- * advertises that our contract does not yet allow). It is NEVER used for argv
- * validation — only for the upstream scanner and `upstream_contracts` probe reports.
- */
 export declare function extractDiscoveredFlags(helpText: string): readonly string[];
 export interface InstalledCliContractProbe {
     cli: CliType;
@@ -115,15 +65,10 @@ export interface InstalledCliContractProbe {
     available: boolean;
     checkedHelpCommands: string[][];
     missingFlags: string[];
-    /** Flags present in the installed binary's --help but absent from the declared contract. */
     extraFlags: readonly string[];
-    /** Sorted list of long flags discovered in the help text (for snapshot diffing). */
     discoveredFlags: readonly string[];
-    /** Stable hash of the concatenated help output (detects subtle text changes even if flag set is stable). */
     helpHash?: string;
-    /** Best-effort version string scraped from the help/version output (if present). */
     versionHint?: string;
-    /** ISO timestamp when this probe was performed. */
     probedAt: string;
     warnings: string[];
 }