termi-kids 0.1.0

package/dist/safety/guardrunner.js

@@ -0,0 +1,125 @@
+/**
+ * llama.cpp runtime for the on-device safety classifier.
+ *
+ * Loads the pinned GGUF once (lazily, kicked off at client creation so the
+ * model warms while the kid reads the greeting) and serializes generation
+ * calls through one context sequence. Wrapper segments are tokenized with
+ * special tokens enabled; judged segments are tokenized as plain text, so
+ * nothing a kid types or a model writes can inject chat-control tokens.
+ *
+ * Every failure path throws; the safety pipeline turns any throw into a
+ * fail-closed block. This module never fails open.
+ */
+import { buildInputSegments, buildOutputSegments, guardVerdict, parseGuardReading, } from './localguard.js';
+import { GUARD_MODEL, guardModelPath, guardModelReady, sha256OfFile } from './modelstore.js';
+/** The verdict is three short lines; anything longer is already garbage. */
+export const GUARD_MAX_TOKENS = 96;
+/** Per-call generation budget. Model load and queue wait are not counted. */
+export const GUARD_TIMEOUT_MS = 20_000;
+/** One-time model load budget. A hung native load must not hang the chat. */
+export const GUARD_LOAD_TIMEOUT_MS = 60_000;
+/** Plenty for the wrapper plus both judged segments at their caps. */
+const GUARD_CONTEXT_SIZE = 8192;
+async function loadRuntime() {
+    // Readiness checks only the size (cheap, per check); the load re-verifies
+    // the pinned digest so a same-size file swapped in by a curious kid never
+    // runs as the guard. Same threat actor the HMAC-signed settings defend
+    // against; a failed digest fails closed through every classify call.
+    const digest = await sha256OfFile(guardModelPath());
+    if (digest !== GUARD_MODEL.sha256) {
+        throw new Error('guard-model-tampered');
+    }
+    const nlc = await import('node-llama-cpp');
+    const llama = await nlc.getLlama({ logLevel: nlc.LlamaLogLevel.error });
+    const model = await llama.loadModel({ modelPath: guardModelPath() });
+    const context = await model.createContext({ contextSize: GUARD_CONTEXT_SIZE });
+    const completion = new nlc.LlamaCompletion({ contextSequence: context.getSequence() });
+    return {
+        async generate(segments, signal) {
+            const prompt = nlc.LlamaText(segments.map((s) => s.kind === 'fixed' ? new nlc.SpecialTokensText(s.text) : s.text));
+            return completion.generateCompletion(prompt, {
+                maxTokens: GUARD_MAX_TOKENS,
+                customStopTriggers: ['<|im_end|>'],
+                signal,
+            });
+        },
+    };
+}
+/** Rejects when the promise takes longer than ms. The load stays bounded. */
+function withDeadline(promise, ms, reason) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(reason)), ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err instanceof Error ? err : new Error(String(err)));
+        });
+    });
+}
+/**
+ * Builds the guard client, or null when the model file is not in place.
+ * Creation starts the model load; classify calls wait for it (bounded by
+ * the load deadline), then get their own generation timeout. Queue wait is
+ * deliberately unbudgeted: every queued call is itself bounded, so a long
+ * file's later chunks wait their turn instead of spuriously failing closed.
+ */
+export function createGuardClient(opts = {}) {
+    if (!guardModelReady()) {
+        return null;
+    }
+    const timeoutMs = opts.timeoutMs ?? GUARD_TIMEOUT_MS;
+    const loadTimeoutMs = opts.loadTimeoutMs ?? GUARD_LOAD_TIMEOUT_MS;
+    const runtime = (opts.loadRuntimeImpl ?? loadRuntime)();
+    // A load failure must surface on classify calls, not as a process crash.
+    void runtime.catch(() => undefined);
+    let queue = Promise.resolve();
+    async function run(segments) {
+        const rt = await withDeadline(runtime, loadTimeoutMs, 'guard-load-timeout');
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new Error('guard-timeout')), timeoutMs);
+        try {
+            // The deadline backstops a native call that ignores the abort signal:
+            // without it, one hung generation would queue every later check
+            // behind it and freeze the chat for good.
+            const raw = await withDeadline(rt.generate(segments, controller.signal), timeoutMs * 2, 'guard-timeout');
+            return guardVerdict(parseGuardReading(raw));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    function enqueue(segments) {
+        const next = queue.then(() => run(segments));
+        queue = next.catch(() => undefined);
+        return next;
+    }
+    return {
+        classifyInput: (text) => enqueue(buildInputSegments(text)),
+        classifyOutput: (kidText, producedText) => enqueue(buildOutputSegments(kidText, producedText)),
+    };
+}
+/**
+ * Accessor that hot-attaches the guard. It returns null while the model
+ * file is still downloading, then builds the client once on the first check
+ * after the file lands and reuses it for the rest of the session. The stat
+ * call per check is trivial next to a model call.
+ */
+export function lazyGuardAccessor(enabled, opts = {}) {
+    let client = null;
+    return () => {
+        if (!enabled) {
+            return null;
+        }
+        if (client === null) {
+            try {
+                client = createGuardClient(opts);
+            }
+            catch {
+                client = null;
+            }
+        }
+        return client;
+    };
+}

package/dist/safety/localguard.js

@@ -0,0 +1,227 @@
+/**
+ * On-device safety classifier contract for Qwen3Guard-Gen-0.6B.
+ *
+ * Pure functions only: prompt segments, output parsing, and the mapping
+ * from guard categories onto Termi's taxonomy. The llama.cpp runtime that
+ * feeds these lives in guardrunner.ts so everything here stays testable
+ * without a model file.
+ *
+ * The prompt wrapper reproduces the classification template that ships in
+ * the model's tokenizer config, byte for byte. Judged text never becomes
+ * part of the wrapper: the runner tokenizes wrapper segments and judged
+ * segments separately, so special tokens inside kid content stay plain text.
+ */
+import { blockMessage, severityBlocks } from './taxonomy.js';
+/** Category names exactly as the guard model prints them. */
+export const GUARD_CATEGORIES = [
+    'Violent',
+    'Non-violent Illegal Acts',
+    'Sexual Content or Sexual Acts',
+    'PII',
+    'Suicide & Self-Harm',
+    'Unethical Acts',
+    'Politically Sensitive Topics',
+    'Copyright Violation',
+    'Jailbreak',
+];
+/** Where each guard category lands in Termi's taxonomy. */
+export const GUARD_TO_TERMI = {
+    Violent: 'violence',
+    'Non-violent Illegal Acts': 'illicit',
+    'Sexual Content or Sexual Acts': 'sexual',
+    PII: 'pii',
+    'Suicide & Self-Harm': 'self_harm',
+    'Unethical Acts': 'illicit',
+    'Politically Sensitive Topics': 'adult_advice',
+    'Copyright Violation': 'copyright',
+    Jailbreak: 'jailbreak',
+};
+const CATEGORY_BLOCK = GUARD_CATEGORIES.map((c) => `${c}.`).join('\n');
+const CATEGORY_BLOCK_NO_JAILBREAK = GUARD_CATEGORIES.filter((c) => c !== 'Jailbreak')
+    .map((c) => `${c}.`)
+    .join('\n');
+const INPUT_HEADER = '<|im_start|>user\n' +
+    '# Task:\n' +
+    "1) Evaluate whether THE LAST USER's query belongs to safe or unsafe content based on our safety policy.\n" +
+    '2) Identify the category of unsafe content found.\n' +
+    '\n' +
+    '<BEGIN SAFETY POLICY>\n' +
+    "**Safety: Safe**: The USER's query does not contain any prohibited content or content that could lead to prohibited content.\n" +
+    "**Safety: Unsafe**: The USER's query contains prohibited content.\n" +
+    "**Safety: Controversial**: The USER's query does not explicitly contain prohibited content, but its intent, context, or potential responses could be misinterpreted, misused, or exploited to generate unsafe content under certain conditions.\n" +
+    '<END SAFETY POLICY>\n' +
+    '\n' +
+    '<BEGIN UNSAFE CONTENT CATEGORIES>\n' +
+    `${CATEGORY_BLOCK}\n` +
+    '<END UNSAFE CONTENT CATEGORIES>\n' +
+    '\n' +
+    '<BEGIN CONVERSATION>\n' +
+    '\n';
+const INPUT_FOOTER = '\n' +
+    '\n' +
+    '<END CONVERSATION>\n' +
+    '\n' +
+    "Provide your safety assessment for ONLY THE LAST **USER's query** in the above conversation:\n" +
+    " - The first line must be one of: 'Safety: Safe', 'Safety: Unsafe', 'Safety: Controversial'.\n" +
+    " - The second line should start with 'Categories:' followed by a list of any unsafe content categories, separated by commas. If the content is safe, use 'Categories: None'.<|im_end|>\n" +
+    '<|im_start|>assistant\n' +
+    '<think>\n' +
+    '\n' +
+    '</think>\n' +
+    '\n';
+const OUTPUT_HEADER = '<|im_start|>user\n' +
+    '# Task:\n' +
+    "1) Evaluate whether THE LAST ASSISTANT's response belongs to safe or unsafe content based on our safety policy.\n" +
+    '2) Identify the category of unsafe content found.\n' +
+    "3) Determine if THE LAST ASSISTANT's response is a refusal to the USER's query.\n" +
+    '\n' +
+    '<BEGIN SAFETY POLICY>\n' +
+    "**Safety: Safe**: The ASSISTANT's response does not contain any prohibited content or content that could lead to prohibited content.\n" +
+    "**Safety: Unsafe**: The ASSISTANT's response contains prohibited content.\n" +
+    "**Safety: Controversial**: The ASSISTANT's response is not explicitly harmful, but could become risky or offensive depending on context or audience.\n" +
+    '<END SAFETY POLICY>\n' +
+    '\n' +
+    '<BEGIN UNSAFE CONTENT CATEGORIES>\n' +
+    `${CATEGORY_BLOCK_NO_JAILBREAK}\n` +
+    '<END UNSAFE CONTENT CATEGORIES>\n' +
+    '\n' +
+    '<BEGIN REFUSAL POLICY>\n' +
+    "**Refusal: Yes**: The ASSISTANT refused to answer or did not comply with the USER's request.\n" +
+    "**Refusal: No**: The ASSISTANT directly answered or complied with the USER's request.\n" +
+    '<END REFUSAL POLICY>\n' +
+    '\n' +
+    '<BEGIN CONVERSATION>\n' +
+    '\n';
+const OUTPUT_FOOTER = '\n' +
+    '\n' +
+    '<END CONVERSATION>\n' +
+    '\n' +
+    "Provide your safety assessment for ONLY THE LAST **ASSISTANT's response** in the above conversation:\n" +
+    " - The first line must be one of: 'Safety: Safe', 'Safety: Unsafe', 'Safety: Controversial'.\n" +
+    " - The second line should start with 'Categories:' followed by a list of any unsafe content categories, separated by commas. If the content is safe, use 'Categories: None'.\n" +
+    " - The third line must be one of: 'Refusal: Yes', 'Refusal: No'.<|im_end|>\n" +
+    '<|im_start|>assistant\n' +
+    '<think>\n' +
+    '\n' +
+    '</think>\n' +
+    '\n';
+/** Longest judged text accepted per call. Callers chunk well below this. */
+export const GUARD_TEXT_CAP = 6000;
+/**
+ * Judged text is data. The wrapper's conversation markers are defanged and
+ * chat-control glyph pairs are broken so judged content can never read as
+ * template structure. Token-level injection is impossible regardless (the
+ * runner never parses special tokens in judged segments); this guards the
+ * plain-text layer.
+ */
+export function sanitizeJudged(text) {
+    return text
+        .slice(0, GUARD_TEXT_CAP)
+        .replace(/\u0000/g, '')
+        .replace(/<\|/g, '< |')
+        .replace(/<(\/?)(BEGIN|END) (CONVERSATION|SAFETY POLICY|UNSAFE CONTENT CATEGORIES|REFUSAL POLICY)>/gi, '($2 $3)')
+        // Verdict-shaped lines inside judged text lose their colon so an echo
+        // can never look like the guard's own output (the parser is anchored
+        // to the first line anyway; this also avoids needless blocks when a
+        // kid literally types a verdict-shaped line).
+        .replace(/^(\s*)(Safety|Categories|Refusal)(\s*):/gim, '$1$2$3;');
+}
+/** Prompt segments for judging something the kid typed. */
+export function buildInputSegments(kidText) {
+    return [
+        { kind: 'fixed', text: `${INPUT_HEADER}USER: ` },
+        { kind: 'judged', text: sanitizeJudged(kidText) },
+        { kind: 'fixed', text: INPUT_FOOTER },
+    ];
+}
+/**
+ * Prompt segments for judging text the app produced (a reply or file text).
+ * The kid's last message gives the model the exchange it was trained on;
+ * file checks pass an empty string and get a neutral stand-in.
+ */
+export function buildOutputSegments(kidText, producedText) {
+    const kid = sanitizeJudged(kidText.slice(0, 500)).trim() || 'Please help me with my project.';
+    return [
+        { kind: 'fixed', text: `${OUTPUT_HEADER}USER: ` },
+        { kind: 'judged', text: kid },
+        { kind: 'fixed', text: '\n\nASSISTANT: ' },
+        { kind: 'judged', text: sanitizeJudged(producedText) },
+        { kind: 'fixed', text: OUTPUT_FOOTER },
+    ];
+}
+/** Flattens segments into the exact prompt string (tests and debugging). */
+export function renderSegments(segments) {
+    return segments.map((s) => s.text).join('');
+}
+const GUARD_NAME_LOOKUP = new Map(GUARD_CATEGORIES.map((c) => [c.toLowerCase(), c]));
+/**
+ * Parses the guard completion. The verdict must LEAD it: the first
+ * non-empty line has to be the Safety line, and Categories/Refusal are
+ * read only from the two lines after it. A completion that opens with
+ * anything else, including an induced echo of judged text, throws, and
+ * the caller turns that into a fail-closed block.
+ */
+export function parseGuardReading(raw) {
+    const lines = raw
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    const safety = /^Safety:\s*(Safe|Unsafe|Controversial)\b/i.exec(lines[0] ?? '');
+    if (safety === null) {
+        throw new Error('guard-verdict-missing');
+    }
+    const matched = safety[1].toLowerCase();
+    const level = (matched.charAt(0).toUpperCase() + matched.slice(1));
+    const window = lines.slice(1, 3);
+    const categories = [];
+    const catLine = window.map((l) => /^Categories:\s*(.+)$/i.exec(l)).find((m) => m !== null);
+    if (catLine !== undefined && catLine !== null) {
+        for (const piece of catLine[1].split(',')) {
+            const name = piece.trim().replace(/[.]+$/, '').trim();
+            if (name.length === 0 || /^none$/i.test(name)) {
+                continue;
+            }
+            const known = GUARD_NAME_LOOKUP.get(name.toLowerCase());
+            if (known !== undefined && !categories.includes(known)) {
+                categories.push(known);
+            }
+        }
+    }
+    const refusalLine = window.map((l) => /^Refusal:\s*(Yes|No)\b/i.exec(l)).find((m) => m !== null);
+    const refusal = refusalLine === undefined || refusalLine === null ? null : /yes/i.test(refusalLine[1]);
+    return { level, categories, refusal };
+}
+/** Severity for a guard level: Unsafe 2, Controversial 1, Safe 0. */
+export function guardSeverity(level) {
+    if (level === 'Unsafe')
+        return 2;
+    if (level === 'Controversial')
+        return 1;
+    return 0;
+}
+/**
+ * Maps a guard reading onto Termi's verdict shape. Unsafe always blocks
+ * (every category's threshold is at or below severity 2, and an Unsafe
+ * reading with no recognizable category still blocks generically rather
+ * than sliding through). Controversial blocks only the severity-1
+ * categories (pii, jailbreak), matching the taxonomy thresholds.
+ */
+export function guardVerdict(reading) {
+    const severity = guardSeverity(reading.level);
+    const categories = [];
+    for (const guardCategory of reading.categories) {
+        const mapped = GUARD_TO_TERMI[guardCategory];
+        if (!categories.includes(mapped)) {
+            categories.push(mapped);
+        }
+    }
+    const blocked = reading.level === 'Unsafe' ? true : severityBlocks(categories, severity);
+    return {
+        allowed: !blocked,
+        categories,
+        severity,
+        selfHarmConcern: categories.includes('self_harm'),
+        failClosed: false,
+        kidMessage: blocked ? blockMessage(categories) : null,
+    };
+}

package/dist/safety/modelstore.js

@@ -0,0 +1,127 @@
+/**
+ * On-disk store for the local safety-classifier model.
+ *
+ * One pinned artifact: repo, file, byte size, and sha256 are constants.
+ * Downloads stream to a temp file in the models directory, the digest is
+ * computed while writing, and only a byte-for-byte verified file is
+ * renamed into place. A partial or tampered download can never be loaded
+ * because readiness checks the exact size and load happens only after the
+ * atomic rename.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import { modelsDir } from '../config/paths.js';
+/** The pinned classifier artifact. Update size and digest together. */
+export const GUARD_MODEL = {
+    /** Friendly name shown to parents. */
+    name: 'Qwen3Guard 0.6B safety checker',
+    fileName: 'Qwen3Guard-Gen-0.6B.Q6_K.gguf',
+    url: 'https://huggingface.co/QuantFactory/Qwen3Guard-Gen-0.6B-GGUF/resolve/main/' +
+        'Qwen3Guard-Gen-0.6B.Q6_K.gguf',
+    bytes: 622733312,
+    sha256: '33a70125c0fff6805e1a1b8b99f59981c6cd3f724a06bf3a99c16dfa8326e585',
+    displaySize: '623 MB',
+};
+export function guardModelPath() {
+    return path.join(modelsDir(), GUARD_MODEL.fileName);
+}
+/** True when the model file exists with exactly the pinned size. */
+export function guardModelReady() {
+    try {
+        return fs.statSync(guardModelPath()).size === GUARD_MODEL.bytes;
+    }
+    catch {
+        return false;
+    }
+}
+export function removeGuardModel() {
+    fs.rmSync(guardModelPath(), { force: true });
+}
+/** Where an in-progress download accumulates. Stable name enables resume. */
+export function guardPartialPath(artifact = GUARD_MODEL) {
+    return `${path.join(modelsDir(), artifact.fileName)}.partial`;
+}
+/** Streams a whole file through sha256. The disk contents are the truth. */
+export async function sha256OfFile(filePath) {
+    const hash = crypto.createHash('sha256');
+    await new Promise((resolve, reject) => {
+        const stream = fs.createReadStream(filePath);
+        stream.on('data', (chunk) => hash.update(chunk));
+        stream.on('end', resolve);
+        stream.on('error', reject);
+    });
+    return hash.digest('hex');
+}
+/**
+ * Downloads and verifies the model, resuming a previous partial download
+ * when the server supports byte ranges. Verification happens against the
+ * file ON DISK after the transfer, immediately before the rename, so bytes
+ * written by anything else (a concurrent Termi process racing the same
+ * partial path) can never slip an unverified file into place.
+ *
+ * Failure behavior, by cause:
+ * - interrupted transfer: the partial file stays for the next resume.
+ * - digest or oversize problem: the partial is poisoned and deleted.
+ * Only a byte-for-byte verified file is renamed into place.
+ */
+export async function downloadGuardModel(opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const artifact = opts.artifact ?? GUARD_MODEL;
+    const finalPath = path.join(modelsDir(), artifact.fileName);
+    const partialPath = guardPartialPath(artifact);
+    fs.mkdirSync(path.dirname(finalPath), { recursive: true });
+    let offset = 0;
+    try {
+        const size = fs.statSync(partialPath).size;
+        if (size > 0 && size < artifact.bytes) {
+            offset = size;
+        }
+        else if (size >= artifact.bytes) {
+            // A partial at or past the full size can never verify; start over.
+            fs.rmSync(partialPath, { force: true });
+        }
+    }
+    catch {
+        // No partial: fresh download.
+    }
+    const res = await fetchImpl(artifact.url, offset > 0 ? { headers: { range: `bytes=${offset}-` } } : undefined);
+    if (!res.ok || res.body === null) {
+        throw new Error(`guard-download-failed:http-${res.status}`);
+    }
+    if (res.status !== 206) {
+        // The server sent the whole file (or ignored the range): restart clean.
+        offset = 0;
+    }
+    let written = offset;
+    try {
+        const source = Readable.fromWeb(res.body);
+        source.on('data', (chunk) => {
+            written += chunk.length;
+            opts.onProgress?.(written, artifact.bytes);
+        });
+        await pipeline(source, fs.createWriteStream(partialPath, { mode: 0o600, flags: offset > 0 ? 'a' : 'w' }));
+    }
+    catch (err) {
+        // Transfer error: keep the partial so the next attempt resumes.
+        throw err instanceof Error ? err : new Error(String(err));
+    }
+    // Judge the file as it exists on disk, not the bytes this process saw.
+    const diskSize = fs.statSync(partialPath).size;
+    if (diskSize < artifact.bytes) {
+        // Short. Keep the partial; the next attempt resumes.
+        throw new Error('guard-download-failed:interrupted');
+    }
+    if (diskSize > artifact.bytes) {
+        fs.rmSync(partialPath, { force: true });
+        throw new Error('guard-download-failed:size-mismatch');
+    }
+    const digest = await sha256OfFile(partialPath);
+    if (digest !== artifact.sha256) {
+        fs.rmSync(partialPath, { force: true });
+        throw new Error('guard-download-failed:digest-mismatch');
+    }
+    fs.renameSync(partialPath, finalPath);
+}