@zenithfoundry/slm-gate 1.2.1

package/dist/setup/startup.js

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview What slm-gate's MCP server does when a coding tool starts it, and every minute after: checks
+ * Ollama and the configured models, and keeps the model gate running. Nobody has to run a command. Problems
+ * are logged, shown as a desktop notification and (at start-up) passed to the AI in the MCP server's
+ * instructions; nothing is said when all is well. None of this can stop the MCP server from starting.
+ */
+import path from 'node:path';
+import { CONFIG } from '../config.js';
+import { checkLocalModels } from './local-models.js';
+import { cliCommand, GATE_LOG_FILE, isStoppedByUser, launchModelGate, probeGate, waitForModelGate } from './model-gate.js';
+import { notifyUser } from './notify.js';
+// The coding tool is waiting for the MCP handshake: the checks before it get at most this long.
+const FAST_CHECK_MS = 1500;
+const WATCH_EVERY_MS = 60_000;
+// The first watch check runs once a gate launched at start-up has had time to come up.
+const FIRST_WATCH_MS = 15_000;
+const port = () => CONFIG.MODEL_GATE_PORT;
+function portTakenNotice() {
+    return {
+        key: 'port-taken',
+        message: `Port ${port()} is used by another program, so the model gate cannot run there and coding tools pointed at http://localhost:${port()} cannot reach their AI provider.`,
+        fix: `Quit that program (\`${cliCommand('doctor')}\` names it). Or set LLM_GATE_PORT to a free port in ${path.join(CONFIG.HOME_DIR, '.env')}, run \`${cliCommand('restart')}\`, change the address in each coding tool (\`${cliCommand('doctor')}\` prints the lines) and restart them.`,
+    };
+}
+function staleNotice() {
+    return {
+        key: 'gate-stale',
+        message: `The model gate on port ${port()} is still running an older slm-gate build.`,
+        fix: `Run \`${cliCommand('restart')}\` when no coding tool is in the middle of an answer.`,
+    };
+}
+function notRunningNotice() {
+    return {
+        key: 'gate-not-running',
+        message: `The model gate on port ${port()} is not running and did not start, so coding tools pointed at it cannot reach their AI provider.`,
+        fix: `Run \`${cliCommand('start')}\`. If it still fails, see ${GATE_LOG_FILE} or run \`${cliCommand('doctor')}\`.`,
+    };
+}
+function report(notice) {
+    console.error(`[slm-gate] ${notice.message} Fix: ${notice.fix}`);
+    notifyUser({ key: notice.key, message: `${notice.message} ${notice.fix}` });
+}
+/**
+ * What the gate probe means at start-up; launches the gate at once when nothing listens.
+ * @returns The problems, and the models a running gate uses (checked along with this process's own)
+ */
+async function checkGateAtStartup() {
+    if (!CONFIG.LLM_GATE_AUTOSTART)
+        return { notices: [] };
+    const probe = await probeGate({ timeoutMs: 1000 });
+    if (probe.kind === 'slm-gate')
+        return { notices: probe.stale ? [staleNotice()] : [], gateModels: probe.health.models };
+    if (probe.kind === 'other')
+        return { notices: [portTakenNotice()] };
+    // Nothing listens. Launch now, so the gate is booting before the coding tool's first model request;
+    // whether it came up, and its models, are checked later by the watch.
+    if (!isStoppedByUser())
+        launchModelGate();
+    return { notices: [] };
+}
+function modelNotices(problems) {
+    return problems.map(problem => ({ key: `models:${problem.fix}`, ...problem }));
+}
+/**
+ * The start-up checks, capped at about 1.5 s. Late results are dropped (their promises are already
+ * handled); a gate launch still happens when the probe answers late.
+ *
+ * @returns The problems to pass to the AI; each has also been logged and notified
+ */
+export async function runStartupChecks() {
+    const cap = new Promise(resolve => setTimeout(() => resolve([]), FAST_CHECK_MS).unref());
+    const gate = checkGateAtStartup().catch(() => ({ notices: [], gateModels: undefined }));
+    // The probe answers in milliseconds, so the model check can wait for the running gate's models.
+    const models = gate
+        .then(result => checkLocalModels({ timeoutMs: FAST_CHECK_MS - 300, gateModels: result.gateModels }))
+        // A check squeezed into the start-up budget, while the editor, the toolbox and often Ollama itself
+        // are all still starting, is weak evidence. Anything that might be a timing artifact waits for the
+        // watch, which gets a quiet moment and a second opinion. This matters more here than anywhere else:
+        // the instructions handed to the editor are fixed for the whole session, so a wrong notice at
+        // start-up is repeated by the AI until the session ends, long after the truth has changed.
+        .then(result => modelNotices(result.problems).filter(notice => !notice.transient))
+        .catch(() => []);
+    const notices = (await Promise.all([Promise.race([gate.then(result => result.notices), cap]), Promise.race([models, cap])])).flat();
+    notices.forEach(report);
+    return notices;
+}
+/**
+ * While the MCP server lives: relaunch the gate if it died (unless you stopped it; at most once a minute
+ * across all sessions) and re-check the local models. Problems are logged and notified.
+ *
+ * @param params.firstMs Delay before the first check (default 15 s)
+ * @param params.everyMs Interval after that (default 60 s)
+ * @returns Stops the watch (tests)
+ */
+export function watchModelGate(params = {}) {
+    if (!CONFIG.LLM_GATE_AUTOSTART)
+        return () => { };
+    // Transient problems reported by the previous check. One that is still there on the next check is
+    // real; one that has gone was the machine being busy, and nobody ever hears about it.
+    let awaitingConfirmation = new Set();
+    const check = async () => {
+        const probe = await probeGate();
+        let gate = probe.kind === 'slm-gate' ? probe.health : null;
+        if (probe.kind === 'other')
+            report(portTakenNotice());
+        if (probe.kind === 'nothing' && !isStoppedByUser()) {
+            const { launched } = launchModelGate();
+            // Not launched = another session already launched it this minute. Give that one a moment, but stay
+            // quiet if it is not up: the next check can launch again, and reports if that launch fails.
+            gate = await waitForModelGate({ timeoutMs: launched ? 10_000 : 2_000 });
+            if (!gate && launched)
+                report(notRunningNotice());
+        }
+        const { problems } = await checkLocalModels({ gateModels: gate?.models });
+        const notices = modelNotices(problems);
+        notices.filter(notice => !notice.transient || awaitingConfirmation.has(notice.key)).forEach(report);
+        awaitingConfirmation = new Set(notices.filter(notice => notice.transient).map(notice => notice.key));
+    };
+    const run = () => void check().catch(err => console.error(`[slm-gate] model gate check failed: ${err instanceof Error ? err.message : String(err)}`));
+    let interval;
+    const first = setTimeout(() => {
+        run();
+        interval = setInterval(run, params.everyMs ?? WATCH_EVERY_MS);
+        interval.unref();
+    }, params.firstMs ?? FIRST_WATCH_MS);
+    first.unref();
+    return () => {
+        clearTimeout(first);
+        if (interval)
+            clearInterval(interval);
+    };
+}

package/dist/setup/tool-settings.js

@@ -0,0 +1,101 @@
+/**
+ * @fileoverview The exact setting that points each coding tool at the model gate, for `slm-gate doctor`
+ * and the docs. Every address uses the configured port, so after changing LLM_GATE_PORT doctor prints the
+ * lines to update. Facts checked against each tool's documentation on 2026-09-18.
+ */
+export function toolSettings(port) {
+    const base = `http://localhost:${port}`;
+    return [
+        {
+            tool: 'Claude Code (CLI and VS Code / JetBrains extension)',
+            login: 'claude.ai Pro/Max login or API key',
+            lines: [
+                `~/.claude/settings.json:  { "env": { "ANTHROPIC_BASE_URL": "${base}" } }   (no /v1 at the end)`,
+                `VS Code user settings:    "claudeCode.environmentVariables": [{ "name": "ANTHROPIC_BASE_URL", "value": "${base}" }]`,
+            ],
+        },
+        {
+            tool: 'Codex (CLI and IDE extension)',
+            login: 'ChatGPT login or API key',
+            lines: [
+                '~/.codex/config.toml:',
+                '  model_provider = "slm-gate"',
+                '  [model_providers.slm-gate]',
+                '  name = "slm-gate"',
+                `  base_url = "${base}/v1"`,
+                '  requires_openai_auth = true',
+                '  (do not set supports_websockets: over WebSocket the gate cannot see the conversation)',
+            ],
+        },
+        {
+            tool: 'Gemini CLI',
+            login: 'Gemini API key only',
+            lines: [
+                `export GOOGLE_GEMINI_BASE_URL=${base}`,
+                'export GEMINI_API_KEY=<your key>',
+                '~/.gemini/settings.json:  { "security": { "auth": { "selectedType": "gemini-api-key" } } }',
+            ],
+        },
+        {
+            tool: 'Antigravity CLI (agy)',
+            login: 'Gemini API key only',
+            lines: [
+                '~/.gemini/antigravity-cli/settings.json:  { "modelProvider": "gemini" }',
+                `export GOOGLE_GEMINI_BASE_URL=${base}`,
+                'export GEMINI_API_KEY=<your key>',
+            ],
+        },
+        {
+            tool: 'OpenCode',
+            login: 'API key',
+            lines: [`opencode.json:  { "provider": { "anthropic": { "options": { "baseURL": "${base}/v1" } } } }`],
+        },
+        {
+            tool: 'Cline / Roo Code (VS Code)',
+            login: 'API key',
+            lines: [`Settings > API Provider "Anthropic" > tick "Use custom base URL" > ${base}`],
+        },
+        {
+            tool: 'Kilo Code (extension and CLI)',
+            login: 'API key',
+            lines: [`Custom provider, Provider API "Anthropic Messages", Base URL ${base}/v1   (CLI: kilo.jsonc provider.<id>.options.baseURL)`],
+        },
+        {
+            tool: 'Continue (VS Code / JetBrains)',
+            login: 'API key',
+            lines: [`~/.continue/config.yaml model:  provider: anthropic, apiBase: ${base}/v1/   (OpenAI models: provider: openai, apiBase: ${base}/v1)`],
+        },
+        {
+            tool: 'Zed',
+            login: 'API key (entered in Agent Settings, not in settings.json)',
+            lines: [`settings.json:  "language_models": { "anthropic": { "api_url": "${base}" } }`],
+        },
+        {
+            tool: 'GitHub Copilot Chat (VS Code) Custom Endpoint',
+            login: 'your own API key',
+            lines: [
+                `Chat > Manage Language Models > Add Models > Custom Endpoint: apiType "messages", url ${base}/v1/messages`,
+                '(inline suggestions and semantic search keep using GitHub\'s own models)',
+            ],
+        },
+        {
+            tool: 'JetBrains Junie CLI',
+            login: 'API key',
+            lines: [`~/.junie/models/slm-gate.json:  { "id": "<model>", "baseUrl": "${base}/v1/messages", "apiType": "Anthropic", "apiKey": "<key>" }`],
+        },
+        {
+            tool: 'Aider',
+            login: 'API key',
+            lines: [`ANTHROPIC_API_BASE=${base}   (OpenAI models: OPENAI_API_BASE=${base}/v1)`],
+        },
+    ];
+}
+/** Tools whose model requests cannot go through a local gate, and why. Their MCP connection still works. */
+export const UNROUTABLE_TOOLS = [
+    { tool: 'Cursor, Windsurf', reason: 'model requests go through the vendor\'s servers first, which cannot reach your machine' },
+    { tool: 'Claude desktop app (chat and its Code tab), claude.ai', reason: 'no setting for the model address' },
+    { tool: 'ChatGPT app/web, Gemini app/web', reason: 'no setting for the model address' },
+    { tool: 'Gemini Code Assist extension, Antigravity IDE, Copilot\'s included models', reason: 'no setting for the model address' },
+    { tool: 'Gemini CLI / agy with a Google-account login', reason: 'that login ignores the address setting, and Google\'s terms forbid using it through other tools' },
+    { tool: 'Models bundled in a tool\'s own subscription (Cline, Kilo, Copilot, …)', reason: 'only your own API key can be pointed at the gate' },
+];

package/dist/utils/backoff.js

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Shared exponential-backoff helper.
+ *
+ * Extracted from llm-gate/pipeline.ts so the ledger's Langfuse flush can reuse the same
+ * retry policy. It cannot simply import from the pipeline: llm-gate/pipeline.ts imports
+ * the ledger, so that direction would be circular.
+ */
+/**
+ * Calculates exponential backoff with jitter and awaits the delay period.
+ *
+ * @desc Computes 1500ms * 2^attempt + jitter, respecting an optional `Retry-After` header value in seconds.
+ * Logs a diagnostic warning to stderr before waiting.
+ * @param attempt Current zero-indexed retry attempt
+ * @param maxRetries Total allowed retry attempts
+ * @param reason Human-readable context for why the backoff is being executed
+ * @param retryAfter Optional `Retry-After` header string from HTTP response
+ * @param layer Log prefix identifying the calling layer (e.g. 'llm-gate', 'ledger')
+ * @returns Promise that resolves once the backoff delay has completed
+ * @example
+ * ```ts
+ * await waitWithBackoff(attempt, MAX_RETRIES, 'Upstream HTTP 429', res.headers.get('retry-after'));
+ * ```
+ */
+export async function waitWithBackoff(attempt, maxRetries, reason, retryAfter, layer = 'llm-gate') {
+    await new Promise((resolve) => setTimeout(resolve, computeBackoffMs(attempt, reason, retryAfter, maxRetries, layer)));
+}
+/**
+ * Pure delay calculation, split out so it can be unit-tested without waiting in real time.
+ *
+ * @param attempt Current zero-indexed retry attempt
+ * @param reason Human-readable context, used only for the log line
+ * @param retryAfter Optional `Retry-After` header string, in seconds
+ * @param maxRetries Total allowed retry attempts, used only for the log line
+ * @param layer Log prefix identifying the calling layer
+ * @returns Delay in milliseconds
+ */
+export function computeBackoffMs(attempt, reason, retryAfter, maxRetries = 0, layer = 'llm-gate') {
+    let delayMs = 1500 * Math.pow(2, attempt) + Math.random() * 500;
+    if (retryAfter) {
+        const parsedSeconds = parseInt(retryAfter, 10);
+        if (!isNaN(parsedSeconds) && parsedSeconds > 0) {
+            delayMs = Math.max(delayMs, parsedSeconds * 1000);
+        }
+    }
+    console.error(`[${layer}] ${reason}. Retrying in ${Math.round(delayMs)}ms (attempt ${attempt + 1}/${maxRetries})...`);
+    return delayMs;
+}

package/dist/utils/compression.js

@@ -0,0 +1,145 @@
+import { extractToolSignature, distillToolResult, estimateTokens, computeElisionId, formatElisionMarker } from './elision.js';
+import { CONFIG } from '../config.js';
+import crypto from 'node:crypto';
+import { writeElision } from '../ledger/index.js';
+/**
+ * Core context compression engine for the LLM Gate.
+ * This function iterates through the conversation history and intelligently prunes,
+ * drops, or distills verbose tool outputs to save tokens and prevent context overflow,
+ * while maintaining strict cache-stability and preserving critical structural data.
+ *
+ * @param messages - The full history of internal messages in the conversation.
+ * @param options - Configuration for pruning aggression.
+ * @returns A promise resolving to the compressed array of messages.
+ */
+export async function compressContext(messages, options = {}) {
+    const { dropStaleToolOutput = true } = options;
+    if (messages.length === 0)
+        return [];
+    const lastIndex = messages.length - 1;
+    // We keep a configurable number of recent tool outputs verbatim to ensure 
+    // the model has full context for its most immediate recent actions.
+    const recentToolTurns = CONFIG.KEEP_RECENT_TOOL_TURNS ?? 2;
+    // Tool outputs smaller than this threshold are considered "cheap" and are kept verbatim 
+    // to save CPU cycles and avoid unnecessary fragmentation.
+    const minTokens = CONFIG.DISTILL_MIN_TOKENS ?? 500;
+    // Pre-process messages to extract structural metadata (tool name, args, target file paths).
+    // This metadata is crucial for detecting when an older tool output is "superseded" by a newer one.
+    const toolResults = messages.map((m, i) => {
+        if (m.role !== 'tool' && m.role !== 'user' && m.role !== 'assistant')
+            return null;
+        const extracted = extractToolSignature(m.content);
+        return {
+            index: i,
+            role: m.role,
+            content: m.content,
+            toolName: extracted.toolName,
+            args: extracted.args,
+            filePath: extracted.filePath,
+            // We hash the raw content here to easily detect exact duplicate responses later.
+            hash: crypto.createHash('sha256').update(m.content).digest('hex')
+        };
+    });
+    // Perform a reverse-scan to flag the N most recent tool results.
+    // These flagged results will be protected from compression.
+    let toolTurnsFound = 0;
+    const isRecentTool = new Array(messages.length).fill(false);
+    for (let i = lastIndex; i >= 0; i--) {
+        if (messages[i].role === 'tool') {
+            if (toolTurnsFound < recentToolTurns) {
+                isRecentTool[i] = true;
+            }
+            toolTurnsFound++;
+        }
+    }
+    // The LLM-gate primarily relies on deterministic truncation (heuristics) for speed.
+    // Since we don't have an active SLM client instantiated here, we pass a dummy passthrough function.
+    // The underlying `distillToolResult` handles deterministic heuristic truncation gracefully even with a dummy SLM.
+    const dummySlm = async (t) => t;
+    const processed = [];
+    // Main forward-scan loop to evaluate each message for compression or dropping.
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        // Always keep the very last message, non-tool messages, or everything if pruning is disabled.
+        if (i === lastIndex || msg.role !== 'tool' || !dropStaleToolOutput) {
+            processed.push(msg);
+            continue;
+        }
+        const currentTool = toolResults[i];
+        const sizeTokens = estimateTokens(msg.content);
+        // Rule 1: KEEP VERBATIM
+        // If the output is tiny or it is one of the most recent tool interactions, protect it.
+        if (sizeTokens < minTokens || isRecentTool[i]) {
+            processed.push(msg);
+            continue;
+        }
+        // Rule 2: Check for Supersession
+        // We scan ahead in the conversation to see if a future action renders this current tool output obsolete.
+        let superseded = false;
+        for (let j = i + 1; j < messages.length; j++) {
+            const later = toolResults[j];
+            if (!later)
+                continue;
+            // Condition A: An exact duplicate of this output appears later in the conversation.
+            if (later.hash === currentTool.hash) {
+                superseded = true;
+                break;
+            }
+            // Condition B: The exact same file was read again later, making this older read obsolete.
+            if (currentTool.filePath && later.filePath === currentTool.filePath && later.role === 'tool') {
+                if (['read_file', 'view_file'].some(t => later.toolName?.includes(t))) {
+                    superseded = true;
+                    break;
+                }
+            }
+            // Condition C: The file this tool read was subsequently modified/written to later,
+            // rendering this older read's contents invalid/stale.
+            if (currentTool.filePath && later.filePath === currentTool.filePath) {
+                if (['write', 'edit', 'replace', 'patch'].some(t => later.toolName?.toLowerCase().includes(t))) {
+                    superseded = true;
+                    break;
+                }
+            }
+        }
+        if (superseded && currentTool.toolName) {
+            // Rule 3: DROP (with marker)
+            // The output is obsolete. We drop the payload but leave a precise breadcrumb (elision marker) 
+            // in the context window and write the full payload to the local SQLite ledger.
+            const elisionId = computeElisionId(currentTool.toolName, currentTool.args, msg.content);
+            const lines = msg.content.split('\n');
+            const marker = formatElisionMarker(elisionId, lines.length, 0, lines.length - 1);
+            writeElision({
+                id: elisionId,
+                tool_name: currentTool.toolName,
+                args: JSON.stringify(currentTool.args || {}),
+                original_text: msg.content,
+                ranges: JSON.stringify({ startLine: 0, endLine: lines.length - 1 }),
+                content_hash: currentTool.hash,
+                size_bytes: Buffer.byteLength(msg.content)
+            });
+            processed.push({ ...msg, content: marker.trim() });
+        }
+        else {
+            // Rule 4: DISTILL (with marker)
+            // The output is not obsolete but it is large and old. We use deterministic heuristics 
+            // (like top-K truncation or log tailing) to shrink it down.
+            let task = '';
+            if (i > 0 && messages[i - 1].role === 'user')
+                task = messages[i - 1].content;
+            // `distillToolResult` will leave its own markers inside the returned compressed string.
+            const distilled = await distillToolResult(dummySlm, msg.content, task, currentTool.toolName, currentTool.args, []);
+            processed.push({ ...msg, content: distilled });
+        }
+    }
+    // Final Pass: Deduplication
+    // Strip out back-to-back identical messages (usually caused by tool errors or retries) 
+    // to save a marginal amount of tokens.
+    const deduped = [];
+    for (let i = 0; i < processed.length; i++) {
+        if (i > 0 && processed[i].role === processed[i - 1].role && processed[i].content === processed[i - 1].content) {
+            continue;
+        }
+        deduped.push(processed[i]);
+    }
+    return deduped;
+}

package/dist/utils/constants.js

@@ -0,0 +1,22 @@
+/**
+ * Standard prefixes used by various tools and plugins to indicate
+ * that the following text is the result of an automated action,
+ * rather than a human user's prompt.
+ */
+export const TOOL_RESULT_PREFIXES = [
+    'Tool result:',
+    'Tool output:',
+    '<tool_response>',
+    '<function_results>',
+    'Command output:',
+    '```output'
+];
+/**
+ * Cursor-specific markers often injected into user messages
+ * to represent intermediate tool calls or steps.
+ */
+export const CURSOR_TOOL_MARKERS = [
+    '<tool_call>',
+    '<tool_response>',
+    'Step:'
+];

package/dist/utils/duration.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Human-readable duration rendering for terminal output and reports.
+ *
+ * This lives apart from `minutesFreed` in pricing/providers.ts on purpose: that function
+ * owns the *arithmetic*, this one owns the *presentation*, and only some consumers can use
+ * it. The Langfuse dashboard cannot: a numeric score row carries `value: number` and no
+ * unit field, and the card aggregates rows server-side, so there is no point at which a
+ * formatted string could be attached. Anywhere we build the final string ourselves — the
+ * sync summary table, the bench leaderboard — renders through here so they cannot drift.
+ */
+const SECONDS_PER_MINUTE = 60;
+const SECONDS_PER_HOUR = 3600;
+/**
+ * Renders a duration in the largest unit that still reads as a real amount of time.
+ *
+ * Below a minute it stays in seconds with one decimal, because that is the range these
+ * estimates actually live in; above it, minutes and seconds; above an hour, hours and
+ * minutes. The point is that the reader never has to multiply anything.
+ *
+ * @param seconds Duration in seconds. Non-finite and non-positive inputs render as '0s'.
+ * @returns e.g. '11.4s', '4m 12s', '1h 02m'
+ */
+export function formatDuration(seconds) {
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        return '0s';
+    if (seconds < SECONDS_PER_MINUTE) {
+        return `${Number(seconds.toFixed(1))}s`;
+    }
+    // Round to whole seconds BEFORE choosing a unit. Rounding inside each branch let 3599.7s
+    // pick the minutes branch and then carry to '60m 00s' instead of '1h 00m'.
+    const whole = Math.round(seconds);
+    if (whole < SECONDS_PER_HOUR) {
+        const minutes = Math.floor(whole / SECONDS_PER_MINUTE);
+        const remainder = whole % SECONDS_PER_MINUTE;
+        return `${minutes}m ${String(remainder).padStart(2, '0')}s`;
+    }
+    const hours = Math.floor(whole / SECONDS_PER_HOUR);
+    const remainder = Math.round((whole % SECONDS_PER_HOUR) / SECONDS_PER_MINUTE);
+    // The same carry one unit up: 7199s is 1h 59.98m, which rounds to a 60th minute.
+    if (remainder === SECONDS_PER_MINUTE)
+        return `${hours + 1}h 00m`;
+    return `${hours}h ${String(remainder).padStart(2, '0')}m`;
+}