@qvac/harness 0.3.2 → 0.4.0

package/dist-lib/index.d.ts

@@ -3,6 +3,7 @@ import ReadyResource from 'ready-resource';
 import { type Agent, type ApproveFn, type AskUserFn, type AttachFn, type CompletionEvent, type FetchAttachmentFn, type Message, type ProgressFn, type RagSearchFn, type ResponseFormat, type ToolDefinition, type ToolExecuteContext } from './lib/capabilities/completion.ts';
 import { type DetectLanguageContext, type DetectedLanguage } from './lib/capabilities/detect-language.ts';
 import { type Capability } from './lib/capabilities/invoke.ts';
+import { type ModelSourcePreview, type PreviewModelSourceContext } from './lib/capabilities/preview-model-source.ts';
 import { type EnhanceMode } from './lib/capabilities/enhance.ts';
 import { type DownloadArgs, type DownloadEventStream } from './lib/capabilities/download.ts';
 import { type EmbedContext } from './lib/capabilities/embed.ts';
@@ -29,6 +30,7 @@ export { CAPABILITIES, isCapability, type Capability } from './lib/capabilities/
 export type { EnhanceMode } from './lib/capabilities/enhance.ts';
 export { EURONANO_LANGUAGES, NMT_FROM_ENGLISH, NMT_TO_ENGLISH, SLM_LANGUAGE_CODES, SLM_LANGUAGE_NAMES, translationPlanFor, type TranslationPlan } from './lib/models/nmt-catalog.ts';
 export type { DetectLanguageContext, DetectedLanguage } from './lib/capabilities/detect-language.ts';
+export type { ModelFitVerdict, ModelSourceFile, ModelSourcePreview, ModelSourceRefusal, PreviewModelSourceContext } from './lib/capabilities/preview-model-source.ts';
 export * from './lib/capabilities/download.ts';
 export type { EmbedContext } from './lib/capabilities/embed.ts';
 export type { SpeakContext, SpeakResult, SpeakStreamContext, TranscribeContext } from './lib/capabilities/voice.ts';
@@ -73,6 +75,7 @@ export interface HarnessOptions {
     gpuStats?: unknown;
     sdkLoader?: SdkLoader;
     skillsDir?: string;
+    modelsDir?: string;
     projectionModel?: string | Record<string, string>;
     imageModel?: string | ImageModelOptions;
     imageClamps?: ImageClamps;
@@ -141,6 +144,7 @@ export declare class Harness extends ReadyResource {
     private _voiceLane;
     private _state;
     private _skillsDir?;
+    private readonly _modelsDir?;
     private _overlayWatcher;
     private _supportedSkills;
     private _projectionModel;
@@ -168,7 +172,7 @@ export declare class Harness extends ReadyResource {
     private _capability;
     private _capabilityInflight;
     private readonly _modelFaults;
-    constructor({ tools, sdkLoader, skillsDir, projectionModel, imageModel, imageClamps, musicModel, musicClamps, llmDevice, llmGpuLayers, contextSize, kvCacheK, kvCacheV, embedDevice, embedGpuLayers, embedBatchSize, transcriptionDevice, completionModelCap, credentialStore, platform, gpuStats }?: HarnessOptions);
+    constructor({ tools, sdkLoader, skillsDir, modelsDir, projectionModel, imageModel, imageClamps, musicModel, musicClamps, llmDevice, llmGpuLayers, contextSize, kvCacheK, kvCacheV, embedDevice, embedGpuLayers, embedBatchSize, transcriptionDevice, completionModelCap, credentialStore, platform, gpuStats }?: HarnessOptions);
     _open(): Promise<void>;
     get suspended(): boolean;
     get skillNames(): string[];
@@ -212,6 +216,7 @@ export declare class Harness extends ReadyResource {
     supportsImagesFor(model: string): boolean;
     private _projectionFor;
     setCustomModels(entries: ReadonlyArray<CustomModelEntry>): void;
+    previewModelSource(context: PreviewModelSourceContext): Promise<ModelSourcePreview>;
     describe(): Promise<HarnessInfo>;
     diagnostics(): HarnessDiagnostics;
     private _loadedModels;

package/dist-lib/index.js

@@ -8,6 +8,7 @@ import { closePythonWorker } from './lib/tools/exec/adapters/python/worker/clien
 import { completion, imageSettingsFrom } from './lib/capabilities/completion.js';
 import { detectLanguage } from './lib/capabilities/detect-language.js';
 import { invoke } from './lib/capabilities/invoke.js';
+import { previewModelSource } from './lib/capabilities/preview-model-source.js';
 import { expandImagePrompt } from './lib/capabilities/enhance.js';
 import { cleanAnswer } from './lib/helpers/clean-answer.js';
 import { isTranslationModel } from './lib/models/nmt-catalog.js';
@@ -21,7 +22,7 @@ import { createVoiceLane, packSamples, speakOnce, speakStreamOnce, transcribeOnc
 import { pushQueue } from './lib/queue.js';
 import { AbortedError, raceAbort } from './lib/helpers/race-abort.js';
 import { audioGenDownloadMetadata, customProjectionMap, defaultProjectionMap, defaultTtsFor, defaultVoiceModel, diffusionDownloadMetadata, infraModelsFor, modelNameToCapabilityProfile, musicModelSet, setCustomModels } from './lib/models/model-catalog.js';
-import { createModelStatusCache, invalidateModelStatusCache, listModels } from './lib/models/model-list.js';
+import { createModelStatusCache, customModelRows, invalidateModelStatusCache, mergeCustomRows, listModels } from './lib/models/model-list.js';
 import { deleteModelFiles, summarizeDelete } from './lib/models/model-delete.js';
 import { createEmbedPool, createLoadTracker, createModelPool, createVoicePool, awaitModelCapacity, evictIdle, evictModelWithin, isResident, leaseResidentModel, leaseCount, loadedModels, modelKey, releaseModel, resolveLoadOptions, progressState } from './lib/models/model-pool.js';
 import { resolveMainGpu } from './lib/models/gpu-selection.js';
@@ -104,6 +105,7 @@ export class Harness extends ReadyResource {
     _voiceLane = createVoiceLane();
     _state;
     _skillsDir;
+    _modelsDir;
     _overlayWatcher = null;
     _supportedSkills;
     _projectionModel;
@@ -131,7 +133,7 @@ export class Harness extends ReadyResource {
     _capability = null;
     _capabilityInflight = null;
     _modelFaults = new Map();
-    constructor({ tools = [], sdkLoader, skillsDir, projectionModel, imageModel, imageClamps, musicModel, musicClamps, llmDevice, llmGpuLayers, contextSize, kvCacheK, kvCacheV, embedDevice, embedGpuLayers, embedBatchSize, transcriptionDevice, completionModelCap, credentialStore, platform, gpuStats } = {}) {
+    constructor({ tools = [], sdkLoader, skillsDir, modelsDir, projectionModel, imageModel, imageClamps, musicModel, musicClamps, llmDevice, llmGpuLayers, contextSize, kvCacheK, kvCacheV, embedDevice, embedGpuLayers, embedBatchSize, transcriptionDevice, completionModelCap, credentialStore, platform, gpuStats } = {}) {
         super();
         this._sdk = sdkLoader ?? createSdkLoader();
         this._llmDevice = llmDevice;
@@ -235,6 +237,7 @@ export class Harness extends ReadyResource {
         this._projectionModel = projectionModel ?? defaultProjectionMap();
         this._state = HarnessState.RESUME;
         this._skillsDir = skillsDir;
+        this._modelsDir = modelsDir;
         this._supportedSkills = [];
         this._allSkills = [];
         this._credentialStore = credentialStore;
@@ -480,6 +483,21 @@ export class Harness extends ReadyResource {
         setCustomModels(entries);
         this._customProjection = customProjectionMap();
     }
+    previewModelSource(context) {
+        return previewModelSource(context, {
+            assessFit: async ({ sha256Checksum, name, contextTokens }) => {
+                const sdk = await this._sdk.load();
+                const result = await sdk.assessModelFit({
+                    models: [{ model: { sha256Checksum, name }, workload: { kind: 'llm', contextTokens } }]
+                });
+                const model = result.models[0];
+                return {
+                    fit: model?.verdict ?? result.verdict,
+                    fitReasons: [...(model?.reasons ?? result.reasons)]
+                };
+            }
+        });
+    }
     async describe() {
         if (!this.opened)
             await this.ready();
@@ -906,12 +924,19 @@ export class Harness extends ReadyResource {
     async list(options = {}) {
         await this.ready();
         const sdk = (await this._sdk.load());
-        return listModels(sdk, options, this._modelStatus, (name) => this._projectionFor(name));
+        const [rows, custom] = await Promise.all([
+            listModels(sdk, options, this._modelStatus, (name) => this._projectionFor(name)),
+            customModelRows(options, {
+                modelsDir: this._modelsDir,
+                loaded: new Set(this._loadedModels().map((entry) => entry.model))
+            })
+        ]);
+        return mergeCustomRows(rows, custom);
     }
     async deleteModel(name) {
         await this.ready();
         const sdk = (await this._sdk.load());
-        const result = await deleteModelFiles(sdk, name);
+        const result = await deleteModelFiles(sdk, name, { modelsDir: this._modelsDir });
         invalidateModelStatusCache(this._modelStatus);
         return summarizeDelete(result);
     }

package/dist-lib/lib/capabilities/completion.js

@@ -29,7 +29,6 @@ import { NETWORK_TOOLSETS, permittedTools } from '../tools/toolsets.js';
 import { promptPrefixHash } from './prompt-prefix.js';
 import { logToolPrompt } from './tool-prompt-log.js';
 import { DIRECT_CALL_ID, loadedSkillFilesFrom, loadedSkillsFrom, TOOL_CONTINUATION_NUDGE, toolResultTurn, withoutSkillLoadTurns } from './tool-turns.js';
-import { projectVisionHistory, visionHistoryCacheKey } from './vision-history.js';
 export function imageSettingsFrom(agent) {
     if (!agent)
         return undefined;
@@ -545,7 +544,7 @@ async function* runRecoveredRoundWith(sdk, args, modelId) {
         const cacheable = candidate.history === args.history;
         const params = {
             modelId,
-            history: projectVisionHistory(candidate.history),
+            history: candidate.history,
             stream: true,
             tools: args.tools,
             generationParams: args.generationParams,
@@ -718,7 +717,6 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
         const toolDialect = model ? customToolDialect(model) : undefined;
         let turns = messages;
         let preloadedSkill = null;
-        let stubDropped = false;
         const preload = mention ?? resolveImplicitSkill(lastUserContent(messages), activeSkills);
         if (preload) {
             const loader = tools.find((tool) => tool.name === SKILL_TOOL_NAME);
@@ -727,7 +725,6 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 preloadedSkill = String(loaded.content);
                 const inlined = preloadLastUser(messages, preload.name, preloadedSkill);
                 turns = withoutSkillLoadTurns(inlined, preload.name);
-                stubDropped = turns.length < inlined.length;
                 if (!loadedSkills.has(preload.name)) {
                     const preloadArgs = { name: preload.name };
                     const preloadEffect = 'read';
@@ -798,7 +795,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
         }
         logSelection();
         let history = annotateLastUserTime(systemContent ? [{ role: 'system', content: systemContent }, ...turns] : turns);
-        let roundCacheKey = stubDropped ? undefined : visionHistoryCacheKey(cacheKey, history);
+        let roundCacheKey = preloadedSkill === null ? cacheKey : undefined;
         const runUsage = () => usageBreakdown(promptParts, stats.cacheTokens, model);
         const denied = new Set();
         const failed = new Map();

package/dist-lib/lib/capabilities/preview-model-source.d.ts

@@ -0,0 +1,67 @@
+import type { HarnessPreviewModelSourceResponse } from '../../spec/hyperschema/types.d.ts';
+export type ModelFitVerdict = 'likely-fits' | 'likely-too-large' | 'unknown';
+export type ModelSourceRefusal = 'invalid-source' | 'not-found' | 'private' | 'gated' | 'web-page' | 'unreachable' | 'not-gguf' | 'not-a-model' | 'no-model-files' | 'invalid-projection';
+export type ModelTaskType = 'llm' | 'embeddings' | 'speech-to-text' | 'text-to-speech' | 'image-generation';
+export interface ModelSourceFile {
+    src: string;
+    label: string;
+    sizeBytes: number;
+}
+export interface ModelSourcePreview {
+    ok: boolean;
+    refusal?: ModelSourceRefusal;
+    reason?: string;
+    src?: string;
+    files?: ModelSourceFile[];
+    sizeBytes?: number;
+    contextLength?: number;
+    architecture?: string;
+    sizeLabel?: string;
+    taskType?: string;
+    license?: string;
+    fit?: ModelFitVerdict;
+    fitReasons?: string[];
+    mmprojSrc?: string;
+}
+export interface PreviewModelSourceContext {
+    src: string;
+    mmprojSrc?: string;
+}
+export interface PreviewResponse {
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+export type PreviewFetch = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    redirect?: 'follow';
+}) => Promise<PreviewResponse>;
+export interface FitQuery {
+    sha256Checksum: string;
+    name: string;
+    contextTokens: number;
+}
+export interface PreviewDeps {
+    fetch?: PreviewFetch;
+    stat?(path: string): Promise<{
+        size: number;
+    } | null>;
+    assessFit?(query: FitQuery): Promise<{
+        fit: ModelFitVerdict;
+        fitReasons: string[];
+    }>;
+}
+interface HuggingFaceRef {
+    repo: string;
+    revision: string;
+    file?: string;
+}
+export declare function previewModelSource(context: PreviewModelSourceContext, deps?: PreviewDeps): Promise<ModelSourcePreview>;
+export declare function readModelSourcePreview(response: HarnessPreviewModelSourceResponse): ModelSourcePreview;
+export declare function parseHuggingFaceRef(src: string): HuggingFaceRef | null;
+export {};

package/dist-lib/lib/capabilities/preview-model-source.js

@@ -0,0 +1,387 @@
+import fs from 'fs';
+import defaultFetch from '#fetch';
+import { defaultContextSize } from '../models/context.js';
+import { isRemoteSource, localSourcePath, parseGgufHeader, readGgufHeaderBytes } from '../models/gguf-header.js';
+const HUGGING_FACE = 'https://huggingface.co';
+const HUGGING_FACE_HOSTS = new Set(['huggingface.co', 'www.huggingface.co', 'hf.co']);
+const NON_MODEL_NAMESPACES = new Set(['api', 'datasets', 'spaces', 'docs', 'models']);
+const SHARD = /^(.+)-(\d{5})-of-(\d{5})\.gguf$/i;
+const PIPELINE_TASKS = {
+    'automatic-speech-recognition': 'speech-to-text',
+    'text-to-speech': 'text-to-speech',
+    'text-to-image': 'image-generation',
+    'feature-extraction': 'embeddings',
+    'sentence-similarity': 'embeddings',
+    'text-generation': 'llm',
+    'image-text-to-text': 'llm'
+};
+const ARCHITECTURE_TASKS = [
+    [/^whisper/i, 'speech-to-text'],
+    [/^parakeet/i, 'speech-to-text'],
+    [/^flux/i, 'image-generation'],
+    [/^supertonic/i, 'text-to-speech'],
+    [/bert/i, 'embeddings']
+];
+const NOT_LLM_REASON = 'Fit is estimated only for text-generation models.';
+const NO_CHECKSUM_REASON = 'Fit is estimated only for files the SDK catalog knows by checksum, and this source publishes none.';
+const NO_ESTIMATOR_REASON = 'This harness has no fit estimator.';
+export async function previewModelSource(context, deps = {}) {
+    const fetch = deps.fetch ?? defaultFetch;
+    const src = context.src.trim();
+    if (!src) {
+        return refuse('invalid-source', 'Paste a Hugging Face link, a direct link to a .gguf file, or a local path.');
+    }
+    const weight = await inspectModelFile(src, fetch, deps);
+    if ('answer' in weight)
+        return weight.answer;
+    const problem = modelProblem(weight.header);
+    if (problem)
+        return refuse(problem[0], problem[1]);
+    const taskType = taskTypeFor({
+        pipelineTag: weight.file.pipelineTag,
+        tags: [...(weight.file.tags ?? []), ...(weight.header.tags ?? [])],
+        architecture: weight.header.architecture
+    });
+    let projectionBytes = 0;
+    let projectionSrc;
+    const mmprojSrc = context.mmprojSrc?.trim();
+    if (mmprojSrc) {
+        const projection = await inspectModelFile(mmprojSrc, fetch, deps);
+        if ('answer' in projection) {
+            return projection.answer.ok
+                ? refuse('invalid-projection', 'Link the projection (mmproj) file itself, not its repository.')
+                : refuse('invalid-projection', `The projection was refused: ${projection.answer.reason ?? ''}`.trim());
+        }
+        if (!isProjection(projection.header)) {
+            return refuse('invalid-projection', 'The projection is not an mmproj file.');
+        }
+        projectionBytes = projection.file.sizeBytes;
+        projectionSrc = projection.file.src;
+    }
+    const { fit, fitReasons } = await assess(weight.file, weight.header, taskType, deps);
+    return defined({
+        ok: true,
+        src: weight.file.src,
+        sizeBytes: weight.file.sizeBytes + projectionBytes || undefined,
+        contextLength: weight.header.contextLength,
+        architecture: weight.header.architecture,
+        sizeLabel: weight.header.sizeLabel,
+        taskType,
+        license: weight.file.license ?? weight.header.license,
+        fit,
+        fitReasons,
+        mmprojSrc: projectionSrc
+    });
+}
+export function readModelSourcePreview(response) {
+    return defined({
+        ok: response.ok === true,
+        refusal: (response.refusal || undefined),
+        reason: response.reason || undefined,
+        src: response.src || undefined,
+        files: response.files?.length
+            ? response.files.map(({ src, label, sizeBytes }) => ({
+                src,
+                label,
+                sizeBytes: sizeBytes ?? 0
+            }))
+            : undefined,
+        sizeBytes: response.sizeBytes || undefined,
+        contextLength: response.contextLength || undefined,
+        architecture: response.architecture || undefined,
+        sizeLabel: response.sizeLabel || undefined,
+        taskType: response.taskType || undefined,
+        license: response.license || undefined,
+        fit: (response.fit || undefined),
+        fitReasons: response.fitReasons?.length ? [...response.fitReasons] : undefined,
+        mmprojSrc: response.mmprojSrc || undefined
+    });
+}
+export function parseHuggingFaceRef(src) {
+    let url;
+    try {
+        url = new URL(src);
+    }
+    catch {
+        return null;
+    }
+    if (!HUGGING_FACE_HOSTS.has(url.hostname))
+        return null;
+    const segments = pathSegments(url.pathname);
+    if (!segments)
+        return null;
+    const [org, name, kind, revision, ...rest] = segments;
+    if (!org || !name || NON_MODEL_NAMESPACES.has(org))
+        return null;
+    const repo = `${org}/${name}`;
+    if (!kind) {
+        const shown = url.searchParams.get('show_file_info');
+        return shown ? { repo, revision: 'main', file: shown } : { repo, revision: 'main' };
+    }
+    if ((kind === 'blob' || kind === 'resolve') && revision && rest.length > 0) {
+        return { repo, revision, file: rest.join('/') };
+    }
+    if (kind === 'tree' && revision)
+        return { repo, revision };
+    return null;
+}
+async function inspectModelFile(src, fetch, deps) {
+    const inspection = await inspect(src, fetch, deps);
+    if (inspection.kind === 'answer')
+        return { answer: inspection.preview };
+    const bytes = await readGgufHeaderBytes(inspection.file.src, {
+        fetch: fetch
+    });
+    if (!bytes) {
+        return {
+            answer: refuse('unreachable', 'Could not read the start of the file to check it is a model.')
+        };
+    }
+    const header = parseGgufHeader(bytes);
+    if (!header) {
+        return {
+            answer: refuse('not-gguf', 'This is not a GGUF file. Only GGUF models run on this device.')
+        };
+    }
+    return { file: inspection.file, header };
+}
+function inspect(src, fetch, deps) {
+    const ref = parseHuggingFaceRef(src);
+    if (ref)
+        return inspectHuggingFace(ref, fetch);
+    if (isRemoteSource(src)) {
+        return wellFormedUrl(src)
+            ? inspectUrl(src, fetch)
+            : Promise.resolve(answer(refuse('invalid-source', 'This link is not a valid URL.')));
+    }
+    const file = localSourcePath(src);
+    if (file === null) {
+        return Promise.resolve(answer(refuse('invalid-source', 'Only Hugging Face links, http(s) links and local paths can be added.')));
+    }
+    return inspectLocal(src, file, deps);
+}
+async function inspectHuggingFace(ref, fetch) {
+    let response;
+    try {
+        response = await fetch(modelInfoUrl(ref));
+    }
+    catch {
+        return answer(refuse('unreachable', 'Could not reach Hugging Face.'));
+    }
+    if (response.status === 401 || response.status === 403) {
+        return answer(refuse('private', `${ref.repo} is private or does not exist on Hugging Face.`));
+    }
+    if (response.status === 404) {
+        return answer(refuse('not-found', `${ref.repo} does not exist on Hugging Face.`));
+    }
+    if (!response.ok) {
+        return answer(refuse('unreachable', `Hugging Face answered HTTP ${response.status}.`));
+    }
+    const info = (await response.json());
+    if (info.private) {
+        return answer(refuse('private', `${ref.repo} is private on Hugging Face.`));
+    }
+    if (info.gated) {
+        return answer(refuse('gated', `${ref.repo} is gated: its files need an accepted license and a Hugging Face sign-in, which custom models do not support.`));
+    }
+    const pipelineTag = info.pipeline_tag;
+    const license = licenseOf(info);
+    const siblings = info.siblings ?? [];
+    const candidates = modelFiles(ref, siblings);
+    const wanted = ref.file;
+    if (wanted) {
+        const sibling = siblings.find((entry) => entry.rfilename === wanted);
+        if (!sibling)
+            return answer(refuse('not-found', `${ref.repo} has no file ${wanted}.`));
+        if (!/\.gguf$/i.test(wanted)) {
+            return answer(refuse('not-gguf', `${wanted} is not a GGUF file. Only GGUF models run on this device.`));
+        }
+        const file = candidates.find((candidate) => candidate.members.includes(wanted)) ?? fileOf(ref, sibling);
+        return { kind: 'file', file: { ...file, license, pipelineTag, tags: info.tags } };
+    }
+    if (candidates.length === 0) {
+        return answer(refuse('no-model-files', `${ref.repo} has no GGUF model file. Only GGUF models run on this device.`));
+    }
+    if (candidates.length === 1) {
+        return { kind: 'file', file: { ...candidates[0], license, pipelineTag, tags: info.tags } };
+    }
+    return answer(defined({
+        ok: true,
+        files: candidates.map(({ src, label, sizeBytes }) => ({ src, label, sizeBytes })),
+        license,
+        taskType: taskTypeFor({ pipelineTag, tags: info.tags })
+    }));
+}
+async function inspectUrl(src, fetch) {
+    let response;
+    try {
+        response = await fetch(src, { method: 'HEAD', redirect: 'follow' });
+    }
+    catch {
+        return answer(refuse('unreachable', `Could not reach ${new URL(src).host}.`));
+    }
+    const { status } = response;
+    if (status === 401 || status === 403) {
+        return answer(refuse('private', `The server refused access (HTTP ${status}). Only public links can be added.`));
+    }
+    if (status === 404 || status === 410) {
+        return answer(refuse('not-found', `Nothing is at this link (HTTP ${status}).`));
+    }
+    if (status === 405 || status === 501) {
+        return { kind: 'file', file: { src, label: basename(src), sizeBytes: 0 } };
+    }
+    if (!response.ok) {
+        return answer(refuse('unreachable', `The server answered HTTP ${status}.`));
+    }
+    if ((response.headers.get('content-type') ?? '').includes('text/html')) {
+        return answer(refuse('web-page', 'This link opens a web page, not a model file. Link to the .gguf file itself.'));
+    }
+    const sizeBytes = positive(response.headers.get('x-linked-size')) ??
+        positive(response.headers.get('content-length')) ??
+        0;
+    return { kind: 'file', file: { src, label: basename(src), sizeBytes } };
+}
+async function inspectLocal(src, file, deps) {
+    const stat = await (deps.stat ?? statFile)(file);
+    if (!stat)
+        return answer(refuse('not-found', `There is no file at ${file}.`));
+    return { kind: 'file', file: { src, label: basename(file), sizeBytes: stat.size } };
+}
+async function statFile(file) {
+    try {
+        const stat = await fs.promises.stat(file);
+        return stat.isFile() ? { size: stat.size } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function modelFiles(ref, siblings) {
+    const singles = [];
+    const shardSets = new Map();
+    for (const sibling of siblings) {
+        const name = sibling.rfilename;
+        if (!/\.gguf$/i.test(name) || /mmproj/i.test(name))
+            continue;
+        const shard = SHARD.exec(name);
+        if (!shard) {
+            singles.push({ ...fileOf(ref, sibling), members: [name] });
+            continue;
+        }
+        const key = `${shard[1]}|${shard[3]}`;
+        shardSets.set(key, [...(shardSets.get(key) ?? []), sibling]);
+    }
+    const sets = [...shardSets.values()].map((parts) => {
+        const sorted = [...parts].sort((a, b) => a.rfilename.localeCompare(b.rfilename));
+        const first = sorted[0];
+        return {
+            src: resolveUrl(ref, first.rfilename),
+            label: `${basename(first.rfilename.replace(/-\d{5}-of-\d{5}\.gguf$/i, '.gguf'))} (${sorted.length} parts)`,
+            sizeBytes: sorted.reduce((total, part) => total + sizeOf(part), 0),
+            members: sorted.map((part) => part.rfilename)
+        };
+    });
+    return [...singles, ...sets];
+}
+function fileOf(ref, sibling) {
+    return defined({
+        src: resolveUrl(ref, sibling.rfilename),
+        label: basename(sibling.rfilename),
+        sizeBytes: sizeOf(sibling),
+        sha256: sibling.lfs?.sha256
+    });
+}
+function modelProblem(header) {
+    if (isProjection(header)) {
+        return [
+            'not-a-model',
+            'This is a vision projection (mmproj), not a model. Add the model file and pass this as its projection.'
+        ];
+    }
+    if (header.type === 'adapter')
+        return ['not-a-model', 'This is a LoRA adapter, not a model.'];
+    return null;
+}
+function isProjection(header) {
+    return header.architecture === 'clip' || header.type === 'mmproj';
+}
+function taskTypeFor({ pipelineTag, tags = [], architecture }) {
+    const tagged = [pipelineTag, ...tags].find((tag) => tag !== undefined && Object.hasOwn(PIPELINE_TASKS, tag));
+    if (tagged)
+        return PIPELINE_TASKS[tagged];
+    return ARCHITECTURE_TASKS.find(([pattern]) => pattern.test(architecture ?? ''))?.[1] ?? 'llm';
+}
+async function assess(file, header, taskType, deps) {
+    if (taskType !== 'llm')
+        return { fit: 'unknown', fitReasons: [NOT_LLM_REASON] };
+    if (!file.sha256)
+        return { fit: 'unknown', fitReasons: [NO_CHECKSUM_REASON] };
+    if (!deps.assessFit)
+        return { fit: 'unknown', fitReasons: [NO_ESTIMATOR_REASON] };
+    try {
+        return await deps.assessFit({
+            sha256Checksum: file.sha256,
+            name: header.name ?? file.label,
+            contextTokens: Math.min(header.contextLength || defaultContextSize(file.src), defaultContextSize(file.src))
+        });
+    }
+    catch (err) {
+        return {
+            fit: 'unknown',
+            fitReasons: [`The fit estimate failed: ${err instanceof Error ? err.message : String(err)}`]
+        };
+    }
+}
+function modelInfoUrl(ref) {
+    const revision = ref.revision === 'main' ? '' : `/revision/${encodeURIComponent(ref.revision)}`;
+    return `${HUGGING_FACE}/api/models/${encodePath(ref.repo)}${revision}?blobs=true`;
+}
+function resolveUrl(ref, file) {
+    return `${HUGGING_FACE}/${encodePath(ref.repo)}/resolve/${encodeURIComponent(ref.revision)}/${encodePath(file)}`;
+}
+function encodePath(path) {
+    return path.split('/').map(encodeURIComponent).join('/');
+}
+function pathSegments(pathname) {
+    try {
+        return pathname.split('/').filter(Boolean).map(decodeURIComponent);
+    }
+    catch {
+        return null;
+    }
+}
+function wellFormedUrl(src) {
+    try {
+        return pathSegments(new URL(src).pathname) !== null;
+    }
+    catch {
+        return false;
+    }
+}
+function licenseOf(info) {
+    const license = info.cardData?.license;
+    if (Array.isArray(license))
+        return license.length ? license.join(', ') : undefined;
+    return license || undefined;
+}
+function sizeOf(sibling) {
+    return sibling.lfs?.size ?? sibling.size ?? 0;
+}
+function basename(src) {
+    const path = src.split(/[?#]/)[0];
+    const name = path.slice(path.lastIndexOf('/') + 1);
+    return (pathSegments(name) ?? [name])[0] || src;
+}
+function positive(raw) {
+    const value = Number(raw);
+    return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+function refuse(refusal, reason) {
+    return { ok: false, refusal, reason };
+}
+function answer(preview) {
+    return { kind: 'answer', preview };
+}
+function defined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}

package/dist-lib/lib/connect.d.ts

@@ -1,6 +1,8 @@
 import EventEmitter from 'events';
 import { type Transport } from './rpc-session.ts';
 import { type KvCacheDeletionResult } from './capabilities/kv-cache.ts';
+import type { CustomModelEntry } from './models/model-catalog.ts';
+import { type ModelSourcePreview, type PreviewModelSourceContext } from './capabilities/preview-model-source.ts';
 import type { CapabilityInfo, CompletionContext, DetectedLanguage, DetectLanguageContext, DownloadContext, EmbedContext, HarnessContract, HarnessDiagnostics, HarnessEvent, HarnessInfo, InvokeContext, ListModelsOptions, ModelInfo, ResolvedSkillCatalogEntry, SpeakContext, SpeakResult, SpeakStreamContext, ToolCatalogEntry, TranscribeContext, WarmModelContext } from './contract-types.ts';
 import { type EmbedDevice } from './models/embed-config.ts';
 import type { DeleteModelSummary } from './models/model-delete.ts';
@@ -54,11 +56,8 @@ export declare class RemoteHarness extends EventEmitter implements HarnessContra
     deleteOverlaySkill(name: string): Promise<{
         removed: boolean;
     }>;
-    setCustomModels(entries: ReadonlyArray<{
-        name: string;
-        src: string;
-        projectionSrc?: string;
-    }>): Promise<void>;
+    setCustomModels(entries: ReadonlyArray<CustomModelEntry>): Promise<void>;
+    previewModelSource(context: PreviewModelSourceContext): Promise<ModelSourcePreview>;
     skills(agentId?: string | null, modelName?: string | null, options?: {
         readonly refresh?: boolean;
         readonly skipCredentialProbe?: boolean;

package/dist-lib/lib/connect.js

@@ -4,6 +4,7 @@ import { settleOnClose } from './rpc-session.js';
 import { harnessClient } from '../spec/calls.js';
 import HRPC from '../spec/hrpc/index.js';
 import { unsupportedKvCacheDeletion } from './capabilities/kv-cache.js';
+import { readModelSourcePreview } from './capabilities/preview-model-source.js';
 import { hlog } from './log.js';
 import { assertEmbedDevice } from './models/embed-config.js';
 import { errorCode, errorMessage } from './error-fields.js';
@@ -462,6 +463,14 @@ export class RemoteHarness extends EventEmitter {
         const { client } = await this._ensure();
         await client.setCustomModels({ models: entries });
     }
+    async previewModelSource(context) {
+        const { client } = await this._ensure();
+        const response = await client.previewModelSource({
+            src: context.src,
+            mmprojSrc: context.mmprojSrc
+        });
+        return readModelSourcePreview(response);
+    }
     async skills(agentId, modelName, options) {
         const { client } = await this._ensure();
         const response = await client.skills({