@atomic-chat/core 0.19.1 → 0.20.6

package/dist/runtime/geniex/host/grammar.js

@@ -0,0 +1,223 @@
+/**
+ * A JSON schema as a llama.cpp GBNF grammar (openspec change `add-geniex-runtime`, design D6): GenieX's
+ * sampler takes `grammar_string`, and its C API offers no converter, so `response_format` is turned
+ * into one here — a TypeScript rendering of llama.cpp's `json_schema_to_grammar` (MIT), kept to what
+ * OpenAI structured outputs use: objects with required and optional properties, arrays with bounds,
+ * strings with enums, lengths and the date/time/uuid formats, numbers, integers, booleans, null,
+ * `anyOf`/`oneOf`, `const`, `enum`, local `$ref`s. A schema it cannot express falls back to a looser
+ * rule rather than failing the request (`unknown` → any JSON value; a `pattern` → any string).
+ */
+const PRIMITIVE_RULES = {
+    'boolean': '("true" | "false") space',
+    'decimal-part': '[0-9]{1,16}',
+    'integral-part': '[0] | [1-9] [0-9]{0,15}',
+    'number': '("-"? integral-part) ("." decimal-part)? ([eE] [-+]? integral-part)? space',
+    'integer': '("-"? integral-part) space',
+    'value': 'object | array | string | number | boolean | null',
+    'object': '"{" space ( string ":" space value ("," space string ":" space value)* )? "}" space',
+    'array': '"[" space ( value ("," space value)* )? "]" space',
+    'uuid': '"\\"" [0-9a-fA-F]{8} "-" [0-9a-fA-F]{4} "-" [0-9a-fA-F]{4} "-" [0-9a-fA-F]{4} "-" [0-9a-fA-F]{12} "\\"" space',
+    'char': '[^"\\\\\\x7F\\x00-\\x1F] | [\\\\] (["\\\\bfnrt] | "u" [0-9a-fA-F]{4})',
+    'string': '"\\"" char* "\\"" space',
+    'null': '"null" space',
+};
+/** Which primitive rules another one needs. */
+const PRIMITIVE_DEPS = {
+    number: ['integral-part', 'decimal-part'],
+    integer: ['integral-part'],
+    value: ['object', 'array', 'string', 'number', 'boolean', 'null'],
+    object: ['string', 'value'],
+    array: ['value'],
+    string: ['char'],
+};
+const DATE_RULES = {
+    'date': '[0-9]{4} "-" ( "0" [1-9] | "1" [0-2] ) "-" ( "0" [1-9] | [1-2] [0-9] | "3" [0-1] )',
+    'time': '([01] [0-9] | "2" [0-3]) ":" [0-5] [0-9] ":" [0-5] [0-9] ( "." [0-9]{3} )? ( "Z" | ( "+" | "-" ) ( [01] [0-9] | "2" [0-3] ) ":" [0-5] [0-9] )',
+    'date-time': 'date "T" time',
+    'date-string': '"\\"" date "\\"" space',
+    'time-string': '"\\"" time "\\"" space',
+    'date-time-string': '"\\"" date-time "\\"" space',
+};
+const DATE_DEPS = {
+    'date-time': ['date', 'time'],
+    'date-string': ['date'],
+    'time-string': ['time'],
+    'date-time-string': ['date-time'],
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** A JSON literal as a GBNF string token. */
+function literal(value) {
+    const text = JSON.stringify(value);
+    return `"${text.replace(/[\\"]/g, (c) => `\\${c}`).replace(/\n/g, '\\n')}"`;
+}
+/** `{min,max}` after a rule; `*`, `+` and `?` where they say it shorter. */
+function repeat(rule, min, max) {
+    if (max === null) {
+        if (min === 0)
+            return `${rule}*`;
+        if (min === 1)
+            return `${rule}+`;
+        return `${rule}{${min},}`;
+    }
+    if (min === max && min === 1)
+        return rule;
+    if (min === 0 && max === 1)
+        return `${rule}?`;
+    return `${rule}{${min},${max}}`;
+}
+class GrammarBuilder {
+    root;
+    rules = new Map([['space', '| " " | "\\n"{1,2} [ \\t]{0,20}']]);
+    refs;
+    constructor(root) {
+        this.root = root;
+        const defs = {
+            ...(isRecord(root['definitions']) ? root['definitions'] : {}),
+            ...(isRecord(root['$defs']) ? root['$defs'] : {}),
+        };
+        this.refs = defs;
+    }
+    add(name, rule) {
+        const key = name.replace(/[^a-zA-Z0-9-]+/g, '-');
+        let unique = key;
+        let n = 0;
+        while (this.rules.has(unique) && this.rules.get(unique) !== rule)
+            unique = `${key}${++n}`;
+        this.rules.set(unique, rule);
+        return unique;
+    }
+    primitive(name) {
+        const rule = PRIMITIVE_RULES[name] ?? DATE_RULES[name];
+        if (!rule)
+            throw new Error(`no primitive ${name}`);
+        if (this.rules.has(name))
+            return name;
+        // Registered before its dependencies: `value` and `object` need each other.
+        this.rules.set(name, rule);
+        for (const dep of PRIMITIVE_DEPS[name] ?? DATE_DEPS[name] ?? [])
+            this.primitive(dep);
+        return name;
+    }
+    resolve(ref) {
+        const match = /^#\/(?:\$defs|definitions)\/(.+)$/.exec(ref);
+        const target = match ? this.refs[match[1]] : undefined;
+        if (!isRecord(target))
+            throw new Error(`cannot resolve ${ref}`);
+        return target;
+    }
+    visit(schema, name) {
+        if (!isRecord(schema))
+            return this.primitive('value');
+        const ruleName = name || 'root';
+        if (typeof schema['$ref'] === 'string')
+            return this.visit(this.resolve(schema['$ref']), ruleName);
+        const types = Array.isArray(schema['type']) ? schema['type'] : schema['type'];
+        const alternatives = (schema['oneOf'] ?? schema['anyOf']);
+        if (Array.isArray(alternatives))
+            return this.add(ruleName, alternatives.map((alt, i) => this.visit(alt, `${ruleName}-${i}`)).join(' | '));
+        if (Array.isArray(types))
+            return this.add(ruleName, types.map((type, i) => this.visit({ ...schema, type }, `${ruleName}-${i}`)).join(' | '));
+        if ('const' in schema)
+            return this.add(ruleName, `${literal(schema['const'])} space`);
+        if (Array.isArray(schema['enum']))
+            return this.add(ruleName, `(${schema['enum'].map(literal).join(' | ')}) space`);
+        if (types === 'object' ||
+            (types === undefined &&
+                (isRecord(schema['properties']) || schema['additionalProperties'] !== undefined)))
+            return this.object(schema, ruleName);
+        if (types === 'array' ||
+            (types === undefined && (schema['items'] !== undefined || schema['prefixItems'] !== undefined)))
+            return this.array(schema, ruleName);
+        if (types === 'string')
+            return this.string(schema, ruleName);
+        if (types === 'number' || types === 'integer' || types === 'boolean' || types === 'null')
+            return this.primitive(types);
+        return this.primitive('value');
+    }
+    string(schema, name) {
+        const format = schema['format'];
+        if (format === 'date' || format === 'time' || format === 'date-time')
+            return this.primitive(`${format}-string`);
+        if (format === 'uuid')
+            return this.primitive('uuid');
+        const min = typeof schema['minLength'] === 'number' ? schema['minLength'] : 0;
+        const max = typeof schema['maxLength'] === 'number' ? schema['maxLength'] : null;
+        if (min === 0 && max === null)
+            return this.primitive('string');
+        this.primitive('char');
+        return this.add(name, `"\\"" ${repeat('char', min, max)} "\\"" space`);
+    }
+    array(schema, name) {
+        const prefix = Array.isArray(schema['prefixItems']) ? schema['prefixItems'] : null;
+        if (prefix) {
+            const items = prefix.map((item, i) => this.visit(item, `${name}-tuple-${i}`));
+            return this.add(name, `"[" space ${items.join(' "," space ')} "]" space`);
+        }
+        const item = this.visit(schema['items'] ?? {}, `${name}-item`);
+        const min = typeof schema['minItems'] === 'number' ? schema['minItems'] : 0;
+        const max = typeof schema['maxItems'] === 'number' ? schema['maxItems'] : null;
+        const rest = max === null
+            ? `("," space ${item})*`
+            : repeat(`("," space ${item})`, Math.max(0, min - 1), Math.max(0, max - 1));
+        const body = max === 0 ? '' : min === 0 ? `(${item} ${rest})?` : `${item} ${rest}`;
+        return this.add(name, `"[" space ${body} "]" space`.replace(/\s+/g, ' ').trim());
+    }
+    object(schema, name) {
+        const properties = isRecord(schema['properties']) ? schema['properties'] : {};
+        const required = new Set(Array.isArray(schema['required']) ? schema['required'] : []);
+        const additional = schema['additionalProperties'];
+        const entries = Object.entries(properties);
+        const kv = (key, valueRule) => this.add(`${name}-${key}-kv`, `${literal(key)} space ":" space ${valueRule}`);
+        const requiredRules = [];
+        const optionalRules = [];
+        for (const [key, value] of entries) {
+            const rule = kv(key, this.visit(value, `${name}-${key}`));
+            if (required.has(key))
+                requiredRules.push(rule);
+            else
+                optionalRules.push(rule);
+        }
+        let additionalRule = null;
+        if (additional === true || additional === undefined || isRecord(additional)) {
+            // OpenAI structured outputs set it to false; otherwise free keys follow the typed ones.
+            const value = isRecord(additional)
+                ? this.visit(additional, `${name}-additional`)
+                : this.primitive('value');
+            this.primitive('string');
+            additionalRule = this.add(`${name}-additional-kv`, `string ":" space ${value}`);
+        }
+        const optionals = [...optionalRules, ...(additionalRule ? [additionalRule] : [])];
+        let rule = '"{" space ';
+        if (requiredRules.length > 0)
+            rule += requiredRules.join(' "," space ');
+        if (optionals.length > 0) {
+            const tail = optionals.map((opt) => additionalRule === opt ? `( "," space ${opt} )*` : `( "," space ${opt} )?`);
+            if (requiredRules.length > 0)
+                rule += ` ${tail.join(' ')}`;
+            else {
+                // No required property: the first one present has no leading comma.
+                const firsts = optionals.map((opt, i) => {
+                    const after = optionals
+                        .slice(i + 1)
+                        .map((o) => (additionalRule === o ? `( "," space ${o} )*` : `( "," space ${o} )?`));
+                    const self = additionalRule === opt ? `${opt} ( "," space ${opt} )*` : opt;
+                    return `${self}${after.length > 0 ? ` ${after.join(' ')}` : ''}`;
+                });
+                rule += `( ${firsts.join(' | ')} )?`;
+            }
+        }
+        rule += ' "}" space';
+        return this.add(name, rule.replace(/\s+/g, ' ').trim());
+    }
+    format() {
+        return [...this.rules.entries()].map(([name, rule]) => `${name} ::= ${rule}`).join('\n') + '\n';
+    }
+}
+/** The GBNF for a JSON schema; `root` is the schema itself. */
+export function jsonSchemaToGrammar(schema) {
+    const builder = new GrammarBuilder(isRecord(schema) ? schema : {});
+    const root = builder.visit(schema, 'root');
+    const text = builder.format();
+    return root === 'root' ? text : `root ::= ${root}\n${text}`;
+}
+//# sourceMappingURL=grammar.js.map

package/dist/runtime/geniex/host/grammar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar.js","sourceRoot":"","sources":["../../../../src/runtime/geniex/host/grammar.ts"],"names":[],"mappings":"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"}

package/dist/runtime/geniex/host/inspect.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `geniex-host inspect <path>` (openspec change `add-geniex-runtime`, task 5.2): what a model says
+ * about itself, read without the library — GenieX has no metadata call short of creating the model.
+ * A GGUF file is read by its header (`general.architecture`, `<arch>.context_length`,
+ * `general.file_type`, `tokenizer.chat_template`), and an `mmproj*.gguf` beside it means vision; an
+ * AI Hub bundle folder is read by the files AI Hub v0.65.0 puts in it (spike S4, 2026-10-28):
+ * `genie_config.json` (the dialog config with the context size; what makes a folder a bundle),
+ * `metadata.json` (`runtime`, `precision`, tool versions) and `htp_backend_ext_config.json` (the
+ * Hexagon generation, which names the chip). The reader leaves `null` for what it cannot find.
+ */
+import type { GeniexBundleMetadata, GeniexChip, GeniexGgufMetadata, GeniexModelMetadata } from '../../../contracts/index.js';
+/** The bundle's dialog config (design "Бандлы AI Hub", as S4 found it): without it, no bundle. */
+export declare const BUNDLE_MANIFEST = "genie_config.json";
+/** The model cannot be read: not a GGUF file, not a bundle folder, or a broken one. */
+export declare class GeniexInspectError extends Error {
+    constructor(message: string);
+}
+/** A GGUF file's facts from its header, and whether an `mmproj*.gguf` lies beside it. */
+export declare function inspectGgufFile(file: string): Promise<GeniexGgufMetadata>;
+/** `x-elite` from the spellings AI Hub uses (`qualcomm-snapdragon-x-elite`, `Snapdragon X Elite`, `x-elite`). */
+export declare function bundleChip(value: unknown): GeniexChip | null;
+/** An AI Hub bundle folder's facts from `genie_config.json`, `metadata.json` and the HTP config. */
+export declare function inspectBundle(dir: string): Promise<GeniexBundleMetadata>;
+/** A file is a GGUF; a folder is a bundle. */
+export declare function inspectGeniexModel(path: string): Promise<GeniexModelMetadata>;

package/dist/runtime/geniex/host/inspect.js

@@ -0,0 +1,177 @@
+/**
+ * `geniex-host inspect <path>` (openspec change `add-geniex-runtime`, task 5.2): what a model says
+ * about itself, read without the library — GenieX has no metadata call short of creating the model.
+ * A GGUF file is read by its header (`general.architecture`, `<arch>.context_length`,
+ * `general.file_type`, `tokenizer.chat_template`), and an `mmproj*.gguf` beside it means vision; an
+ * AI Hub bundle folder is read by the files AI Hub v0.65.0 puts in it (spike S4, 2026-10-28):
+ * `genie_config.json` (the dialog config with the context size; what makes a folder a bundle),
+ * `metadata.json` (`runtime`, `precision`, tool versions) and `htp_backend_ext_config.json` (the
+ * Hexagon generation, which names the chip). The reader leaves `null` for what it cannot find.
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { GENIEX_CHIPS } from '../../../contracts/index.js';
+import { GgufParseError, readGgufMetadataFromFile } from '../../../models/index.js';
+/** `llama_ftype` of llama.cpp, by `general.file_type`. */
+const FILE_TYPES = {
+    0: 'F32',
+    1: 'F16',
+    2: 'Q4_0',
+    3: 'Q4_1',
+    7: 'Q8_0',
+    8: 'Q5_0',
+    9: 'Q5_1',
+    10: 'Q2_K',
+    11: 'Q3_K_S',
+    12: 'Q3_K_M',
+    13: 'Q3_K_L',
+    14: 'Q4_K_S',
+    15: 'Q4_K_M',
+    16: 'Q5_K_S',
+    17: 'Q5_K_M',
+    18: 'Q6_K',
+    19: 'IQ2_XXS',
+    20: 'IQ2_XS',
+    21: 'Q2_K_S',
+    22: 'IQ3_XS',
+    23: 'IQ3_XXS',
+    24: 'IQ1_S',
+    25: 'IQ4_NL',
+    26: 'IQ3_S',
+    27: 'IQ3_M',
+    28: 'IQ2_S',
+    29: 'IQ2_M',
+    30: 'IQ4_XS',
+    31: 'IQ1_M',
+    32: 'BF16',
+    36: 'TQ1_0',
+    37: 'TQ2_0',
+    38: 'MXFP4_MOE',
+};
+/** The bundle's dialog config (design "Бандлы AI Hub", as S4 found it): without it, no bundle. */
+export const BUNDLE_MANIFEST = 'genie_config.json';
+const BUNDLE_METADATA = 'metadata.json';
+const BUNDLE_HTP_CONFIG = 'htp_backend_ext_config.json';
+/** The `runtime` of `metadata.json` of a bundle the `qairt` plugin runs; `genie` bundles are not. */
+const BUNDLE_RUNTIME = 'geniex_qairt';
+/**
+ * Hexagon generation (`devices[].dsp_arch` of `htp_backend_ext_config.json`) → the Snapdragon X it
+ * ships in. S4: the x2-elite bundle says `v81`; `v73` is X Elite's Hexagon.
+ */
+const DSP_ARCH_CHIP = { v73: 'x-elite', v81: 'x2-elite' };
+/** `mmproj-F16.gguf` (llama.cpp's spelling) and `gemma-4-E2B-it-mmproj.gguf` (Google's). */
+const MMPROJ_RE = /mmproj.*\.gguf$/i;
+/** The model cannot be read: not a GGUF file, not a bundle folder, or a broken one. */
+export class GeniexInspectError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GeniexInspectError';
+    }
+}
+const whole = (value) => {
+    const n = typeof value === 'string' ? Number(value) : typeof value === 'number' ? value : NaN;
+    return Number.isSafeInteger(n) && n > 0 ? n : null;
+};
+/** A GGUF file's facts from its header, and whether an `mmproj*.gguf` lies beside it. */
+export async function inspectGgufFile(file) {
+    let metadata;
+    try {
+        metadata = (await readGgufMetadataFromFile(file)).metadata;
+    }
+    catch (error) {
+        if (error instanceof GgufParseError)
+            throw new GeniexInspectError(`${file} is not a GGUF file: ${error.message}`);
+        throw new GeniexInspectError(`${file} cannot be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const architecture = metadata['general.architecture'] ?? null;
+    const fileType = whole(metadata['general.file_type']);
+    const siblings = await readdir(dirname(file)).catch(() => []);
+    return {
+        kind: 'gguf',
+        architecture,
+        max_context_tokens: architecture ? whole(metadata[`${architecture}.context_length`]) : null,
+        quantization: fileType !== null
+            ? (FILE_TYPES[fileType] ?? null)
+            : metadata['general.file_type'] === '0'
+                ? 'F32'
+                : null,
+        chat_template: typeof metadata['tokenizer.chat_template'] === 'string',
+        vision: siblings.some((name) => MMPROJ_RE.test(name) && name !== basename(file)),
+    };
+}
+const pick = (record, keys) => {
+    for (const key of keys) {
+        const value = key
+            .split('.')
+            .reduce((at, part) => (at && typeof at === 'object' ? at[part] : undefined), record);
+        if (value !== undefined && value !== null)
+            return value;
+    }
+    return undefined;
+};
+/** `x-elite` from the spellings AI Hub uses (`qualcomm-snapdragon-x-elite`, `Snapdragon X Elite`, `x-elite`). */
+export function bundleChip(value) {
+    if (typeof value !== 'string')
+        return null;
+    const flat = value.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+    for (const chip of GENIEX_CHIPS)
+        if (flat.endsWith(chip) || flat.includes(`-${chip}-`))
+            return chip;
+    if (/x2-elite|x2e/.test(flat))
+        return 'x2-elite';
+    if (/x-elite|x1e/.test(flat))
+        return 'x-elite';
+    return null;
+}
+/** A JSON object from a bundle file; `null` when the file is absent. */
+async function bundleJson(dir, name) {
+    const file = join(dir, name);
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new GeniexInspectError(`${file} cannot be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        throw new GeniexInspectError(`${file} is not a JSON object`);
+    return raw;
+}
+/** An AI Hub bundle folder's facts from `genie_config.json`, `metadata.json` and the HTP config. */
+export async function inspectBundle(dir) {
+    const genie = await bundleJson(dir, BUNDLE_MANIFEST);
+    if (!genie)
+        throw new GeniexInspectError(`${dir} is not an AI Hub bundle: no ${BUNDLE_MANIFEST} in it`);
+    const metadata = (await bundleJson(dir, BUNDLE_METADATA)) ?? {};
+    const runtime = pick(metadata, ['runtime']);
+    if (typeof runtime === 'string' && runtime !== BUNDLE_RUNTIME)
+        throw new GeniexInspectError(`${dir} is a ${runtime} bundle, not ${BUNDLE_RUNTIME}`);
+    const htp = (await bundleJson(dir, BUNDLE_HTP_CONFIG)) ?? {};
+    const devices = pick(htp, ['devices']);
+    const dspArch = Array.isArray(devices)
+        ? pick((devices[0] ?? {}), ['dsp_arch'])
+        : undefined;
+    const version = pick(metadata, ['min_runtime_version', 'min_geniex_version', 'tool_versions.geniex']);
+    const precision = pick(metadata, ['precision']);
+    return {
+        kind: 'qairt',
+        chip: (typeof dspArch === 'string' ? DSP_ARCH_CHIP[dspArch.toLowerCase()] : undefined) ??
+            bundleChip(pick(metadata, ['chipset', 'chip'])) ??
+            bundleChip(basename(dir)),
+        max_context_tokens: whole(pick(genie, ['dialog.context.size', 'context_length'])),
+        precision: typeof precision === 'string' && precision !== '' ? precision : null,
+        min_runtime_version: typeof version === 'string' && /^\d+\.\d+(\.\d+)?/.test(version)
+            ? /^\d+\.\d+(\.\d+)?/.exec(version)[0]
+            : null,
+    };
+}
+/** A file is a GGUF; a folder is a bundle. */
+export async function inspectGeniexModel(path) {
+    const info = await stat(path).catch(() => null);
+    if (!info)
+        throw new GeniexInspectError(`${path} does not exist`);
+    return info.isDirectory() ? inspectBundle(path) : inspectGgufFile(path);
+}
+//# sourceMappingURL=inspect.js.map

package/dist/runtime/geniex/host/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../../../src/runtime/geniex/host/inspect.ts"],"names":[],"mappings":"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"}

package/dist/runtime/geniex/host/library.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The part of GenieX's C API (`geniex.h` of v0.9.3, the binding's ABI 1) the host uses, as an
+ * interface the Worker calls synchronously. `ffi-bun.ts` implements it over `bun:ffi`; the protocol
+ * and server tests (tasks 5.2–5.5) run against a fake one. Every call blocks the calling thread —
+ * `generate` for the whole answer, calling `onToken` from inside — which is why the Worker, not the
+ * host's main thread, owns the library (design D1).
+ */
+import type { GeniexDevice, GeniexPlugin } from '../../../contracts/index.js';
+/** A library call returned an error code (the library's own message) or a null handle. */
+export declare class GeniexLibraryError extends Error {
+    readonly operation: string;
+    /** `geniex_ErrorCode` when the call returned one. */
+    readonly code: number | null;
+    constructor(operation: string, message: string, 
+    /** `geniex_ErrorCode` when the call returned one. */
+    code?: number | null);
+}
+/** `GENIEX_ERROR_COMMON_CANCELLED`: the token callback returned `false`. */
+export declare const GENIEX_CANCELLED = -100006;
+/** `geniex_PowerMode`, in the library's order: the index is the enum value. */
+export declare const GENIEX_POWER_MODES: readonly ["low_power_saver", "power_saver", "high_power_saver", "low_balanced", "balanced", "high_performance", "sustained_high_performance", "burst"];
+export type GeniexPowerMode = (typeof GENIEX_POWER_MODES)[number];
+/** One part of a message's content: text, or an image the library reads from a file. */
+export type GeniexContent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    path: string;
+};
+/** One message of `apply_chat_template` (`geniex_LlmChatMessage` / `geniex_VlmChatMessage`). */
+export interface GeniexChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: GeniexContent[];
+    /** `assistant`: the calls it issued this turn. */
+    tool_calls?: Array<{
+        id: string | null;
+        name: string;
+        arguments: string;
+    }>;
+    /** `tool`: which call this answers. */
+    tool_call_id?: string | null;
+    tool_name?: string | null;
+}
+export interface GeniexTemplateInput {
+    messages: GeniexChatMessage[];
+    /** OpenAI-shaped `tools` as one JSON string; `null` for none. */
+    tools: string | null;
+    enableThinking: boolean;
+}
+/** `geniex_SamplerConfig` without the paths; `null` fields keep the plugin's defaults. */
+export interface GeniexSampler {
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    seed?: number;
+    /** llama.cpp GBNF; `null` for none. */
+    grammar: string | null;
+}
+export interface GeniexGenerationConfig {
+    maxTokens: number;
+    stop: string[];
+    sampler: GeniexSampler;
+    /** VLM only: the images of this turn, in the order the content names them. */
+    imagePaths: string[];
+}
+/** `geniex_ProfileData.stop_reason`, plus `cancelled` for a callback that said stop. */
+export type GeniexStopReason = 'eos' | 'length' | 'user' | 'stop_sequence' | 'context_length' | 'cancelled' | 'unknown';
+export interface GeniexGenerateResult {
+    stopReason: GeniexStopReason;
+    promptTokens: number;
+    generatedTokens: number;
+}
+export interface GeniexModelSettings {
+    plugin: GeniexPlugin;
+    /** The alias the library resolves (`geniex_resolve_device`). */
+    device: GeniexDevice;
+    /** A GGUF file, or an AI Hub bundle folder. */
+    model: string;
+    /** `llama_cpp` only: creates a VLM instead of an LLM. */
+    mmproj: string | null;
+    nCtx: number;
+    /** Generation and batch threads for `llama_cpp` (spike S3: the plugin's default halves CPU decode). */
+    threads: number;
+    powerMode: GeniexPowerMode;
+}
+export interface GeniexModel {
+    /** Created with a vision projector: takes images. */
+    readonly vision: boolean;
+    applyChatTemplate(input: GeniexTemplateInput): string;
+    /**
+     * The whole generation, blocking; `onToken` runs for each token in this thread and ends the
+     * generation by returning `false` (the library answers `cancelled`). Throws `GeniexLibraryError`
+     * for anything but a clean end or a cancel.
+     */
+    generate(prompt: string, config: GeniexGenerationConfig, onToken: (token: string) => boolean): GeniexGenerateResult;
+    destroy(): void;
+}
+export interface GeniexLibrary {
+    /** `geniex_version()`; `null` where it cannot be read. */
+    version: string | null;
+    /** The binding's ABI number. */
+    abi: number;
+    /** `geniex_get_plugin_list`. */
+    plugins(): string[];
+    /** `geniex_get_device_list` of one plugin: device ids (`HTP0`, `GPUOpenCL`, `CPU`). */
+    devices(plugin: string): string[];
+    createModel(settings: GeniexModelSettings): GeniexModel;
+    /** `geniex_deinit`. */
+    close(): void;
+}
+/** Opens the library of one build (`<build>/lib`); throws `GeniexLibraryError` when it does not load. */
+export type LoadGeniexLibrary = (libDir: string) => Promise<GeniexLibrary>;
+/** The ABI number `ffi-bun.ts` binds; see `SUPPORTED_GENIEX_ABI` in engine-builds. */
+export declare const BOUND_GENIEX_ABI = 1;
+/** The plugin whose devices `probe` reports: the GGUF one, which lists the NPU, the GPU and the CPU. */
+export declare const PROBE_PLUGIN = "llama_cpp";

package/dist/runtime/geniex/host/library.js

@@ -0,0 +1,38 @@
+/**
+ * The part of GenieX's C API (`geniex.h` of v0.9.3, the binding's ABI 1) the host uses, as an
+ * interface the Worker calls synchronously. `ffi-bun.ts` implements it over `bun:ffi`; the protocol
+ * and server tests (tasks 5.2–5.5) run against a fake one. Every call blocks the calling thread —
+ * `generate` for the whole answer, calling `onToken` from inside — which is why the Worker, not the
+ * host's main thread, owns the library (design D1).
+ */
+/** A library call returned an error code (the library's own message) or a null handle. */
+export class GeniexLibraryError extends Error {
+    operation;
+    code;
+    constructor(operation, message, 
+    /** `geniex_ErrorCode` when the call returned one. */
+    code = null) {
+        super(`${operation}: ${message}`);
+        this.operation = operation;
+        this.code = code;
+        this.name = 'GeniexLibraryError';
+    }
+}
+/** `GENIEX_ERROR_COMMON_CANCELLED`: the token callback returned `false`. */
+export const GENIEX_CANCELLED = -100006;
+/** `geniex_PowerMode`, in the library's order: the index is the enum value. */
+export const GENIEX_POWER_MODES = [
+    'low_power_saver',
+    'power_saver',
+    'high_power_saver',
+    'low_balanced',
+    'balanced',
+    'high_performance',
+    'sustained_high_performance',
+    'burst',
+];
+/** The ABI number `ffi-bun.ts` binds; see `SUPPORTED_GENIEX_ABI` in engine-builds. */
+export const BOUND_GENIEX_ABI = 1;
+/** The plugin whose devices `probe` reports: the GGUF one, which lists the NPU, the GPU and the CPU. */
+export const PROBE_PLUGIN = 'llama_cpp';
+//# sourceMappingURL=library.js.map

package/dist/runtime/geniex/host/library.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"library.js","sourceRoot":"","sources":["../../../../src/runtime/geniex/host/library.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,0FAA0F;AAC1F,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEhC;IAGA;IAJX,YACW,SAAiB,EAC1B,OAAe;IACf,qDAAqD;IAC5C,OAAsB,IAAI;QAEnC,KAAK,CAAC,GAAG,SAAS,KAAK,OAAO,EAAE,CAAC,CAAA;QALxB,cAAS,GAAT,SAAS,CAAQ;QAGjB,SAAI,GAAJ,IAAI,CAAsB;QAGnC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;IAClC,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,CAAA;AAEvC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,iBAAiB;IACjB,aAAa;IACb,kBAAkB;IAClB,cAAc;IACd,UAAU;IACV,kBAAkB;IAClB,4BAA4B;IAC5B,OAAO;CACC,CAAA;AAoGV,sFAAsF;AACtF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAA;AAEjC,wGAAwG;AACxG,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAA"}