@zenithfoundry/slm-gate 1.2.1

package/dist/models/reasoning.js

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import { roles } from './roles.js';
+import { withSlmTimeout } from './helpers.js';
+import { CONFIG } from '../config.js';
+export function checkAgreement(samples) {
+    if (samples.length === 0)
+        return null;
+    const normalize = (val) => {
+        if (typeof val === 'string') {
+            return val.toLowerCase().replace(/\s+/g, ' ').replace(/[.,!?]$/, '').trim();
+        }
+        return JSON.stringify(val);
+    };
+    const counts = new Map();
+    let maxCount = 0;
+    let majorityValue = null;
+    for (const sample of samples) {
+        const norm = normalize(sample);
+        const existing = counts.get(norm) || { count: 0, original: sample };
+        existing.count += 1;
+        counts.set(norm, existing);
+        if (existing.count > maxCount) {
+            maxCount = existing.count;
+            majorityValue = existing.original;
+        }
+    }
+    const threshold = Math.floor(samples.length / 2) + 1;
+    return maxCount >= threshold ? majorityValue : null;
+}
+export async function selfConsistency(slm, model, prompt, schema, k = 3, temperature = 0.7) {
+    const promises = Array.from({ length: k }).map(() => withSlmTimeout(slm.generateJSON(model, prompt, schema, temperature), 'selfConsistency', CONFIG.SLM_TIMEOUT_MS).catch(() => null));
+    const results = await Promise.all(promises);
+    const validResults = results.filter((r) => r !== null);
+    const agreed = checkAgreement(validResults);
+    if (agreed !== null) {
+        return agreed;
+    }
+    // Fallback to a temp=0 run if no agreement
+    return withSlmTimeout(slm.generateJSON(model, prompt, schema, 0), 'selfConsistency', CONFIG.SLM_TIMEOUT_MS);
+}
+export async function classify(slm, text) {
+    const schema = z.object({
+        category: z.enum(['classify', 'extract', 'format', 'boolean', 'short_factual', 'trivial_edit', 'other'])
+    });
+    const prompt = `Categorize the following user request into exactly one category:
+- 'format': Generating, structuring, or converting data to JSON, XML, CSV, or markdown.
+- 'other': Math word problems, arithmetic calculations, multi-step reasoning, logic, coding, or complex tasks.
+- 'short_factual': Simple direct fact lookup (e.g. "What is the capital of Japan?"). NEVER use for arithmetic or math.
+- 'boolean': Answering yes/no or true/false questions.
+- 'extract': Extracting specific data spans from provided text.
+- 'classify': Classifying items into categories.
+- 'trivial_edit': Fixing spelling or grammar.
+
+Rule: Any question requiring arithmetic calculation, word problem math, or multi-step logic MUST be classified as 'other'.
+
+Text: ${text}`;
+    const result = await withSlmTimeout(slm.generateJSON(roles.gate, prompt, schema, 0), 'classify', CONFIG.SLM_TIMEOUT_MS);
+    return result.category;
+}
+export async function compress(slm, text) {
+    const schema = z.object({
+        compressedText: z.string()
+    });
+    const prompt = `Compress the following text while maintaining the core meaning.\n\nText: ${text}`;
+    const result = await withSlmTimeout(slm.generateJSON(roles.gate, prompt, schema, 0), 'compress', CONFIG.SLM_TIMEOUT_MS);
+    return result.compressedText;
+}
+/**
+ * Compresses ONE narrative run for `distillToolResult`, which never sends protected content here, so
+ * this prompt carries no placeholder-custody rules — a 3B model reliably summarises prose and reliably
+ * loses opaque tokens. An explicit word budget is what actually drives the ratio: without it the model
+ * rewords instead of condensing (measured 4-8% vs 44-60%). Shared by the MCP layer and the model gate.
+ *
+ * @param params.slm The local model client
+ * @param params.text The narrative run to compress
+ * @param params.task Optional task context for the model
+ * @returns The compressed run
+ */
+export function compressNarrativeRun(params) {
+    const { slm, text, task } = params;
+    const wordCount = text.trim().split(/\s+/).length;
+    const targetWords = Math.max(20, Math.ceil(wordCount * 0.35));
+    const prompt = `Compress the text below to AT MOST ${targetWords} words.\n\nKeep: every instruction, requirement, constraint, name, number, path and technical specific.\nDelete: background, history, rationale, motivation, repetition and filler.\nOutput ONLY the compressed text as terse bullet points. No preamble, no heading.\n\nTask context: ${task || 'None'}\n\n${text}`;
+    // This was the only model call in the pipeline with neither a token ceiling nor a timeout.
+    // Ollama sends HTTP response headers only AFTER generation completes, so the effective cap
+    // is Node fetch's 300s header timeout surfacing as `fetch failed`, misclassified as a
+    // transport error, long after the MCP client had given up. SLM_TIMEOUT_MS now governs it.
+    // The ceiling is per-run and generous against the target so a summary is never cut mid-
+    // sentence; the run is discarded anyway if it comes back longer than the original.
+    return withSlmTimeout(slm.generateText(CONFIG.SLM_GATE_MODEL, [{ role: 'user', content: prompt }], CONFIG.TEMPERATURE, Math.max(128, Math.ceil(wordCount * 0.6))), 'distill', CONFIG.SLM_TIMEOUT_MS);
+}

package/dist/models/roles.js

@@ -0,0 +1,9 @@
+import { CONFIG } from '../config.js';
+export const roles = {
+    get brain() {
+        return CONFIG.SLM_BRAIN_MODEL;
+    },
+    get gate() {
+        return CONFIG.SLM_GATE_MODEL;
+    }
+};

package/dist/models/slm.js

@@ -0,0 +1,243 @@
+import { Ollama } from 'ollama';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { CONFIG } from '../config.js';
+import { SlmFormatError } from './helpers.js';
+function stripThinkTags(text) {
+    return text.replace(/<think>[\s\S]*?<\/think>/g, '').trim();
+}
+export class SLM {
+    client;
+    constructor(client) {
+        this.client = client || new Ollama({ host: CONFIG.OLLAMA_HOST });
+    }
+    /**
+     * Generates a deterministic JSON payload from the Small Language Model.
+     * This is used internally for agentic logic, routing decisions, and prompt conditioning.
+     *
+     * It enforces a strict JSON schema and parses the response. If the model returns malformed JSON,
+     * it will catch the error and retry the generation with a temperature of 0 (fully deterministic).
+     *
+     * @WARNING Do not use markdown extraction, regex parsing, or `stop` tokens to force JSON generation.
+     * Native Structured Outputs (`format: jsonSchema` or `response_format: { type: "json_schema" }`) MUST be used.
+     * Relying on prompt engineering and markdown parsing for JSON has caused severe rambling and timeouts
+     * (especially on Apple Silicon / llama.cpp) where the model fails to emit a closing brace or stop token.
+     *
+     * @param model The ID of the local model to execute (e.g., 'qwen2.5-coder:3b')
+     * @param prompt The instruction prompt for the model
+     * @param schema A Zod schema defining the exact JSON structure expected back
+     * @param temperature Generation temperature (randomness). Defaults to CONFIG.TEMPERATURE
+     * @returns A validated, strongly-typed JSON object matching the provided schema
+     */
+    async generateJSON(model, prompt, schema, temperature = CONFIG.TEMPERATURE) {
+        const attempt = async (temp) => {
+            // Convert the Zod schema to a standard JSON schema so the LLM understands the expected structure
+            const jsonSchema = zodToJsonSchema(schema);
+            let responseText = '';
+            const promptWithSchema = `${prompt}\n\nRespond with valid JSON matching the schema.`;
+            if (CONFIG.SLM_PROVIDER === 'ollama') {
+                const response = await this.client.chat({
+                    model,
+                    messages: [{ role: 'user', content: promptWithSchema }],
+                    format: jsonSchema,
+                    keep_alive: CONFIG.OLLAMA_KEEP_ALIVE,
+                    // `think` is a REQUEST-level field, not an `options` entry. Ollama silently drops
+                    // unknown keys from `options`: a thinking model
+                    // (qwen3 / qwen3.5, the default brain for ram-24 and above) reasoned until it hit
+                    // num_predict, returned done_reason:length with EMPTY content, and the parse failed.
+                    // That produced `resolver_error: format` on essentially every standalone call, twice
+                    // per call because of the retry below. Keep this out of `options`.
+                    think: false,
+                    // Every key below is a real Ollama option, so a future typo fails the build
+                    // instead of being silently ignored the way `think` was.
+                    options: {
+                        temperature: temp,
+                        num_ctx: CONFIG.NUM_CTX,
+                        num_predict: 2000
+                    }
+                });
+                responseText = response.message.content;
+            }
+            else if (CONFIG.SLM_PROVIDER === 'openai') {
+                const response = await fetch(`${CONFIG.OLLAMA_HOST}/v1/chat/completions`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        ...(CONFIG.CLOUD_API_KEY && { 'Authorization': `Bearer ${CONFIG.CLOUD_API_KEY}` })
+                    },
+                    body: JSON.stringify({
+                        model,
+                        messages: [{ role: 'user', content: promptWithSchema }],
+                        temperature: temp,
+                        max_tokens: 2000,
+                        response_format: {
+                            type: "json_schema",
+                            json_schema: {
+                                name: "slm_output",
+                                strict: true,
+                                schema: jsonSchema
+                            }
+                        }
+                    }),
+                    signal: AbortSignal.timeout(CONFIG.SLM_TIMEOUT_MS)
+                });
+                if (!response.ok) {
+                    throw new Error(`OpenAI API error: ${response.statusText}`);
+                }
+                const data = await response.json();
+                responseText = data.choices[0].message.content;
+            }
+            else {
+                throw new Error(`Unsupported SLM_PROVIDER: ${CONFIG.SLM_PROVIDER}`);
+            }
+            let stripped = stripThinkTags(responseText).trim();
+            try {
+                const parsed = JSON.parse(stripped);
+                return schema.parse(parsed);
+            }
+            catch (err) {
+                throw new SlmFormatError(`Failed to parse or validate JSON: ${err.message}\nContent: ${stripped}`);
+            }
+        };
+        try {
+            return await attempt(temperature);
+        }
+        catch (err) {
+            if (err instanceof SlmFormatError) {
+                // If the model hallucinated malformed JSON, retry once with zero temperature (maximum determinism)
+                return await attempt(0);
+            }
+            throw err;
+        }
+    }
+    /**
+      * Generates a raw, unstructured text completion from the SLM.
+      *
+      * Architectural Note:
+      * This maintains a deliberate separation of concerns between internal reasoning
+      * and external proxying. Unlike `generateJSON` (which is used strictly for internal,
+      * deterministic agentic logic and routing), `generateText` is used to directly proxy
+      * conversational responses back to the end-user/client. Bypassing schema enforcement
+      * here eliminates JSON formatting token overhead and allows for seamless real-time
+      * Markdown streaming via `streamText`.
+      *
+      * @param model The ID of the model to execute
+      * @param messages Array of history messages
+      * @param temperature Generation temperature, default from CONFIG
+      * @param maxTokens Optional ceiling on generated tokens. Left unset for conversational
+      *   proxying (llm-gate), where truncating the user's answer would be wrong. Summarising
+      *   callers (mcp-gate distill) MUST pass one: with temperature 0 and repetitive input a 3B
+      *   model can loop until the context window fills, which at local speeds runs for minutes.
+      * @returns Raw text completion
+      */
+    async generateText(model, messages, temperature = CONFIG.TEMPERATURE, maxTokens) {
+        if (CONFIG.SLM_PROVIDER === 'ollama') {
+            const response = await this.client.chat({
+                model,
+                messages,
+                keep_alive: CONFIG.OLLAMA_KEEP_ALIVE,
+                // Request-level, never inside `options` — see generateJSON for what that cost us.
+                think: false,
+                options: {
+                    temperature,
+                    num_ctx: CONFIG.NUM_CTX,
+                    ...(maxTokens !== undefined && { num_predict: maxTokens })
+                }
+            });
+            return stripThinkTags(response.message.content);
+        }
+        else if (CONFIG.SLM_PROVIDER === 'openai') {
+            const response = await fetch(`${CONFIG.OLLAMA_HOST}/v1/chat/completions`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(CONFIG.CLOUD_API_KEY && { 'Authorization': `Bearer ${CONFIG.CLOUD_API_KEY}` })
+                },
+                body: JSON.stringify({
+                    model,
+                    messages,
+                    temperature,
+                    ...(maxTokens !== undefined && { max_tokens: maxTokens })
+                }),
+                signal: AbortSignal.timeout(CONFIG.SLM_TIMEOUT_MS)
+            });
+            if (!response.ok) {
+                throw new Error(`OpenAI API error: ${response.statusText}`);
+            }
+            const data = await response.json();
+            return stripThinkTags(data.choices[0].message.content);
+        }
+        throw new Error(`Unsupported SLM_PROVIDER: ${CONFIG.SLM_PROVIDER}`);
+    }
+    /**
+     * Generates a streaming text completion from the SLM.
+     *
+     * Note on Syntax (`async *streamText`):
+     * An asterisk (*) used with a function defines a generator function, which is a
+     * special function that can pause its work and resume it later. You usually write
+     * it as `function* myFunc()` or as a short method inside an object like `*myFunc()`.
+     * By returning an AsyncGenerator, it yields content chunks iteratively as they
+     * are produced by the local model.
+     *
+     * @param model The ID of the model to execute
+     * @param messages Array of history messages
+     * @param temperature Generation temperature, default from CONFIG
+     * @returns AsyncGenerator yielding string chunks
+     */
+    async *streamText(model, messages, temperature = CONFIG.TEMPERATURE) {
+        if (CONFIG.SLM_PROVIDER === 'ollama') {
+            const response = await this.client.chat({
+                model,
+                messages,
+                stream: true,
+                keep_alive: CONFIG.OLLAMA_KEEP_ALIVE,
+                // Request-level, never inside `options` — see generateJSON for what that cost us.
+                think: false,
+                options: {
+                    temperature,
+                    num_ctx: CONFIG.NUM_CTX
+                }
+            });
+            for await (const chunk of response) {
+                yield chunk.message.content;
+            }
+        }
+        else {
+            // Fallback: just yield the whole text at once for non-streaming providers
+            const text = await this.generateText(model, messages, temperature);
+            yield text;
+        }
+    }
+    /**
+     * Generates embeddings for the given text using the specified local model.
+     */
+    async embed(model, text) {
+        if (CONFIG.SLM_PROVIDER === 'ollama') {
+            const response = await this.client.embeddings({
+                model,
+                prompt: text,
+                keep_alive: CONFIG.OLLAMA_KEEP_ALIVE,
+            });
+            return response.embedding;
+        }
+        else {
+            // For openai-compatible embeddings endpoint
+            const response = await fetch(`${CONFIG.OLLAMA_HOST}/v1/embeddings`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(CONFIG.CLOUD_API_KEY && { 'Authorization': `Bearer ${CONFIG.CLOUD_API_KEY}` })
+                },
+                body: JSON.stringify({
+                    model,
+                    input: text
+                }),
+                signal: AbortSignal.timeout(CONFIG.SLM_TIMEOUT_MS)
+            });
+            if (!response.ok) {
+                throw new Error(`OpenAI API error (embeddings): ${response.statusText}`);
+            }
+            const data = await response.json();
+            return data.data[0].embedding;
+        }
+    }
+}

package/dist/models/types.js

@@ -0,0 +1 @@
+export {};

package/dist/pricing/index.js

@@ -0,0 +1,115 @@
+/**
+ * USD per 1,000,000 tokens (standard, non-batch, non-cached input).
+ *
+ * Verified against provider documentation on 2026-09-13:
+ *   OpenAI    https://developers.openai.com/api/docs/pricing
+ *   Anthropic https://platform.claude.com/docs/en/about-claude/models/overview
+ *   Google    https://ai.google.dev/gemini-api/docs/pricing
+ *
+ * Re-verify before trusting cost figures: providers change these often, and a stale rate
+ * silently corrupts every "Cost Saved" number on the dashboard.
+ */
+export const PRICING = {
+    // ── OpenAI ──
+    'gpt-6-astra': { in: 10, out: 50 },
+    'gpt-5.6-sol': { in: 4, out: 20 }, // promotional through 2026-11-21
+    'gpt-5.6-terra': { in: 2, out: 12 },
+    'gpt-5.6-luna': { in: 0.20, out: 1.20 },
+    'gpt-5.6-cyber': { in: 12.50, out: 75 },
+    // ── Anthropic ──
+    'claude-fable-5-1': { in: 10, out: 50 },
+    'claude-opus-5': { in: 5, out: 25 },
+    'claude-sonnet-5': { in: 2, out: 10 },
+    'claude-haiku-4-5': { in: 1, out: 5 },
+    // ── Google ──
+    // 3.8/3.7/3.6 Flash share promotional pricing through 2026-12-31,
+    // after which input rises to 1.50 and output to 7.50.
+    'gemini-3.8-flash': { in: 0.75, out: 3.75 },
+    'gemini-3.7-flash': { in: 0.75, out: 3.75 },
+    'gemini-3.6-flash': { in: 0.75, out: 3.75 },
+    'gemini-3.5-flash': { in: 1.50, out: 9.00 },
+    'gemini-3.5-flash-lite': { in: 0.30, out: 2.50 },
+    'gemini-3.1-flash-lite': { in: 0.25, out: 1.50 },
+    // Pro preview is tiered: these are the <=200k-token prompt rates.
+    'gemini-3.1-pro-preview': { in: 2.00, out: 12.00 },
+    // Retired 2026-10-16 (Gemini Developer API). Retained only so historical ledger rows
+    // still price correctly; do not use for new traffic.
+    'gemini-2.5-pro': { in: 1.25, out: 10.00 },
+    'gemini-2.5-flash': { in: 0.30, out: 2.50 },
+    'gemini-2.5-flash-lite': { in: 0.10, out: 0.40 },
+    'gemini-2.5-flash-free': { in: 0, out: 0 },
+    // To add a model, use its exact API id and cite the pricing page above.
+};
+export const LOCAL_RATE = { in: 0, out: 0 };
+export function isLocal(model) {
+    // Keep as ONLY a fallback guess. The real decision is explicit in the ledger caller.
+    if (model.startsWith('local:'))
+        return true;
+    const lower = model.toLowerCase();
+    // 'gemma' deliberately excluded: providerFromModel() classifies it as the Gemini
+    // provider, so treating it as local here made cost and provider attribution disagree.
+    // A genuinely local gemma should be tagged 'local:' by the caller.
+    return ['qwen', 'llama', 'phi', 'mistral', 'deepseek'].some(tag => lower.includes(tag));
+}
+/**
+ * Strips host-specific decorations from a model id so it matches a PRICING key.
+ *
+ * Agents report ids like `claude-opus-5[1m]` (context-window suffix) or
+ * `anthropic/claude-sonnet-5` (vendor-prefixed router style). Without normalisation these
+ * all missed the table and silently fell back to the reference cloud model's rates.
+ *
+ * @param model Raw model id as reported by the host
+ * @returns Normalised id suitable for a PRICING lookup
+ */
+export function normalizeModelId(model) {
+    return model
+        .trim()
+        .replace(/\[[^\]]*\]$/, '') // trailing [1m] context-window marker
+        .replace(/^[^/]+\//, '') // vendor/ prefix
+        .replace(/[:@](latest|preview)$/, '')
+        .trim();
+}
+export function ratesFor(model) {
+    if (model in PRICING) {
+        return PRICING[model];
+    }
+    const normalized = normalizeModelId(model);
+    if (normalized in PRICING) {
+        return PRICING[normalized];
+    }
+    // Longest-prefix match so dated snapshots (claude-opus-5-20260401) resolve to their family.
+    const prefixMatch = Object.keys(PRICING)
+        .filter(key => normalized.startsWith(key))
+        .sort((a, b) => b.length - a.length)[0];
+    if (prefixMatch) {
+        return PRICING[prefixMatch];
+    }
+    const known = Object.keys(PRICING).join(', ');
+    const error = new Error(`Pricing missing for model: ${model}. Known API models are: ${known}`);
+    error.name = 'PricingMissingError';
+    throw error;
+}
+export function calculateCostUsd(model, inTok, outTok) {
+    let rate;
+    if (isLocal(model)) {
+        rate = LOCAL_RATE;
+    }
+    else {
+        rate = ratesFor(model);
+    }
+    return (inTok * rate.in + outTok * rate.out) / 1e6;
+}
+export function safeCalculateCostUsd(model, inTok, outTok, fallbackModel = 'gemini-2.5-flash') {
+    const target = model || fallbackModel;
+    try {
+        return calculateCostUsd(target, inTok, outTok);
+    }
+    catch {
+        try {
+            return calculateCostUsd(fallbackModel, inTok, outTok);
+        }
+        catch {
+            return 0;
+        }
+    }
+}

package/dist/pricing/plans.js

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Plan registry for authoritative window lengths. Window budgets are NOT
+ * derived from plans: providers publish no token counts (see providers.ts).
+ *
+ * IMPORTANT MAINTAINER WARNING:
+ * Providers change these limits often. Re-verify the numbers against the cited sources!
+ *
+ * Sources:
+ *   claude  : https://support.claude.com/en/articles/11049741-what-is-the-max-plan
+ *   chatgpt : https://help.openai.com          (search "ChatGPT usage limits")
+ *   gemini  : https://support.google.com/gemini/answer/16275805
+ */
+// Define raw constants as pinned by research
+const RAW_PLANS = {
+    // CLAUDE — 5h rolling window + weekly cap
+    'claude-pro': { provider: 'claude', windowMinutes: 300 },
+    'claude-max-5x': { provider: 'claude', windowMinutes: 300 },
+    'claude-max-20x': { provider: 'claude', windowMinutes: 300 },
+    // CHATGPT — 3h rolling window
+    'chatgpt-go': { provider: 'chatgpt', windowMinutes: 180 },
+    'chatgpt-plus': { provider: 'chatgpt', windowMinutes: 180 },
+    'chatgpt-pro-5x': { provider: 'chatgpt', windowMinutes: 180 },
+    'chatgpt-pro-20x': { provider: 'chatgpt', windowMinutes: 180 },
+    // GEMINI — 5h compute-based rolling window + weekly
+    'gemini-plus': { provider: 'gemini', windowMinutes: 300 },
+    'gemini-pro': { provider: 'gemini', windowMinutes: 300 },
+    'gemini-ultra': { provider: 'gemini', windowMinutes: 300 },
+};
+const SOURCES = {
+    claude: 'https://support.claude.com/en/articles/11049741-what-is-the-max-plan',
+    chatgpt: 'https://help.openai.com',
+    gemini: 'https://support.google.com/gemini/answer/16275805'
+};
+/**
+ * Returns a fully resolved subscription plan.
+ */
+export function getSubscriptionPlan(planKey) {
+    const raw = RAW_PLANS[planKey];
+    if (!raw) {
+        throw new Error(`Unknown plan key: '${planKey}'. Valid keys: ${Object.keys(RAW_PLANS).join(', ')}`);
+    }
+    return {
+        provider: raw.provider,
+        windowMinutes: raw.windowMinutes,
+        source: SOURCES[raw.provider],
+        verifiedOn: '2026-09-09'
+    };
+}
+export function isValidPlanKey(planKey) {
+    return planKey in RAW_PLANS;
+}
+export function getValidPlanKeys() {
+    return Object.keys(RAW_PLANS);
+}