llm-cli-gateway 1.0.0

package/dist/approval-manager.js

@@ -0,0 +1,156 @@
+import { createHash, randomUUID } from "crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import { noopLogger } from "./logger.js";
+import { isReviewContext } from "./review-integrity.js";
+function parsePolicy(policy) {
+    if (policy) {
+        return policy;
+    }
+    const envPolicy = (process.env.LLM_GATEWAY_APPROVAL_POLICY || "").trim();
+    if (envPolicy === "strict" || envPolicy === "balanced" || envPolicy === "permissive") {
+        return envPolicy;
+    }
+    return "balanced";
+}
+function promptPreview(prompt) {
+    if (process.env.APPROVAL_LOG_PROMPTS === "1") {
+        return prompt.replace(/\s+/g, " ").trim().slice(0, 280);
+    }
+    return "[redacted]";
+}
+function promptHash(prompt) {
+    return createHash("sha256").update(prompt).digest("hex");
+}
+function parseLogLine(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+}
+export class ApprovalManager {
+    logger;
+    logPath;
+    constructor(customPath, logger = noopLogger) {
+        this.logger = logger;
+        this.logPath = customPath || join(homedir(), ".llm-cli-gateway", "approvals.jsonl");
+        const dir = dirname(this.logPath);
+        mkdirSync(dir, { recursive: true });
+    }
+    decide(request) {
+        const policy = parsePolicy(request.policy);
+        const reasons = [];
+        let score = 0;
+        if (request.bypassRequested) {
+            score += 3;
+            reasons.push("Request includes full permission bypass");
+        }
+        if (request.fullAuto) {
+            score += 2;
+            reasons.push("Request enables full-auto execution");
+        }
+        if (request.bypassRequested && request.fullAuto) {
+            score += 2;
+            reasons.push("Request combines full permission bypass with full-auto execution");
+        }
+        if (request.requestedMcpServers.includes("exa")) {
+            score += 2;
+            reasons.push("Request enables external web/company research MCP (exa)");
+        }
+        if (request.requestedMcpServers.includes("ref_tools")) {
+            score += 1;
+            reasons.push("Request enables documentation retrieval MCP (ref_tools)");
+        }
+        if (request.allowedTools && request.allowedTools.length === 0) {
+            // Independently verify review context from the prompt — never trust caller-supplied flags alone
+            const promptIsReview = isReviewContext(request.prompt);
+            if (promptIsReview) {
+                score += 6;
+                reasons.push("Empty allowedTools in review context — reviewers need tool access");
+            }
+            else {
+                // Neutral score — tool restrictions should never reduce risk score
+                // (prevents gaming via review-context evasion + restrictive tools = negative score)
+                reasons.push("No tool permissions requested");
+            }
+        }
+        if (request.disallowedTools && request.disallowedTools.length > 0) {
+            const promptIsReviewForDisallowed = isReviewContext(request.prompt);
+            const criticalTools = ["Read", "Grep", "Glob", "Bash"];
+            // Canonicalize to handle scoped forms like "Read(*)", "Bash(git:*)"
+            const canonicalized = request.disallowedTools.map(s => {
+                const trimmed = s.trim();
+                const cut = Math.min(...[trimmed.indexOf("("), trimmed.indexOf(":")].filter(i => i >= 0).concat([trimmed.length]));
+                return trimmed.slice(0, cut).trim();
+            });
+            const blockedCritical = criticalTools.filter(t => canonicalized.includes(t));
+            if (promptIsReviewForDisallowed && blockedCritical.length > 0) {
+                score += 6;
+                reasons.push(`Critical review tools disallowed: ${blockedCritical.join(", ")} — reviewers need these`);
+            }
+            else {
+                // Neutral score — tool restrictions should never reduce risk score
+                reasons.push("Has explicit disallowed tool restrictions");
+            }
+        }
+        if (/\b(delete|destroy|wipe|exfiltrate|credential|token|password|secret)\b/i.test(request.prompt)) {
+            score += 3;
+            reasons.push("Prompt contains sensitive or destructive keywords");
+        }
+        if (request.reviewIntegrity && request.reviewIntegrity.violations.length > 0) {
+            for (const violation of request.reviewIntegrity.violations) {
+                // Skip empty_allowed_tools and critical_tools_disallowed — already handled in context-dependent scoring above
+                if (violation.type === "empty_allowed_tools" || violation.type === "critical_tools_disallowed")
+                    continue;
+                score += violation.score;
+                reasons.push(`Review integrity: ${violation.detail}`);
+            }
+        }
+        // Balanced policy allows routine full-auto requests with standard MCP servers,
+        // while still denying bypass/sensitive combinations.
+        const threshold = policy === "strict" ? 2 : policy === "balanced" ? 5 : 7;
+        const status = score <= threshold ? "approved" : "denied";
+        const record = {
+            id: randomUUID(),
+            ts: new Date().toISOString(),
+            status,
+            policy,
+            cli: request.cli,
+            operation: request.operation,
+            score,
+            reasons,
+            promptPreview: promptPreview(request.prompt),
+            promptSha256: promptHash(request.prompt),
+            requestedMcpServers: request.requestedMcpServers,
+            bypassRequested: request.bypassRequested,
+            fullAuto: request.fullAuto,
+            metadata: request.metadata,
+            reviewIntegrity: request.reviewIntegrity
+        };
+        appendFileSync(this.logPath, `${JSON.stringify(record)}\n`, { encoding: "utf-8", mode: 0o600 });
+        this.logger.info(`Approval decision: ${status} (score=${score}, policy=${policy})`, {
+            cli: request.cli,
+            operation: request.operation
+        });
+        return record;
+    }
+    list(limit = 50, cli) {
+        if (!existsSync(this.logPath)) {
+            return [];
+        }
+        const content = readFileSync(this.logPath, "utf-8");
+        const rows = content
+            .split("\n")
+            .map(line => line.trim())
+            .filter(Boolean)
+            .map(parseLogLine)
+            .filter((row) => row !== null);
+        const filtered = cli ? rows.filter(row => row.cli === cli) : rows;
+        const result = filtered.slice(Math.max(0, filtered.length - limit)).reverse();
+        this.logger.debug(`Approval list retrieved: ${result.length} records`, { cli, limit });
+        return result;
+    }
+}

package/dist/async-job-manager.d.ts

@@ -0,0 +1,57 @@
+import type { Logger } from "./logger.js";
+import { type JobHealth } from "./process-monitor.js";
+export type LlmCli = "claude" | "codex" | "gemini";
+export type AsyncJobStatus = "running" | "completed" | "failed" | "canceled";
+export interface AsyncJobSnapshot {
+    id: string;
+    cli: LlmCli;
+    status: AsyncJobStatus;
+    startedAt: string;
+    finishedAt: string | null;
+    exitCode: number | null;
+    correlationId: string;
+    outputTruncated: boolean;
+    stdoutBytes: number;
+    stderrBytes: number;
+    error: string | null;
+    exited: boolean;
+}
+export interface AsyncJobResult extends AsyncJobSnapshot {
+    stdout: string;
+    stderr: string;
+    stdoutTruncated: boolean;
+    stderrTruncated: boolean;
+}
+export declare class AsyncJobManager {
+    private logger;
+    private onJobComplete?;
+    private jobs;
+    private evictionTimer;
+    private processMonitor;
+    constructor(logger?: Logger, onJobComplete?: ((cli: LlmCli, durationMs: number, success: boolean) => void) | undefined);
+    private emitMetrics;
+    private evictCompletedJobs;
+    startJob(cli: LlmCli, args: string[], correlationId: string, cwd?: string, idleTimeoutMs?: number, outputFormat?: string): AsyncJobSnapshot;
+    getJobSnapshot(jobId: string): AsyncJobSnapshot | null;
+    getJobResult(jobId: string, maxChars?: number): AsyncJobResult | null;
+    cancelJob(jobId: string): {
+        canceled: boolean;
+        reason?: string;
+    };
+    getRunningJobs(): {
+        jobId: string;
+        cli: string;
+        status: string;
+        pid: number | null;
+        startedAt: string;
+    }[];
+    getJobHealth(): {
+        runningJobs: number;
+        deadJobs: number;
+        zombieJobs: number;
+        jobs: JobHealth[];
+    };
+    getJobOutputFormat(jobId: string): string | undefined;
+    private snapshot;
+    private appendOutput;
+}

package/dist/async-job-manager.js

@@ -0,0 +1,334 @@
+import { spawn } from "child_process";
+import { randomUUID } from "crypto";
+import { getExtendedPath, killProcessGroup, registerProcessGroup, unregisterProcessGroup } from "./executor.js";
+import { noopLogger } from "./logger.js";
+import { ProcessMonitor } from "./process-monitor.js";
+const MAX_OUTPUT_SIZE = 50 * 1024 * 1024;
+const JOB_TTL_MS = 60 * 60 * 1000; // 1 hour
+const EVICTION_INTERVAL_MS = 5 * 60 * 1000; // Check every 5 minutes
+function truncateText(value, maxChars) {
+    if (value.length <= maxChars) {
+        return { text: value, truncated: false };
+    }
+    return {
+        text: value.slice(value.length - maxChars),
+        truncated: true
+    };
+}
+export class AsyncJobManager {
+    logger;
+    onJobComplete;
+    jobs = new Map();
+    evictionTimer = null;
+    processMonitor;
+    constructor(logger = noopLogger, onJobComplete) {
+        this.logger = logger;
+        this.onJobComplete = onJobComplete;
+        this.processMonitor = new ProcessMonitor(logger);
+        this.evictionTimer = setInterval(() => this.evictCompletedJobs(), EVICTION_INTERVAL_MS);
+        // Allow the process to exit even if the timer is active
+        if (this.evictionTimer.unref) {
+            this.evictionTimer.unref();
+        }
+    }
+    emitMetrics(job) {
+        if (job.metricsRecorded)
+            return;
+        if (job.status === "canceled")
+            return;
+        if (job.status !== "completed" && job.status !== "failed")
+            return;
+        job.metricsRecorded = true;
+        const durationMs = Date.now() - new Date(job.startedAt).getTime();
+        try {
+            this.onJobComplete?.(job.cli, durationMs, job.status === "completed");
+        }
+        catch (err) {
+            this.logger.error("onJobComplete callback threw", err);
+        }
+    }
+    evictCompletedJobs() {
+        const now = Date.now();
+        let evicted = 0;
+        // Dead process auto-recovery: check for running jobs whose process no longer exists
+        for (const [id, job] of this.jobs) {
+            if (job.status === "running" && job.process.pid) {
+                try {
+                    process.kill(job.process.pid, 0);
+                }
+                catch (err) {
+                    if (err.code === "ESRCH") {
+                        job.status = "failed";
+                        job.exitCode = job.exitCode ?? 1;
+                        job.error = "Process no longer exists (dead process detected)";
+                        job.finishedAt = new Date().toISOString();
+                        job.exited = true;
+                        unregisterProcessGroup(job.process.pid);
+                        this.logger.error(`Job ${id} process ${job.process.pid} no longer exists, marking as failed`);
+                        this.emitMetrics(job);
+                    }
+                    // EPERM: process exists but we can't signal it — ignore
+                }
+            }
+            // Check for exited flag mismatch (close handler may have fired but status wasn't updated)
+            if (job.status === "running" && job.exited) {
+                job.status = "failed";
+                job.error = "Process exited without proper status transition";
+                job.finishedAt = job.finishedAt || new Date().toISOString();
+                if (job.process.pid)
+                    unregisterProcessGroup(job.process.pid);
+                this.logger.error(`Job ${id} has exited flag but was still in running state, marking as failed`);
+                this.emitMetrics(job);
+            }
+        }
+        for (const [id, job] of this.jobs) {
+            if (job.status !== "running" && job.finishedAt) {
+                const finishedMs = new Date(job.finishedAt).getTime();
+                if (now - finishedMs > JOB_TTL_MS) {
+                    this.jobs.delete(id);
+                    evicted++;
+                }
+            }
+        }
+        if (evicted > 0) {
+            this.logger.debug(`Evicted ${evicted} completed jobs`);
+        }
+    }
+    startJob(cli, args, correlationId, cwd, idleTimeoutMs, outputFormat) {
+        const id = randomUUID();
+        const startedAt = new Date().toISOString();
+        const child = spawn(cli, args, {
+            cwd,
+            detached: true,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env, PATH: getExtendedPath() }
+        });
+        if (child.pid)
+            registerProcessGroup(child.pid);
+        child.unref();
+        // Single cleanup flag to prevent double-unregister
+        let groupCleaned = false;
+        const cleanupGroup = () => {
+            if (groupCleaned)
+                return;
+            groupCleaned = true;
+            if (child.pid)
+                unregisterProcessGroup(child.pid);
+        };
+        const job = {
+            id,
+            cli,
+            args: [...args],
+            correlationId,
+            status: "running",
+            startedAt,
+            finishedAt: null,
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            outputTruncated: false,
+            canceled: false,
+            error: null,
+            process: child,
+            exited: false,
+            metricsRecorded: false,
+            outputFormat,
+            cleanupGroup
+        };
+        this.jobs.set(id, job);
+        this.logger.info(`Job ${id} started for ${cli}`, { correlationId });
+        // Idle timeout: kill process if no output activity for idleTimeoutMs
+        let idleTimerId;
+        const resetIdleTimer = () => {
+            if (!idleTimeoutMs || idleTimeoutMs <= 0)
+                return;
+            if (idleTimerId)
+                clearTimeout(idleTimerId);
+            idleTimerId = setTimeout(() => {
+                if (job.status !== "running")
+                    return;
+                job.status = "failed";
+                job.exitCode = 125;
+                job.error = `Process killed after ${idleTimeoutMs}ms of inactivity`;
+                job.finishedAt = new Date().toISOString();
+                killProcessGroup(job.process, "SIGTERM");
+                this.logger.info(`Job ${id} killed due to inactivity (${idleTimeoutMs}ms)`, { correlationId });
+                this.emitMetrics(job);
+                setTimeout(() => {
+                    if (!job.exited)
+                        killProcessGroup(job.process, "SIGKILL");
+                    job.cleanupGroup?.();
+                }, 5000);
+            }, idleTimeoutMs);
+        };
+        job.resetIdleTimer = resetIdleTimer;
+        job.clearIdleTimer = () => {
+            if (idleTimerId)
+                clearTimeout(idleTimerId);
+        };
+        resetIdleTimer();
+        child.stdout?.on("data", (chunk) => {
+            this.appendOutput(job, "stdout", chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            this.appendOutput(job, "stderr", chunk);
+        });
+        child.on("error", (error) => {
+            job.exited = true;
+            job.clearIdleTimer?.();
+            job.cleanupGroup?.();
+            if (job.status === "running") {
+                job.status = job.canceled ? "canceled" : "failed";
+                job.error = error.message;
+                job.finishedAt = new Date().toISOString();
+                this.logger.error(`Job ${id} error: ${error.message}`, { correlationId });
+                this.emitMetrics(job);
+            }
+        });
+        child.on("close", (code) => {
+            job.exited = true;
+            job.clearIdleTimer?.();
+            // Unregister process group on clean exit (no kill was issued)
+            if (!job.canceled && job.status === "running") {
+                job.cleanupGroup?.();
+            }
+            if (job.status !== "running") {
+                job.exitCode = code ?? job.exitCode;
+                if (!job.finishedAt) {
+                    job.finishedAt = new Date().toISOString();
+                }
+                return;
+            }
+            job.exitCode = code ?? 0;
+            job.finishedAt = new Date().toISOString();
+            if (job.canceled) {
+                job.status = "canceled";
+            }
+            else if (job.exitCode === 0) {
+                job.status = "completed";
+            }
+            else {
+                job.status = "failed";
+            }
+            this.emitMetrics(job);
+        });
+        return this.snapshot(job);
+    }
+    getJobSnapshot(jobId) {
+        const job = this.jobs.get(jobId);
+        if (!job) {
+            return null;
+        }
+        return this.snapshot(job);
+    }
+    getJobResult(jobId, maxChars = 200000) {
+        const job = this.jobs.get(jobId);
+        if (!job) {
+            return null;
+        }
+        const stdout = truncateText(job.stdout, maxChars);
+        const stderr = truncateText(job.stderr, maxChars);
+        return {
+            ...this.snapshot(job),
+            stdout: stdout.text,
+            stderr: stderr.text,
+            stdoutTruncated: stdout.truncated,
+            stderrTruncated: stderr.truncated
+        };
+    }
+    cancelJob(jobId) {
+        const job = this.jobs.get(jobId);
+        if (!job) {
+            return { canceled: false, reason: "Job not found" };
+        }
+        if (job.status !== "running") {
+            return { canceled: false, reason: `Job is already ${job.status}` };
+        }
+        job.canceled = true;
+        job.status = "canceled";
+        job.finishedAt = new Date().toISOString();
+        job.clearIdleTimer?.();
+        killProcessGroup(job.process, "SIGTERM");
+        this.logger.info(`Job ${jobId} canceled`, { correlationId: job.correlationId });
+        setTimeout(() => {
+            if (!job.exited)
+                killProcessGroup(job.process, "SIGKILL");
+            job.cleanupGroup?.();
+        }, 5000);
+        return { canceled: true };
+    }
+    getRunningJobs() {
+        const result = [];
+        for (const [id, job] of this.jobs) {
+            if (job.status === "running") {
+                result.push({
+                    jobId: id, cli: job.cli, status: job.status,
+                    pid: job.process.pid ?? null, startedAt: job.startedAt
+                });
+            }
+        }
+        return result;
+    }
+    getJobHealth() {
+        const running = this.getRunningJobs();
+        const health = this.processMonitor.checkJobHealth(running);
+        // Clean up stale CPU samples for PIDs that are no longer running
+        const activePids = new Set(running.map(j => j.pid).filter((p) => p !== null));
+        this.processMonitor.cleanupSamples(activePids);
+        return {
+            runningJobs: running.length,
+            deadJobs: health.filter(h => h.isDead).length,
+            zombieJobs: health.filter(h => h.isZombie).length,
+            jobs: health
+        };
+    }
+    getJobOutputFormat(jobId) {
+        return this.jobs.get(jobId)?.outputFormat;
+    }
+    snapshot(job) {
+        return {
+            id: job.id,
+            cli: job.cli,
+            status: job.status,
+            startedAt: job.startedAt,
+            finishedAt: job.finishedAt,
+            exitCode: job.exitCode,
+            correlationId: job.correlationId,
+            outputTruncated: job.outputTruncated,
+            stdoutBytes: Buffer.byteLength(job.stdout),
+            stderrBytes: Buffer.byteLength(job.stderr),
+            error: job.error,
+            exited: job.exited
+        };
+    }
+    appendOutput(job, stream, chunk) {
+        const totalBytes = Buffer.byteLength(job.stdout) + Buffer.byteLength(job.stderr) + chunk.length;
+        if (totalBytes > MAX_OUTPUT_SIZE) {
+            job.outputTruncated = true;
+            if (job.status === "running") {
+                job.status = "failed";
+                job.exitCode = 126;
+                job.error = "Output exceeded maximum size (50MB)";
+                job.finishedAt = new Date().toISOString();
+                job.clearIdleTimer?.();
+                killProcessGroup(job.process, "SIGTERM");
+                this.logger.info(`Job ${job.id} killed due to output overflow`, { correlationId: job.correlationId });
+                this.emitMetrics(job);
+                setTimeout(() => {
+                    if (!job.exited)
+                        killProcessGroup(job.process, "SIGKILL");
+                    job.cleanupGroup?.();
+                }, 5000);
+            }
+            return;
+        }
+        job.resetIdleTimer?.();
+        const text = chunk.toString();
+        if (stream === "stdout") {
+            job.stdout += text;
+        }
+        else {
+            job.stderr += text;
+        }
+    }
+}

package/dist/claude-mcp-config.d.ts

@@ -0,0 +1,8 @@
+export declare const CLAUDE_MCP_SERVER_NAMES: readonly ["sqry", "exa", "ref_tools", "trstr"];
+export type ClaudeMcpServerName = (typeof CLAUDE_MCP_SERVER_NAMES)[number];
+export interface ClaudeMcpConfigResult {
+    path: string;
+    enabled: ClaudeMcpServerName[];
+    missing: ClaudeMcpServerName[];
+}
+export declare function buildClaudeMcpConfig(servers: ClaudeMcpServerName[]): ClaudeMcpConfigResult;