@atomic-chat/core 0.5.1

package/dist/settings/store.js

@@ -0,0 +1,350 @@
+/**
+ * `<data>/atomic-core/settings.json` — the core's replacement for the app's `localStorage[<extension>]`
+ * descriptor arrays (core/src/browser/extension.ts:150-240) and its loose service keys
+ * (`llama_cpp_pending_backend`, `llama_cpp_better_backend_recommendation`, … — PLAN.md §8.1).
+ *
+ * Shape (PLAN.md §3.4):
+ *   { version, revision, updated_at,
+ *     providers: { <provider>: { <canonical key>: <typed value> } },
+ *     server: ServerSettings, cloud: { providers: [] },
+ *     state: { providers: { <provider>: { backend_type, pending_backend, better_backend_recommendation,
+ *                                          last_recheck_outcome } },
+ *              migrations: { <scope>: { baseline, legacy_hash, acknowledged_revision } } } }
+ *
+ * Rules:
+ *  - `revision` is monotonic and only moves when a value actually changed; callers pass
+ *    `expectedRevision` to get a conflict (`INVALID_ARGUMENT`) instead of a lost update.
+ *  - Every write is atomic: `<file>.tmp` then rename, mode 0600 (protected like credentials).
+ *  - Unknown keys — at the top level, inside a provider, inside `state` — survive read → write, so an
+ *    older core never destroys what a newer one stored (PLAN.md §5.1).
+ *  - Values are canonicalized on read and on write (`canonicalizeSettingValues`), so `get()` returns
+ *    the types Rust `LlamacppConfig` expects even when the file was hand-edited with strings.
+ *  - I/O is injected (`fs`, `now`) so tests run on an in-memory fake.
+ */
+import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { AtomicCoreError, DEFAULT_SERVER_SETTINGS } from '../contracts/index.js';
+import { LOCAL_PROVIDER_IDS, canonicalizeSettingValues, defaultSettingValues } from './schema.js';
+import { classifyImport, legacyHash, planImport } from './import.js';
+export const SETTINGS_FILE_VERSION = 1;
+const NODE_FS = { readFile, writeFile, rename, mkdir, stat };
+export const EMPTY_PROVIDER_STATE = {
+    backend_type: null,
+    pending_backend: null,
+    better_backend_recommendation: null,
+    last_recheck_outcome: null,
+};
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function asRecord(v) {
+    return isRecord(v) ? v : {};
+}
+function isEnoent(e) {
+    return isRecord(e) && e['code'] === 'ENOENT';
+}
+function sameValue(a, b) {
+    return a === b || JSON.stringify(a) === JSON.stringify(b);
+}
+/** Schema defaults with the wire types applied — what a fresh provider section holds. */
+export function canonicalProviderDefaults(provider) {
+    return canonicalizeSettingValues(provider, defaultSettingValues(provider));
+}
+/**
+ * Fill every known section with defaults, keep everything else. `raw` may be `{}` (fresh file) or
+ * anything a previous core wrote. Throws `IO_ERROR` when the file claims a newer format version.
+ */
+export function normalizeSettingsDocument(raw, nowMs) {
+    const version = raw['version'];
+    if (typeof version === 'number' && version > SETTINGS_FILE_VERSION) {
+        throw new AtomicCoreError('IO_ERROR', `settings.json version ${version} is newer than this core supports (${SETTINGS_FILE_VERSION})`);
+    }
+    const revisionRaw = raw['revision'];
+    const revision = typeof revisionRaw === 'number' && Number.isInteger(revisionRaw) && revisionRaw >= 0 ? revisionRaw : 0;
+    const rawProviders = asRecord(raw['providers']);
+    const providers = { ...rawProviders };
+    for (const p of LOCAL_PROVIDER_IDS) {
+        providers[p] = canonicalizeSettingValues(p, {
+            ...canonicalProviderDefaults(p),
+            ...asRecord(rawProviders[p]),
+        });
+    }
+    const rawState = asRecord(raw['state']);
+    const rawStateProviders = asRecord(rawState['providers']);
+    const stateProviders = { ...rawStateProviders };
+    for (const p of LOCAL_PROVIDER_IDS) {
+        stateProviders[p] = { ...EMPTY_PROVIDER_STATE, ...asRecord(rawStateProviders[p]) };
+    }
+    const rawMigrations = asRecord(rawState['migrations']);
+    const migrations = {};
+    for (const [scope, rec] of Object.entries(rawMigrations)) {
+        const r = asRecord(rec);
+        migrations[scope] = {
+            ...r,
+            baseline: isRecord(r['baseline']) ? r['baseline'] : null,
+            legacy_hash: typeof r['legacy_hash'] === 'string' ? r['legacy_hash'] : null,
+            acknowledged_revision: typeof r['acknowledged_revision'] === 'number' ? r['acknowledged_revision'] : null,
+        };
+    }
+    const rawCloud = asRecord(raw['cloud']);
+    const cloudProviders = Array.isArray(rawCloud['providers'])
+        ? rawCloud['providers'].filter(isRecord)
+        : [];
+    return {
+        ...raw,
+        version: SETTINGS_FILE_VERSION,
+        revision,
+        updated_at: typeof raw['updated_at'] === 'string' ? raw['updated_at'] : new Date(nowMs).toISOString(),
+        providers,
+        server: { ...DEFAULT_SERVER_SETTINGS, ...asRecord(raw['server']) },
+        cloud: { ...rawCloud, providers: cloudProviders },
+        state: { ...rawState, providers: stateProviders, migrations },
+    };
+}
+export class SettingsStore {
+    path;
+    doc;
+    fs;
+    now;
+    listeners = new Set();
+    /** Serialises mutations so two concurrent `update`s never race on `.tmp`. */
+    chain = Promise.resolve();
+    constructor(path, doc, fs, now) {
+        this.path = path;
+        this.doc = doc;
+        this.fs = fs;
+        this.now = now;
+    }
+    /** Read the file, or create it with schema defaults when absent. Corrupt JSON is an `IO_ERROR`. */
+    static async open(path, options = {}) {
+        const fs = options.fs ?? NODE_FS;
+        const now = options.now ?? Date.now;
+        let exists = true;
+        try {
+            await fs.stat(path);
+        }
+        catch (e) {
+            if (!isEnoent(e))
+                throw new AtomicCoreError('IO_ERROR', `cannot stat ${path}: ${e.message}`);
+            exists = false;
+        }
+        if (!exists) {
+            const store = new SettingsStore(path, normalizeSettingsDocument(options.ownerScope ? { owner_scope: options.ownerScope } : {}, now()), fs, now);
+            await store.persist();
+            return store;
+        }
+        let text;
+        try {
+            text = await fs.readFile(path, 'utf8');
+        }
+        catch (e) {
+            throw new AtomicCoreError('IO_ERROR', `cannot read ${path}: ${e.message}`);
+        }
+        let raw;
+        try {
+            raw = JSON.parse(text);
+        }
+        catch (e) {
+            throw new AtomicCoreError('IO_ERROR', `${path} is not valid JSON: ${e.message}`);
+        }
+        if (!isRecord(raw))
+            throw new AtomicCoreError('IO_ERROR', `${path} is not a JSON object`);
+        if (options.ownerScope && raw['owner_scope'] && raw['owner_scope'] !== options.ownerScope)
+            throw new AtomicCoreError('CORE_ALREADY_RUNNING', 'This data folder belongs to another core scope.');
+        const store = new SettingsStore(path, normalizeSettingsDocument(options.ownerScope ? { ...raw, owner_scope: options.ownerScope } : raw, now()), fs, now);
+        if (options.ownerScope && !raw['owner_scope'])
+            await store.persist();
+        return store;
+    }
+    get revision() {
+        return this.doc.revision;
+    }
+    /** Full deep copy of the document (control API snapshot). */
+    snapshot() {
+        return structuredClone(this.doc);
+    }
+    get(provider) {
+        assertProvider(provider);
+        return structuredClone(this.doc.providers[provider]);
+    }
+    get server() {
+        return structuredClone(this.doc.server);
+    }
+    get state() {
+        return structuredClone(this.doc.state);
+    }
+    /** Apply `patch` (canonicalized) to a provider; keys whose value is unchanged are ignored. */
+    async update(provider, patch, options = {}) {
+        assertProvider(provider);
+        const canonical = canonicalizeSettingValues(provider, patch);
+        return this.mutate(options, (doc) => applyPatch(doc.providers[provider], canonical, (key, value) => ({ scope: provider, key, value })));
+    }
+    async updateServer(patch, options = {}) {
+        return this.mutate(options, (doc) => applyPatch(doc.server, patch, (key, value) => ({ scope: 'server', key, value })));
+    }
+    /**
+     * Replace the cloud provider list (non-secret parts only; keys live in credentials.json). One
+     * change is reported for the whole list when anything in it differs.
+     */
+    async setCloudProviders(providers, options = {}) {
+        return this.mutate(options, (doc) => {
+            if (JSON.stringify(doc.cloud.providers) === JSON.stringify(providers))
+                return [];
+            doc.cloud.providers = structuredClone(providers);
+            return [{ scope: 'cloud', key: 'providers', value: providers.map((p) => p['provider']) }];
+        });
+    }
+    async updateState(provider, patch, options = {}) {
+        assertProvider(provider);
+        return this.mutate(options, (doc) => applyPatch(doc.state.providers[provider], patch, (key, value) => ({
+            scope: 'state',
+            key: `${provider}.${key}`,
+            value,
+        })));
+    }
+    /**
+     * Take the desktop app's settings for a provider (PLAN.md §3.4).
+     *
+     * Three-way, not a copy: see `import.ts`. Nothing is written when any key conflicts, so a scope
+     * is either fully migrated or not migrated at all — a half-applied import would leave the app and
+     * the core disagreeing about settings neither side accepted.
+     *
+     * The migration record is written even when the merge applies no values, because the record is
+     * what stops the next start from merging the same change all over again.
+     */
+    async importProvider(provider, legacyValues, options = {}) {
+        assertProvider(provider);
+        const canonicalLegacy = canonicalizeSettingValues(provider, legacyValues);
+        const hash = legacyHash(canonicalLegacy);
+        let outcome = { status: 'unchanged', applied: [], conflicts: [] };
+        const result = await this.mutate(options, (doc) => {
+            const record = doc.state.migrations[provider] ?? null;
+            // A first import has no base of its own: the provider's defaults stand in, so a value the CLI
+            // already changed reads as a change rather than as where both sides started.
+            const base = record?.baseline ?? canonicalProviderDefaults(provider);
+            const core = doc.providers[provider];
+            const plan = planImport(base, core, canonicalLegacy, options.resolutions ?? {});
+            const status = classifyImport(record?.legacy_hash ?? null, record?.baseline != null, hash, plan);
+            outcome = { status, applied: Object.keys(plan.apply), conflicts: plan.conflicts };
+            if (status === 'conflict' || status === 'unchanged')
+                return [];
+            const changes = applyPatch(core, plan.apply, (key, value) => ({
+                scope: provider,
+                key,
+                value,
+            }));
+            doc.state.migrations[provider] = {
+                ...(record ?? { acknowledged_revision: null }),
+                baseline: structuredClone(canonicalLegacy),
+                legacy_hash: hash,
+            };
+            changes.push({ scope: 'state', key: `migrations.${provider}`, value: hash });
+            return changes;
+        });
+        return { ...outcome, revision: result.revision };
+    }
+    /**
+     * Record that the app has mirrored the core's settings up to `revision`.
+     *
+     * Only meaningful after an import: it is how a planned rollback knows whether the app's copy is
+     * current enough to hand ownership back (PLAN.md §3.4). The acknowledgement itself is a
+     * metadata-only write, but it advances the file's revision like every other write. Store that
+     * resulting revision as the equivalent mirrored state so status is in sync immediately after it.
+     */
+    async acknowledge(scope, revision) {
+        return this.mutate({}, (doc) => {
+            const record = doc.state.migrations[scope];
+            if (!record)
+                return [];
+            // The app can retry after losing the response. Both its original snapshot revision and
+            // the post-ack revision identify the same provider values, so neither retry is a new write.
+            if (record.acknowledged_revision === doc.revision &&
+                (revision === doc.revision || revision === doc.revision - 1))
+                return [];
+            // A value changed while the app was copying the snapshot. Acknowledging that stale copy
+            // would authorize rollback with settings that the core has already replaced.
+            if (revision !== doc.revision) {
+                throw new AtomicCoreError('INVALID_ARGUMENT', `settings revision conflict: expected ${revision}, current ${doc.revision}`, this.path);
+            }
+            const acknowledged = doc.revision + 1;
+            record.acknowledged_revision = acknowledged;
+            return [{ scope: 'state', key: `migrations.${scope}.acknowledged_revision`, value: acknowledged }];
+        });
+    }
+    /** What the core knows about a scope's migration, or `null` when it has never been imported. */
+    migration(scope) {
+        const record = this.doc.state.migrations[scope];
+        return record ? structuredClone(record) : null;
+    }
+    /** Called once per changed key after the write landed; returns the unsubscribe function. */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    mutate(options, apply) {
+        const run = this.chain.then(async () => {
+            const expected = options.expectedRevision;
+            if (expected !== undefined && expected !== this.doc.revision) {
+                throw new AtomicCoreError('INVALID_ARGUMENT', `settings revision conflict: expected ${expected}, current ${this.doc.revision}`, this.path);
+            }
+            const next = structuredClone(this.doc);
+            const changes = apply(next);
+            if (changes.length === 0)
+                return { revision: this.doc.revision, changed: [] };
+            next.revision = this.doc.revision + 1;
+            next.updated_at = new Date(this.now()).toISOString();
+            const previous = this.doc;
+            this.doc = next;
+            try {
+                await this.persist();
+            }
+            catch (e) {
+                this.doc = previous;
+                throw e;
+            }
+            for (const change of changes) {
+                for (const listener of this.listeners) {
+                    try {
+                        listener({ ...change, revision: next.revision });
+                    }
+                    catch {
+                        // a broken listener must not undo a write that already landed
+                    }
+                }
+            }
+            return { revision: next.revision, changed: changes.map((c) => c.key) };
+        });
+        this.chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async persist() {
+        const text = JSON.stringify(this.doc, null, 2) + '\n';
+        const tmp = `${this.path}.tmp`;
+        try {
+            await this.fs.mkdir(dirname(this.path), { recursive: true });
+            await this.fs.writeFile(tmp, text, { encoding: 'utf8', mode: 0o600 });
+            await this.fs.rename(tmp, this.path);
+        }
+        catch (e) {
+            throw new AtomicCoreError('IO_ERROR', `cannot write ${this.path}: ${e.message}`);
+        }
+    }
+}
+function assertProvider(provider) {
+    if (!LOCAL_PROVIDER_IDS.includes(provider))
+        throw new AtomicCoreError('PROVIDER_NOT_FOUND', `unknown provider '${provider}'`);
+}
+/** Write the differing keys of `patch` into `target`; `undefined` means "leave as is". */
+function applyPatch(target, patch, describe) {
+    const changes = [];
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined || sameValue(target[key], value))
+            continue;
+        target[key] = value;
+        changes.push(describe(key, value));
+    }
+    return changes;
+}
+//# sourceMappingURL=store.js.map

package/dist/settings/store.js.map

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

package/dist/speculative/chat-template-overrides.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Ported verbatim from: extensions/llamacpp-upstream-extension/src/chatTemplateOverrides.ts
+ * @file Load-time chat_template overrides for models whose embedded Jinja
+ * template carries a strict guard that breaks llama.cpp's `--jinja` auto-parser.
+ *
+ * The unsloth conversions of Llama 3.x ship a chat template with a hard guard
+ * `{{- raise_exception('System message must be at the beginning') }}`. When the
+ * server runs with `--jinja`, the auto-parser feeds the template synthetic
+ * message permutations during differential analysis; one of those probes
+ * violates the guard, so parser generation aborts with
+ * `400 Unable to generate parser for this template`. The canonical Meta Llama
+ * 3.x template has no such guard (it softly defaults the system message to "").
+ *
+ * We detect the strict guard in the embedded template and, only for Llama-3
+ * format models, substitute the canonical Meta template via `cfg.chat_template`
+ * (-> `--chat-template`). The substitute is the standard Llama 3 tool format the
+ * auto-parser already supports.
+ */
+/** Signature of the strict system-message guard embedded in the bad templates. */
+export declare const STRICT_SYSTEM_GUARD_SIGNATURE = "System message must be at the beginning";
+/**
+ * Canonical Meta Llama 3.x instruct chat template (covers 3.1/3.2/3.3).
+ *
+ * Sourced verbatim from
+ * `models/templates/meta-llama-Llama-3.2-3B-Instruct.jinja` in the llama.cpp
+ * backend repo. `String.raw` preserves the literal `\n` escapes inside the
+ * Jinja string literals (minja interprets them, not JS).
+ */
+export declare const CANONICAL_LLAMA3_CHAT_TEMPLATE: string;
+/**
+ * Returns the canonical Meta Llama 3.x chat template when the embedded template
+ * carries the strict system-message guard AND the model is Llama-3 format;
+ * otherwise `null` (leave the embedded template untouched).
+ */
+export declare function resolveLlama3TemplateOverride(modelId: string, embeddedTemplate: string | null | undefined): string | null;

package/dist/speculative/chat-template-overrides.js

@@ -0,0 +1,142 @@
+/**
+ * Ported verbatim from: extensions/llamacpp-upstream-extension/src/chatTemplateOverrides.ts
+ * @file Load-time chat_template overrides for models whose embedded Jinja
+ * template carries a strict guard that breaks llama.cpp's `--jinja` auto-parser.
+ *
+ * The unsloth conversions of Llama 3.x ship a chat template with a hard guard
+ * `{{- raise_exception('System message must be at the beginning') }}`. When the
+ * server runs with `--jinja`, the auto-parser feeds the template synthetic
+ * message permutations during differential analysis; one of those probes
+ * violates the guard, so parser generation aborts with
+ * `400 Unable to generate parser for this template`. The canonical Meta Llama
+ * 3.x template has no such guard (it softly defaults the system message to "").
+ *
+ * We detect the strict guard in the embedded template and, only for Llama-3
+ * format models, substitute the canonical Meta template via `cfg.chat_template`
+ * (-> `--chat-template`). The substitute is the standard Llama 3 tool format the
+ * auto-parser already supports.
+ */
+/** Signature of the strict system-message guard embedded in the bad templates. */
+export const STRICT_SYSTEM_GUARD_SIGNATURE = 'System message must be at the beginning';
+/** Matches Llama 3 / 3.x model ids (e.g. `Llama-3_2-3B`, `llama-3.1-8b`). */
+const LLAMA3_MODEL_ID_RE = /llama[-_. ]?3(\.\d+)?/i;
+/** Llama 3 prompt-format marker present in any genuine Llama 3 template. */
+const LLAMA3_FORMAT_MARKER = '<|start_header_id|>';
+/**
+ * Canonical Meta Llama 3.x instruct chat template (covers 3.1/3.2/3.3).
+ *
+ * Sourced verbatim from
+ * `models/templates/meta-llama-Llama-3.2-3B-Instruct.jinja` in the llama.cpp
+ * backend repo. `String.raw` preserves the literal `\n` escapes inside the
+ * Jinja string literals (minja interprets them, not JS).
+ */
+export const CANONICAL_LLAMA3_CHAT_TEMPLATE = String.raw `{{- bos_token }}
+{%- if custom_tools is defined %}
+    {%- set tools = custom_tools %}
+{%- endif %}
+{%- if not tools_in_user_message is defined %}
+    {%- set tools_in_user_message = true %}
+{%- endif %}
+{%- if not date_string is defined %}
+    {%- if strftime_now is defined %}
+        {%- set date_string = strftime_now("%d %b %Y") %}
+    {%- else %}
+        {%- set date_string = "26 Jul 2024" %}
+    {%- endif %}
+{%- endif %}
+{%- if not tools is defined %}
+    {%- set tools = none %}
+{%- endif %}
+
+{#- This block extracts the system message, so we can slot it into the right place. #}
+{%- if messages[0]['role'] == 'system' %}
+    {%- set system_message = messages[0]['content']|trim %}
+    {%- set messages = messages[1:] %}
+{%- else %}
+    {%- set system_message = "" %}
+{%- endif %}
+
+{#- System message #}
+{{- "<|start_header_id|>system<|end_header_id|>\n\n" }}
+{%- if tools is not none %}
+    {{- "Environment: ipython\n" }}
+{%- endif %}
+{{- "Cutting Knowledge Date: December 2023\n" }}
+{{- "Today Date: " + date_string + "\n\n" }}
+{%- if tools is not none and not tools_in_user_message %}
+    {{- "You have access to the following functions. To call a function, please respond with JSON for a function call." }}
+    {{- 'Respond in the format {"name": function name, "parameters": dictionary of argument name and its value}.' }}
+    {{- "Do not use variables.\n\n" }}
+    {%- for t in tools %}
+        {{- t | tojson(indent=4) }}
+        {{- "\n\n" }}
+    {%- endfor %}
+{%- endif %}
+{{- system_message }}
+{{- "<|eot_id|>" }}
+
+{#- Custom tools are passed in a user message with some extra guidance #}
+{%- if tools_in_user_message and not tools is none %}
+    {#- Extract the first user message so we can plug it in here #}
+    {%- if messages | length != 0 %}
+        {%- set first_user_message = messages[0]['content']|trim %}
+        {%- set messages = messages[1:] %}
+    {%- else %}
+        {{- raise_exception("Cannot put tools in the first user message when there's no first user message!") }}
+{%- endif %}
+    {{- '<|start_header_id|>user<|end_header_id|>\n\n' -}}
+    {{- "Given the following functions, please respond with a JSON for a function call " }}
+    {{- "with its proper arguments that best answers the given prompt.\n\n" }}
+    {{- 'Respond in the format {"name": function name, "parameters": dictionary of argument name and its value}.' }}
+    {{- "Do not use variables.\n\n" }}
+    {%- for t in tools %}
+        {{- t | tojson(indent=4) }}
+        {{- "\n\n" }}
+    {%- endfor %}
+    {{- first_user_message + "<|eot_id|>"}}
+{%- endif %}
+
+{%- for message in messages %}
+    {%- if not (message.role == 'ipython' or message.role == 'tool' or 'tool_calls' in message) %}
+        {{- '<|start_header_id|>' + message['role'] + '<|end_header_id|>\n\n'+ message['content'] | trim + '<|eot_id|>' }}
+    {%- elif 'tool_calls' in message %}
+        {%- if not message.tool_calls|length == 1 %}
+            {{- raise_exception("This model only supports single tool-calls at once!") }}
+        {%- endif %}
+        {%- set tool_call = message.tool_calls[0].function %}
+        {{- '<|start_header_id|>assistant<|end_header_id|>\n\n' -}}
+        {{- '{"name": "' + tool_call.name + '", ' }}
+        {{- '"parameters": ' }}
+        {{- tool_call.arguments | tojson }}
+        {{- "}" }}
+        {{- "<|eot_id|>" }}
+    {%- elif message.role == "tool" or message.role == "ipython" %}
+        {{- "<|start_header_id|>ipython<|end_header_id|>\n\n" }}
+        {%- if message.content is mapping or message.content is iterable %}
+            {{- message.content | tojson }}
+        {%- else %}
+            {{- message.content }}
+        {%- endif %}
+        {{- "<|eot_id|>" }}
+    {%- endif %}
+{%- endfor %}
+{%- if add_generation_prompt %}
+    {{- '<|start_header_id|>assistant<|end_header_id|>\n\n' }}
+{%- endif %}
+`;
+/**
+ * Returns the canonical Meta Llama 3.x chat template when the embedded template
+ * carries the strict system-message guard AND the model is Llama-3 format;
+ * otherwise `null` (leave the embedded template untouched).
+ */
+export function resolveLlama3TemplateOverride(modelId, embeddedTemplate) {
+    if (!embeddedTemplate)
+        return null;
+    if (!embeddedTemplate.includes(STRICT_SYSTEM_GUARD_SIGNATURE))
+        return null;
+    const looksLikeLlama3 = LLAMA3_MODEL_ID_RE.test(modelId) || embeddedTemplate.includes(LLAMA3_FORMAT_MARKER);
+    if (!looksLikeLlama3)
+        return null;
+    return CANONICAL_LLAMA3_CHAT_TEMPLATE;
+}
+//# sourceMappingURL=chat-template-overrides.js.map

package/dist/speculative/chat-template-overrides.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-template-overrides.js","sourceRoot":"","sources":["../../src/speculative/chat-template-overrides.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,kFAAkF;AAClF,MAAM,CAAC,MAAM,6BAA6B,GAAG,yCAAyC,CAAA;AAEtF,6EAA6E;AAC7E,MAAM,kBAAkB,GAAG,wBAAwB,CAAA;AAEnD,4EAA4E;AAC5E,MAAM,oBAAoB,GAAG,qBAAqB,CAAA;AAElD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6FvD,CAAA;AAED;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAC3C,OAAe,EACf,gBAA2C;IAE3C,IAAI,CAAC,gBAAgB;QAAE,OAAO,IAAI,CAAA;IAClC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QAAE,OAAO,IAAI,CAAA;IAE1E,MAAM,eAAe,GAAG,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,gBAAgB,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAA;IAC3G,IAAI,CAAC,eAAe;QAAE,OAAO,IAAI,CAAA;IAEjC,OAAO,8BAA8B,CAAA;AACvC,CAAC"}

package/dist/speculative/dflash-registry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Ported verbatim from: extensions/llamacpp-upstream-extension/src/dflashRegistry.ts
+ * @file Static registry mapping a DFlash *target* model to the separate DFlash
+ * *draft* GGUF it needs for upstream llama.cpp multi-layer draft speculative
+ * decoding (`--model-draft <draft> --spec-type draft-dflash`, PR
+ * ggml-org/llama.cpp#22105, commit d1b34251b, first tagged release `b9831`).
+ *
+ * DFlash ships the draft as a second, small GGUF that must be downloaded next
+ * to the target model (the same way `mmproj` and Gemma 4 MTP heads are handled
+ * — see gemmaMtpRegistry.ts). The upstream MLX DFlash drafts are published as
+ * safetensors and would need conversion; these entries instead point at
+ * GGUF repos built for mainline llama.cpp so the file can be consumed
+ * directly. Fork-only `dflash-draft` / `qwen35-dflash-draft` architectures
+ * are deliberately excluded.
+ *
+ * Draft files were verified against the live Hugging Face API (sha256 + size
+ * pinned so the downloader validates them). Atomic Chat's verified Q8_0
+ * conversions are the default for every target-model quantization when
+ * available; compatible community conversions provide the remaining draft
+ * choices and cover families without an Atomic Chat conversion.
+ */
+export interface DflashDraft {
+    /** Quantization label shown in the settings picker. */
+    quant: string;
+    /** Hugging Face repo id that hosts the DFlash draft GGUF. */
+    repo: string;
+    /** Exact filename of the draft inside the repo. */
+    draftFilename: string;
+    /** Pinned sha256 of the draft file (lowercase hex) for download validation. */
+    draftSha256: string;
+    /** Pinned byte size of the draft file for download validation. */
+    draftSize: number;
+}
+/**
+ * Every draft this registry downloads — the files the app itself puts on disk
+ * next to a target. The web app's model-file filter is tested against them so
+ * a local scan never offers one back as a model (ATO-523).
+ */
+export declare const DFLASH_DRAFT_FILENAMES: readonly string[];
+export declare const DEFAULT_DFLASH_DRAFT_QUANT = "Q8_0";
+/**
+ * Resolve the DFlash draft for a target model id, or `null` if the model is
+ * not a DFlash-capable target in the registry.
+ */
+export declare function listDflashDrafts(modelId: string): DflashDraft[];
+export declare function resolveDflashDraft(modelId: string, quant?: string): DflashDraft | null;
+/** Whether the given model id is a DFlash-capable target. */
+export declare function checkDflashSupport(modelId: string): boolean;
+/** Build the Hugging Face resolve URL for a DFlash draft. */
+export declare function dflashDraftUrl(draft: DflashDraft): string;