@zenithfoundry/slm-gate 1.2.1

package/dist/llm-gate/server.js

@@ -0,0 +1,289 @@
+import fs from 'node:fs';
+import http from 'node:http';
+import { fileURLToPath } from 'node:url';
+import { CONFIG } from '../config.js';
+import { writeEvent } from '../ledger/index.js';
+import { estimateTokens } from '../utils/elision.js';
+import { distilRequest } from './distill.js';
+import * as anthropic from './formats/anthropic.js';
+import * as chatCompletions from './formats/chat-completions.js';
+import * as gemini from './formats/gemini.js';
+import * as responses from './formats/responses.js';
+import { forwardRequest, resolveUpstream, SUPPORTED_PATHS } from './forward.js';
+import { answerFirstRequestLocally } from './local-first.js';
+import { HEALTH_PATH } from '../setup/model-gate.js';
+import { requiredModels } from '../setup/local-models.js';
+import { isLocalRequest } from '../utils/local-only.js';
+const FORMATS = {
+    anthropic,
+    'chat-completions': chatCompletions,
+    responses,
+    gemini,
+};
+// The answer to "is the model gate running, and which one?" (HEALTH_PATH) — answered here, never
+// forwarded. Read once at start and frozen: when this file on disk later has another modification time,
+// the running gate is older than the installed build (see src/setup/model-gate.ts).
+const SERVER_FILE = fileURLToPath(import.meta.url);
+const HEALTH = {
+    service: 'slm-gate',
+    pid: process.pid,
+    entry: SERVER_FILE,
+    build: String(Math.round(fs.statSync(SERVER_FILE).mtimeMs)),
+    startedAt: new Date().toISOString(),
+    // So the MCP servers also check the models the gate's own settings (slm-gate's .env) name.
+    models: requiredModels(),
+};
+function generateId() {
+    return 'req_' + Math.random().toString(36).substring(2, 15);
+}
+/** The model a request is for: Gemini names it in the path, the other formats in the body. */
+function requestModel(route, body) {
+    if (route.pathModel)
+        return route.pathModel;
+    try {
+        const model = JSON.parse(body.toString('utf8'))?.model;
+        return typeof model === 'string' ? model : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseJsonObject(body) {
+    try {
+        const parsed = JSON.parse(body.toString('utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Step A: a first request the local model answers itself, in the request's own format. Anything else —
+ * a later request, structured output, a busy or slow local model, a declined or rejected answer —
+ * returns no reply and the request goes on unchanged.
+ */
+async function localFirst(params) {
+    const { route, parsed, body } = params;
+    const format = FORMATS[route.format];
+    const prompt = format.firstRequestPrompt(parsed);
+    // Gemini's JSON-array streaming (no `alt=sse`) is left to the provider.
+    if (!prompt || route.geminiStream === 'json-array')
+        return null;
+    const stream = route.format === 'gemini' ? route.geminiStream === 'sse' : parsed.stream === true;
+    const started = Date.now();
+    let local;
+    try {
+        local = await answerFirstRequestLocally({ task: prompt.text, toolsListed: prompt.toolsListed });
+    }
+    catch (err) {
+        // Step A can only make a request cheaper; if it fails in any way the request goes on as normal.
+        console.error(`LLM Gate: local answer skipped: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    const { attempt, outcome } = local;
+    const step = {
+        reply: null,
+        latencyMs: Date.now() - started,
+        verifierFlags: attempt?.verifierFlags ?? [],
+        meta: {
+            local_outcome: outcome,
+            category: attempt?.category ?? null,
+            local_attempted: attempt?.attempted ? 1 : 0,
+            local_accepted: attempt?.accepted ? 1 : 0,
+            from_cache: attempt?.fromCache ? 1 : 0,
+            prompt_chars: prompt.text.length,
+            prompt_tok_est: estimateTokens(prompt.text),
+            has_code_fence: /```/.test(prompt.text) ? 1 : 0,
+        },
+    };
+    if (!attempt || attempt.answer === null)
+        return step;
+    const answer = attempt.answer;
+    const reply = format.buildLocalReply({
+        text: answer,
+        stream,
+        model: attempt.model,
+        usage: { inputTokens: estimateTokens(body.toString('utf8')), outputTokens: estimateTokens(answer) },
+    });
+    return { ...step, reply: { ...reply, answer, model: attempt.model } };
+}
+/**
+ * Step B: the bytes to forward. The original bytes go out whenever nothing changed, the body is not
+ * JSON, or distillation fails in any way — it can make a request smaller, never break it.
+ */
+async function distilBody(params) {
+    const { route, parsed, body } = params;
+    if (!parsed)
+        return { sent: body, distill: null };
+    try {
+        const result = await distilRequest({ format: FORMATS[route.format], body: parsed });
+        return { sent: result.body ? Buffer.from(JSON.stringify(result.body)) : body, distill: result.stats };
+    }
+    catch (err) {
+        console.error(`LLM Gate: distillation skipped for this request: ${err instanceof Error ? err.message : String(err)}`);
+        return { sent: body, distill: null };
+    }
+}
+/**
+ * Writes the ledger row for a forwarded generation request or a rejected path. Hello pings, model
+ * lists and token counts get no row, so they never count as model work in the metrics.
+ */
+function recordRequest(params) {
+    recordSafely({ reqId: params.reqId, path: params.path, write: () => writeLedgerRow(params) });
+}
+function recordSafely(params) {
+    try {
+        params.write();
+    }
+    catch (err) {
+        // Telemetry must never hold up model traffic: the row is lost, the request is not.
+        console.error(`LLM Gate: ledger row for ${params.reqId} (${params.path}) not written: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** The ledger row of a first request the local model answered: the whole cloud request was avoided. */
+function recordLocalAnswer(params) {
+    const { reqId, path, body, route, local } = params;
+    recordSafely({
+        reqId,
+        path,
+        write: () => writeEvent({
+            ts: new Date().toISOString(),
+            layer: 'llm',
+            request_id: reqId,
+            route: 'defer_local',
+            is_local_call: 1,
+            slm_model: local.reply.model,
+            // The provider whose request was avoided, for per-provider savings.
+            api_model: requestModel(route, body),
+            in_tok: estimateTokens(body.toString('utf8')),
+            out_tok: estimateTokens(local.reply.answer),
+            api_in_tok: 0,
+            api_out_tok: 0,
+            cost_usd: 0,
+            slm_latency_s: local.latencyMs / 1000,
+            api_latency_s: 0,
+            verifier_flags: JSON.stringify(local.verifierFlags),
+            slm_gate: 'on',
+            meta: JSON.stringify({ format: route.format, path, status: 200, ...local.meta }),
+        }),
+    });
+}
+function writeLedgerRow(params) {
+    const { reqId, path, body, route, outcome, distill = null, local = null } = params;
+    const sent = params.sent ?? body;
+    const distilled = sent !== body;
+    writeEvent({
+        ts: new Date().toISOString(),
+        layer: 'llm',
+        request_id: reqId,
+        route: distilled ? 'forward_compressed' : 'forward_raw',
+        is_local_call: 0,
+        api_model: route ? requestModel(route, body) : undefined,
+        in_tok: 0,
+        out_tok: 0,
+        // Estimated from the bodies until provider usage is read from responses.
+        api_in_tok: route ? estimateTokens(sent.toString('utf8')) : 0,
+        api_out_tok: 0,
+        cost_usd: 0,
+        slm_latency_s: (local?.latencyMs ?? 0) / 1000,
+        api_latency_s: (outcome.durationMs ?? 0) / 1000,
+        ...(local ? { verifier_flags: JSON.stringify(local.verifierFlags) } : {}),
+        slm_gate: 'on',
+        meta: JSON.stringify({
+            // A Step A attempt that did not answer: ROUTING_TUNE learns from local_attempted/local_accepted.
+            ...(local?.meta ?? {}),
+            format: route?.format ?? null,
+            path,
+            status: outcome.status,
+            bytes_in: body.length,
+            bytes_sent: sent.length,
+            bytes_out: outcome.bytesOut ?? 0,
+            client_aborted: outcome.clientAborted ? 1 : 0,
+            upstream_error: outcome.error ?? null,
+            tokens_estimated: 1,
+            // The metrics read raw_in_tok as "input before distillation" on forward_compressed rows.
+            ...(distilled ? { raw_in_tok: estimateTokens(body.toString('utf8')) } : {}),
+            distill,
+        }),
+    });
+}
+async function handleRequest(params) {
+    const { req, res, reqId, body } = params;
+    const path = new URL(req.url || '/', 'http://gate.local').pathname;
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('x-correlation-id', reqId);
+    if (req.method === 'GET' && path === HEALTH_PATH) {
+        const address = req.socket.localPort;
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ...HEALTH, port: address }));
+        return;
+    }
+    const route = resolveUpstream({ pathAndQuery: req.url || '/', headers: req.headers });
+    if (!route) {
+        res.writeHead(404, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({
+            error: { type: 'slm_gate_unsupported_path', message: `slm-gate does not handle ${req.method} ${path}`, supported: SUPPORTED_PATHS },
+        }));
+        console.info(`LLM Gate: ${req.method} ${path} -> 404 (unsupported path)`);
+        recordRequest({ reqId, path, body, route, outcome: { status: 404 } });
+        return;
+    }
+    const parsed = route.generation ? parseJsonObject(body) : null;
+    const local = parsed && CONFIG.LLM_GATE_LOCAL_FIRST ? await localFirst({ route, parsed, body }) : null;
+    if (local?.reply) {
+        res.writeHead(200, { 'content-type': local.reply.contentType, 'x-slm-gate-route': 'defer_local' });
+        res.end(local.reply.body);
+        console.info(`LLM Gate: ${req.method} ${path} -> answered locally by ${local.reply.model} in ${local.latencyMs}ms`);
+        recordLocalAnswer({ reqId, path, body, route, local });
+        return;
+    }
+    const { sent, distill } = CONFIG.LLM_GATE_DISTILL
+        ? await distilBody({ route, parsed, body })
+        : { sent: body, distill: null };
+    const outcome = await forwardRequest({ req, res, body: sent, route });
+    const saved = sent === body ? '' : `, distilled ${body.length} -> ${sent.length} bytes`;
+    console.info(`LLM Gate: ${req.method} ${path} -> ${route.format} ${outcome.status} in ${outcome.durationMs}ms${saved}${outcome.clientAborted ? ' (client aborted)' : ''}`);
+    if (route.generation)
+        recordRequest({ reqId, path, body, route, outcome, sent, distill, local });
+}
+/**
+ * Handles every request to the `llm-gate`.
+ *
+ * Only programs on this computer are served (src/utils/local-only.ts); anything else gets a 403 and is
+ * neither forwarded nor recorded. Every supported request is forwarded, unchanged and with the tool's own
+ * login, to the provider its wire format belongs to (see forward.ts), and the response is streamed back
+ * unchanged. Answers CORS preflights itself so web pages served from this computer can reach it.
+ */
+export function requestListener(req, res) {
+    if (!isLocalRequest(req.headers)) {
+        res.writeHead(403, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: { type: 'slm_gate_error', message: 'slm-gate only accepts requests from programs on this computer' } }));
+        return;
+    }
+    const reqId = generateId();
+    if (req.method === 'OPTIONS') {
+        res.writeHead(204, {
+            'Access-Control-Allow-Origin': '*',
+            'Access-Control-Allow-Methods': 'GET, HEAD, POST, OPTIONS',
+            'Access-Control-Allow-Headers': '*'
+        });
+        res.end();
+        return;
+    }
+    const chunks = [];
+    req.on('data', (chunk) => chunks.push(chunk));
+    req.on('end', () => {
+        handleRequest({ req, res, reqId, body: Buffer.concat(chunks) }).catch(err => {
+            // Only a ledger or programming error reaches here; the response may already be complete.
+            console.error('LLM Gate Error:', err);
+            if (!res.headersSent) {
+                res.writeHead(500, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ error: { type: 'slm_gate_error', message: err instanceof Error ? err.message : String(err) } }));
+            }
+        });
+    });
+    // The client dropped while still sending: nothing was forwarded, so there is nothing to record.
+    req.on('error', () => res.destroy());
+}
+/** A server for tests; the gate itself listens through listenOnThisComputer (index.ts). */
+export const server = http.createServer(requestListener);

package/dist/mcp-gate/ground.js

@@ -0,0 +1,64 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+export async function scan(rootUri) {
+    let rootPath = rootUri;
+    if (rootUri.startsWith('file://')) {
+        try {
+            rootPath = fileURLToPath(rootUri);
+        }
+        catch {
+            rootPath = rootUri.substring(7);
+        }
+    }
+    const detected = [];
+    const fileExists = async (filename) => {
+        try {
+            const stats = await fs.stat(path.join(rootPath, filename));
+            return stats.isFile();
+        }
+        catch {
+            return false;
+        }
+    };
+    if (await fileExists('package.json')) {
+        detected.push('Node.js / npm project');
+        try {
+            const pkg = JSON.parse(await fs.readFile(path.join(rootPath, 'package.json'), 'utf-8'));
+            const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+            if (allDeps['react'])
+                detected.push('React');
+            if (allDeps['next'])
+                detected.push('Next.js');
+            if (allDeps['vue'])
+                detected.push('Vue');
+            if (allDeps['svelte'])
+                detected.push('Svelte');
+            if (allDeps['jest'])
+                detected.push('Jest');
+            if (allDeps['vitest'])
+                detected.push('Vitest');
+        }
+        catch (e) {
+            // ignore parse errors
+        }
+    }
+    if (await fileExists('tsconfig.json'))
+        detected.push('TypeScript');
+    if (await fileExists('yarn.lock'))
+        detected.push('Yarn package manager');
+    if (await fileExists('pnpm-lock.yaml'))
+        detected.push('pnpm package manager');
+    if (await fileExists('package-lock.json'))
+        detected.push('npm package manager');
+    if (await fileExists('Cargo.toml'))
+        detected.push('Rust (Cargo)');
+    if (await fileExists('go.mod'))
+        detected.push('Go modules');
+    if (detected.length === 0) {
+        return 'No specific framework or environment detected from root files.';
+    }
+    // Single `\n`: `\\n` emitted the two characters backslash-n, so the whole environment
+    // context reached the cloud model as one run-on line.
+    return 'Detected environment context:\n- ' + detected.join('\n- ');
+}

package/dist/mcp-gate/index.js

@@ -0,0 +1,57 @@
+import { CONFIG } from '../config.js';
+import { createServer } from './server.js';
+import { installLangfuseFlushLifecycle } from '../ledger/flush-lifecycle.js';
+import { logLedgerInfo } from '../ledger/index.js';
+import { exitWithParent } from '../setup/parent-watch.js';
+import { runStartupChecks, watchModelGate } from '../setup/startup.js';
+/**
+ * Leave nothing running that no coding tool owns. Registered before any work that could hang, so a
+ * toolbox that never finishes connecting cannot strand a server either.
+ */
+function shutDownWhenNobodyOwnsUs() {
+    const quit = () => process.kill(process.pid, 'SIGTERM');
+    if (CONFIG.MCP_GATE_TRANSPORT === 'stdio') {
+        // Our input closing means the coding tool is gone (closed or crashed). Whichever of these arrives
+        // first wins; SIGTERM is idempotent here, and stdin is deliberately not resumed, because reading
+        // it ourselves would swallow the handshake the transport is about to read.
+        process.stdin.once('end', quit);
+        process.stdin.once('close', quit);
+        process.stdin.on('error', quit);
+    }
+    // The backstop: this arrives even when start-up hangs before anything reads stdin, and it is the
+    // only signal at all when the transport is HTTP.
+    exitWithParent();
+}
+async function main() {
+    if (CONFIG.MCP_GATE_TRANSPORT === 'stdio') {
+        console.log = console.error;
+    }
+    shutDownWhenNobodyOwnsUs();
+    console.error(`[mcp-gate] Starting up...`);
+    console.error(`[mcp-gate] Mode: ${CONFIG.DOWNSTREAM_MCP ? 'Proxy' : 'Standalone'}`);
+    console.error(`[mcp-gate] Transport: ${CONFIG.MCP_GATE_TRANSPORT}`);
+    console.error(`[mcp-gate] Models -> Brain: ${CONFIG.SLM_BRAIN_MODEL} | Gate: ${CONFIG.SLM_GATE_MODEL}`);
+    logLedgerInfo('mcp-gate');
+    installLangfuseFlushLifecycle('mcp-gate');
+    // A coding tool starting this server is the sign that work is about to start: check Ollama and the
+    // configured models and make sure the model gate runs (launched in the background if it does not).
+    // At most ~1.5 s; problems reach the AI through the instructions and you through a notification.
+    let notices = [];
+    try {
+        notices = await runStartupChecks();
+    }
+    catch (err) {
+        console.error(`[mcp-gate] Start-up checks failed (continuing):`, err);
+    }
+    try {
+        const { start } = await createServer({ notices });
+        await start();
+        console.error(`[mcp-gate] Server is running and listening for messages.`);
+        watchModelGate();
+    }
+    catch (err) {
+        console.error(`[mcp-gate] Fatal error during startup:`, err);
+        process.exit(1);
+    }
+}
+main();

package/dist/mcp-gate/pipeline.js

@@ -0,0 +1,252 @@
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { checkSemanticCache, setSemanticCache } from '../cache/index.js';
+import { CONFIG } from '../config.js';
+import { cacheGet, cacheSet, writeEvent } from '../ledger/index.js';
+import { handleSlmError } from '../models/helpers.js';
+import { compressNarrativeRun } from '../models/reasoning.js';
+import { SLM } from '../models/slm.js';
+import { resolveAmbiguities } from '../resolver/index.js';
+import { distillToolResult } from '../utils/elision.js';
+import { scan } from './ground.js';
+import { buildPreserveList } from '../utils/preserve-patterns.js';
+let slmClient;
+/**
+ * Creates and initializes a new instance of the Small Language Model (SLM) client.
+ * @returns {SLM} A new SLM client instance.
+ */
+function createSlmClient() {
+    return new SLM();
+}
+let cachedPreserveList = null;
+/**
+ * Retrieves the compiled list of regular expressions used to identify text blocks
+ * that must be preserved verbatim during the distillation process. Results are cached.
+ * @returns {Promise<RegExp[]>} A promise resolving to an array of preservation regular expressions.
+ */
+async function getPreserveList() {
+    if (!cachedPreserveList) {
+        cachedPreserveList = await buildPreserveList();
+    }
+    return cachedPreserveList;
+}
+const SLM_ERROR_NOTES = {
+    timeout: 'The local model exceeded SLM_TIMEOUT_MS. Raise the budget or use a smaller model.',
+    format: 'The local model returned output that could not be parsed. Try a larger or more instruction-following model.',
+    transport: 'The local model could not be reached. Check that Ollama is running at OLLAMA_HOST.',
+    unknown: 'The local model failed for an unrecognised reason. See stderr for details.',
+};
+/**
+ * Classifies an SLM failure so the cause is actionable.
+ *
+ * @param err The thrown error
+ * @returns The error class, never null (callers use null to mean "no error").
+ */
+function classifySlmError(err) {
+    const name = err?.name ?? '';
+    const message = (err?.message ?? '').toLowerCase();
+    if (name === 'SlmTimeoutError' || message.includes('timed out') || message.includes('timeout'))
+        return 'timeout';
+    if (name === 'SlmFormatError' || message.includes('json') || message.includes('parse'))
+        return 'format';
+    if (message.includes('fetch failed') || message.includes('econnrefused') || message.includes('econnreset'))
+        return 'transport';
+    return 'unknown';
+}
+/**
+ * Writes a single `condition` ledger event.
+ *
+ * Centralised so the cache-hit path, the semantic-cache path and the full pipeline all
+ * report identically — previously only the slow path emitted anything at all.
+ *
+ * @param params.text Raw inbound tool output
+ * @param params.conditioned Text actually returned to the host
+ * @param params.args Tool arguments, carrying host-supplied model/agent/session hints
+ * @param params.startTime Epoch ms when conditioning began
+ * @param params.cacheHit Which cache served this request, if any
+ * @param params.errorKinds Per-stage failure classes, for diagnosis
+ */
+function emitConditionEvent(params) {
+    const { text, conditioned, args, startTime, cacheHit, errorKinds } = params;
+    const meta = {};
+    if (cacheHit)
+        meta.cache_hit = cacheHit;
+    if (errorKinds?.distill)
+        meta.distill_error = errorKinds.distill;
+    if (errorKinds?.resolver)
+        meta.resolver_error = errorKinds.resolver;
+    writeEvent({
+        ts: new Date().toISOString(),
+        layer: 'mcp',
+        // randomUUID, not Date.now()+short random: the old id could collide within the same
+        // millisecond, and INSERT OR REPLACE on the request_id PK then silently dropped a row.
+        request_id: `cond_${crypto.randomUUID()}`,
+        session_id: args?.sessionId ? String(args.sessionId) : (args?.session_id ? String(args.session_id) : undefined),
+        skill: args?.skillName ? String(args.skillName) : undefined,
+        route: 'condition',
+        is_local_call: 1,
+        slm_model: CONFIG.SLM_GATE_MODEL,
+        api_model: args?.model ? String(args.model) : undefined,
+        agent: args?.agent ? String(args.agent) : undefined,
+        in_tok: Math.round(text.length / 4),
+        out_tok: Math.round(conditioned.length / 4),
+        api_in_tok: 0,
+        api_out_tok: 0,
+        cost_usd: 0,
+        // A cache hit does no SLM work; charging it the wall-clock time would inflate latency stats.
+        slm_latency_s: cacheHit ? 0 : (Date.now() - startTime) / 1000,
+        api_latency_s: 0,
+        slm_gate: 'on',
+        meta: Object.keys(meta).length > 0 ? JSON.stringify(meta) : undefined,
+    });
+}
+/**
+ * The main entry point for the MCP gate pipeline. Processes an incoming prompt by checking the cache,
+ * optionally distilling (compressing) the text, grounding it with workspace context, and resolving
+ * ambiguities using a small language model.
+ *
+ * @param {string} text - The raw skill/prompt text received from the client.
+ * @param {string} task - A description of the current task for context during distillation and resolution.
+ * @param {string} [rootUri] - Optional URI of the workspace root to enable grounding and file context extraction.
+ * @returns {Promise<string>} The conditioned and enriched prompt ready for the cloud model.
+ */
+export async function conditionPrompt(text, task, rootUri, toolName, args) {
+    const startTime = Date.now();
+    if (!slmClient) {
+        slmClient = createSlmClient();
+        console.error(`[pipeline] Initialized SLM with OLLAMA_HOST=${CONFIG.OLLAMA_HOST}`);
+    }
+    // 1. Cache Check
+    // PROMPT_VERSION participates in the key. It is documented in .env.example as the lever to
+    // bump when prompt logic changes.
+    const hash = crypto.createHash('sha256')
+        .update(text + '||' + task + '||' + (rootUri || '') + '||' + (toolName || '') + '||' + CONFIG.PROMPT_VERSION)
+        .digest('hex');
+    const cacheKey = `condition_${hash}`;
+    const cached = cacheGet(cacheKey);
+    if (cached) {
+        // A cache hit is the BEST outcome — full compression at zero SLM compute — yet it used
+        // to return before any writeEvent, making it invisible to every metric and biasing all
+        // savings figures toward the slow path.
+        emitConditionEvent({ text, conditioned: cached, args, startTime, cacheHit: 'exact' });
+        return cached;
+    }
+    if (CONFIG.SEMCACHE) {
+        const semCached = await checkSemanticCache(text);
+        if (semCached && typeof semCached === 'string') {
+            emitConditionEvent({ text, conditioned: semCached, args, startTime, cacheHit: 'semantic' });
+            return semCached;
+        }
+    }
+    const preserveList = await getPreserveList();
+    // 2. Distill (the compressor is shared with the model gate; see compressNarrativeRun)
+    const slmFunc = (t, taskDesc) => compressNarrativeRun({ slm: slmClient, text: t, task: taskDesc });
+    const startDistill = Date.now();
+    let conditioned = text;
+    let distillErrorKind = null;
+    try {
+        conditioned = await distillToolResult(slmFunc, text, task, toolName, args, preserveList);
+    }
+    catch (err) {
+        handleSlmError(err, 'pipeline:distill', CONFIG.SLM_GATE_MODEL);
+        distillErrorKind = classifySlmError(err);
+        conditioned = text;
+    }
+    console.error(`[pipeline] distill ${((Date.now() - startDistill) / 1000).toFixed(1)}s`);
+    // 3. Ground
+    let groundCtx = '';
+    if (rootUri) {
+        groundCtx = await scan(rootUri);
+    }
+    // 4. Clarify (Resolver)
+    let fsReadFn = async (pattern) => [];
+    if (rootUri) {
+        let rootPath = rootUri;
+        if (rootUri.startsWith('file://')) {
+            try {
+                rootPath = fileURLToPath(rootUri);
+            }
+            catch {
+                rootPath = rootUri.substring(7);
+            }
+        }
+        fsReadFn = async (pattern) => {
+            try {
+                const content = await fs.readFile(path.join(rootPath, pattern), 'utf-8');
+                // Single `\n`: splitting on the two characters backslash-n never matched, so the whole
+                // file arrived as ONE element and the 50-line cap silently did nothing.
+                return content.split('\n').slice(0, 50);
+            }
+            catch {
+                return [];
+            }
+        };
+    }
+    const startResolver = Date.now();
+    let resolveOut = { autoApplied: [], askUser: [] };
+    let resolverErrorKind = null;
+    try {
+        resolveOut = await resolveAmbiguities(slmClient, fsReadFn, {
+            skillText: text,
+            task,
+            repoRoot: rootUri ? (rootUri.startsWith('file://') ? fileURLToPath(rootUri) : rootUri) : undefined
+        });
+    }
+    catch (err) {
+        handleSlmError(err, 'pipeline:resolver', CONFIG.SLM_BRAIN_MODEL);
+        resolverErrorKind = classifySlmError(err);
+    }
+    console.error(`[pipeline] resolver ${((Date.now() - startResolver) / 1000).toFixed(1)}s`);
+    // Append findings to the conditioned output.
+    // NOTE: single `\n` inside these template literals. `\\n` emits the two characters backslash-n,
+    // so every appended section used to arrive at the cloud model as one unbroken line littered
+    // with literal "\n" — markdown the model then had to read through.
+    if (groundCtx) {
+        conditioned += `\n\n# Environment Context\n${groundCtx}`;
+    }
+    if (resolveOut.autoApplied.length > 0) {
+        conditioned += `\n\n# Auto-Resolved Decisions\n`;
+        for (const res of resolveOut.autoApplied) {
+            conditioned += `- **${res.question}**: ${res.answer}\n`;
+        }
+    }
+    if (resolveOut.askUser.length > 0) {
+        conditioned += `\n\n# Pending Clarifications (Ask User)\n`;
+        for (const ask of resolveOut.askUser) {
+            conditioned += `- **${ask.question}** (Recommendation: ${ask.recommendedAnswer || 'None'})\n`;
+        }
+    }
+    // Report the ACTUAL failure. Both stages previously reported "timed out" for every error
+    // class, so a model that simply could not produce valid JSON was indistinguishable from a
+    // genuine timeout — the difference between raising SLM_TIMEOUT_MS and changing the model.
+    if (distillErrorKind) {
+        conditioned += `\n\n# Note\n[distill_${distillErrorKind}] ${SLM_ERROR_NOTES[distillErrorKind]}`;
+    }
+    if (resolverErrorKind) {
+        conditioned += `\n\n# Note\n[resolver_${resolverErrorKind}] ${SLM_ERROR_NOTES[resolverErrorKind]}`;
+    }
+    // 5. Ledger
+    emitConditionEvent({
+        text,
+        conditioned,
+        args,
+        startTime,
+        errorKinds: { distill: distillErrorKind, resolver: resolverErrorKind }
+    });
+    // 6. Cache Set.
+    //
+    // Previously this required BOTH stages to succeed. The resolver fails on essentially
+    // every call in practice, so the cache was never written and every identical tool call
+    // re-ran the full distil + resolve pipeline from scratch. Distillation is the expensive,
+    // valuable half and its result is correct on its own, so a resolver failure alone no
+    // longer blocks caching.
+    if (!distillErrorKind) {
+        cacheSet(cacheKey, conditioned);
+        if (CONFIG.SEMCACHE) {
+            await setSemanticCache(text, conditioned);
+        }
+    }
+    return conditioned;
+}