@zenithfoundry/slm-gate 1.2.1

package/dist/utils/local-only.js

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview "Only programs on this computer": the one rule both slm-gate HTTP servers apply (the model
+ * gate on LLM_GATE_PORT and the MCP server's HTTP mode on MCP_GATE_PORT). Kept in one place because it is a
+ * security rule and two copies could drift.
+ *
+ * Two parts, because binding alone is not enough:
+ * - Listen on the loopback addresses only, so other machines on the network cannot connect.
+ * - Refuse requests addressed to another name (Host) or sent by a web page from another site (Origin).
+ *   A page open in the browser runs on this computer too: through DNS rebinding it can reach 127.0.0.1
+ *   under its own domain name, and any page can send cross-site requests to localhost.
+ */
+import http from 'node:http';
+/** Names for this computer. Other spellings (`localhost.`, `127.1`, …) are refused: fail closed. */
+const LOCAL_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1']);
+/** A Host header's name without the port or IPv6 brackets, e.g. `[::1]:8787` → `::1`. */
+function hostnameOf(host) {
+    const value = host.trim().toLowerCase();
+    if (value.startsWith('['))
+        return value.slice(1, value.indexOf(']'));
+    const colon = value.lastIndexOf(':');
+    return colon === -1 ? value : value.slice(0, colon);
+}
+function isLocalOrigin(origin) {
+    try {
+        const url = new URL(origin);
+        const hostname = url.hostname.replace(/^\[|\]$/g, '');
+        return (url.protocol === 'http:' || url.protocol === 'https:') && LOCAL_HOSTNAMES.has(hostname);
+    }
+    catch {
+        return false; // includes the literal `null` sent by sandboxed pages and file:// documents
+    }
+}
+/**
+ * True for a request addressed to this computer by name, and either sent by a program (no Origin) or by a
+ * web page served from this computer. Coding tools' model clients send no Origin.
+ */
+export function isLocalRequest(headers) {
+    if (!headers.host || !LOCAL_HOSTNAMES.has(hostnameOf(headers.host)))
+        return false;
+    return headers.origin === undefined || isLocalOrigin(headers.origin);
+}
+function listenOn(params) {
+    return new Promise((resolve, reject) => {
+        params.server.once('error', reject);
+        params.server.listen({ host: params.host, port: params.port, ipv6Only: params.host === '::1' }, () => {
+            params.server.off('error', reject);
+            resolve();
+        });
+    });
+}
+/**
+ * Serves `handler` on 127.0.0.1 and ::1, so `localhost` works whichever address a client's resolver picks
+ * first (macOS answers ::1 first, and not every client falls back).
+ *
+ * @param params.port The port (0 picks a free one, the same for both addresses)
+ * @param params.onListening Called once both addresses listen
+ * @returns The listening servers (to close them)
+ * @throws When 127.0.0.1 cannot be used (e.g. the port is taken), or ::1 fails for any reason other than
+ *   IPv6 being unavailable; nothing is left listening then
+ */
+export async function listenOnThisComputer(params) {
+    const ipv4 = http.createServer(params.handler);
+    await listenOn({ server: ipv4, host: '127.0.0.1', port: params.port });
+    const port = ipv4.address().port;
+    const ipv6 = http.createServer(params.handler);
+    try {
+        await listenOn({ server: ipv6, host: '::1', port });
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'EADDRNOTAVAIL' && code !== 'EAFNOSUPPORT') {
+            // E.g. another program holds [::1]:port: `localhost` clients would reach it, not us.
+            await new Promise(resolve => ipv4.close(resolve));
+            throw err;
+        }
+        console.error(`[slm-gate] IPv6 is not available on this computer; listening on 127.0.0.1:${port} only.`);
+        params.onListening?.();
+        return [ipv4];
+    }
+    params.onListening?.();
+    return [ipv4, ipv6];
+}

package/dist/utils/preserve-patterns.js

@@ -0,0 +1,115 @@
+import fs from 'fs/promises';
+import { CONFIG } from '../config.js';
+/**
+ * A rigid set of baseline RegExp patterns used to identify lines that MUST NEVER be dropped
+ * during local offline Small Language Model (SLM) contextual compression.
+ *
+ * The system ensures that any line matching these patterns is explicitly preserved and shielded
+ * via placeholder substitution before handing the text to the SLM. This guarantees that
+ * critical structural integrity, hard requirements, and specific directives survive the
+ * lossy distillation process.
+ */
+export const BUILTIN_PATTERNS = [
+    // requirement keywords
+    /.*(?:MUST|MUST NOT|SHALL|REQUIRED|SHOULD NOT|NEVER|ALWAYS|DO NOT|MANDATORY|PROHIBITED|IMPORTANT|CRITICAL|WARNING|CAUTION).*/i,
+    // markdown headings
+    /^#{1,6}\s/,
+    // numbered steps
+    /^\s*\d+[.)]\s/,
+    // checklist items
+    /^\s*[-*]\s+\[[ xX]\]/,
+    // fenced code blocks / inline code lines (contain backticks)
+    /`/,
+    // URLs
+    /https?:\/\//,
+    // path/KEY[:=]value config lines
+    /^[A-Za-z0-9_.\/-]+[:=]/,
+    // output/format directives
+    /(?:format:|respond with|output must|Answer:)/i,
+    // hard quantities
+    /(?:no more than \d|at most|exactly \d|maximum|minimum)/i,
+    // YAML frontmatter block markers
+    /^---/,
+];
+/**
+ * Attempts to compile a regular expression string into an executable RegExp object.
+ * It first attempts to use `re2` (a fast, linear-time regex engine safe against ReDoS attacks)
+ * if installed. If `re2` is missing or rejects the pattern (e.g., due to unsupported features
+ * like complex lookaheads), it gracefully falls back to the native V8 RegExp engine.
+ *
+ * @param pattern - The raw regular expression string to compile
+ * @returns The compiled RegExp instance, or null if the pattern is fatally invalid
+ */
+async function compilePattern(pattern) {
+    let Re2;
+    try {
+        // @ts-ignore - optional dependency
+        Re2 = (await import('re2')).default;
+    }
+    catch {
+        // re2 not installed, will fallback
+    }
+    if (Re2) {
+        try {
+            return new Re2(pattern);
+        }
+        catch (e) {
+            // Re2 threw (e.g. unsupported syntax like lookaheads), fallback to native RegExp
+        }
+    }
+    try {
+        return new RegExp(pattern);
+    }
+    catch (e) {
+        console.error(`[distill] Warning: Skipping invalid regex pattern: ${pattern}`);
+        return null;
+    }
+}
+/**
+ * Constructs the aggregate array of preservation Regex patterns for the current session.
+ * Depending on the configuration (`DISTILL_PRESERVE_MODE`), it will either:
+ * - 'extend': Combine `BUILTIN_PATTERNS`, user-defined JSON patterns, and adapter-specific patterns.
+ * - 'replace': Ignore `BUILTIN_PATTERNS` entirely, relying only on user/adapter specifications.
+ *
+ * @returns A promise resolving to the final array of compiled RegExp patterns
+ */
+export async function buildPreserveList() {
+    let patterns = [];
+    const mode = CONFIG.DISTILL_PRESERVE_MODE || 'extend';
+    if (mode === 'extend') {
+        patterns = [...BUILTIN_PATTERNS];
+    }
+    // Load custom preservation patterns defined in an external JSON file by the user
+    if (CONFIG.DISTILL_PRESERVE_PATH) {
+        try {
+            const data = await fs.readFile(CONFIG.DISTILL_PRESERVE_PATH, 'utf-8');
+            const parsed = JSON.parse(data);
+            if (Array.isArray(parsed.patterns)) {
+                for (const p of parsed.patterns) {
+                    const compiled = await compilePattern(p);
+                    if (compiled) {
+                        patterns.push(compiled);
+                    }
+                }
+            }
+        }
+        catch (e) {
+            console.error(`[distill] Warning: Failed to read or parse user preserve patterns from ${CONFIG.DISTILL_PRESERVE_PATH}`);
+        }
+    }
+    // Optionally load tech-lead-stack patterns if running in decoupled integration mode
+    if (CONFIG.TLS_ADAPTER) {
+        try {
+            // Guarded dynamic import
+            // @ts-ignore - Decoupling: adapter may not exist in pure MCP-gate configurations
+            const adapter = await import('../adapters/tech-lead-stack.js');
+            if (adapter.tlsPreservePatterns) {
+                patterns.push(...adapter.tlsPreservePatterns);
+            }
+        }
+        catch (e) {
+            console.error(`[distill] Warning: Failed to load TLS adapter patterns`, e);
+        }
+    }
+    return patterns;
+}

package/dist/utils/safety.js

@@ -0,0 +1,30 @@
+import { TOOL_RESULT_PREFIXES, CURSOR_TOOL_MARKERS } from './constants.js';
+/**
+ * Heuristic to detect if the *last* message in the conversation actually represents
+ * a tool response or a file output, rather than the user's own turn.
+ *
+ * If it is a tool output, it's unsafe to locally defer since we shouldn't execute
+ * commands derived directly from data.
+ */
+export function isLatestInstructionFromTool(messages) {
+    if (messages.length === 0)
+        return false;
+    const last = messages[messages.length - 1];
+    if (last.role === 'tool') {
+        return true;
+    }
+    // Some clients encode tool results as 'user' or 'assistant' messages.
+    const content = last.content.trim();
+    if (TOOL_RESULT_PREFIXES.some(prefix => content.startsWith(prefix))) {
+        return true;
+    }
+    if (CURSOR_TOOL_MARKERS.some(marker => content.includes(marker))) {
+        return true;
+    }
+    // A very common pattern: JSON objects embedded directly at the start that look like tool returns
+    if (content.startsWith('{"') && content.includes('}') && (content.includes('result') || content.includes('output'))) {
+        // Basic heuristic for raw JSON return
+        return true;
+    }
+    return false;
+}

package/dist/verifier/index.js

@@ -0,0 +1,67 @@
+/**
+ * The Verifier Module for small-language-model-gate.
+ *
+ * This module is responsible for analyzing the output of the local Small Language Model (SLM)
+ * and deciding whether the response is acceptable or if the request must be escalated to the
+ * downstream cloud LLM. It acts as a safety and quality gate.
+ *
+ * It is primarily used by the `llm-gate` routing layer to evaluate the confidence and
+ * structural validity of local inferences before deferring to them.
+ *
+ * The verification strictness is monotonic (levels 1-5), meaning each level is a superset
+ * of the one below it. As the strictness level increases, the likelihood of escalation also increases.
+ *
+ * Strictness Levels:
+ * - Level 1: Escalates if the answer is completely empty.
+ * - Level 2: Escalates if the answer fails a provided regex format constraint.
+ * - Level 3: Escalates if the answer contains hedging language (e.g., "I'm not sure").
+ * - Level 4: Escalates if multiple generated samples disagree with each other.
+ * - Level 5: Always escalates to the cloud model (bypasses local SLM entirely).
+ */
+import { checkAgreement } from '../models/reasoning.js';
+export const HEDGING_LEXICON = [
+    "i'm not sure",
+    "i am not sure",
+    "i think",
+    "possibly",
+    "cannot determine",
+    "unclear",
+    "it's unclear"
+];
+const HEDGING_REGEX = new RegExp(`\\b(${HEDGING_LEXICON.join('|')})\\b`, 'i');
+export function verify(answer, samples, constraints, level) {
+    const flags = [];
+    // Level 1: empty or unparseable
+    if (level >= 1) {
+        if (answer.trim() === '') {
+            flags.push('empty');
+        }
+    }
+    // Level 2: fails format constraint
+    if (level >= 2) {
+        if (constraints.formatRe && !constraints.formatRe.test(answer)) {
+            flags.push('format_mismatch');
+        }
+    }
+    // Level 3: hedging language
+    if (level >= 3) {
+        if (HEDGING_REGEX.test(answer)) {
+            flags.push('hedging');
+        }
+    }
+    // Level 4: samples disagree
+    if (level >= 4) {
+        if (samples.length > 0 && checkAgreement(samples) === null) {
+            flags.push('disagreement');
+        }
+    }
+    // Level 5: always escalate
+    if (level >= 5) {
+        flags.push('always_escalate');
+    }
+    return {
+        escalate: flags.length > 0,
+        level,
+        flags
+    };
+}

package/package.json

@@ -0,0 +1,121 @@
+{
+  "name": "@zenithfoundry/slm-gate",
+  "version": "1.2.1",
+  "type": "module",
+  "description": "A decoupled local-SLM pre-processing and routing layer for MCP and cloud LLMs. Intercepts, distills, and routes prompts locally with Ollama to cut token costs and protect monthly quota.",
+  "license": "MIT",
+  "author": "bronz3beard",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zenithfoundry/slm-gate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zenithfoundry/slm-gate/issues"
+  },
+  "homepage": "https://github.com/zenithfoundry/slm-gate#readme",
+  "keywords": [
+    "ai",
+    "slm",
+    "small-language-model",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "local-ai",
+    "ollama",
+    "qwen",
+    "prompt-compression",
+    "llm-routing",
+    "token-optimization",
+    "cost-reduction",
+    "agentic-workflows",
+    "ai-agents",
+    "antigravity",
+    "cursor",
+    "claude-code"
+  ],
+  "bin": {
+    "slm-gate": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.js",
+    "configs",
+    ".env.example"
+  ],
+  "engines": {
+    "node": ">=22",
+    "pnpm": ">=10"
+  },
+  "dependencies": {
+    "@langfuse/client": "^5.11.1",
+    "@langfuse/otel": "^5.11.1",
+    "@langfuse/tracing": "^5.11.1",
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "@opentelemetry/sdk-node": "^0.222.0",
+    "better-sqlite3": "^13.0.3",
+    "dotenv": "^16.4.5",
+    "markdown-it": "^15.0.2",
+    "ollama": "^0.6.3",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.23.1"
+  },
+  "optionalDependencies": {
+    "re2": "^1.21.4"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.5.2",
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/jest": "^29.5.12",
+    "@types/markdown-it": "^14.2.0",
+    "@types/node": "^20.14.9",
+    "fast-check": "^4.10.2",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.13",
+    "tsx": "^4.23.15",
+    "typescript": "^5.5.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "slm-gate": "tsx src/cli.ts",
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "config": "node --import tsx src/config.ts",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --passWithNoTests",
+    "test:summary": "NODE_OPTIONS=--experimental-vm-modules jest --passWithNoTests --reporters=\"summary\"",
+    "test:decoupling": "bash -c 'trap \"mv .src_adapters_tmp src/adapters 2>/dev/null\" EXIT; mv src/adapters .src_adapters_tmp; pnpm run build && pnpm run test'",
+    "models:check": "node --import tsx src/models/check.ts",
+    "ledger:smoke": "tsx src/ledger/smoke.ts",
+    "llm-gate:serve": "tsx src/llm-gate/index.ts",
+    "mcp-gate:stdio": "tsx src/mcp-gate/index.ts",
+    "mcp-gate:http": "tsx src/mcp-gate/index.ts",
+    "e2e:standalone-mcp": "tsx scripts/e2e-standalone-mcp.ts",
+    "e2e:llm-gate-routing": "tsx scripts/e2e-llm-gate-routing.ts",
+    "e2e:distill-fallback": "tsx scripts/e2e-distill-fallback.ts",
+    "e2e:resolver-ambiguities": "tsx scripts/e2e-resolver-ambiguities.ts",
+    "smoke:e2e": "tsx scripts/smoke-e2e.ts",
+    "e2e:tls-downstream": "tsx scripts/e2e-tls-downstream.ts",
+    "e2e:npm-install": "tsx scripts/e2e-npm-install.ts",
+    "test:e2e": "pnpm run build && pnpm run e2e:standalone-mcp && pnpm run e2e:llm-gate-routing && pnpm run e2e:distill-fallback && pnpm run e2e:resolver-ambiguities && pnpm run smoke:e2e",
+    "e2e": "pnpm run test:e2e",
+    "bench": "tsx harness/run.ts",
+    "bench:reset": "rm -rf harness/.cache && pnpm run bench",
+    "metrics": "tsx harness/metrics.ts",
+    "migrate:provider": "tsx scripts/migrations/001-add-provider.ts",
+    "ledger:sync": "tsx src/ledger/sync.ts",
+    "ledger:verify": "tsx src/ledger/verify.ts",
+    "ledger:report": "tsx src/ledger/report.ts",
+    "dashboard": "tsx src/dashboard/serve.ts",
+    "dashboard:export": "tsx src/dashboard/export.ts",
+    "ledger:reset": "rm -f output/ledger.sqlite output/ledger.sqlite-wal output/ledger.sqlite-shm output/deferral_curve.svg output/leaderboard.md",
+    "ledger:wipe-langfuse": "tsx src/ledger/wipe-langfuse.ts",
+    "langfuse:wipe": "tsx src/ledger/wipe-langfuse.ts",
+    "langfuse:setup-dashboard": "tsx src/ledger/setup-dashboard.ts",
+    "elision:stats": "node scripts/elision-clean.mjs --stats",
+    "elision:clean": "node scripts/elision-clean.mjs --interactive",
+    "elision:clean:dry": "node scripts/elision-clean.mjs --older-than 180d --dry-run",
+    "elision:clean:old": "node scripts/elision-clean.mjs --older-than 180d",
+    "elision:clean:all": "node scripts/elision-clean.mjs --all"
+  }
+}