llm-cli-gateway 1.14.0 → 1.15.0

package/dist/session-manager.d.ts

@@ -15,11 +15,27 @@ 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;
     private storage;
     private readonly sessionTtlMs;
-    constructor(customPath?: string, sessionTtlMs?: number);
+    private readonly cleanupHook?;
+    private readonly logger;
+    constructor(customPath?: string, sessionTtlMs?: number, opts?: {
+        cleanupHook?: SessionCleanupHook;
+        logger?: Logger;
+    });
+    private invokeCleanupHook;
     private isExpired;
     private evictExpiredSessions;
     private ensureStorageDirectory;
@@ -59,4 +75,6 @@ export interface ISessionManager {
  * @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): Promise<ISessionManager>;
+export declare function createSessionManager(config?: Config, db?: DatabaseConnection, logger?: Logger, opts?: {
+    cleanupHook?: SessionCleanupHook;
+}): Promise<ISessionManager>;

package/dist/session-manager.js

@@ -17,12 +17,31 @@ export class FileSessionManager {
     storagePath;
     storage = { sessions: {}, activeSession: createEmptyActiveSessions() };
     sessionTtlMs;
-    constructor(customPath, sessionTtlMs) {
+    cleanupHook;
+    logger;
+    constructor(customPath, sessionTtlMs, opts) {
         this.sessionTtlMs = sessionTtlMs ?? DEFAULT_SESSION_TTL_SECONDS * 1000;
         this.storagePath = customPath || join(homedir(), ".llm-cli-gateway", "sessions.json");
+        this.cleanupHook = opts?.cleanupHook;
+        this.logger = opts?.logger ?? noopLogger;
         this.ensureStorageDirectory();
         this.loadStorage();
     }
+    invokeCleanupHook(session) {
+        if (!this.cleanupHook)
+            return;
+        try {
+            const result = this.cleanupHook(session);
+            if (result && typeof result.catch === "function") {
+                result.catch(err => {
+                    this.logger.error(`session cleanup hook rejected for ${session.id}`, err);
+                });
+            }
+        }
+        catch (err) {
+            this.logger.error(`session cleanup hook threw for ${session.id}`, err);
+        }
+    }
     isExpired(session) {
         const ts = new Date(session.lastUsedAt).getTime();
         if (!Number.isFinite(ts))
@@ -33,6 +52,7 @@ export class FileSessionManager {
         let count = 0;
         for (const [id, session] of Object.entries(this.storage.sessions)) {
             if (this.isExpired(session)) {
+                this.invokeCleanupHook(session);
                 delete this.storage.sessions[id];
                 if (this.storage.activeSession[session.cli] === id) {
                     this.storage.activeSession[session.cli] = null;
@@ -123,6 +143,7 @@ export class FileSessionManager {
             return false;
         }
         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) {
@@ -189,6 +210,7 @@ export class FileSessionManager {
             ? Object.values(this.storage.sessions).filter(s => s.cli === cli)
             : Object.values(this.storage.sessions);
         sessionsToDelete.forEach(session => {
+            this.invokeCleanupHook(session);
             delete this.storage.sessions[session.id];
             if (this.storage.activeSession[session.cli] === session.id) {
                 this.storage.activeSession[session.cli] = null;
@@ -207,7 +229,7 @@ export const SessionManager = FileSessionManager;
  * @param db - Optional pre-existing DatabaseConnection (avoids creating duplicate connections)
  * @param logger - Logger instance for structured logging
  */
-export async function createSessionManager(config, db, logger) {
+export async function createSessionManager(config, db, logger, opts) {
     if (config?.database && config?.redis) {
         // Import dynamically to avoid loading pg/ioredis if not needed
         const { PostgreSQLSessionManager } = await import("./session-manager-pg.js");
@@ -223,6 +245,9 @@ export async function createSessionManager(config, db, logger) {
         const sessionTtlMs = config?.sessionTtl
             ? config.sessionTtl * 1000
             : DEFAULT_SESSION_TTL_SECONDS * 1000;
-        return new FileSessionManager(undefined, sessionTtlMs);
+        return new FileSessionManager(undefined, sessionTtlMs, {
+            cleanupHook: opts?.cleanupHook,
+            logger,
+        });
     }
 }

package/dist/worktree-manager.d.ts

@@ -0,0 +1,41 @@
+import { type Logger } from "./logger.js";
+export interface WorktreeHandle {
+    name: string;
+    path: string;
+    ref: string;
+    createdAt: string;
+}
+export interface CreateWorktreeOptions {
+    repoRoot: string;
+    name?: string;
+    ref?: string;
+    logger?: Logger;
+}
+export interface RemoveWorktreeOptions {
+    repoRoot: string;
+    path: string;
+    name?: string;
+    logger?: Logger;
+}
+export declare class WorktreeError extends Error {
+    constructor(message: string);
+}
+export declare class WorktreeCollisionError extends WorktreeError {
+    constructor(path: string);
+}
+export declare function sanitizeWorktreeName(input: string): string;
+export declare function createWorktree(opts: CreateWorktreeOptions): Promise<WorktreeHandle>;
+/**
+ * Build a SessionCleanupHook that tears down per-session worktrees. The
+ * hook reads `session.metadata.worktreePath` (recorded by
+ * `resolveWorktreeForRequest`) and the optional `session.metadata.worktreeName`,
+ * derives `repoRoot` from the path layout (`<repoRoot>/.worktrees/<name>`),
+ * and fires `removeWorktree` asynchronously. Failures are logged by
+ * `removeWorktree` itself — the hook always resolves so session deletion
+ * never blocks on git.
+ */
+export declare function createWorktreeSessionCleanupHook(logger: Logger): (session: {
+    id: string;
+    metadata?: Record<string, unknown>;
+}) => Promise<void>;
+export declare function removeWorktree(opts: RemoveWorktreeOptions): Promise<void>;

package/dist/worktree-manager.js

@@ -0,0 +1,214 @@
+import { spawn } from "child_process";
+import { randomUUID } from "crypto";
+import { existsSync } from "fs";
+import { resolve as resolvePath, join, sep } from "path";
+import { logWarn, noopLogger } from "./logger.js";
+const GIT_TIMEOUT_MS = 10_000;
+const NAME_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+export class WorktreeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WorktreeError";
+    }
+}
+export class WorktreeCollisionError extends WorktreeError {
+    constructor(path) {
+        super(`worktree path already exists and is not a registered git worktree: ${path}. ` +
+            `Remove the stale directory (or pick a different worktree name) and retry.`);
+        this.name = "WorktreeCollisionError";
+    }
+}
+export function sanitizeWorktreeName(input) {
+    if (typeof input !== "string") {
+        throw new WorktreeError("worktree name must be a string");
+    }
+    if (input.length === 0) {
+        throw new WorktreeError("worktree name must not be empty");
+    }
+    if (input.length > 64) {
+        throw new WorktreeError("worktree name must be ≤ 64 characters");
+    }
+    if (input === "." || input === "..") {
+        throw new WorktreeError(`worktree name "${input}" is reserved`);
+    }
+    if (input.startsWith(".")) {
+        throw new WorktreeError("worktree name must not start with '.'");
+    }
+    if (input.startsWith("-")) {
+        throw new WorktreeError("worktree name must not start with '-'");
+    }
+    if (input.includes("..")) {
+        throw new WorktreeError("worktree name must not contain '..'");
+    }
+    if (!NAME_PATTERN.test(input)) {
+        throw new WorktreeError(`worktree name "${input}" contains disallowed characters ` +
+            `(allowed: A-Z a-z 0-9 . _ -, length 1-64)`);
+    }
+    return input;
+}
+function generateDefaultName() {
+    return randomUUID().replace(/-/g, "");
+}
+async function execGit(repoRoot, args, logger) {
+    return new Promise((resolveExec, rejectExec) => {
+        const proc = spawn("git", args, {
+            cwd: repoRoot,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: process.env,
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                proc.kill("SIGKILL");
+            }
+            catch {
+                // ignore — process may already be gone
+            }
+            rejectExec(new WorktreeError(`git ${args.join(" ")} timed out after ${GIT_TIMEOUT_MS}ms`));
+        }, GIT_TIMEOUT_MS);
+        proc.stdout.on("data", chunk => stdoutChunks.push(chunk));
+        proc.stderr.on("data", chunk => stderrChunks.push(chunk));
+        proc.on("error", err => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            rejectExec(new WorktreeError(`git ${args.join(" ")} failed to spawn: ${err.message}`));
+        });
+        proc.on("close", code => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            logger.debug?.(`git ${args.join(" ")} exited ${code}`);
+            resolveExec({
+                stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                stderr: Buffer.concat(stderrChunks).toString("utf8"),
+                code: code ?? -1,
+            });
+        });
+    });
+}
+async function listExistingWorktreePaths(repoRoot, logger) {
+    const result = await execGit(repoRoot, ["worktree", "list", "--porcelain"], logger);
+    if (result.code !== 0) {
+        throw new WorktreeError(`git worktree list failed (code ${result.code}): ${result.stderr.trim()}`);
+    }
+    const paths = new Set();
+    for (const line of result.stdout.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            paths.add(line.slice("worktree ".length).trim());
+        }
+    }
+    return paths;
+}
+export async function createWorktree(opts) {
+    const logger = opts.logger ?? noopLogger;
+    if (!opts.repoRoot || !existsSync(opts.repoRoot)) {
+        throw new WorktreeError(`repoRoot does not exist: ${opts.repoRoot}`);
+    }
+    const name = opts.name ? sanitizeWorktreeName(opts.name) : generateDefaultName();
+    const worktreesDir = join(opts.repoRoot, ".worktrees");
+    const expectedPrefix = worktreesDir + sep;
+    const worktreePath = resolvePath(opts.repoRoot, ".worktrees", name);
+    // Defense in depth — sanitizeWorktreeName already blocks slashes, but
+    // double-check that the resolved path is under <repoRoot>/.worktrees/.
+    if (!worktreePath.startsWith(expectedPrefix)) {
+        throw new WorktreeError(`resolved worktree path escapes the expected prefix: ${worktreePath} (expected under ${expectedPrefix})`);
+    }
+    const refArg = opts.ref ?? "HEAD";
+    const revParse = await execGit(opts.repoRoot, ["rev-parse", "--verify", `${refArg}^{commit}`], logger);
+    if (revParse.code !== 0) {
+        throw new WorktreeError(`git rev-parse ${refArg} failed (code ${revParse.code}): ${revParse.stderr.trim()}`);
+    }
+    const resolvedRef = revParse.stdout.trim();
+    const existingPaths = await listExistingWorktreePaths(opts.repoRoot, logger);
+    const pathOnDisk = existsSync(worktreePath);
+    const registered = existingPaths.has(worktreePath);
+    if (pathOnDisk) {
+        if (!registered) {
+            throw new WorktreeCollisionError(worktreePath);
+        }
+        // Resume reuse: the worktree already exists and is registered with git.
+        // Return a handle pointing at it without touching anything.
+        logger.info?.(`reusing existing worktree at ${worktreePath}`);
+        return {
+            name,
+            path: worktreePath,
+            ref: resolvedRef,
+            createdAt: new Date().toISOString(),
+        };
+    }
+    if (registered) {
+        // Path is registered but the directory is gone — let git prune it
+        // before we recreate, so `worktree add` doesn't error on the stale
+        // registration.
+        const prune = await execGit(opts.repoRoot, ["worktree", "prune"], logger);
+        if (prune.code !== 0) {
+            logWarn(logger, `git worktree prune failed before creating ${name}: ${prune.stderr.trim()}`);
+        }
+    }
+    const branch = `gateway/${name}`;
+    const add = await execGit(opts.repoRoot, ["worktree", "add", "-b", branch, worktreePath, resolvedRef], logger);
+    if (add.code !== 0) {
+        throw new WorktreeError(`git worktree add failed (code ${add.code}): ${add.stderr.trim() || add.stdout.trim()}`);
+    }
+    return {
+        name,
+        path: worktreePath,
+        ref: resolvedRef,
+        createdAt: new Date().toISOString(),
+    };
+}
+/**
+ * Build a SessionCleanupHook that tears down per-session worktrees. The
+ * hook reads `session.metadata.worktreePath` (recorded by
+ * `resolveWorktreeForRequest`) and the optional `session.metadata.worktreeName`,
+ * derives `repoRoot` from the path layout (`<repoRoot>/.worktrees/<name>`),
+ * and fires `removeWorktree` asynchronously. Failures are logged by
+ * `removeWorktree` itself — the hook always resolves so session deletion
+ * never blocks on git.
+ */
+export function createWorktreeSessionCleanupHook(logger) {
+    return async (session) => {
+        const meta = session.metadata ?? {};
+        const worktreePath = typeof meta.worktreePath === "string" ? meta.worktreePath : undefined;
+        if (!worktreePath)
+            return;
+        const worktreeName = typeof meta.worktreeName === "string" ? meta.worktreeName : undefined;
+        // Layout invariant from createWorktree: <repoRoot>/.worktrees/<name>.
+        // Strip the trailing two segments to recover repoRoot.
+        const marker = `${sep}.worktrees${sep}`;
+        const markerIdx = worktreePath.lastIndexOf(marker);
+        if (markerIdx === -1) {
+            logWarn(logger, `worktreePath on session ${session.id} does not match the gateway layout — skipping cleanup: ${worktreePath}`);
+            return;
+        }
+        const repoRoot = worktreePath.slice(0, markerIdx);
+        await removeWorktree({ repoRoot, path: worktreePath, name: worktreeName, logger });
+    };
+}
+export async function removeWorktree(opts) {
+    const logger = opts.logger ?? noopLogger;
+    if (!opts.repoRoot || !opts.path) {
+        return;
+    }
+    const remove = await execGit(opts.repoRoot, ["worktree", "remove", "--force", opts.path], logger);
+    if (remove.code !== 0) {
+        logWarn(logger, `git worktree remove --force ${opts.path} failed (code ${remove.code}): ${remove.stderr.trim()}`);
+    }
+    if (opts.name) {
+        const branch = `gateway/${opts.name}`;
+        const del = await execGit(opts.repoRoot, ["branch", "-D", branch], logger);
+        if (del.code !== 0) {
+            // Branch may already be gone (user deleted, never existed if add
+            // half-failed, etc.). Demote to debug — this is best-effort cleanup.
+            logger.debug?.(`git branch -D ${branch} returned code ${del.code}: ${del.stderr.trim()}`);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-cli-gateway",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "mcpName": "io.github.verivus-oss/llm-cli-gateway",
   "description": "MCP server providing unified access to Claude Code, Codex, Gemini, Grok, and Mistral Vibe CLIs with session management, retry logic, async job orchestration, durable job results, and cross-LLM validation.",
   "license": "MIT",