@zenithfoundry/slm-gate 1.2.1

package/dist/mcp-gate/server.js

@@ -0,0 +1,302 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListToolsResultSchema, CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
+import { CONFIG } from '../config.js';
+import { isLocalRequest, listenOnThisComputer } from '../utils/local-only.js';
+import { conditionPrompt } from './pipeline.js';
+import { buildGateInstructions, rewriteToolReferences } from './tool-names.js';
+/**
+ * @param options.notices Set-up problems from the start-up checks, passed to the AI in the instructions
+ */
+export async function createServer(options = {}) {
+    let rootUri;
+    let downstreamClient;
+    // Tools the connected toolbox serves. Learned at connect time and refreshed on every
+    // tools/list, so any toolbox works without toolbox-specific configuration.
+    let downstreamToolNames = [];
+    // Standalone mode has no toolbox to describe, but still passes on set-up notices.
+    let instructions = buildGateInstructions({ toolNames: [], notices: options.notices });
+    // We intercept initialize via transport.onmessage below to capture rootUri without breaking SDK logic.
+    if (CONFIG.DOWNSTREAM_MCP) {
+        // Proxy mode. Connect to the toolbox BEFORE creating our server: the instructions we
+        // hand the editor are fixed at construction and are built from what the toolbox reports.
+        downstreamClient = new Client({ name: "mcp-gate-proxy", version: "1.0.0" }, { capabilities: {} });
+        let transport;
+        if (CONFIG.DOWNSTREAM_MCP.command) {
+            transport = new StdioClientTransport({
+                command: CONFIG.DOWNSTREAM_MCP.command,
+                args: CONFIG.DOWNSTREAM_MCP.args || [],
+                env: { ...process.env, ...(CONFIG.DOWNSTREAM_MCP.env || {}) }
+            });
+        }
+        else if (CONFIG.DOWNSTREAM_MCP.url) {
+            transport = new StreamableHTTPClientTransport(new URL(CONFIG.DOWNSTREAM_MCP.url));
+        }
+        if (transport) {
+            await downstreamClient.connect(transport);
+            const { tools } = await downstreamClient.request({ method: "tools/list" }, ListToolsResultSchema);
+            downstreamToolNames = (tools || []).map(t => t.name);
+            instructions = buildGateInstructions({
+                toolNames: downstreamToolNames,
+                downstreamInstructions: downstreamClient.getInstructions(),
+                notices: options.notices,
+            });
+        }
+    }
+    const server = new Server({
+        name: "small-language-model-gate",
+        version: "1.0.0",
+    }, {
+        capabilities: {
+            tools: {},
+        },
+        instructions,
+    });
+    if (CONFIG.DOWNSTREAM_MCP) {
+        server.setRequestHandler(ListToolsRequestSchema, async () => {
+            let tools = [];
+            if (downstreamClient) {
+                const res = await downstreamClient.request({ method: "tools/list" }, ListToolsResultSchema);
+                tools = res.tools || [];
+                downstreamToolNames = tools.map(t => t.name);
+            }
+            // Advertise expand_elision
+            tools.push({
+                name: "expand_elision",
+                description: "Expand a previously elided block of text using its elisionId",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        elisionId: { type: "string" },
+                        range: {
+                            type: "object",
+                            properties: {
+                                startLine: { type: "number" },
+                                endLine: { type: "number" }
+                            }
+                        }
+                    },
+                    required: ["elisionId"]
+                }
+            });
+            return { tools };
+        });
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const name = request.params.name;
+            const args = request.params.arguments;
+            const task = typeof args?.task === 'string' ? args.task : 'Unknown task';
+            if (name === "expand_elision") {
+                const elisionId = args?.elisionId;
+                const range = args?.range;
+                if (!elisionId)
+                    throw new Error("elisionId is required");
+                // Dynamic imports to prevent circular dependencies at boot
+                const { getElision, writeElision, writeDistillFeedback, writeEvent } = await import('../ledger/index.js');
+                const { formatElisionMarker, pageLines } = await import('../utils/elision.js');
+                const { embedText, float64ArrayToBuffer } = await import('../utils/embedding.js');
+                const crypto = await import('node:crypto');
+                const record = getElision(elisionId);
+                if (record) {
+                    // Fire-and-forget: Embed the text the user explicitly wanted expanded.
+                    // This populates the Adaptive Feedback DB, teaching the engine to preserve 
+                    // semantically similar lines in future compressions.
+                    embedText(record.original_text).then(emb => {
+                        if (emb) {
+                            writeDistillFeedback({
+                                id: `fd_${Date.now()}_${Math.random().toString(36).substring(2, 7)}`,
+                                tool_name: record.tool_name,
+                                skill: '',
+                                content_hash: record.content_hash,
+                                region_text: record.original_text,
+                                embedding_blob: float64ArrayToBuffer(emb),
+                                signal: 1
+                            });
+                        }
+                    });
+                    // Log the manual expansion for analytics/billing
+                    writeEvent({
+                        ts: new Date().toISOString(),
+                        layer: 'mcp',
+                        request_id: `fb_${crypto.randomUUID()}`,
+                        // Its own route: this is a user feedback signal, not a conditioning event.
+                        // As 'condition' it polluted route counts and collected a free accuracy score.
+                        route: 'feedback',
+                        is_local_call: 0,
+                        api_model: args?.model ? String(args.model) : undefined,
+                        agent: args?.agent ? String(args.agent) : undefined,
+                        api_in_tok: 0,
+                        api_out_tok: 0,
+                        in_tok: 0,
+                        out_tok: 0,
+                        cost_usd: 0,
+                        slm_latency_s: 0,
+                        api_latency_s: 0,
+                        slm_gate: 'on',
+                        meta: JSON.stringify({ type: 'distill_feedback', elision_id: elisionId, action: 'expand' })
+                    });
+                    // If it's a file read, we should theoretically re-read if hash changed, but we can't easily read here without downstreamClient calling the exact same tool.
+                    // Let's check if downstreamClient is available to re-run
+                    let textToReturn = record.original_text;
+                    if (downstreamClient && ['read_file', 'view_file'].some(t => record.tool_name.includes(t))) {
+                        try {
+                            const result = await downstreamClient.request({
+                                method: "tools/call",
+                                params: { name: record.tool_name, arguments: JSON.parse(record.args) }
+                            }, CallToolResultSchema);
+                            let newerText = '';
+                            if (result.content && Array.isArray(result.content)) {
+                                const textBlock = result.content.find((c) => c.type === 'text');
+                                if (textBlock && typeof textBlock.text === 'string') {
+                                    newerText = textBlock.text;
+                                }
+                            }
+                            const newHash = crypto.createHash('sha256').update(newerText).digest('hex');
+                            if (newHash !== record.content_hash) {
+                                textToReturn = newerText;
+                                // Update cache with new text
+                                writeElision({ ...record, original_text: newerText, content_hash: newHash, size_bytes: Buffer.byteLength(newerText) });
+                            }
+                        }
+                        catch (e) {
+                            // ignore
+                        }
+                    }
+                    const lines = textToReturn.split('\n');
+                    const hasRange = range && typeof range.startLine === 'number' && typeof range.endLine === 'number';
+                    // No range means the whole original, from the top.
+                    const startLine = hasRange ? Math.max(0, range.startLine) : 0;
+                    const endLine = hasRange ? Math.min(lines.length - 1, range.endLine) : lines.length - 1;
+                    // The caller asked for these exact lines, so never cut out the middle of them again:
+                    // that made a large region impossible to retrieve. Return them in order, one
+                    // budget-sized page at a time, and say exactly which range to ask for next.
+                    const page = pageLines({ lines, startLine, endLine, maxTokens: CONFIG.DISTILL_MAX_TOKENS || 2000 });
+                    const expandedText = page.nextStart === undefined
+                        ? page.text
+                        : page.text + formatElisionMarker(elisionId, endLine - page.nextStart + 1, page.nextStart, endLine);
+                    return { content: [{ type: "text", text: rewriteToolReferences(expandedText, downstreamToolNames) }] };
+                }
+                else {
+                    // Missing or expired, try to re-run if we have args
+                    if (!downstreamClient)
+                        throw new Error("Elision not found and no downstream client to re-run.");
+                    // We don't have tool_name/args if it's missing from cache and user only provided elisionId.
+                    throw new Error(`Elision ${elisionId} not found in cache. Cannot recover without original tool arguments.`);
+                }
+            }
+            if (!downstreamClient)
+                throw new Error("No downstream client");
+            // Pass request unchanged downstream
+            const result = await downstreamClient.request({
+                method: "tools/call",
+                params: request.params
+            }, CallToolResultSchema);
+            const textBlocks = result.content.filter((block) => block.type === 'text');
+            if (textBlocks.length === 0)
+                return result;
+            const conditioned = await conditionPrompt(textBlocks.map(block => block.text).join('\n\n'), task, rootUri, name, args);
+            // The conditioned text takes the first text block's place; later text blocks are part of it.
+            const content = result.content.flatMap((block) => {
+                if (block === textBlocks[0])
+                    return [{ ...block, text: rewriteToolReferences(conditioned, downstreamToolNames) }];
+                return block.type === 'text' ? [] : [block];
+            });
+            return { ...result, content };
+        });
+    }
+    else {
+        // Standalone mode
+        server.setRequestHandler(ListToolsRequestSchema, async () => {
+            return {
+                tools: [
+                    {
+                        name: "condition_prompt",
+                        description: "Condense and condition a prompt using a local SLM",
+                        inputSchema: {
+                            type: "object",
+                            properties: {
+                                text: { type: "string" },
+                                task: { type: "string" }
+                            },
+                            required: ["text", "task"]
+                        }
+                    }
+                ]
+            };
+        });
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            if (request.params.name === "condition_prompt") {
+                const text = String(request.params.arguments?.text || '');
+                const task = String(request.params.arguments?.task || '');
+                const conditioned = await conditionPrompt(text, task, rootUri);
+                return {
+                    content: [{ type: "text", text: conditioned }]
+                };
+            }
+            throw new Error(`Tool not found: ${request.params.name}`);
+        });
+    }
+    /** Resolves once serving; in HTTP mode with the listening servers (tests close them), else with none. */
+    const start = async () => {
+        const sinks = ['sqlite'];
+        if (CONFIG.LANGFUSE_PUBLIC_KEY && CONFIG.LANGFUSE_SECRET_KEY && CONFIG.LANGFUSE_HOST) {
+            sinks.push('langfuse');
+        }
+        const sinksStr = `sinks: [${sinks.join(', ')}]`;
+        if (CONFIG.MCP_GATE_TRANSPORT === 'stdio') {
+            const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+            process.stdout.write = process.stderr.write.bind(process.stderr);
+            console.error(`[mcp-gate] Stdio server starting. ${sinksStr}`);
+            const transport = new StdioServerTransport();
+            const origStart = transport.start.bind(transport);
+            transport.start = async () => {
+                const origOnmessage = transport.onmessage;
+                if (origOnmessage) {
+                    transport.onmessage = (message) => {
+                        if (message?.method === 'initialize') {
+                            const rootsCap = message.params?.capabilities?.roots;
+                            // Check if roots is passed directly in capabilities (older clients)
+                            if (Array.isArray(rootsCap) && rootsCap.length > 0 && rootsCap[0]?.uri) {
+                                rootUri = rootsCap[0].uri;
+                            }
+                            else if (message.params?.rootUri) {
+                                // Fallback for non-compliant clients passing top-level rootUri
+                                rootUri = message.params.rootUri;
+                            }
+                            console.error(`[mcp-gate] rootUri: ${rootUri || 'none'}`);
+                        }
+                        origOnmessage(message);
+                    };
+                }
+                await origStart();
+            };
+            await server.connect(transport);
+            process.stdout.write = originalStdoutWrite;
+            return [];
+        }
+        else {
+            const { randomUUID } = await import('node:crypto');
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID()
+            });
+            await server.connect(transport);
+            // This server's tools can read and patch files: only programs on this computer may call them.
+            return listenOnThisComputer({
+                handler: (req, res) => {
+                    if (!isLocalRequest(req.headers)) {
+                        res.writeHead(403, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32000, message: 'slm-gate only accepts requests from programs on this computer' }, id: null }));
+                        return;
+                    }
+                    transport.handleRequest(req, res);
+                },
+                port: CONFIG.MCP_GATE_PORT,
+                onListening: () => console.error(`[mcp-gate] HTTP Streamable server running on port ${CONFIG.MCP_GATE_PORT}, for programs on this computer only. ${sinksStr}`),
+            });
+        }
+    };
+    return { server, start };
+}

package/dist/mcp-gate/tool-names.js

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Makes any downstream toolbox's tool names resolve to slm-gate.
+ *
+ * A toolbox usually refers to its own tools by the name its installer registered them under.
+ * Tech-Lead-Stack's slash commands, for example, say `mcp__tech-lead-stack__get_skills`.
+ * Behind slm-gate those tools are served by the gate, so that name does not exist in the
+ * editor. The gate learns the toolbox's tool list when it connects and uses it to
+ * (1) tell the editor which tools it serves, and (2) rewrite prefixed references to those
+ * tools in results. Nothing here is specific to any one toolbox.
+ */
+/** The name slm-gate is registered under in the editor (see docs/setup.md → Step 4). */
+export const GATE_MCP_NAME = 'slm-gate';
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Rewrites `mcp__<any server>__<tool>` (and the single-underscore `mcp_<server>_<tool>` form)
+ * to `mcp__slm-gate__<tool>`, but only for tools the connected toolbox actually serves.
+ *
+ * @param text Text returned to the editor
+ * @param toolNames Tool names served by the connected toolbox
+ * @returns The text with those tool references pointing at slm-gate
+ */
+export function rewriteToolReferences(text, toolNames) {
+    if (!text || toolNames.length === 0)
+        return text;
+    // Longest first, so `get_skill` can never match inside `get_skills`.
+    const tools = [...toolNames].sort((a, b) => b.length - a.length).map(escapeRegExp).join('|');
+    // Server names are matched without underscores, so the tool name must start right after
+    // the separator: `mcp__foo__bar_get_skill` is NOT read as tool `get_skill`.
+    const pattern = new RegExp(`\\bmcp__?[A-Za-z0-9][A-Za-z0-9-]*__?(${tools})\\b`, 'g');
+    return text.replace(pattern, (_match, tool) => `mcp__${GATE_MCP_NAME}__${tool}`);
+}
+/**
+ * Builds the instructions the gate hands the editor when it connects.
+ *
+ * @param params.toolNames Tool names served by the connected toolbox
+ * @param params.downstreamInstructions The toolbox's own instructions, passed through
+ * @param params.notices Set-up problems found at start-up (src/setup/startup.ts), passed on to the user
+ * @returns Instructions text, or undefined when there is nothing to say
+ */
+export function buildGateInstructions(params) {
+    const { toolNames, downstreamInstructions, notices = [] } = params;
+    const parts = [];
+    if (notices.length > 0) {
+        // These instructions are fixed when the server starts and cannot be changed afterwards, so they are
+        // written as what was true at start-up rather than as a live fact, and the AI is told it may be out
+        // of date. Without that, one bad check at start-up has the AI repeating it for the whole session.
+        parts.push(`${GATE_MCP_NAME} notice — what slm-gate found when it started. Tell the user about this at the start of your next reply, word for word:`, ...notices.map(notice => `- ${notice.message} Fix: ${notice.fix}`), 'This was checked once, when slm-gate started, and is not rechecked in these instructions. If the user shows you it is already working, they are right and this notice is stale.', '');
+    }
+    if (toolNames.length > 0) {
+        parts.push(`This server (${GATE_MCP_NAME}) serves the tools of the toolbox connected behind it: ${toolNames.join(', ')}.`, `Commands, skills or docs may refer to these tools under another server name, for example \`mcp__<toolbox>__${toolNames[0]}\`. ` +
+            `They mean the tool of the same name on this server: call \`mcp__${GATE_MCP_NAME}__<tool>\` instead.`);
+    }
+    if (downstreamInstructions?.trim()) {
+        parts.push('', 'Instructions from the connected toolbox:', downstreamInstructions.trim());
+    }
+    return parts.length > 0 ? parts.join('\n') : undefined;
+}

package/dist/models/check.js

@@ -0,0 +1,26 @@
+import { footprintReport, warmup } from './footprint.js';
+import { handleSlmError } from './helpers.js';
+import { isEntryPoint } from '../utils/entry-point.js';
+async function check() {
+    try {
+        await warmup();
+        await footprintReport();
+    }
+    catch (err) {
+        if (err.name === 'SlmTimeoutError' || err.message?.includes('fetch failed') || err.code === 'ECONNREFUSED' || err.message?.includes('ECONNREFUSED')) {
+            handleSlmError(err, 'models:check', 'unknown (check config)');
+        }
+        else {
+            if (err instanceof Error) {
+                console.error(`Error: ${err.message}`);
+            }
+            else {
+                console.error(`Error: ${String(err)}`);
+            }
+        }
+        process.exit(1);
+    }
+}
+if (isEntryPoint(import.meta.url)) {
+    check();
+}

package/dist/models/footprint.js

@@ -0,0 +1,137 @@
+import ollama from 'ollama';
+import { CONFIG } from '../config.js';
+import { detectHardware, MIN_RAM_GB, modelsForRam, recommendPreset } from '../hardware.js';
+/**
+ * Warms up the provided SLM models by sending a single, short prompt.
+ * This forces the Ollama backend to load the model into memory, reducing latency on subsequent requests.
+ *
+ * @param client - The Ollama client instance (defaults to the global imported ollama instance).
+ * @returns A promise that resolves when the warmup chats are dispatched (or fail gracefully).
+ *
+ * @example
+ * // Warms up models configured in SLM_BRAIN_MODEL and SLM_GATE_MODEL
+ * await warmup();
+ */
+export async function warmup(client = ollama) {
+    const modelsToWarm = new Set([CONFIG.SLM_BRAIN_MODEL, CONFIG.SLM_GATE_MODEL]);
+    try {
+        const listResponse = await client.list();
+        const availableModels = listResponse.models || [];
+        for (const model of modelsToWarm) {
+            if (!availableModels.some(m => m.name === model || m.model === model)) {
+                console.warn(`not pulled — run ollama pull ${model}`);
+            }
+            else {
+                try {
+                    await client.chat({
+                        model: model,
+                        messages: [{ role: 'user', content: 'hi' }],
+                        options: { num_predict: 1 }
+                    });
+                }
+                catch (e) {
+                    // Ignore error during warmup chat
+                }
+            }
+        }
+    }
+    catch (err) {
+        console.error('Failed to connect to Ollama for warmup:', err);
+    }
+}
+/**
+ * Fetches the footprint (size in bytes) of specific models from the Ollama backend.
+ *
+ * @param models - An array of model strings to check (e.g., ['qwen3:14b', 'qwen3:1.7b']).
+ * @param client - The Ollama client instance (defaults to the global imported ollama instance).
+ * @returns A promise that resolves to an object mapping each model name to its size in bytes.
+ *
+ * @example
+ * const sizes = await getModelsFootprint(['qwen3:14b']);
+ * console.log(`Size: ${sizes['qwen3:14b']} bytes`);
+ */
+export async function getModelsFootprint(models, client = ollama) {
+    const result = {};
+    try {
+        const listResponse = await client.list();
+        const availableModels = listResponse.models || [];
+        for (const model of models) {
+            const found = availableModels.find(m => m.name === model || m.model === model);
+            if (found && found.size) {
+                result[model] = found.size;
+            }
+        }
+    }
+    catch (err) {
+        // Ignore error
+    }
+    return result;
+}
+/**
+ * Generates and prints a detailed footprint report of the configured SLM models.
+ * Used primarily for diagnostic purposes to ensure the user's models fit within their RAM budget.
+ *
+ * @param client - The Ollama client instance.
+ * @throws {Error} If the Ollama backend is completely unreachable.
+ *
+ * @example
+ * await footprintReport();
+ * // Outputs:
+ * // === SLM Footprint Report ===
+ * // - qwen3:14b: 8.50 GB
+ * // - qwen3:1.7b: 1.10 GB
+ * // Total footprint: 9.60 GB
+ * // Current RAM preset: custom
+ * //
+ * // --- Recommendations (24GB RAM Detected) ---
+ * // * Dedicated AI Node:   ram-24 (Max capacity)
+ * // * Primary Workhorse:   ram-16 (Leaves headroom for apps)
+ * // -----------------------------------------------
+ */
+export async function footprintReport(client = ollama) {
+    console.log(`\n=== SLM Footprint Report ===`);
+    const modelsToCheck = new Set([CONFIG.SLM_BRAIN_MODEL, CONFIG.SLM_GATE_MODEL]);
+    let totalBytes = 0;
+    try {
+        const listResponse = await client.list();
+        const availableModels = listResponse.models || [];
+        for (const model of modelsToCheck) {
+            const found = availableModels.find(m => m.name === model || m.model === model);
+            if (found && found.size) {
+                const sizeGB = (found.size / (1024 * 1024 * 1024)).toFixed(2);
+                console.log(`- ${model}: ${sizeGB} GB`);
+                totalBytes += found.size;
+            }
+            else {
+                console.log(`- ${model}: not pulled — run ollama pull ${model}`);
+            }
+        }
+        const totalGB = (totalBytes / (1024 * 1024 * 1024)).toFixed(2);
+        console.log(`Total footprint: ${totalGB} GB`);
+        console.log(`Current RAM preset: ${CONFIG.RAM_PRESET}`);
+        try {
+            const hw = detectHardware();
+            const workhorseRamGB = Math.max(MIN_RAM_GB, hw.totalRamGB - 8);
+            const dedicatedPreset = recommendPreset(hw.totalRamGB);
+            const workhorsePreset = recommendPreset(workhorseRamGB);
+            const dedicatedModels = modelsForRam(hw.totalRamGB);
+            const workhorseModels = modelsForRam(workhorseRamGB);
+            console.log(`\n--- Recommendations (${hw.totalRamGB}GB RAM Detected) ---\n`);
+            console.log(`OPTION A: Dedicated AI Node (Preset: ${dedicatedPreset})`);
+            console.log(`- Recommended Models: ${dedicatedModels.brain} (Brain) + ${dedicatedModels.gate} (Gate)`);
+            console.log(`- Target Workload: Machines where SLM-Gate is the primary running application.`);
+            console.log(`- Note: This maximizes AI capabilities but leaves minimal RAM for other heavy applications.\n`);
+            console.log(`OPTION B: Primary Workhorse (Preset: ${workhorsePreset})`);
+            console.log(`- Recommended Models: ${workhorseModels.brain} (Brain) + ${workhorseModels.gate} (Gate)`);
+            console.log(`- Target Workload: Daily driver machines running browsers, IDEs, or databases simultaneously.`);
+            console.log(`- Note: If you choose to run Option A's larger models on a workhorse machine, you MUST actively free up system RAM before starting. Otherwise, the OS will swap heavily, causing severe UI lag and slow token generation.`);
+            console.log(`-----------------------------------------------`);
+        }
+        catch {
+            // In case hardware detection fails gracefully
+        }
+    }
+    catch (err) {
+        throw new Error('Could not fetch model sizes. Is Ollama running?');
+    }
+}

package/dist/models/helpers.js

@@ -0,0 +1,91 @@
+/**
+ * Represents an error that occurs when the SLM returns a response that cannot be parsed
+ * or formatted correctly (e.g. invalid JSON when JSON is expected).
+ *
+ * @example
+ * ```typescript
+ * throw new SlmFormatError("Invalid JSON returned by the model");
+ * ```
+ */
+export class SlmFormatError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SlmFormatError';
+    }
+}
+/**
+ * Represents an error that occurs when a call to the SLM exceeds the configured timeout duration.
+ *
+ * @example
+ * ```typescript
+ * throw new SlmTimeoutError("classification");
+ * ```
+ */
+export class SlmTimeoutError extends Error {
+    constructor(stage) {
+        super(`SLM call timed out during stage: ${stage}`);
+        this.name = 'SlmTimeoutError';
+    }
+}
+/**
+ * Wraps a promise (usually an SLM generation call) with a timeout. If the promise does not
+ * resolve within `timeoutMs`, an `SlmTimeoutError` is thrown.
+ *
+ * @param promise - The asynchronous operation to wrap.
+ * @param stage - The name of the pipeline stage (e.g. 'distill', 'classify') used in the error message.
+ * @param timeoutMs - The maximum allowed time in milliseconds.
+ * @returns A promise that resolves with the original result if completed in time.
+ *
+ * @example
+ * ```typescript
+ * const result = await withSlmTimeout(slm.generateText(model, prompt), 'generate', 15000);
+ * ```
+ */
+export async function withSlmTimeout(promise, stage, timeoutMs) {
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new SlmTimeoutError(stage)), timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * A centralized error handler for formatting and logging SLM failures.
+ * Handles timeouts and network connection issues by printing actionable remediation
+ * steps to the console, while falling back to standard error logging for other issues.
+ *
+ * @param err - The caught error object.
+ * @param stage - The stage of the pipeline where the error occurred.
+ * @param model - The name of the model being used.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await slm.generateText(model, prompt);
+ * } catch (err) {
+ *   handleSlmError(err, 'pipeline:distill', model);
+ * }
+ * ```
+ */
+export function handleSlmError(err, stage, model) {
+    const isTimeout = err instanceof SlmTimeoutError || err.name === 'SlmTimeoutError';
+    const isNetwork = err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED') || err.code === 'ECONNREFUSED';
+    if (isTimeout || isNetwork) {
+        const errorType = isTimeout ? 'Timeout' : 'Unreachable';
+        console.error(`\n[${stage}] ❌ SLM Error (${errorType}) - Model: ${model}`);
+        console.error(`  Usually the model is too large for available RAM or is cold-loading.`);
+        console.error(`  Fixes:`);
+        console.error(`  1. Switch to a smaller model (check SLM_BRAIN_MODEL/SLM_GATE_MODEL against the RAM table in docs/prerequisites-and-hardware.md).`);
+        console.error(`  2. Raise SLM_TIMEOUT_MS in your .env if it is just cold-loading.`);
+        console.error(`  3. Confirm the model is pulled ('ollama pull ${model}') and Ollama is running ('ollama list').`);
+        console.error(`  4. Free up system RAM.\n`);
+    }
+    else {
+        console.error(`\n[${stage}] ❌ SLM Error - Model: ${model}`);
+        console.error(`  ${err.message || String(err)}\n`);
+    }
+}

package/dist/models/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './roles.js';
+export * from './slm.js';
+export * from './footprint.js';
+export * from './reasoning.js';