@atomic-chat/core 0.5.1

package/dist/lock/process-identity.d.ts

@@ -0,0 +1,48 @@
+/**
+ * "Is the process that wrote this file still the process behind that PID?"
+ *
+ * A PID alone cannot answer it: the OS reuses PIDs, so a dead owner's PID can belong to something
+ * else by the time a client looks (PLAN.md §3.4). Every owner therefore records a *start identity*
+ * next to its PID, and a taker-over must see that identity gone or different before it may steal
+ * the lock. When the identity cannot be established (no procfs, probe refused, unknown platform)
+ * the answer is `unknown`, never `mismatch` — an unproven claim must not kill a live owner.
+ *
+ * No native addons: Linux reads procfs, macOS asks `ps`, Windows asks PowerShell.
+ */
+export type IdentityVerdict = 'match' | 'mismatch' | 'dead' | 'unknown';
+export interface IdentityDeps {
+    platform?: NodeJS.Platform;
+    /** Read a procfs entry (Linux). */
+    readText?: (path: string) => Promise<string>;
+    /** Run a probe and return its stdout. */
+    run?: (file: string, args: string[]) => Promise<string>;
+    /** Signal-0 liveness probe. */
+    alive?: (pid: number) => boolean;
+}
+/**
+ * PowerShell on Windows takes several seconds to start cold, and on a loaded CI runner more than
+ * five; a probe that is cut short answers `undefined`, which is safe for takeover but leaves a
+ * child journalled without its identity. The budget is generous because a slow answer is worth
+ * more than a fast "unknown".
+ */
+export declare const IDENTITY_PROBE_TIMEOUT_MS = 15000;
+export declare function isProcessAlive(pid: number): boolean;
+export declare function runProbe(file: string, args: string[]): Promise<string>;
+/**
+ * An opaque, comparable token for "this incarnation of this PID", or `undefined` when the platform
+ * cannot tell us. Only ever compared for equality, never parsed.
+ */
+export declare function processStartId(pid: number, deps?: IdentityDeps): Promise<string | undefined>;
+/** Cross-language process identity used in files shared with the Rust desktop app. */
+export declare function processStartEpoch(pid: number, deps?: IdentityDeps): Promise<string | undefined>;
+/**
+ * The executable name of a live process, without its directory (and without `.exe`), or `undefined`
+ * when it cannot be read. A second, independent check next to the start identity for a process that
+ * is only ever ended by name *and* identity — the remote-access tunnel, because people who want that
+ * feature often run a `cloudflared` of their own that must never be touched.
+ */
+export declare function processName(pid: number, deps?: IdentityDeps): Promise<string | undefined>;
+/** Compare a recorded identity with the live process. `unknown` means "cannot prove"; treat as live. */
+export declare function verifyProcessIdentity(pid: number, expected: string | null | undefined, deps?: IdentityDeps): Promise<IdentityVerdict>;
+/** Only a proven-gone process releases what it held. */
+export declare function identityPermitsTakeover(verdict: IdentityVerdict): boolean;

package/dist/lock/process-identity.js

@@ -0,0 +1,180 @@
+/**
+ * "Is the process that wrote this file still the process behind that PID?"
+ *
+ * A PID alone cannot answer it: the OS reuses PIDs, so a dead owner's PID can belong to something
+ * else by the time a client looks (PLAN.md §3.4). Every owner therefore records a *start identity*
+ * next to its PID, and a taker-over must see that identity gone or different before it may steal
+ * the lock. When the identity cannot be established (no procfs, probe refused, unknown platform)
+ * the answer is `unknown`, never `mismatch` — an unproven claim must not kill a live owner.
+ *
+ * No native addons: Linux reads procfs, macOS asks `ps`, Windows asks PowerShell.
+ */
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+/**
+ * PowerShell on Windows takes several seconds to start cold, and on a loaded CI runner more than
+ * five; a probe that is cut short answers `undefined`, which is safe for takeover but leaves a
+ * child journalled without its identity. The budget is generous because a slow answer is worth
+ * more than a fast "unknown".
+ */
+export const IDENTITY_PROBE_TIMEOUT_MS = 15_000;
+const readUtf8 = (path) => readFile(path, 'utf8');
+export function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+export function runProbe(file, args) {
+    return new Promise((resolve, reject) => {
+        execFile(file, args, { timeout: IDENTITY_PROBE_TIMEOUT_MS, windowsHide: true }, (err, stdout) => {
+            if (err)
+                reject(err);
+            else
+                resolve(stdout);
+        });
+    });
+}
+/**
+ * An opaque, comparable token for "this incarnation of this PID", or `undefined` when the platform
+ * cannot tell us. Only ever compared for equality, never parsed.
+ */
+export async function processStartId(pid, deps = {}) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return undefined;
+    const platform = deps.platform ?? process.platform;
+    const readText = deps.readText ?? readUtf8;
+    const run = deps.run ?? runProbe;
+    try {
+        if (platform === 'linux') {
+            // /proc/<pid>/stat field 22 (starttime, in clock ticks since boot). The comm field may contain
+            // spaces and parentheses, so fields are counted after the last ')'.
+            const stat = await readText(`/proc/${pid}/stat`);
+            const tail = stat
+                .slice(stat.lastIndexOf(')') + 1)
+                .trim()
+                .split(/\s+/);
+            const startTicks = tail[19]; // field 22 = 3rd after state, which is tail[0]
+            return startTicks && /^\d+$/.test(startTicks) ? `linux:${startTicks}` : undefined;
+        }
+        if (platform === 'darwin') {
+            // `lstart` has one-second resolution; a PID reused inside the same second is indistinguishable,
+            // which the takeover path treats as "unknown", never as a free lock.
+            const out = await run('/bin/ps', ['-o', 'lstart=', '-p', String(pid)]);
+            const value = out.trim().replace(/\s+/g, ' ');
+            return value ? `darwin:${value}` : undefined;
+        }
+        if (platform === 'win32') {
+            const out = await run('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.Ticks`,
+            ]);
+            const value = out.trim();
+            return /^\d+$/.test(value) ? `win32:${value}` : undefined;
+        }
+    }
+    catch {
+        return undefined; // process gone, probe missing or refused
+    }
+    return undefined;
+}
+/** Cross-language process identity used in files shared with the Rust desktop app. */
+export async function processStartEpoch(pid, deps = {}) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return undefined;
+    const platform = deps.platform ?? process.platform;
+    const readText = deps.readText ?? readUtf8;
+    const run = deps.run ?? runProbe;
+    try {
+        if (platform === 'linux') {
+            const [stat, procStat] = await Promise.all([readText(`/proc/${pid}/stat`), readText('/proc/stat')]);
+            const tail = stat
+                .slice(stat.lastIndexOf(')') + 1)
+                .trim()
+                .split(/\s+/);
+            const ticks = Number(tail[19]);
+            const boot = Number(/^btime\s+(\d+)$/m.exec(procStat)?.[1]);
+            if (!Number.isFinite(ticks) || !Number.isFinite(boot))
+                return undefined;
+            // Linux USER_HZ is 100 on the desktop targets Atomic Chat supports.
+            return `epoch:${Math.floor(boot + ticks / 100)}`;
+        }
+        if (platform === 'darwin') {
+            const out = (await run('/bin/ps', ['-o', 'lstart=', '-p', String(pid)])).trim();
+            const epoch = Math.floor(Date.parse(out) / 1000);
+            return Number.isFinite(epoch) ? `epoch:${epoch}` : undefined;
+        }
+        if (platform === 'win32') {
+            const out = await run('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                `[DateTimeOffset](Get-Process -Id ${pid} -ErrorAction Stop).StartTime | ForEach-Object { $_.ToUnixTimeSeconds() }`,
+            ]);
+            const epoch = Number(out.trim());
+            return Number.isInteger(epoch) ? `epoch:${epoch}` : undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * The executable name of a live process, without its directory (and without `.exe`), or `undefined`
+ * when it cannot be read. A second, independent check next to the start identity for a process that
+ * is only ever ended by name *and* identity — the remote-access tunnel, because people who want that
+ * feature often run a `cloudflared` of their own that must never be touched.
+ */
+export async function processName(pid, deps = {}) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return undefined;
+    const platform = deps.platform ?? process.platform;
+    const readText = deps.readText ?? readUtf8;
+    const run = deps.run ?? runProbe;
+    try {
+        let raw;
+        if (platform === 'linux')
+            raw = await readText(`/proc/${pid}/comm`);
+        else if (platform === 'darwin')
+            raw = await run('/bin/ps', ['-o', 'comm=', '-p', String(pid)]);
+        else if (platform === 'win32')
+            raw = await run('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                `(Get-Process -Id ${pid} -ErrorAction Stop).ProcessName`,
+            ]);
+        else
+            return undefined;
+        const name = (raw.trim().split(/[\\/]/).pop() ?? '').replace(/\.exe$/i, '');
+        return name === '' ? undefined : name;
+    }
+    catch {
+        return undefined; // process gone, probe missing or refused
+    }
+}
+/** Compare a recorded identity with the live process. `unknown` means "cannot prove"; treat as live. */
+export async function verifyProcessIdentity(pid, expected, deps = {}) {
+    const alive = deps.alive ?? isProcessAlive;
+    if (!alive(pid))
+        return 'dead';
+    if (!expected)
+        return 'unknown';
+    const actual = await processStartId(pid, deps);
+    if (!actual)
+        return 'unknown';
+    return actual === expected ? 'match' : 'mismatch';
+}
+/** Only a proven-gone process releases what it held. */
+export function identityPermitsTakeover(verdict) {
+    return verdict === 'dead' || verdict === 'mismatch';
+}
+//# sourceMappingURL=process-identity.js.map

package/dist/lock/process-identity.js.map

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

package/dist/lock/process-journal.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `<data>/atomic-core/processes.json` — every backend process this core spawned, with the identity
+ * needed to recognise it later (PLAN.md §3.4).
+ *
+ * After a crash the new owner must clean up the previous owner's `llama-server` processes without
+ * killing anything else. A PID from a dead owner's journal may have been recycled, so a process is
+ * only a *confirmed* orphan when its recorded start identity still matches the live process and the
+ * owner that spawned it is provably gone. Anything unproven is left running and reported.
+ */
+import type { LocalProviderId } from '../contracts/index.js';
+import type { DataLayout } from '../config/index.js';
+import type { IdentityDeps } from './process-identity.js';
+export interface ChildProcessRecord {
+    /** Core instance that spawned it. */
+    instance_id: string;
+    pid: number;
+    process_start_id: string | null;
+    exe: string;
+    /** `diffusion` for the image engine, which is not a provider (its `sd-server` is reaped all the same). */
+    provider: LocalProviderId | 'diffusion';
+    model_id: string;
+    port: number;
+    started_at: string;
+}
+export interface OrphanScan {
+    /** Same process, spawned by an owner that is gone: safe to terminate. */
+    confirmed: ChildProcessRecord[];
+    /** Alive but unprovable, or owned by the live owner: left alone. */
+    skipped: Array<{
+        record: ChildProcessRecord;
+        reason: 'owner-alive' | 'identity-unproven' | 'current-instance';
+    }>;
+    /** Already gone: drop from the journal. */
+    gone: ChildProcessRecord[];
+}
+export declare class ProcessJournal {
+    private readonly path;
+    private records;
+    private queue;
+    private constructor();
+    static open(layout: DataLayout): Promise<ProcessJournal>;
+    list(): ChildProcessRecord[];
+    /** A journal entry must exist before the child can produce work, so this write is awaited. */
+    add(record: ChildProcessRecord): Promise<void>;
+    remove(pid: number): Promise<void>;
+    replace(records: ChildProcessRecord[]): Promise<void>;
+    /**
+     * Classify the journal against reality. `currentInstanceId` is this owner: its own children are
+     * never orphans, and an entry from an owner that is still alive belongs to that owner.
+     */
+    scanOrphans(currentInstanceId: string, liveOwnerInstanceIds: ReadonlySet<string>, deps?: IdentityDeps): Promise<OrphanScan>;
+    /** Forget entries for processes that are gone or were adopted elsewhere. */
+    forget(records: ChildProcessRecord[]): Promise<void>;
+    /** Serialised so concurrent adds cannot interleave a read-modify-write. */
+    private flush;
+}

package/dist/lock/process-journal.js

@@ -0,0 +1,113 @@
+/**
+ * `<data>/atomic-core/processes.json` — every backend process this core spawned, with the identity
+ * needed to recognise it later (PLAN.md §3.4).
+ *
+ * After a crash the new owner must clean up the previous owner's `llama-server` processes without
+ * killing anything else. A PID from a dead owner's journal may have been recycled, so a process is
+ * only a *confirmed* orphan when its recorded start identity still matches the live process and the
+ * owner that spawned it is provably gone. Anything unproven is left running and reported.
+ */
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { verifyProcessIdentity } from './process-identity.js';
+export class ProcessJournal {
+    path;
+    records = [];
+    queue = Promise.resolve();
+    constructor(path) {
+        this.path = path;
+    }
+    static async open(layout) {
+        const journal = new ProcessJournal(layout.core.processes);
+        journal.records = await readJournal(layout.core.processes);
+        return journal;
+    }
+    list() {
+        return this.records.map((r) => ({ ...r }));
+    }
+    /** A journal entry must exist before the child can produce work, so this write is awaited. */
+    async add(record) {
+        this.records = [...this.records.filter((r) => r.pid !== record.pid), record];
+        await this.flush();
+    }
+    async remove(pid) {
+        if (!this.records.some((r) => r.pid === pid))
+            return;
+        this.records = this.records.filter((r) => r.pid !== pid);
+        await this.flush();
+    }
+    async replace(records) {
+        this.records = [...records];
+        await this.flush();
+    }
+    /**
+     * Classify the journal against reality. `currentInstanceId` is this owner: its own children are
+     * never orphans, and an entry from an owner that is still alive belongs to that owner.
+     */
+    async scanOrphans(currentInstanceId, liveOwnerInstanceIds, deps = {}) {
+        const scan = { confirmed: [], skipped: [], gone: [] };
+        for (const record of this.records) {
+            if (record.instance_id === currentInstanceId) {
+                scan.skipped.push({ record, reason: 'current-instance' });
+                continue;
+            }
+            if (liveOwnerInstanceIds.has(record.instance_id)) {
+                scan.skipped.push({ record, reason: 'owner-alive' });
+                continue;
+            }
+            const verdict = await verifyProcessIdentity(record.pid, record.process_start_id, deps);
+            if (verdict === 'dead' || verdict === 'mismatch')
+                scan.gone.push(record);
+            else if (verdict === 'match')
+                scan.confirmed.push(record);
+            else
+                scan.skipped.push({ record, reason: 'identity-unproven' });
+        }
+        return scan;
+    }
+    /** Forget entries for processes that are gone or were adopted elsewhere. */
+    async forget(records) {
+        if (records.length === 0)
+            return;
+        const drop = new Set(records.map((r) => r.pid));
+        this.records = this.records.filter((r) => !drop.has(r.pid));
+        await this.flush();
+    }
+    /** Serialised so concurrent adds cannot interleave a read-modify-write. */
+    flush() {
+        this.queue = this.queue.then(() => writeJournal(this.path, this.records));
+        return this.queue;
+    }
+}
+async function readJournal(path) {
+    const text = await readFile(path, 'utf8').catch(() => '');
+    if (!text.trim())
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return []; // a truncated journal costs cleanup, not correctness: unknown processes are never killed
+    }
+    const list = Array.isArray(raw) ? raw : raw?.processes;
+    if (!Array.isArray(list))
+        return [];
+    return list.filter(isChildProcessRecord);
+}
+function isChildProcessRecord(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const r = value;
+    return typeof r['pid'] === 'number' && typeof r['instance_id'] === 'string' && typeof r['exe'] === 'string';
+}
+async function writeJournal(path, records) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, `${JSON.stringify({ version: 1, processes: records }, null, 2)}\n`);
+    await rename(tmp, path).catch(async (e) => {
+        await rm(tmp, { force: true }).catch(() => { });
+        throw e;
+    });
+}
+//# sourceMappingURL=process-journal.js.map

package/dist/lock/process-journal.js.map

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

package/dist/models/capabilities.d.ts

@@ -0,0 +1,73 @@
+/**
+ * What the app asks about a model without loading it (PLAN.md §4, stage 3d).
+ *
+ * These are the extension's remaining "off-contract" methods — the ones that are not part of the
+ * provider interface but that the app calls anyway: is this file a usable GGUF, does this model
+ * have a projector, how large a context was it trained for, can it use speculative decoding. Every
+ * one of them is a question about files inside the data folder, which is why they move with the
+ * folder's owner rather than staying in a process that may no longer own it.
+ *
+ * All of them answer rather than throw. "This file is not a model" is the answer to a question the
+ * user asked by pointing at a file, not a failure of the core; the caller renders it.
+ */
+import type { DataLayout } from '../config/index.js';
+import type { LocalProviderId } from '../contracts/index.js';
+import type { ModelRegistry } from './registry.js';
+export interface GgufValidation {
+    isValid: boolean;
+    error?: string;
+    metadata?: Record<string, string>;
+}
+export interface ModelCapabilities {
+    modelId: string;
+    /** `{general.architecture}.context_length` — the ceiling for the context ladder. */
+    maxCtxTrain?: number;
+    /** A projector file exists, so this model can be given images. */
+    mmprojExists: boolean;
+    isEmbedding: boolean;
+    vision: boolean;
+    audio: boolean;
+    /** Speculative decoding this model id is known to support. */
+    gemmaMtp: boolean;
+    dflash: boolean;
+    dflashDrafts: string[];
+}
+export interface CapabilitiesDeps {
+    layout: DataLayout;
+    registry: (provider: LocalProviderId) => ModelRegistry;
+    /** Test seam; production reads the file. */
+    readMetadata?: (path: string) => Promise<Record<string, string>>;
+    exists?: (path: string) => Promise<boolean>;
+}
+export declare class ModelCapabilityService {
+    private readonly deps;
+    constructor(deps: CapabilitiesDeps);
+    /**
+     * Whether a file can be imported as a text-generation model.
+     *
+     * The one rejection that matters is a CLIP architecture: those files are projectors, they parse
+     * as perfectly good GGUF, and importing one as a model produces a session that answers every
+     * prompt with nothing. The app has always named this case specifically, so the core does too.
+     */
+    validateGguf(filePath: string): Promise<GgufValidation>;
+    /**
+     * Everything the app wants to know about an installed model.
+     *
+     * Answered from `model.yml` and the GGUF header together: the yml says where the files are and
+     * may name a projector explicitly, and the header says what the model is. A model whose files
+     * cannot be read still gets an answer — every capability false — because the caller is deciding
+     * what to show in a list, not whether to load it.
+     */
+    capabilities(provider: LocalProviderId, modelId: string): Promise<ModelCapabilities>;
+    /**
+     * A projector for this model.
+     *
+     * `model.yml` may name one; when it does not, the conventional `mmproj.gguf` beside the model is
+     * still a projector — the app has always looked for both, and a model imported before the yml
+     * carried the field would otherwise lose its vision.
+     */
+    mmprojExists(provider: LocalProviderId, modelId: string, declared?: string): Promise<boolean>;
+    /** Where this model's projector is, if it has one. */
+    private projectorPath;
+    private readMetadata;
+}

package/dist/models/capabilities.js

@@ -0,0 +1,123 @@
+/**
+ * What the app asks about a model without loading it (PLAN.md §4, stage 3d).
+ *
+ * These are the extension's remaining "off-contract" methods — the ones that are not part of the
+ * provider interface but that the app calls anyway: is this file a usable GGUF, does this model
+ * have a projector, how large a context was it trained for, can it use speculative decoding. Every
+ * one of them is a question about files inside the data folder, which is why they move with the
+ * folder's owner rather than staying in a process that may no longer own it.
+ *
+ * All of them answer rather than throw. "This file is not a model" is the answer to a question the
+ * user asked by pointing at a file, not a failure of the core; the caller renders it.
+ */
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { checkDflashSupport, checkGemmaMtpSupport, listDflashDrafts } from '../speculative/index.js';
+import { classifyProjector, ggufContextLength, isEmbeddingGguf } from './gguf/index.js';
+import { readGgufMetadataFromFile } from './gguf/read-file.js';
+const defaultExists = (path) => stat(path).then(() => true, () => false);
+export class ModelCapabilityService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Whether a file can be imported as a text-generation model.
+     *
+     * The one rejection that matters is a CLIP architecture: those files are projectors, they parse
+     * as perfectly good GGUF, and importing one as a model produces a session that answers every
+     * prompt with nothing. The app has always named this case specifically, so the core does too.
+     */
+    async validateGguf(filePath) {
+        let metadata;
+        try {
+            metadata = await this.readMetadata(filePath);
+        }
+        catch (e) {
+            return { isValid: false, error: e.message };
+        }
+        const architecture = metadata['general.architecture'];
+        if (architecture === 'clip') {
+            return {
+                isValid: false,
+                error: 'This model has CLIP architecture and cannot be imported as a text generation model. ' +
+                    'CLIP models are designed for vision tasks and require different handling.',
+                metadata,
+            };
+        }
+        return { isValid: true, metadata };
+    }
+    /**
+     * Everything the app wants to know about an installed model.
+     *
+     * Answered from `model.yml` and the GGUF header together: the yml says where the files are and
+     * may name a projector explicitly, and the header says what the model is. A model whose files
+     * cannot be read still gets an answer — every capability false — because the caller is deciding
+     * what to show in a list, not whether to load it.
+     */
+    async capabilities(provider, modelId) {
+        const base = {
+            modelId,
+            mmprojExists: false,
+            isEmbedding: false,
+            vision: false,
+            audio: false,
+            gemmaMtp: checkGemmaMtpSupport(modelId),
+            dflash: checkDflashSupport(modelId),
+            dflashDrafts: listDflashDrafts(modelId).map((draft) => draft.quant),
+        };
+        const registry = this.deps.registry(provider);
+        const yml = await registry.read(modelId).catch(() => undefined);
+        if (!yml)
+            return base;
+        const paths = registry.resolvePaths(yml);
+        const projectorPath = await this.projectorPath(provider, modelId, paths.mmprojPath);
+        base.mmprojExists = projectorPath !== undefined;
+        // What a model can be given comes from the *projector's* header, not the model's:
+        // `classifyProjector` answers "vision" for metadata with no clip keys at all, because a file
+        // that is a projector and says nothing else is a vision projector. Asked about a text model it
+        // would therefore claim every one of them takes images.
+        if (projectorPath) {
+            const projectorMeta = await this.readMetadata(projectorPath).catch(() => undefined);
+            if (projectorMeta) {
+                const projector = classifyProjector(projectorMeta);
+                base.vision = projector.vision;
+                base.audio = projector.audio;
+            }
+        }
+        const metadata = await this.readMetadata(paths.modelPath).catch(() => undefined);
+        if (!metadata)
+            return base;
+        const maxCtxTrain = ggufContextLength(metadata);
+        return {
+            ...base,
+            ...(maxCtxTrain !== undefined ? { maxCtxTrain } : {}),
+            isEmbedding: isEmbeddingGguf(metadata),
+        };
+    }
+    /**
+     * A projector for this model.
+     *
+     * `model.yml` may name one; when it does not, the conventional `mmproj.gguf` beside the model is
+     * still a projector — the app has always looked for both, and a model imported before the yml
+     * carried the field would otherwise lose its vision.
+     */
+    async mmprojExists(provider, modelId, declared) {
+        return (await this.projectorPath(provider, modelId, declared)) !== undefined;
+    }
+    /** Where this model's projector is, if it has one. */
+    async projectorPath(provider, modelId, declared) {
+        const exists = this.deps.exists ?? defaultExists;
+        // An absolute path already: `resolvePaths` resolved it against the data folder.
+        if (declared && (await exists(declared)))
+            return declared;
+        const conventional = join(this.deps.layout.provider(provider).modelsDir, modelId, 'mmproj.gguf');
+        return (await exists(conventional)) ? conventional : undefined;
+    }
+    async readMetadata(path) {
+        if (this.deps.readMetadata)
+            return this.deps.readMetadata(path);
+        return (await readGgufMetadataFromFile(path)).metadata;
+    }
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/models/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/models/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAGhC,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AACpG,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACvF,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAgC9D,MAAM,aAAa,GAAG,CAAC,IAAY,EAAE,EAAE,CACrC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CACb,GAAG,EAAE,CAAC,IAAI,EACV,GAAG,EAAE,CAAC,KAAK,CACZ,CAAA;AAEH,MAAM,OAAO,sBAAsB;IACJ;IAA7B,YAA6B,IAAsB;QAAtB,SAAI,GAAJ,IAAI,CAAkB;IAAG,CAAC;IAEvD;;;;;;OAMG;IACH,KAAK,CAAC,YAAY,CAAC,QAAgB;QACjC,IAAI,QAAgC,CAAA;QACpC,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAA;QAC9C,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAG,CAAW,CAAC,OAAO,EAAE,CAAA;QACxD,CAAC;QACD,MAAM,YAAY,GAAG,QAAQ,CAAC,sBAAsB,CAAC,CAAA;QACrD,IAAI,YAAY,KAAK,MAAM,EAAE,CAAC;YAC5B,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EACH,sFAAsF;oBACtF,2EAA2E;gBAC7E,QAAQ;aACT,CAAA;QACH,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;IACpC,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,YAAY,CAAC,QAAyB,EAAE,OAAe;QAC3D,MAAM,IAAI,GAAsB;YAC9B,OAAO;YACP,YAAY,EAAE,KAAK;YACnB,WAAW,EAAE,KAAK;YAClB,MAAM,EAAE,KAAK;YACb,KAAK,EAAE,KAAK;YACZ,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC;YACvC,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC;YACnC,YAAY,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC;SACpE,CAAA;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;QAC7C,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QAC/D,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAA;QAErB,MAAM,KAAK,GAAG,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,CAAA;QACxC,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;QACnF,IAAI,CAAC,YAAY,GAAG,aAAa,KAAK,SAAS,CAAA;QAE/C,kFAAkF;QAClF,6FAA6F;QAC7F,+FAA+F;QAC/F,wDAAwD;QACxD,IAAI,aAAa,EAAE,CAAC;YAClB,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;YACnF,IAAI,aAAa,EAAE,CAAC;gBAClB,MAAM,SAAS,GAAG,iBAAiB,CAAC,aAAa,CAAC,CAAA;gBAClD,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,CAAA;gBAC9B,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC,KAAK,CAAA;YAC9B,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QAChF,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAA;QAE1B,MAAM,WAAW,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAA;QAC/C,OAAO;YACL,GAAG,IAAI;YACP,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,WAAW,EAAE,eAAe,CAAC,QAAQ,CAAC;SACvC,CAAA;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,YAAY,CAAC,QAAyB,EAAE,OAAe,EAAE,QAAiB;QAC9E,OAAO,CAAC,MAAM,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,KAAK,SAAS,CAAA;IAC9E,CAAC;IAED,sDAAsD;IAC9C,KAAK,CAAC,aAAa,CACzB,QAAyB,EACzB,OAAe,EACf,QAAiB;QAEjB,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,aAAa,CAAA;QAChD,gFAAgF;QAChF,IAAI,QAAQ,IAAI,CAAC,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;YAAE,OAAO,QAAQ,CAAA;QACzD,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,aAAa,CAAC,CAAA;QAChG,OAAO,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAA;IAChE,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,IAAY;QACrC,IAAI,IAAI,CAAC,IAAI,CAAC,YAAY;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAA;QAC/D,OAAO,CAAC,MAAM,wBAAwB,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAA;IACxD,CAAC;CACF"}

package/dist/models/embed.d.ts

@@ -0,0 +1,30 @@
+import type { LocalProviderId, SessionInfo } from '../contracts/index.js';
+export interface EmbeddingResponse {
+    model: string;
+    object: 'list';
+    usage: {
+        prompt_tokens: number;
+        total_tokens: number;
+    };
+    data: Array<{
+        embedding: number[];
+        index: number;
+    }>;
+}
+export interface EmbedDeps {
+    findSession: (provider: LocalProviderId, modelId: string) => SessionInfo | undefined;
+    load: (provider: LocalProviderId, modelId: string) => Promise<SessionInfo>;
+    unload: (provider: LocalProviderId, modelId: string) => Promise<unknown>;
+    fetch?: typeof fetch;
+}
+export declare class EmbedService {
+    private readonly deps;
+    constructor(deps: EmbedDeps);
+    embed(provider: LocalProviderId, modelId: string, input: string[], ubatchSize: number): Promise<EmbeddingResponse>;
+    private request;
+}
+/** Same 3-chars/token, 50% safety-margin packing the legacy extension uses. */
+export declare function buildEmbedBatches(input: string[], ubatchSize: number): Array<{
+    batch: string[];
+    offset: number;
+}>;