@zenithfoundry/slm-gate 1.2.1

package/configs/generic-stdio/README.md

@@ -0,0 +1,24 @@
+# Generic Stdio MCP Configuration
+
+**File Location:** Depends on your MCP client's configuration schema.
+
+```json
+{
+  "mcpServers": {
+    "slm-gate": {
+      "command": "node",
+      "args": [
+        "<ABS_PATH>/dist/mcp-gate/index.js"
+      ],
+      "env": {
+        "TLS_ADAPTER": "on",
+        "DOWNSTREAM_MCP": "{\"command\":\"node\",\"args\":[\"<ABS_PATH_TO_TLS>/dist/mcp-server.mjs\"]}"
+      }
+    }
+  }
+}
+```
+
+After adding this, make sure to build TLS first by running `pnpm run mcp:build` in your TLS directory, then restart/refresh MCP servers and verify with `slm-gate doctor`.
+
+When your client starts this MCP server, it also starts the model gate (Layer 2) if it isn't running. If your client has a setting for the model's address, `slm-gate doctor` prints the line for the tools it knows; the `env` values above never reach the model gate, which reads only `slm-gate`'s `.env`.

package/configs/preserve/README.md

@@ -0,0 +1,26 @@
+# Preserved Patterns Configuration
+
+This directory contains JSON files specifying regular expression patterns that the distillation engine will protect.
+
+## The Contract
+Files must follow the `{ "patterns": string[] }` schema:
+```json
+{
+  "patterns": [
+    "^\\s*\\|.*\\|\\s*$",
+    "<!--\\s*slm-gate:verbatim-start\\s*-->"
+  ]
+}
+```
+
+## Extend vs Replace
+Controlled by `DISTILL_PRESERVE_MODE` in your `.env`:
+- `extend`: Your patterns are appended to the built-in defaults.
+- `replace`: Only your patterns (plus any adapter patterns like TLS) are used.
+
+## RE2 Safety
+Patterns are executed in Node.js using V8's regex engine. Avoid pathological backtracking by keeping patterns simple and bounded.
+
+## The Line-Based Caveat
+The regex preservation engine operates **line-by-line**. It cannot inherently protect multi-line blocks (like a fenced code block) unless every internal line independently matches a pattern.
+For atomic structural protection, `slm-gate` employs an AST-based tokenizer (Phase 1) and adaptive DB-driven policies (Phase 2 & 3). Regexes serve as the fallback floor.

package/configs/preserve/tls.json

@@ -0,0 +1,61 @@
+{
+  "patterns": [
+    "^name:",
+    "^description:",
+    "^phase:",
+    "^kind:",
+    "^domain:",
+    "^spans:",
+    "^targets:",
+    "^minModelClass:",
+    "^ownership:",
+    "^drive:",
+    "^approve:",
+    "cost: ~\\d+ tokens",
+    "^modes:",
+    "^surface:",
+    "^category:",
+    "^policies:",
+
+    "G-Stack / Diagnosis-First",
+    "MinimumCD",
+    "^## MinimumCD",
+    "Production-Grade Ethos",
+    "Modern Web Guidance",
+    "^## Four Pillars",
+
+    "^Phase \\d",
+    "^## Phase",
+    "^### Step \\d",
+
+    "^// turbo-all",
+    "^\\*\\*CRITICAL: PHASE 0",
+    "^> \\[!(IMPORTANT|WARNING|CAUTION|NOTE|TIP)\\]",
+
+    "^## Commands",
+    "^## Stack quirks",
+    "^## MCP tool naming",
+    "^## Policies & Execution",
+    "^## Git discipline",
+    "^## Code style",
+    "^## Scope",
+
+    "^## Objective",
+    "^## ⛔️ STRICT GUARDRAILS",
+    "^## Guardrails",
+    "^## 🛠 Execution Steps",
+    "^## Execution Steps",
+    "^## Code Modification Convention",
+    "^## Runtime modes",
+    "^## Pre-Flight Model Contract",
+    "^## Telemetry",
+    "^## Three Mandatory End-State Disclosures",
+    "^## 🎯",
+    "^## 🔍 Validation Gates",
+    "^## 🛠 Outcome Actions",
+    "^## 🔒",
+    "^# Lane:",
+    "^## Quota Discipline",
+    "^## Quality Verification"
+  ]
+}

package/dist/adapters/tech-lead-stack.js

@@ -0,0 +1,38 @@
+export const tlsPreservePatterns = [
+    /cost: ~\d+ tokens/i,
+    /^modes:/i,
+    /^## MinimumCD/i,
+    /^## Quality Verification/i,
+    /^Phase \d/i
+];
+export function mapLedgerEventToTlsAnalytics(event) {
+    return {
+        eventId: event.request_id,
+        timestamp: event.ts,
+        sessionId: event.session_id,
+        toolName: event.skill || 'unknown',
+        routingMode: event.route,
+        localModel: event.slm_model,
+        cloudModel: event.api_model,
+        tokens: {
+            input: event.api_in_tok,
+            output: event.api_out_tok,
+            localInput: event.in_tok,
+            localOutput: event.out_tok
+        },
+        latency: {
+            local: event.slm_latency_s,
+            cloud: event.api_latency_s
+        },
+        tags: [
+            `slm_gate=${event.slm_gate}`
+        ]
+    };
+}
+export function buildTlsDownstreamConfig(tlsRepoPath) {
+    return {
+        command: 'node',
+        args: [`${tlsRepoPath}/dist/mcp-server.mjs`],
+        env: {}
+    };
+}

package/dist/cache/index.js

@@ -0,0 +1,173 @@
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+import { CONFIG } from '../config.js';
+import { getDb } from '../ledger/index.js';
+import { cosineSimilarity, embedText } from '../utils/embedding.js';
+let dbInitialized = false;
+/**
+ * Initializes the semantic cache table in the local SQLite ledger.
+ * This is called lazily before cache operations to ensure the `semcache`
+ * table exists without blocking the main application boot.
+ */
+export function initCacheDb() {
+    if (dbInitialized)
+        return;
+    const db = getDb();
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS semcache (
+      id TEXT PRIMARY KEY,
+      embedding_blob BLOB,
+      response TEXT,
+      file_hashes TEXT,
+      ts TEXT
+    );
+  `);
+    dbInitialized = true;
+}
+/**
+ * Calculates the cosine similarity between two high-dimensional vectors.
+ * A score of 1.0 means perfectly identical directions (identical meaning),
+ * while 0 means orthogonal (no semantic overlap).
+ *
+ * @param a The first vector (e.g., the current prompt's embedding)
+ * @param b The second vector (e.g., a stored prompt's embedding)
+ * @returns A similarity score between -1.0 and 1.0
+ */
+/**
+ * Scans a prompt text for potential file paths, reads those files from disk,
+ * and returns a map of their SHA-256 hashes. This acts as a stale-context guard:
+ * if a referenced file is edited, its hash changes, invalidating previous cache hits.
+ *
+ * @param text The raw prompt or task text containing potential file paths.
+ * @returns A dictionary mapping absolute file paths to their SHA-256 hashes.
+ */
+export async function getReferencedFilesHashes(text) {
+    const hashes = {};
+    // Regex to extract standard file paths or file:// URIs
+    const regex = /(?:file:\/\/)?(\/?(?:[a-zA-Z0-9_\-\.]+\/)+[a-zA-Z0-9_\-\.]+)/g;
+    let match;
+    const potentialPaths = new Set();
+    while ((match = regex.exec(text)) !== null) {
+        potentialPaths.add(match[1]);
+    }
+    // Secondary regex for isolated relative paths like "src/index.ts"
+    const wordRegex = /([a-zA-Z0-9_\-\.\/]+)/g;
+    while ((match = wordRegex.exec(text)) !== null) {
+        if (match[1].includes('.') && match[1].includes('/')) {
+            potentialPaths.add(match[1]);
+        }
+    }
+    for (let p of potentialPaths) {
+        // Strip URI protocol if present
+        if (p.startsWith('file://'))
+            p = p.substring(7);
+        // Resolve relative paths against the project root
+        let fullPath = p;
+        if (!path.isAbsolute(fullPath)) {
+            fullPath = path.join(CONFIG.ROOT_DIR, fullPath);
+        }
+        try {
+            // Hash the file contents if it exists and is a valid file
+            const stat = await fs.stat(fullPath);
+            if (stat.isFile()) {
+                const content = await fs.readFile(fullPath);
+                hashes[fullPath] = crypto.createHash('sha256').update(content).digest('hex');
+            }
+        }
+        catch {
+            // Safely ignore missing files or invalid paths
+        }
+    }
+    return hashes;
+}
+/**
+ * Checks the semantic cache for a sufficiently similar previous request.
+ *
+ * Flow:
+ * 1. Generates an embedding for the current request using the local model.
+ * 2. Extracts and hashes any files referenced in the current request.
+ * 3. Scans stored cache entries:
+ *    a. Rejects if the stored referenced file hashes do not match exactly.
+ *    b. Calculates cosine similarity of the prompt embeddings.
+ *    c. Accepts and returns the stored response if similarity >= threshold.
+ *
+ * @param text The current task or prompt text to evaluate.
+ * @returns The cached response object/string if a match is found, otherwise null.
+ */
+export async function checkSemanticCache(text) {
+    if (!CONFIG.SEMCACHE)
+        return null;
+    initCacheDb();
+    let currentEmbedding;
+    try {
+        currentEmbedding = await embedText(text);
+        if (!currentEmbedding)
+            return null;
+    }
+    catch (e) {
+        console.error(`[cache] Failed to generate embedding: ${e}`);
+        return null;
+    }
+    const currentHashes = await getReferencedFilesHashes(text);
+    const db = getDb();
+    const rows = db.prepare('SELECT id, embedding_blob, response, file_hashes FROM semcache').all();
+    for (const row of rows) {
+        const storedHashes = JSON.parse(row.file_hashes);
+        // Validate that the context files haven't changed (stale-context guard)
+        const keys1 = Object.keys(currentHashes);
+        const keys2 = Object.keys(storedHashes);
+        let match = keys1.length === keys2.length;
+        if (match) {
+            for (const k of keys1) {
+                if (currentHashes[k] !== storedHashes[k]) {
+                    match = false;
+                    break;
+                }
+            }
+        }
+        // Skip this cache entry if file contexts differ
+        if (!match)
+            continue;
+        // Convert the stored SQLite BLOB back into a Float64Array for math operations
+        const buf = row.embedding_blob;
+        const storedEmbedding = new Float64Array(buf.buffer, buf.byteOffset, buf.byteLength / 8);
+        const sim = cosineSimilarity(currentEmbedding, Array.from(storedEmbedding));
+        if (sim >= CONFIG.SEMCACHE_THRESHOLD) {
+            console.error(`[cache] HIT! Similarity: ${sim.toFixed(4)}`);
+            return JSON.parse(row.response);
+        }
+    }
+    return null;
+}
+/**
+ * Stores a new entry in the semantic cache.
+ *
+ * Generates the vector embedding for the prompt, hashes its referenced files,
+ * and stores the original response payload in the SQLite ledger.
+ *
+ * @param text The original prompt or task text.
+ * @param responseObj The response payload or string to store.
+ */
+export async function setSemanticCache(text, responseObj) {
+    if (!CONFIG.SEMCACHE)
+        return;
+    initCacheDb();
+    let embedding;
+    try {
+        embedding = await embedText(text);
+        if (!embedding)
+            return;
+    }
+    catch (e) {
+        console.error(`[cache] Failed to generate embedding for storage: ${e}`);
+        return;
+    }
+    // Convert the array of floats into a binary buffer for SQLite BLOB storage
+    const blob = Buffer.from(new Float64Array(embedding).buffer);
+    const currentHashes = await getReferencedFilesHashes(text);
+    const db = getDb();
+    const stmt = db.prepare('INSERT INTO semcache (id, embedding_blob, response, file_hashes, ts) VALUES (?, ?, ?, ?, ?)');
+    // Store the request embedding alongside the serialized response and the file context state
+    stmt.run(crypto.randomUUID(), blob, JSON.stringify(responseObj), JSON.stringify(currentHashes), new Date().toISOString());
+}

package/dist/cli.js

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+/**
+ * Entry point for the `slm-gate` CLI.
+ *
+ * Why it is written this way:
+ * 1. Dual Execution Environments: We need to support running via `tsx src/cli.ts` in development,
+ *    and `node dist/cli.js` when installed globally or built for production.
+ * 2. Process Spawning: Instead of heavily coupling the CLI directly to the module logic (which might
+ *    carry complex dependencies or require TS execution), this script acts purely as an orchestrator.
+ *    It determines whether to use Node or tsx and spawns child processes for the actual commands.
+ * 3. Environment Overrides: It allows injecting temporary environment variables (like RAM presets)
+ *    into the spawned processes without permanently mutating the parent process environment.
+ */
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { isPackageInstall, resolveHomeDir } from './home-dir.js';
+const filename = fileURLToPath(import.meta.url);
+const dirname = path.dirname(filename);
+// ROOT_DIR ensures that no matter where the command is executed from, it executes relative to the project root.
+const ROOT_DIR = path.resolve(dirname, '..');
+/**
+ * Spawns a child process for a given command.
+ *
+ * @param command - The executable to run (e.g., 'node' or 'tsx')
+ * @param args - Arguments to pass to the executable
+ * @param env - Additional environment variables to overlay on top of process.env
+ * @returns The spawned ChildProcess instance
+ */
+function runCommand(command, args, env = {}) {
+    const child = spawn(command, args, {
+        stdio: 'inherit', // Connects child's stdout/stderr directly to the terminal
+        cwd: ROOT_DIR,
+        env: { ...process.env, ...env }
+    });
+    child.on('error', (err) => {
+        console.error(`Failed to start process: ${err.message}`);
+        process.exit(1);
+    });
+    child.on('exit', (code) => {
+        if (code !== 0) {
+            process.exit(code || 1);
+        }
+    });
+    return child;
+}
+// Determine if we are running the compiled JavaScript (from dist/) or TypeScript (from src/)
+const isCompiled = filename.endsWith('.js');
+const tsxPath = path.join(ROOT_DIR, 'node_modules', '.bin', 'tsx');
+/**
+ * Resolves the correct execution path and command for a given source script.
+ *
+ * @param srcPath - The relative path to the TypeScript source file (e.g., 'src/config.ts')
+ * @returns An object containing the executable ('node' or 'tsx') and the absolute path to the target file.
+ */
+function getRunPath(srcPath) {
+    // If we're executing the compiled CLI (dist/cli.js), we map 'src/*.ts' to 'dist/*.js' and use 'node'
+    if (isCompiled && srcPath.startsWith('src/')) {
+        const distPath = srcPath.replace(/^src\//, 'dist/').replace(/\.ts$/, '.js');
+        return { command: 'node', args: [path.join(ROOT_DIR, distPath)] };
+    }
+    // If running in development, we use 'tsx' to execute the TypeScript files directly
+    return { command: tsxPath, args: [path.join(ROOT_DIR, srcPath)] };
+}
+/** `bench` and `metrics` run the evaluation harness with tsx; only a git checkout has either. */
+function requireCheckout(params) {
+    if (fs.existsSync(path.join(ROOT_DIR, params.script)) && fs.existsSync(tsxPath))
+        return;
+    console.error(`\`slm-gate ${params.command}\` needs a git checkout of slm-gate (https://github.com/zenithfoundry/slm-gate): it runs the evaluation harness, which an npm install does not include.`);
+    process.exit(1);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (!command || command === 'help' || command === '--help' || command === '-h') {
+        console.log(`
+Usage: slm-gate <command> [options]
+
+Commands:
+  init           Create your settings file (.env), set up for this computer's RAM. Never replaces one
+                 that exists
+                 Options:
+                   --ram <GB>               (set up for a computer with this much RAM instead)
+  mcp            Run the MCP server for a coding tool. This is what you register in the tool:
+                 command \`slm-gate\`, argument \`mcp\`. It starts the model gate by itself
+  serve          Run the model gate in this terminal (normally not needed: it starts by itself
+                 whenever a coding tool starts slm-gate's MCP server)
+                 Options:
+                   --layer llm|mcp|both     (default: llm; your coding tools start the MCP server)
+                   --transport stdio|http   (MCP server transport, default: stdio)
+                   --preset <preset>        (override RAM preset, e.g., ram-24)
+  start          Start the model gate in the background (if it is not running)
+  stop           Stop the model gate; it stays stopped until start, restart or a reboot
+  restart        Stop and start the model gate (e.g. after updating slm-gate)
+  bench          Run the offline evaluation harness
+                 Options:
+                   --n <number>             (number of tasks to run)
+  metrics        Show performance and cost metrics from the local ledger
+  ledger:sync    Sync local SQLite ledger traces and scores to Langfuse
+                 Options:
+                   --all                    (sync all historical events)
+                   --limit <number>         (limit number of events to sync)
+                   --dry-run                (simulate without sending network requests)
+  ledger:reset   Nuke local SQLite database and start fresh
+  setup-dashboard Setup Langfuse dashboard and widgets
+  config         Print the current resolved configuration
+  models:check   Check if required models are pulled and fit in RAM
+  doctor         Run preflight readiness checks
+`);
+        process.exit(0);
+    }
+    if (command === 'init') {
+        const ramAt = args.indexOf('--ram');
+        const ramGb = ramAt >= 0 ? Number(args[ramAt + 1]) : undefined;
+        if (ramGb !== undefined && !(Number.isInteger(ramGb) && ramGb > 0)) {
+            console.error('--ram takes a whole number of gigabytes, e.g. --ram 64');
+            process.exit(1);
+        }
+        const { initSettings } = await import('./setup/init.js');
+        const { detectHardware } = await import('./hardware.js');
+        const setUpFor = ramGb ?? detectHardware().totalRamGB;
+        let result;
+        try {
+            result = initSettings({
+                installDir: ROOT_DIR,
+                homeDir: resolveHomeDir({ installDir: ROOT_DIR, env: process.env, userHome: os.homedir() }),
+                ramGb: setUpFor,
+            });
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+        const self = isPackageInstall(ROOT_DIR) ? 'slm-gate' : `node ${path.join(ROOT_DIR, 'dist', 'cli.js')}`;
+        if (!result.created) {
+            console.log(`Your settings file already exists, so nothing was changed: ${result.envPath}`);
+            console.log(`Edit it directly, or delete it and run \`${self} init\` again.`);
+            return;
+        }
+        console.log(`Created your settings file: ${result.envPath}`);
+        console.log(`It is set up for ${setUpFor} GB of RAM (RAM_PRESET=${result.preset}); every other setting is explained in the file.`);
+        if (result.preset === 'custom') {
+            console.log('That is more than 128 GB, so it starts from the 128 GB models; you can choose bigger ones (step 4).');
+        }
+        console.log('\nNext:');
+        console.log(`  1. Download the local models:  ${result.models.map(model => `ollama pull ${model}`).join(' && ')}`);
+        console.log(`  2. Check everything:           ${self} doctor`);
+        console.log(`  3. Connect your coding tool:   add an MCP server that runs \`${self} mcp\`.`);
+        console.log(`     \`${self} doctor\` also prints the address for tools that can send their AI requests through slm-gate.`);
+        console.log('  4. To pick models that fit this computer best, use llmfit: https://github.com/AlexsJones/llmfit');
+        console.log('     Then set SLM_BRAIN_MODEL and SLM_GATE_MODEL in the settings file.');
+        return;
+    }
+    if (command === 'mcp') {
+        // In this process, not a child: the coding tool talks to it over this process's stdin/stdout and
+        // stops it by stopping this process. The server sends all logging to stderr and starts on import.
+        await import('./mcp-gate/index.js');
+        return;
+    }
+    if (command === 'serve') {
+        // The MCP server is started by the coding tools themselves; by hand you usually want the model gate.
+        let layer = 'llm';
+        let transport = 'stdio';
+        let preset = '';
+        for (let i = 1; i < args.length; i++) {
+            if (args[i] === '--layer')
+                layer = args[++i];
+            else if (args[i] === '--transport')
+                transport = args[++i];
+            else if (args[i] === '--preset')
+                preset = args[++i];
+        }
+        if (!layer || !['mcp', 'llm', 'both'].includes(layer)) {
+            console.error('Error: --layer must be mcp, llm, or both');
+            process.exit(1);
+        }
+        const envOverride = {};
+        if (preset)
+            envOverride['RAM_PRESET'] = preset;
+        if (transport)
+            envOverride['MCP_GATE_TRANSPORT'] = transport;
+        const layersToStart = [];
+        if (layer === 'mcp' || layer === 'both')
+            layersToStart.push('src/mcp-gate/index.ts');
+        if (layer === 'llm' || layer === 'both')
+            layersToStart.push('src/llm-gate/index.ts');
+        for (const src of layersToStart) {
+            const { command: cmd, args: cmdArgs } = getRunPath(src);
+            runCommand(cmd, cmdArgs, envOverride);
+        }
+    }
+    else if (command === 'bench') {
+        requireCheckout({ command: 'bench', script: 'harness/run.ts' });
+        // Pass all args after bench to the run script
+        const benchArgs = args.slice(1);
+        runCommand(tsxPath, [path.join(ROOT_DIR, 'harness/run.ts'), ...benchArgs]);
+    }
+    else if (command === 'metrics') {
+        requireCheckout({ command: 'metrics', script: 'harness/metrics.ts' });
+        runCommand(tsxPath, [path.join(ROOT_DIR, 'harness/metrics.ts')]);
+    }
+    else if (command === 'ledger:sync' || command === 'sync') {
+        const syncArgs = args.slice(1);
+        const { command: cmd, args: cmdArgs } = getRunPath('src/ledger/sync.ts');
+        runCommand(cmd, [...cmdArgs, ...syncArgs]);
+    }
+    else if (command === 'setup-dashboard') {
+        const { command: cmd, args: cmdArgs } = getRunPath('src/ledger/setup-dashboard.ts');
+        runCommand(cmd, cmdArgs);
+    }
+    else if (command === 'ledger:reset') {
+        const outputDir = path.join(resolveHomeDir({ installDir: ROOT_DIR, env: process.env, userHome: os.homedir() }), 'output');
+        const filesToNuke = [
+            path.join(outputDir, 'ledger.sqlite'),
+            path.join(outputDir, 'ledger.sqlite-wal'),
+            path.join(outputDir, 'ledger.sqlite-shm'),
+            path.join(outputDir, 'deferral_curve.svg'),
+            path.join(outputDir, 'leaderboard.md')
+        ];
+        for (const f of filesToNuke) {
+            if (fs.existsSync(f)) {
+                fs.unlinkSync(f);
+            }
+        }
+        console.log('Local SQLite ledger and benchmark outputs nuked successfully.');
+        process.exit(0);
+    }
+    else if (command === 'config') {
+        const { command: cmd, args: cmdArgs } = getRunPath('src/config.ts');
+        // For config, if using node, we need to make sure we don't just import it but run it.
+        // The config.ts has a block that checks if it's the main module.
+        runCommand(cmd, cmdArgs);
+    }
+    else if (command === 'models:check') {
+        const { command: cmd, args: cmdArgs } = getRunPath('src/models/check.ts');
+        runCommand(cmd, cmdArgs);
+    }
+    else if (command === 'doctor') {
+        const { command: cmd, args: cmdArgs } = getRunPath('src/doctor.ts');
+        runCommand(cmd, cmdArgs);
+    }
+    else if (command === 'start' || command === 'stop' || command === 'restart') {
+        const { command: cmd, args: cmdArgs } = getRunPath('src/setup/gate-command.ts');
+        runCommand(cmd, [...cmdArgs, command]);
+    }
+    else {
+        console.error(`Unknown command: ${command}`);
+        process.exit(1);
+    }
+}
+main().catch(err => {
+    console.error(err);
+    process.exit(1);
+});