kynjal-cli 3.1.3 → 4.0.0

package/dist/src/appliance/gguf-engine.js

@@ -0,0 +1,664 @@
+/**
+ * ruvLLM GGUF Inference Engine -- Pure Node.js GGUF Model Interface
+ *
+ * Provides:
+ *   1. GGUF binary header parsing (metadata without loading weights)
+ *   2. Model loading abstraction (node-llama-cpp when available, metadata-only fallback)
+ *   3. Token generation interface with async iterator streaming
+ *   4. KV-cache persistence to RVF-compatible binary format
+ *
+ * Zero external dependencies. node-llama-cpp is an optional peer.
+ *
+ * @module @claude-flow/cli/appliance/gguf-engine
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function verb(n) { if (g[n]) i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+import { open, readFile, writeFile, stat as fsStat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { basename } from 'node:path';
+// ── GGUF Metadata Value Types ───────────────────────────────
+var GgufValueType;
+(function (GgufValueType) {
+    GgufValueType[GgufValueType["UINT8"] = 0] = "UINT8";
+    GgufValueType[GgufValueType["INT8"] = 1] = "INT8";
+    GgufValueType[GgufValueType["UINT16"] = 2] = "UINT16";
+    GgufValueType[GgufValueType["INT16"] = 3] = "INT16";
+    GgufValueType[GgufValueType["UINT32"] = 4] = "UINT32";
+    GgufValueType[GgufValueType["INT32"] = 5] = "INT32";
+    GgufValueType[GgufValueType["FLOAT32"] = 6] = "FLOAT32";
+    GgufValueType[GgufValueType["BOOL"] = 7] = "BOOL";
+    GgufValueType[GgufValueType["STRING"] = 8] = "STRING";
+    GgufValueType[GgufValueType["ARRAY"] = 9] = "ARRAY";
+    GgufValueType[GgufValueType["UINT64"] = 10] = "UINT64";
+    GgufValueType[GgufValueType["INT64"] = 11] = "INT64";
+    GgufValueType[GgufValueType["FLOAT64"] = 12] = "FLOAT64";
+})(GgufValueType || (GgufValueType = {}));
+var GGUF_MAGIC = 0x46554747; // "GGUF" in little-endian
+var RVKV_MAGIC = 0x564B5652; // "RVKV" in little-endian
+var RVKV_VERSION = 1;
+// ── Internal Buffer Reader ──────────────────────────────────
+/** Stateful cursor over a Buffer for sequential binary reads. */
+var BufferReader = /** @class */ (function () {
+    function BufferReader(buf) {
+        this.buf = buf;
+        this.offset = 0;
+    }
+    Object.defineProperty(BufferReader.prototype, "remaining", {
+        get: function () { return this.buf.length - this.offset; },
+        enumerable: false,
+        configurable: true
+    });
+    BufferReader.prototype.readU8 = function () { var v = this.buf.readUInt8(this.offset); this.offset += 1; return v; };
+    BufferReader.prototype.readI8 = function () { var v = this.buf.readInt8(this.offset); this.offset += 1; return v; };
+    BufferReader.prototype.readU16 = function () { var v = this.buf.readUInt16LE(this.offset); this.offset += 2; return v; };
+    BufferReader.prototype.readI16 = function () { var v = this.buf.readInt16LE(this.offset); this.offset += 2; return v; };
+    BufferReader.prototype.readU32 = function () { var v = this.buf.readUInt32LE(this.offset); this.offset += 4; return v; };
+    BufferReader.prototype.readI32 = function () { var v = this.buf.readInt32LE(this.offset); this.offset += 4; return v; };
+    BufferReader.prototype.readF32 = function () { var v = this.buf.readFloatLE(this.offset); this.offset += 4; return v; };
+    BufferReader.prototype.readF64 = function () { var v = this.buf.readDoubleLE(this.offset); this.offset += 8; return v; };
+    BufferReader.prototype.readU64 = function () { var v = this.buf.readBigUInt64LE(this.offset); this.offset += 8; return v; };
+    BufferReader.prototype.readI64 = function () { var v = this.buf.readBigInt64LE(this.offset); this.offset += 8; return v; };
+    /** Safe for values up to 2^53. Real GGUF files never exceed this for tensor/kv counts. */
+    BufferReader.prototype.readU64AsNumber = function () { return Number(this.readU64()); };
+    BufferReader.prototype.readBool = function () { return this.readU8() !== 0; };
+    /** GGUF string: [length u64 LE][utf-8 bytes]. */
+    BufferReader.prototype.readString = function () {
+        var len = this.readU64AsNumber();
+        if (len === 0)
+            return '';
+        if (len > this.remaining)
+            throw new Error("String length " + len + " exceeds remaining buffer");
+        var s = this.buf.toString('utf-8', this.offset, this.offset + len);
+        this.offset += len;
+        return s;
+    };
+    return BufferReader;
+}());
+// ── GGUF Value Reading ──────────────────────────────────────
+/** Read a typed scalar from the buffer (shared by value and array-element readers). */
+function readScalar(reader, t) {
+    switch (t) {
+        case GgufValueType.UINT8: return reader.readU8();
+        case GgufValueType.INT8: return reader.readI8();
+        case GgufValueType.UINT16: return reader.readU16();
+        case GgufValueType.INT16: return reader.readI16();
+        case GgufValueType.UINT32: return reader.readU32();
+        case GgufValueType.INT32: return reader.readI32();
+        case GgufValueType.FLOAT32: return reader.readF32();
+        case GgufValueType.BOOL: return reader.readBool();
+        case GgufValueType.STRING: return reader.readString();
+        case GgufValueType.UINT64: return Number(reader.readU64());
+        case GgufValueType.INT64: return Number(reader.readI64());
+        case GgufValueType.FLOAT64: return reader.readF64();
+        default: return undefined;
+    }
+}
+/** Read a single GGUF typed value (scalar or array) from the buffer. */
+function readGgufValue(reader) {
+    var valueType = reader.readU32();
+    if (valueType === GgufValueType.ARRAY) {
+        var elemType = reader.readU32();
+        var len = reader.readU64AsNumber();
+        var arr = [];
+        for (var i = 0; i < len; i++) {
+            var v_1 = readScalar(reader, elemType);
+            if (v_1 === undefined)
+                throw new Error("Unknown GGUF array element type: " + elemType);
+            arr.push(v_1);
+        }
+        return arr;
+    }
+    var v = readScalar(reader, valueType);
+    if (v === undefined)
+        throw new Error("Unknown GGUF value type: " + valueType);
+    return v;
+}
+// ── GGUF Header Parsing ─────────────────────────────────────
+/**
+ * Parse the header and metadata from a GGUF file without loading tensors.
+ * Reads only the first 256 KB of the file.
+ */
+export function parseGgufHeader(path) {
+    return __awaiter(this, void 0, Promise, function () {
+        var fileInfo, readSize, fh, buf;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, fsStat(path)];
+                case 1:
+                    fileInfo = _a.sent();
+                    readSize = Math.min(fileInfo.size, 256 * 1024);
+                    return [4 /*yield*/, open(path, 'r')];
+                case 2:
+                    fh = _a.sent();
+                    _a.label = 3;
+                case 3:
+                    _a.trys.push([3, , 5, 7]);
+                    buf = Buffer.alloc(readSize);
+                    return [4 /*yield*/, fh.read(buf, 0, readSize, 0)];
+                case 4:
+                    _a.sent();
+                    return [2 /*return*/, parseGgufBuffer(buf, fileInfo.size, path)];
+                case 5: return [4 /*yield*/, fh.close()];
+                case 6:
+                    _a.sent();
+                    return [7 /*endfinally*/];
+                case 7: return [2 /*return*/];
+            }
+        });
+    });
+}
+function parseGgufBuffer(buf, fileSize, filePath) {
+    var reader = new BufferReader(buf);
+    var magic = reader.readU32();
+    if (magic !== GGUF_MAGIC) {
+        throw new Error("Invalid GGUF magic: 0x" + magic.toString(16) + " (expected 0x" + GGUF_MAGIC.toString(16) + ")");
+    }
+    var version = reader.readU32();
+    if (version < 2 || version > 3) {
+        throw new Error("Unsupported GGUF version: " + version + " (expected 2 or 3)");
+    }
+    var tensorCount = reader.readU64AsNumber();
+    var kvCount = reader.readU64AsNumber();
+    var metadata = {};
+    for (var i = 0; i < kvCount; i++) {
+        if (reader.remaining < 12)
+            break;
+        try {
+            var key = reader.readString();
+            metadata[key] = readGgufValue(reader);
+        }
+        catch (_a) {
+            break; // reached end of read window
+        }
+    }
+    var arch = asString(metadata['general.architecture']);
+    var pfx = arch || 'llama'; // fallback prefix for well-known keys
+    return {
+        magic: 'GGUF',
+        version: version,
+        tensorCount: tensorCount,
+        kvCount: kvCount,
+        architecture: arch,
+        name: asString(metadata['general.name']),
+        contextLength: asNumber(metadata[pfx + ".context_length"]),
+        embeddingLength: asNumber(metadata[pfx + ".embedding_length"]),
+        blockCount: asNumber(metadata[pfx + ".block_count"]),
+        vocabSize: inferVocabSize(metadata),
+        quantization: inferQuantFromMetadata(metadata, filePath),
+        fileSize: fileSize,
+        metadata: metadata
+    };
+}
+// ── Metadata Helpers ────────────────────────────────────────
+function asString(v) { return typeof v === 'string' ? v : undefined; }
+function asNumber(v) { return typeof v === 'number' ? v : undefined; }
+var QUANT_RE = [
+    [/q2_k/i, 'Q2_K'], [/q3_k_s/i, 'Q3_K_S'], [/q3_k_m/i, 'Q3_K_M'], [/q3_k_l/i, 'Q3_K_L'],
+    [/q4_k_s/i, 'Q4_K_S'], [/q4_k_m/i, 'Q4_K_M'], [/q4_0/i, 'Q4_0'], [/q4_1/i, 'Q4_1'],
+    [/q5_k_s/i, 'Q5_K_S'], [/q5_k_m/i, 'Q5_K_M'], [/q5_0/i, 'Q5_0'], [/q5_1/i, 'Q5_1'],
+    [/q6_k/i, 'Q6_K'], [/q8_0/i, 'Q8_0'], [/f16/i, 'F16'], [/f32/i, 'F32'],
+];
+function inferQuantFromMetadata(meta, filePath) {
+    var ft = meta['general.file_type'];
+    if (typeof ft === 'number')
+        return "file_type_" + ft;
+    var name = basename(filePath);
+    for (var _i = 0, QUANT_RE_1 = QUANT_RE; _i < QUANT_RE_1.length; _i++) {
+        var _a = QUANT_RE_1[_i], re = _a[0], label = _a[1];
+        if (re.test(name))
+            return label;
+    }
+    return 'unknown';
+}
+function inferVocabSize(meta) {
+    var tokens = meta['tokenizer.ggml.tokens'];
+    if (Array.isArray(tokens))
+        return tokens.length;
+    return asNumber(meta['tokenizer.ggml.vocab_size']);
+}
+// ── GGUF Engine ─────────────────────────────────────────────
+var GgufEngine = /** @class */ (function () {
+    function GgufEngine(config) {
+        var _a, _b, _c, _d, _e;
+        this.llamaCpp = null;
+        this.llamaModel = null;
+        this.llamaContext = null;
+        this.loadedModels = new Map();
+        this.activeModelPath = null;
+        this.kvCache = new Map();
+        this.config = {
+            contextSize: (_a = config.contextSize) !== null && _a !== void 0 ? _a : 4096,
+            maxTokens: (_b = config.maxTokens) !== null && _b !== void 0 ? _b : 512,
+            temperature: (_c = config.temperature) !== null && _c !== void 0 ? _c : 0.7,
+            kvCachePath: (_d = config.kvCachePath) !== null && _d !== void 0 ? _d : '',
+            verbose: (_e = config.verbose) !== null && _e !== void 0 ? _e : false
+        };
+    }
+    /** Probe for node-llama-cpp availability. */
+    GgufEngine.prototype.initialize = function () {
+        return __awaiter(this, void 0, Promise, function () {
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        _a = this;
+                        return [4 /*yield*/, this.tryLoadLlamaCpp()];
+                    case 1:
+                        _a.llamaCpp = _b.sent();
+                        if (this.config.verbose) {
+                            console.log("[gguf-engine] node-llama-cpp: " + (this.llamaCpp ? 'available' : 'not found (metadata-only mode)'));
+                        }
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /** Parse GGUF header and optionally load the model for inference. */
+    GgufEngine.prototype.loadModel = function (path) {
+        return __awaiter(this, void 0, Promise, function () {
+            var meta, getLlama, llama, _a, _b, err_1;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0: return [4 /*yield*/, parseGgufHeader(path)];
+                    case 1:
+                        meta = _c.sent();
+                        this.loadedModels.set(path, meta);
+                        this.activeModelPath = path;
+                        if (!this.llamaCpp) return [3 /*break*/, 7];
+                        _c.label = 2;
+                    case 2:
+                        _c.trys.push([2, 6, , 7]);
+                        getLlama = this.llamaCpp.getLlama;
+                        return [4 /*yield*/, getLlama()];
+                    case 3:
+                        llama = _c.sent();
+                        _a = this;
+                        return [4 /*yield*/, llama.loadModel({ modelPath: path })];
+                    case 4:
+                        _a.llamaModel = _c.sent();
+                        _b = this;
+                        return [4 /*yield*/, this.llamaModel.createContext({ contextSize: this.config.contextSize })];
+                    case 5:
+                        _b.llamaContext = _c.sent();
+                        if (this.config.verbose)
+                            console.log("[gguf-engine] Model loaded: " + basename(path));
+                        return [3 /*break*/, 7];
+                    case 6:
+                        err_1 = _c.sent();
+                        if (this.config.verbose)
+                            console.warn('[gguf-engine] node-llama-cpp load failed:', err_1);
+                        this.llamaModel = null;
+                        this.llamaContext = null;
+                        return [3 /*break*/, 7];
+                    case 7: return [2 /*return*/, meta];
+                }
+            });
+        });
+    };
+    /** Generate text. Delegates to node-llama-cpp or returns a metadata-only stub. */
+    GgufEngine.prototype.generate = function (request) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        return __awaiter(this, void 0, Promise, function () {
+            var start, modelPath, modelName, session, text, tokensUsed, seq, err_2, meta;
+            var _this = this;
+            return __generator(this, function (_h) {
+                switch (_h.label) {
+                    case 0:
+                        start = performance.now();
+                        modelPath = (_a = request.model) !== null && _a !== void 0 ? _a : this.activeModelPath;
+                        modelName = modelPath ? basename(modelPath) : 'none';
+                        if (!(this.llamaContext && this.llamaModel)) return [3 /*break*/, 4];
+                        _h.label = 1;
+                    case 1:
+                        _h.trys.push([1, 3, , 4]);
+                        session = new this.llamaCpp.LlamaChatSession({
+                            contextSequence: this.llamaContext.getSequence()
+                        });
+                        return [4 /*yield*/, session.prompt(request.prompt, {
+                                maxTokens: (_b = request.maxTokens) !== null && _b !== void 0 ? _b : this.config.maxTokens,
+                                temperature: (_c = request.temperature) !== null && _c !== void 0 ? _c : this.config.temperature,
+                                stopGenerationTrigger: request.stopSequences
+                                    ? request.stopSequences.map(function (s) { return new _this.llamaCpp.LlamaText([s]); })
+                                    : undefined
+                            })];
+                    case 2:
+                        text = _h.sent();
+                        tokensUsed = void 0;
+                        try {
+                            seq = this.llamaContext.getSequence();
+                            tokensUsed = (_d = seq.tokenCount) !== null && _d !== void 0 ? _d : Math.ceil(text.length / 4);
+                        }
+                        catch (_j) {
+                            tokensUsed = Math.ceil(text.length / 4); // ~4 chars per token heuristic
+                        }
+                        return [2 /*return*/, {
+                                text: text,
+                                model: modelName,
+                                tokensUsed: tokensUsed,
+                                latencyMs: performance.now() - start, metadataOnly: false
+                            }];
+                    case 3:
+                        err_2 = _h.sent();
+                        if (this.config.verbose)
+                            console.warn('[gguf-engine] Generation failed:', err_2);
+                        return [3 /*break*/, 4];
+                    case 4:
+                        meta = modelPath ? this.loadedModels.get(modelPath) : undefined;
+                        return [2 /*return*/, {
+                                text: meta
+                                    ? "[metadata-only] Model: " + ((_e = meta.name) !== null && _e !== void 0 ? _e : modelName) + ", arch: " + ((_f = meta.architecture) !== null && _f !== void 0 ? _f : 'unknown') + ", ctx: " + ((_g = meta.contextLength) !== null && _g !== void 0 ? _g : 'unknown')
+                                    : '[metadata-only] No model loaded',
+                                model: modelName, tokensUsed: 0,
+                                latencyMs: performance.now() - start, metadataOnly: true
+                            }];
+                }
+            });
+        });
+    };
+    /** Stream tokens via async iterator. Falls back to yielding full response. */
+    GgufEngine.prototype.stream = function (request) {
+        var _a, _b;
+        return __asyncGenerator(this, arguments, function stream_1() {
+            var session, it, it_1, it_1_1, chunk, e_1_1, _c, response;
+            var e_1, _d;
+            return __generator(this, function (_e) {
+                switch (_e.label) {
+                    case 0:
+                        if (!(this.llamaContext && this.llamaModel)) return [3 /*break*/, 22];
+                        _e.label = 1;
+                    case 1:
+                        _e.trys.push([1, 21, , 22]);
+                        session = new this.llamaCpp.LlamaChatSession({
+                            contextSequence: this.llamaContext.getSequence()
+                        });
+                        it = session.promptWithMeta(request.prompt, {
+                            maxTokens: (_a = request.maxTokens) !== null && _a !== void 0 ? _a : this.config.maxTokens,
+                            temperature: (_b = request.temperature) !== null && _b !== void 0 ? _b : this.config.temperature
+                        });
+                        if (!(it && typeof it[Symbol.asyncIterator] === 'function')) return [3 /*break*/, 20];
+                        _e.label = 2;
+                    case 2:
+                        _e.trys.push([2, 12, 13, 18]);
+                        it_1 = __asyncValues(it);
+                        _e.label = 3;
+                    case 3: return [4 /*yield*/, __await(it_1.next())];
+                    case 4:
+                        if (!(it_1_1 = _e.sent(), !it_1_1.done)) return [3 /*break*/, 11];
+                        chunk = it_1_1.value;
+                        if (!(typeof chunk === 'string')) return [3 /*break*/, 7];
+                        return [4 /*yield*/, __await(chunk)];
+                    case 5: return [4 /*yield*/, _e.sent()];
+                    case 6:
+                        _e.sent();
+                        return [3 /*break*/, 10];
+                    case 7:
+                        if (!(chunk === null || chunk === void 0 ? void 0 : chunk.text)) return [3 /*break*/, 10];
+                        return [4 /*yield*/, __await(chunk.text)];
+                    case 8: return [4 /*yield*/, _e.sent()];
+                    case 9:
+                        _e.sent();
+                        _e.label = 10;
+                    case 10: return [3 /*break*/, 3];
+                    case 11: return [3 /*break*/, 18];
+                    case 12:
+                        e_1_1 = _e.sent();
+                        e_1 = { error: e_1_1 };
+                        return [3 /*break*/, 18];
+                    case 13:
+                        _e.trys.push([13, , 16, 17]);
+                        if (!(it_1_1 && !it_1_1.done && (_d = it_1["return"]))) return [3 /*break*/, 15];
+                        return [4 /*yield*/, __await(_d.call(it_1))];
+                    case 14:
+                        _e.sent();
+                        _e.label = 15;
+                    case 15: return [3 /*break*/, 17];
+                    case 16:
+                        if (e_1) throw e_1.error;
+                        return [7 /*endfinally*/];
+                    case 17: return [7 /*endfinally*/];
+                    case 18: return [4 /*yield*/, __await(void 0)];
+                    case 19: return [2 /*return*/, _e.sent()];
+                    case 20: return [3 /*break*/, 22];
+                    case 21:
+                        _c = _e.sent();
+                        return [3 /*break*/, 22];
+                    case 22: return [4 /*yield*/, __await(this.generate(request))];
+                    case 23:
+                        response = _e.sent();
+                        return [4 /*yield*/, __await(response.text)];
+                    case 24: return [4 /*yield*/, _e.sent()];
+                    case 25:
+                        _e.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Persist the KV cache to an RVF-compatible binary file.
+     * Format: RVKV magic | version u32 | model SHA-256 (32B) | entry count u32
+     *         entries: [key_len u32, key, val_len u32, val] | footer SHA-256 (32B)
+     */
+    GgufEngine.prototype.persistKvCache = function (outputPath) {
+        var _a;
+        return __awaiter(this, void 0, Promise, function () {
+            var path, modelHash, entryBufs, _i, _b, _c, key, value, keyBuf, hdr, entryData, footer, header;
+            return __generator(this, function (_d) {
+                switch (_d.label) {
+                    case 0:
+                        path = outputPath || this.config.kvCachePath;
+                        if (!path)
+                            throw new Error('No KV cache output path specified');
+                        modelHash = createHash('sha256').update((_a = this.activeModelPath) !== null && _a !== void 0 ? _a : 'no-model').digest();
+                        entryBufs = [];
+                        for (_i = 0, _b = this.kvCache; _i < _b.length; _i++) {
+                            _c = _b[_i], key = _c[0], value = _c[1];
+                            keyBuf = Buffer.from(key, 'utf-8');
+                            hdr = Buffer.alloc(8);
+                            hdr.writeUInt32LE(keyBuf.length, 0);
+                            hdr.writeUInt32LE(value.length, 4);
+                            entryBufs.push(hdr, keyBuf, value);
+                        }
+                        entryData = Buffer.concat(entryBufs);
+                        footer = createHash('sha256').update(entryData).digest();
+                        header = Buffer.alloc(44);
+                        header.writeUInt32LE(RVKV_MAGIC, 0);
+                        header.writeUInt32LE(RVKV_VERSION, 4);
+                        modelHash.copy(header, 8);
+                        header.writeUInt32LE(this.kvCache.size, 40);
+                        return [4 /*yield*/, writeFile(path, Buffer.concat([header, entryData, footer]))];
+                    case 1:
+                        _d.sent();
+                        if (this.config.verbose)
+                            console.log("[gguf-engine] KV cache persisted: " + this.kvCache.size + " entries");
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /** Restore KV cache from an RVF-compatible binary file. */
+    GgufEngine.prototype.loadKvCache = function (inputPath) {
+        return __awaiter(this, void 0, Promise, function () {
+            var data, magic, version, entryCount, offset, entries, i, keyLen, valLen, stored, computed;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, readFile(inputPath)];
+                    case 1:
+                        data = _a.sent();
+                        if (data.length < 44)
+                            throw new Error('KV cache file too small');
+                        magic = data.readUInt32LE(0);
+                        if (magic !== RVKV_MAGIC)
+                            throw new Error("Invalid KV cache magic: 0x" + magic.toString(16));
+                        version = data.readUInt32LE(4);
+                        if (version !== RVKV_VERSION)
+                            throw new Error("Unsupported KV cache version: " + version);
+                        entryCount = data.readUInt32LE(40);
+                        offset = 44;
+                        entries = new Map();
+                        for (i = 0; i < entryCount; i++) {
+                            if (offset + 8 > data.length)
+                                throw new Error('KV cache file truncated');
+                            keyLen = data.readUInt32LE(offset);
+                            valLen = data.readUInt32LE(offset + 4);
+                            offset += 8;
+                            if (offset + keyLen + valLen > data.length)
+                                throw new Error('KV cache file truncated');
+                            entries.set(data.toString('utf-8', offset, offset + keyLen), Buffer.from(data.subarray(offset + keyLen, offset + keyLen + valLen)));
+                            offset += keyLen + valLen;
+                        }
+                        // Verify footer hash (mandatory)
+                        if (offset + 32 > data.length) {
+                            throw new Error('KV cache file missing SHA256 footer');
+                        }
+                        stored = data.subarray(offset, offset + 32);
+                        computed = createHash('sha256').update(data.subarray(44, offset)).digest();
+                        if (!stored.equals(computed))
+                            throw new Error('KV cache integrity check failed: hash mismatch');
+                        this.kvCache = entries;
+                        if (this.config.verbose)
+                            console.log("[gguf-engine] KV cache loaded: " + entries.size + " entries");
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /** Return metadata for all loaded models. */
+    GgufEngine.prototype.getLoadedModels = function () { return Array.from(this.loadedModels.values()); };
+    /** Store a key-value pair in the in-memory KV cache. */
+    GgufEngine.prototype.setKvEntry = function (key, value) { this.kvCache.set(key, value); };
+    /** Retrieve a key-value pair from the in-memory KV cache. */
+    GgufEngine.prototype.getKvEntry = function (key) { return this.kvCache.get(key); };
+    /** Release resources, unload models, and optionally persist the KV cache. */
+    GgufEngine.prototype.shutdown = function () {
+        var _a, _b;
+        return __awaiter(this, void 0, Promise, function () {
+            var err_3, _c, _d;
+            return __generator(this, function (_e) {
+                switch (_e.label) {
+                    case 0:
+                        if (!(this.config.kvCachePath && this.kvCache.size > 0)) return [3 /*break*/, 4];
+                        _e.label = 1;
+                    case 1:
+                        _e.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, this.persistKvCache(this.config.kvCachePath)];
+                    case 2:
+                        _e.sent();
+                        return [3 /*break*/, 4];
+                    case 3:
+                        err_3 = _e.sent();
+                        if (this.config.verbose)
+                            console.warn('[gguf-engine] KV persist failed:', err_3);
+                        return [3 /*break*/, 4];
+                    case 4:
+                        if (!((_a = this.llamaContext) === null || _a === void 0 ? void 0 : _a.dispose)) return [3 /*break*/, 8];
+                        _e.label = 5;
+                    case 5:
+                        _e.trys.push([5, 7, , 8]);
+                        return [4 /*yield*/, this.llamaContext.dispose()];
+                    case 6:
+                        _e.sent();
+                        return [3 /*break*/, 8];
+                    case 7:
+                        _c = _e.sent();
+                        return [3 /*break*/, 8];
+                    case 8:
+                        if (!((_b = this.llamaModel) === null || _b === void 0 ? void 0 : _b.dispose)) return [3 /*break*/, 12];
+                        _e.label = 9;
+                    case 9:
+                        _e.trys.push([9, 11, , 12]);
+                        return [4 /*yield*/, this.llamaModel.dispose()];
+                    case 10:
+                        _e.sent();
+                        return [3 /*break*/, 12];
+                    case 11:
+                        _d = _e.sent();
+                        return [3 /*break*/, 12];
+                    case 12:
+                        this.llamaContext = null;
+                        this.llamaModel = null;
+                        this.activeModelPath = null;
+                        this.loadedModels.clear();
+                        this.kvCache.clear();
+                        if (this.config.verbose)
+                            console.log('[gguf-engine] Shutdown complete');
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    // ── Private ───────────────────────────────────────────────
+    GgufEngine.prototype.tryLoadLlamaCpp = function () {
+        return __awaiter(this, void 0, Promise, function () {
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        _b.trys.push([0, 2, , 3]);
+                        return [4 /*yield*/, import('node-llama-cpp')];
+                    case 1: return [2 /*return*/, _b.sent()];
+                    case 2:
+                        _a = _b.sent();
+                        return [2 /*return*/, null];
+                    case 3: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    return GgufEngine;
+}());
+export { GgufEngine };
+//# sourceMappingURL=gguf-engine.js.map