@zenithfoundry/slm-gate 1.2.1

package/dist/pricing/providers.js

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview Provider registry — the single, data-driven source of truth for how each
+ * subscription provider meters its rolling usage window, and how to recognise one.
+ *
+ * Two problems this replaces:
+ *
+ * 1. Provider/agent detection was hard-coded substring matching inside ledger/index.ts, so
+ *    supporting a new host or vendor meant editing code and cutting a release.
+ *
+ * 2. "Cycle Extended (min)" was computed as `windowMinutes * (tokensSaved / baselineTokens)`.
+ *    That multiplies a PER-EVENT COMPRESSION RATIO by a GLOBAL WINDOW LENGTH, which is
+ *    dimensionally meaningless — it claimed a single tool call that compressed 4,511 tokens
+ *    to 1,825 freed 178 of 300 window minutes, i.e. two such calls would free the entire
+ *    window. Converting savings into minutes requires a RATE:
+ *
+ *        minutesFreed = unitsSaved / (windowBudget / windowMinutes)
+ *
+ *    where the unit depends on how the provider actually meters:
+ *      - 'compute' providers bill tokens  -> unitsSaved = tokens saved
+ *      - 'message' providers bill requests -> unitsSaved = requests never sent (defer_local)
+ *
+ *    `windowBudget` is a real quantity the operator must supply; it is NOT knowable from
+ *    inside the gate. When it is unset we emit NO score rather than inventing one.
+ *
+ * Override the built-in defaults by pointing PROVIDER_REGISTRY_PATH at a JSON file with the
+ * same shape. Keys are provider ids; unknown ids are accepted, which is what keeps the gate
+ * agent- and vendor-agnostic.
+ */
+import fs from 'node:fs';
+/**
+ * Shortest permitted match pattern. Matching is substring-based, so two-character needles
+ * (the retired 'o1'/'o3'/'o4' OpenAI patterns) collide with unrelated model ids.
+ */
+const MIN_PATTERN_LENGTH = 3;
+export const DEFAULT_PROVIDER_REGISTRY = {
+    claude: {
+        windowMinutes: 300,
+        // Claude's usage limits scale with how much text is sent (message length, attachments,
+        // conversation length), not with a flat message count, so tokens saved by distillation
+        // do extend the window.
+        metering: 'compute',
+        windowBudget: null,
+        // 'fable' and 'mythos' are current frontier families (claude-fable-5-1); they are NOT
+        // covered by the opus/sonnet/haiku tier names. Verified against platform.claude.com
+        // 2026-09-13.
+        modelPatterns: ['claude', 'anthropic', 'fable', 'mythos', 'opus', 'sonnet', 'haiku'],
+        agentPatterns: ['claude'],
+    },
+    chatgpt: {
+        windowMinutes: 180,
+        metering: 'message',
+        windowBudget: null,
+        // The o-series (o1/o3/o4) is RETIRED — OpenAI merged reasoning into the unified GPT
+        // line. Those patterns were also unsafe here: matching is substring-based, so a
+        // two-character needle like 'o1' can collide with unrelated ids.
+        // Every current text model is 'gpt-*' (gpt-6-astra, gpt-5.6-sol/terra/luna/cyber)
+        // EXCEPT the daybreak-red / daybreak-blue security aliases, which contain neither
+        // 'gpt' nor 'openai' and were previously unattributable.
+        // Verified against developers.openai.com/api/docs/models 2026-09-13.
+        modelPatterns: ['gpt', 'openai', 'daybreak', 'codex'],
+        agentPatterns: ['chatgpt', 'openai', 'codex'],
+    },
+    gemini: {
+        windowMinutes: 300,
+        metering: 'compute',
+        windowBudget: null,
+        // 'bison' is retained only for PaLM-era ids; all current models are gemini-*/gemma-*.
+        modelPatterns: ['gemini', 'gemma', 'bison'],
+        agentPatterns: ['antigravity', 'gemini'],
+    },
+};
+/**
+ * Minutes of a provider's window freed by a number of saved units. The one place this
+ * formula lives, so the dashboard and the bench report can never disagree.
+ *
+ * @param profile The provider's profile
+ * @param unitsSaved Tokens saved ('compute') or requests avoided ('message')
+ * @returns Minutes freed, clamped to [0, windowMinutes], or null when no budget is set.
+ */
+export function minutesFreed(profile, unitsSaved) {
+    if (!profile.windowBudget || profile.windowBudget <= 0)
+        return null;
+    const minutes = unitsSaved * (profile.windowMinutes / profile.windowBudget);
+    return Math.min(profile.windowMinutes, Math.max(0, minutes));
+}
+let cachedRegistry = null;
+/**
+ * Returns the active provider registry, loading a JSON override once if configured.
+ *
+ * @param overridePath Optional path to a JSON registry; defaults to PROVIDER_REGISTRY_PATH.
+ * @returns Provider id -> profile.
+ */
+export function getProviderRegistry(overridePath = process.env.PROVIDER_REGISTRY_PATH) {
+    if (cachedRegistry)
+        return cachedRegistry;
+    // Clone each profile: a shallow spread would share the profile objects with
+    // DEFAULT_PROVIDER_REGISTRY, so writing windowBudget below would permanently mutate the
+    // module-level defaults and survive every subsequent reset.
+    const registry = Object.fromEntries(Object.entries(DEFAULT_PROVIDER_REGISTRY).map(([id, profile]) => [id, { ...profile }]));
+    if (overridePath) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(overridePath, 'utf-8'));
+            for (const [id, profile] of Object.entries(parsed)) {
+                registry[id] = { ...(registry[id] ?? DEFAULT_PROVIDER_REGISTRY.claude), ...profile };
+            }
+            // Matching is substring-based, so a very short needle silently mis-attributes
+            // unrelated models. This is how the retired 'o1'/'o3'/'o4' patterns became a hazard.
+            for (const [id, profile] of Object.entries(registry)) {
+                for (const pattern of [...profile.modelPatterns, ...profile.agentPatterns]) {
+                    if (pattern.length < MIN_PATTERN_LENGTH) {
+                        console.error(`[providers] Ignoring pattern '${pattern}' for '${id}': patterns must be at least ${MIN_PATTERN_LENGTH} characters to avoid false matches.`);
+                    }
+                }
+                profile.modelPatterns = profile.modelPatterns.filter(p => p.length >= MIN_PATTERN_LENGTH);
+                profile.agentPatterns = profile.agentPatterns.filter(p => p.length >= MIN_PATTERN_LENGTH);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[providers] Could not read PROVIDER_REGISTRY_PATH (${overridePath}): ${message}. Using defaults.`);
+        }
+    }
+    // Window budgets are operator-supplied, per provider, via env.
+    // e.g. CLAUDE_WINDOW_BUDGET=2000000  (tokens per 5h window)
+    //      CHATGPT_WINDOW_BUDGET=80        (messages per 3h window)
+    for (const id of Object.keys(registry)) {
+        const raw = process.env[`${id.toUpperCase()}_WINDOW_BUDGET`];
+        if (raw) {
+            const parsed = Number(raw);
+            if (Number.isFinite(parsed) && parsed > 0)
+                registry[id].windowBudget = parsed;
+        }
+    }
+    cachedRegistry = registry;
+    return registry;
+}
+/** Test hook: forces the registry to be re-read on next access. */
+export function __resetProviderRegistry() {
+    cachedRegistry = null;
+}
+/**
+ * Identifies the provider behind a model id.
+ *
+ * @param model Model id as reported by the host, e.g. 'claude-opus-5[1m]'
+ * @returns Provider id, or null when nothing matches.
+ */
+export function providerFromModelId(model) {
+    if (!model)
+        return null;
+    const lower = model.toLowerCase();
+    for (const [id, profile] of Object.entries(getProviderRegistry())) {
+        if (profile.modelPatterns.some(p => lower.includes(p)))
+            return id;
+    }
+    return null;
+}
+/**
+ * Identifies the provider behind a host/agent name.
+ *
+ * @param agent Agent or host identifier, e.g. 'claude-code'
+ * @returns Provider id, or null when nothing matches.
+ */
+export function providerFromAgentName(agent) {
+    if (!agent)
+        return null;
+    const lower = agent.toLowerCase();
+    for (const [id, profile] of Object.entries(getProviderRegistry())) {
+        if (profile.agentPatterns.some(p => lower.includes(p)))
+            return id;
+    }
+    return null;
+}

package/dist/resolver/index.js

@@ -0,0 +1,277 @@
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { selfConsistency } from '../models/reasoning.js';
+import { getDb, writeEvent } from '../ledger/index.js';
+import { CONFIG } from '../config.js';
+import { withSlmTimeout } from '../models/helpers.js';
+// Helper to determine if we can afford a cloud call
+function checkCloudBudget() {
+    if (!CONFIG.RESOLVER_CLOUD_TIER || !CONFIG.CLOUD_API_KEY || !CONFIG.CLOUD_MODEL) {
+        return false;
+    }
+    if (CONFIG.RESOLVER_CLOUD_BUDGET_USD <= 0) {
+        return false; // budget is 0
+    }
+    const row = getDb().prepare('SELECT SUM(cost_usd) as total FROM events').get();
+    const spent = row.total || 0;
+    return spent < CONFIG.RESOLVER_CLOUD_BUDGET_USD;
+}
+// Bounded cloud API call
+async function batchCloudResolve(unresolved, skillText, task) {
+    if (unresolved.length === 0)
+        return;
+    const prompt = `You are an expert developer resolving ambiguities for a local agent.
+Task: ${task}
+Skill/Context: ${skillText}
+
+For the following open decisions, provide the best answer. If uncertain, leave it null.
+Decisions:
+${unresolved.map(u => `- [${u.id}] ${u.question}`).join('\n')}
+
+Respond in JSON matching this schema:
+{
+  "answers": [
+    { "id": "decision_id", "answer": "best answer or null", "confidence": 0.0 to 1.0, "options": ["opt1", "opt2"] }
+  ]
+}`;
+    const schema = z.object({
+        answers: z.array(z.object({
+            id: z.string(),
+            answer: z.string().nullable(),
+            confidence: z.number(),
+            options: z.array(z.string()).optional()
+        }))
+    });
+    const startTime = Date.now();
+    let inTok = prompt.length / 4; // rough estimate
+    let outTok = 0;
+    let cost = 0;
+    try {
+        const url = CONFIG.CLOUD_BASE_URL || (CONFIG.CLOUD_API_STYLE === 'anthropic' ? 'https://api.anthropic.com/v1/messages' : 'https://api.openai.com/v1/chat/completions');
+        // Using standard OpenAI compatible payload for routing purposes since it natively supports json_schema
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${CONFIG.CLOUD_API_KEY}`
+            },
+            body: JSON.stringify({
+                model: CONFIG.CLOUD_MODEL,
+                messages: [{ role: 'user', content: prompt }],
+                response_format: {
+                    type: "json_schema",
+                    json_schema: {
+                        name: "resolver_output",
+                        strict: true,
+                        schema: zodToJsonSchema(schema)
+                    }
+                },
+                temperature: 0
+            })
+        });
+        if (res.ok) {
+            const data = await res.json();
+            const content = data.choices[0].message.content;
+            outTok = content.length / 4;
+            try {
+                const parsed = schema.parse(JSON.parse(content));
+                for (const item of parsed.answers) {
+                    const target = unresolved.find(u => u.id === item.id);
+                    if (target && item.answer !== null) {
+                        target.answer = item.answer;
+                        target.confidence = item.confidence;
+                        target.source = 'api';
+                        if (item.options)
+                            target.options = item.options;
+                    }
+                }
+            }
+            catch (err) {
+                // failed to parse
+            }
+        }
+    }
+    catch (err) {
+        // network or other error
+    }
+    finally {
+        const { calculateCostUsd } = await import('../pricing/index.js');
+        try {
+            cost = calculateCostUsd(CONFIG.CLOUD_MODEL || 'unknown', inTok, outTok);
+        }
+        catch {
+            cost = 0;
+        }
+        writeEvent({
+            ts: new Date().toISOString(),
+            layer: 'mcp',
+            request_id: `resolver_cloud_${Date.now()}`,
+            route: 'escalate',
+            is_local_call: 0,
+            api_model: CONFIG.CLOUD_MODEL || 'unknown',
+            in_tok: 0,
+            out_tok: 0,
+            api_in_tok: Math.round(inTok),
+            api_out_tok: Math.round(outTok),
+            cost_usd: cost,
+            slm_latency_s: 0,
+            api_latency_s: (Date.now() - startTime) / 1000,
+            slm_gate: 'on'
+        });
+    }
+}
+export async function extractAmbiguities(slm, skillText, task) {
+    const schema = z.object({
+        decisions: z.array(z.object({
+            id: z.string(),
+            question: z.string(),
+            kind: z.string()
+        }))
+    });
+    const prompt = `Extract concrete open decisions or ambiguities from the following task and skill context.
+Task: ${task}
+Context: ${skillText}
+
+Output a list of decisions that need to be made before work can begin. If none, return an empty array. Limit to AT MOST 3 critical decisions. Be very concise.`;
+    const res = await withSlmTimeout(slm.generateJSON(CONFIG.SLM_BRAIN_MODEL, prompt, schema, 0), 'resolver', CONFIG.SLM_TIMEOUT_MS);
+    return res.decisions;
+}
+export async function resolveEach(slm, fsRead, decisions, repoRoot) {
+    const results = [];
+    for (const dec of decisions) {
+        let resolved = {
+            id: dec.id,
+            question: dec.question,
+            answer: null,
+            confidence: 0,
+            source: 'unresolved'
+        };
+        // (a) EVIDENCE
+        if (repoRoot) {
+            const patternSchema = z.object({ patterns: z.array(z.string()) });
+            try {
+                const patternPrompt = `What file paths or contents should we grep to answer this question: "${dec.question}"?
+Return 1 or 2 simple patterns like "package.json" or "yarn.lock" or "docker-compose.yml".`;
+                const patternRes = await withSlmTimeout(slm.generateJSON(CONFIG.SLM_BRAIN_MODEL, patternPrompt, patternSchema, 0), 'resolver', CONFIG.SLM_TIMEOUT_MS);
+                let evidenceFound = '';
+                for (const p of patternRes.patterns) {
+                    const contents = await fsRead(p);
+                    if (contents.length > 0) {
+                        // Single `\n`: the evidence block was previously joined with the literal characters
+                        // backslash-n, so the brain model saw one unbroken line of file contents.
+                        evidenceFound += contents.join('\n') + '\n';
+                        break;
+                    }
+                }
+                if (evidenceFound) {
+                    const ansSchema = z.object({ answer: z.string(), options: z.array(z.string()) });
+                    const ansPrompt = `Given this evidence from the repository:\n${evidenceFound.slice(0, 1000)}\nAnswer the question: ${dec.question}`;
+                    const ansRes = await withSlmTimeout(slm.generateJSON(CONFIG.SLM_BRAIN_MODEL, ansPrompt, ansSchema, 0), 'resolver', CONFIG.SLM_TIMEOUT_MS);
+                    resolved = {
+                        id: dec.id,
+                        question: dec.question,
+                        answer: ansRes.answer,
+                        confidence: 0.95,
+                        source: 'evidence',
+                        evidence: `Found evidence matching pattern.`,
+                        options: ansRes.options
+                    };
+                    results.push(resolved);
+                    continue;
+                }
+            }
+            catch (err) {
+                // ignore and fall through
+            }
+        }
+        // (b) & (c) CONVENTION & SELF-CONSISTENCY
+        const scSchema = z.object({
+            answer: z.string(),
+            options: z.array(z.string())
+        });
+        const scPrompt = `Based on standard software conventions, answer this open decision:
+Question: ${dec.question}
+Provide the most standard choice as 'answer' and 2-3 alternatives as 'options'.`;
+        try {
+            const scRes = await selfConsistency(slm, CONFIG.SLM_BRAIN_MODEL, scPrompt, scSchema, CONFIG.SELF_CONSISTENCY_K, CONFIG.SELF_CONSISTENCY_TEMP);
+            resolved = {
+                id: dec.id,
+                question: dec.question,
+                answer: scRes.answer,
+                confidence: 0.6,
+                source: 'convention',
+                options: scRes.options
+            };
+            if (CONFIG.SELF_CONSISTENCY_K > 1) {
+                resolved.source = 'self_consistency';
+                resolved.confidence = 0.75;
+            }
+        }
+        catch (err) {
+            // ignore
+        }
+        results.push(resolved);
+    }
+    return results;
+}
+export async function gateDecisions(slm, items) {
+    const output = {
+        autoApplied: [],
+        askUser: []
+    };
+    const schema = z.object({
+        risk: z.enum(['reversible', 'low', 'security', 'destructive'])
+    });
+    for (const item of items) {
+        let risk = 'low';
+        try {
+            const prompt = `Classify the risk of deciding this question automatically:
+Question: ${item.question}
+Answer: ${item.answer}
+
+Categories:
+- reversible: trivial formatting, naming conventions, minor tools
+- low: standard library choices, standard config
+- security: auth, tokens, crypto, permissions, network exposure
+- destructive: dropping databases, deleting files, overwriting critical data`;
+            const res = await withSlmTimeout(slm.generateJSON(CONFIG.SLM_GATE_MODEL, prompt, schema, 0), 'resolver', CONFIG.SLM_TIMEOUT_MS);
+            risk = res.risk;
+        }
+        catch (err) {
+            risk = 'security';
+        }
+        item.risk = risk;
+        if (item.confidence >= 0.8 && (risk === 'reversible' || risk === 'low')) {
+            output.autoApplied.push({
+                id: item.id,
+                question: item.question,
+                answer: item.answer || 'Unknown',
+                note: `Auto-resolved based on ${item.source}`
+            });
+        }
+        else {
+            output.askUser.push({
+                id: item.id,
+                question: item.question,
+                recommendedAnswer: item.answer,
+                confidence: item.confidence,
+                options: item.options || [],
+                evidence: item.evidence
+            });
+        }
+    }
+    return output;
+}
+export async function resolveAmbiguities(slm, fsRead, input) {
+    const decisions = await extractAmbiguities(slm, input.skillText, input.task);
+    if (decisions.length === 0) {
+        return { autoApplied: [], askUser: [] };
+    }
+    const resolved = await resolveEach(slm, fsRead, decisions, input.repoRoot);
+    // Cloud API Tier
+    const unresolved = resolved.filter(r => r.confidence < 0.8);
+    if (unresolved.length > 0 && checkCloudBudget()) {
+        await batchCloudResolve(unresolved, input.skillText, input.task);
+    }
+    return gateDecisions(slm, resolved);
+}

package/dist/resolver/types.js

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

package/dist/setup/claim.js

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview "At most once per time window, across every slm-gate process on this machine." Several
+ * copies of slm-gate's MCP server run at once (one per IDE window / CLI session); this is how they agree
+ * that only one of them shows a notification or launches the model gate.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * True for exactly one caller per window. Windows are fixed slices of time (with a minute: 12:00–12:01,
+ * 12:01–12:02, …), and each has its own marker file, created atomically (`wx`): of several callers in one
+ * window only the first succeeds. Nothing is ever read back or replaced, so no caller can mistake a marker
+ * that another process is still writing, or has just replaced, for an expired one.
+ *
+ * @param params.file The marker file for this action; the window number is appended
+ * @param params.windowMs How long one window lasts
+ * @param params.now Current time, for tests
+ */
+export function claimWindow(params) {
+    const window = Math.floor((params.now ?? Date.now()) / params.windowMs);
+    const dir = path.dirname(params.file);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(`${params.file}.${window}`, '', { flag: 'wx' });
+    }
+    catch {
+        return false; // another process claimed this window first (or the folder is not writable)
+    }
+    // Markers of earlier windows are never looked at again. The previous one is kept so a caller whose clock
+    // reads a moment earlier still finds it.
+    const prefix = `${path.basename(params.file)}.`;
+    try {
+        for (const name of fs.readdirSync(dir)) {
+            if (name.startsWith(prefix) && Number(name.slice(prefix.length)) < window - 1)
+                fs.rmSync(path.join(dir, name), { force: true });
+        }
+    }
+    catch {
+        // Clean-up only.
+    }
+    return true;
+}

package/dist/setup/gate-command.js

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview `slm-gate start | stop | restart` — recovery commands for the model gate. Day to day it
+ * starts by itself whenever a coding tool starts slm-gate's MCP server; these are for when you want to
+ * control it by hand (`stop` keeps it stopped until `start`, `restart` or a reboot).
+ */
+import { CONFIG } from '../config.js';
+import { cliCommand, GATE_LOG_FILE, startModelGate, stopModelGate } from './model-gate.js';
+const address = `http://localhost:${CONFIG.MODEL_GATE_PORT}`;
+async function main(action) {
+    if (!['start', 'stop', 'restart'].includes(action)) {
+        console.error(`Unknown action "${action}": use start, stop or restart.`);
+        process.exitCode = 1;
+        return;
+    }
+    if (action === 'stop' || action === 'restart') {
+        const stopped = await stopModelGate();
+        console.log(stopped ? `Stopped the model gate on ${address} (pid ${stopped.pid}).` : `No model gate was running on ${address}.`);
+        if (action === 'stop') {
+            console.log(`It stays stopped until \`${cliCommand('start')}\`, \`${cliCommand('restart')}\` or a reboot. Coding tools pointed at it cannot reach their AI provider meanwhile.`);
+            return;
+        }
+    }
+    const probe = await startModelGate();
+    if (probe.kind === 'slm-gate') {
+        console.log(`The model gate is running on ${address} (pid ${probe.health.pid}).`);
+        if (probe.stale)
+            console.log(`It is an older slm-gate build: run \`${cliCommand('restart')}\` when no coding tool is in the middle of an answer.`);
+    }
+    else if (probe.kind === 'other') {
+        console.error(`Port ${CONFIG.MODEL_GATE_PORT} is used by another program, so the model gate cannot start there. Run \`${cliCommand('doctor')}\` to see which program and how to change the port.`);
+        process.exitCode = 1;
+    }
+    else {
+        console.error(`The model gate did not start. See ${GATE_LOG_FILE}, or run \`${cliCommand('doctor')}\`.`);
+        process.exitCode = 1;
+    }
+}
+main(process.argv[2] ?? 'start').catch(err => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+});

package/dist/setup/init.js

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview `slm-gate init`: creates the settings file (`.env` in the settings folder, src/home-dir.ts).
+ *
+ * It copies the full template (`.env.example`, every setting explained) and fills in only the lines that
+ * depend on this computer, with the values doctor recommends for its RAM. It assumes no coding tool, AI
+ * provider or toolbox: PROVIDER is left blank, and so are keys and DOWNSTREAM_MCP. An existing settings
+ * file is never replaced.
+ */
+import { parse } from 'dotenv';
+import fs from 'node:fs';
+import path from 'node:path';
+import { MIN_RAM_GB, modelsForRam, recommendNumCtx, recommendPreset } from '../hardware.js';
+import { modelsFor } from './required-models.js';
+/**
+ * The template lines `init` fills in for a computer with `ramGb` of RAM: the same preset, models and
+ * NUM_CTX doctor recommends (src/hardware.ts). Above 128 GB the preset is `custom`, with the 128 GB models.
+ *
+ * @throws When `ramGb` is below MIN_RAM_GB, which slm-gate does not support
+ */
+export function settingsForRam(ramGb) {
+    if (ramGb < MIN_RAM_GB) {
+        throw new Error(`slm-gate needs at least ${MIN_RAM_GB} GB of RAM; this is set up for ${ramGb} GB.`);
+    }
+    const preset = recommendPreset(ramGb);
+    const { brain, gate } = modelsForRam(ramGb);
+    return {
+        preset,
+        lines: {
+            RAM_PRESET: preset,
+            SLM_BRAIN_MODEL: brain,
+            SLM_GATE_MODEL: gate,
+            SLM_GATE_TESTING_MODEL: gate,
+            NUM_CTX: String(recommendNumCtx(ramGb)),
+            PROVIDER: '',
+        },
+    };
+}
+/**
+ * Sets `KEY=value` lines in a settings template.
+ *
+ * @param template The template text
+ * @param lines The values to set, by key
+ * @returns The template with those lines set
+ * @throws When a key is not on exactly one line of its own: the template changed, and guessing where the
+ *   setting goes could leave the file with a value slm-gate never reads
+ */
+export function fillSettings(template, lines) {
+    return Object.entries(lines).reduce((text, [key, value]) => {
+        const line = new RegExp(`^${key}=.*$`, 'gm');
+        const found = text.match(line)?.length ?? 0;
+        if (found !== 1)
+            throw new Error(`.env.example has ${found} ${key}= lines; expected exactly 1.`);
+        return text.replace(line, `${key}=${value}`);
+    }, template);
+}
+/**
+ * The local models a settings file needs, by the start-up check's rule (src/setup/required-models.ts), so
+ * following init's download step leaves nothing for that check to report.
+ */
+function modelsIn(settingsText) {
+    const settings = parse(settingsText);
+    // As config.ts reads them: on, true or 1 is on; anything else, blank included, is off (both default to off).
+    const isOn = (value) => ['on', 'true', '1'].includes((value ?? '').toLowerCase());
+    const models = modelsFor({
+        SLM_GATE_MODEL: settings.SLM_GATE_MODEL ?? '',
+        SLM_BRAIN_MODEL: settings.SLM_BRAIN_MODEL ?? '',
+        EMBED_MODEL: settings.EMBED_MODEL ?? '',
+        SEMCACHE: isOn(settings.SEMCACHE),
+        DISTILL_ADAPTIVE: isOn(settings.DISTILL_ADAPTIVE),
+    });
+    return [...new Set(models.map(model => model.name).filter(Boolean))];
+}
+/**
+ * Creates the settings file for this computer, unless one exists.
+ *
+ * @param params.installDir The install folder, where `.env.example` is
+ * @param params.homeDir The settings folder
+ * @param params.ramGb This computer's RAM, in GB
+ * @returns Whether the file was created, where it is, the RAM preset and the models to download
+ */
+export function initSettings(params) {
+    const envPath = path.join(params.homeDir, '.env');
+    const { preset, lines } = settingsForRam(params.ramGb);
+    if (fs.existsSync(envPath))
+        return { created: false, envPath, preset, models: modelsIn(fs.readFileSync(envPath, 'utf8')) };
+    const template = fs.readFileSync(path.join(params.installDir, '.env.example'), 'utf8');
+    const text = fillSettings(template, lines);
+    fs.mkdirSync(params.homeDir, { recursive: true });
+    // 'wx' fails rather than replace a file created meanwhile; 0o600 because the file may later hold keys.
+    fs.writeFileSync(envPath, text, { flag: 'wx', mode: 0o600 });
+    return { created: true, envPath, preset, models: modelsIn(text) };
+}