@camstack/addon-ai 0.4.3 → 0.4.4

package/dist/addon.js

@@ -8,9 +8,9 @@ let node_path$1 = require_chunk.__toESM(node_path, 1);
 node_path = require_chunk.__toESM(node_path);
 let node_crypto = require("node:crypto");
 let node_net = require("node:net");
-let node_util = require("node:util");
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs, 1);
+let node_util = require("node:util");
 let node_zlib = require("node:zlib");
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = require_chunk.__toESM(node_fs_promises);
@@ -12474,6 +12474,18 @@ var LlmGenerateBaseInputSchema = object({
 * Resource ceiling = llama-server flags + idleStopMinutes ONLY (no RSS
 * watchdog — operator decision #3).
 */
+/**
+* A companion artifact that MUST land beside the main GGUF: the `mmproj`
+* projector of a vision model, or shards 2..N of a split GGUF. Carried on the
+* REF rather than looked up at install time, so what the operator approved in
+* the preview is exactly what the node downloads.
+*/
+var ManagedModelExtraFileSchema = object({
+	url: string(),
+	filename: string(),
+	sizeBytes: number$1(),
+	sha256: string().optional()
+});
 var ManagedModelRefSchema = discriminatedUnion("kind", [
 	object({
 		kind: literal("catalog"),
@@ -12482,7 +12494,11 @@ var ManagedModelRefSchema = discriminatedUnion("kind", [
 	object({
 		kind: literal("url"),
 		url: string(),
-		sha256: string().optional()
+		sha256: string().optional(),
+		/** Picker/status label; the file basename when absent. */
+		label: string().optional(),
+		sizeBytes: number$1().optional(),
+		extraFiles: array(ManagedModelExtraFileSchema).optional()
 	}),
 	object({
 		kind: literal("path"),
@@ -12543,11 +12559,39 @@ var ManagedRuntimeConfigSchema = object({
 		"q4_1",
 		"q4_0"
 	]).optional(),
+	/**
+	* Escape hatch for llama-server flags this schema does NOT model — `--jinja`
+	* (which most vision chat templates need and some language-only models
+	* dislike), `--cont-batching`, `--rope-scaling`, …
+	*
+	* It is NOT a second place to set the flags above. A token that collides
+	* with a typed field is REJECTED at start, naming the field that owns it
+	* (`assertNoOwnedFlags`), because two knobs writing the same argv is exactly
+	* the "two switches that disagree" failure this repo has already shipped
+	* twice (D62).
+	*/
+	extraArgs: array(string()).default([]),
 	/** Else lazy: first generate boots it. */
 	autoStart: boolean().default(false),
 	/** 0 = never; frees RAM after quiet periods. */
 	idleStopMinutes: number$1().int().default(30)
 });
+/**
+* Where a multi-GB install currently is. A single 0..1 fraction cannot answer
+* "is it stuck?" for an install that is three files (shards + mmproj) followed
+* by a sha256 pass over 22 GB — during which the fraction sat at 1.0 and the
+* node looked hung. Phase + file + bytes is the smallest shape that does.
+*/
+var LlmDownloadProgressSchema = object({
+	phase: _enum(["downloading", "verifying"]),
+	/** The artifact currently moving, e.g. `mmproj-F16.gguf`. */
+	file: string(),
+	fileIndex: number$1().int(),
+	fileCount: number$1().int(),
+	/** Across the WHOLE install, not the current file. */
+	downloadedBytes: number$1(),
+	totalBytes: number$1().optional()
+});
 var LlmRuntimeStatusSchema = object({
 	/** Status is ALWAYS node-qualified. */
 	nodeId: string(),
@@ -12564,6 +12608,8 @@ var LlmRuntimeStatusSchema = object({
 	modelPath: string().optional(),
 	modelId: string().optional(),
 	downloadProgress: number$1().min(0).max(1).optional(),
+	/** Detail behind `downloadProgress`; present for the same lifetime. */
+	download: LlmDownloadProgressSchema.optional(),
 	lastError: string().optional(),
 	crashesInWindow: number$1(),
 	/** Child RSS (sampled best-effort). */
@@ -12574,7 +12620,14 @@ var LlmNodeModelSchema = object({
 	file: string(),
 	sizeBytes: number$1(),
 	catalogId: string().optional(),
-	installedAt: number$1().optional()
+	installedAt: number$1().optional(),
+	/**
+	* Absolute path on the node. Present so a file that is on disk but matches
+	* no catalog entry — a custom Hugging Face install, or a GGUF the operator
+	* copied in by hand — is still SELECTABLE, as a `{kind:'path'}` ref. Without
+	* it the picker could list such a file and do nothing with it.
+	*/
+	path: string().optional()
 });
 var LlmRuntimeDiskUsageSchema = object({
 	nodeId: string(),
@@ -12735,6 +12788,36 @@ var ManagedModelCatalogEntrySchema = object({
 	/** Vision models: companion projector file. */
 	mmprojUrl: string().optional()
 });
+/**
+* The outcome of turning one operator-typed Hugging Face reference into a
+* download plan. A RESULT, never a throw: "this repo has 24 quantizations and
+* I will not pick for you" is a normal answer the UI has to render, not an
+* exception.
+*
+* `candidates` is the whole reason the refusal is usable — every string in it
+* is a tag that resolves when pasted back as `<org>/<repo>:<TAG>`.
+*/
+var HfModelResolutionSchema = discriminatedUnion("ok", [object({
+	ok: literal(true),
+	/** Ready to hand to `installModel` unchanged. */
+	model: ManagedModelRefSchema,
+	label: string(),
+	repo: string(),
+	quantization: string(),
+	purpose: _enum(["text", "vision"]),
+	totalBytes: number$1(),
+	/** mmproj + shards, for the preview: an operator approving 23 GB should
+	*  see that 0.9 GB of it is a projector they did not name. */
+	extraFilenames: array(string())
+}), object({
+	ok: literal(false),
+	code: string(),
+	message: string(),
+	candidates: array(string()).optional(),
+	/** Set when the refusal was only the ceiling: re-calling with
+	*  `maxBytes: requiredBytes` is the operator's explicit override. */
+	requiredBytes: number$1().optional()
+})]);
 var LlmRuntimeNodeSchema = object({
 	nodeId: string(),
 	reachable: boolean(),
@@ -12802,6 +12885,25 @@ var llmCapability = {
 		listModelCatalog: method(object({}), array(ManagedModelCatalogEntrySchema)),
 		listRuntimeNodes: method(object({}), array(LlmRuntimeNodeSchema)),
 		listNodeModels: method(object({ nodeId: string() }), array(LlmNodeModelSchema)),
+		/**
+		* One typed Hugging Face reference → a pinned, verified `ManagedModelRef`.
+		*
+		* Runs on the HUB, not on the target node: resolution needs egress to
+		* huggingface.co, and an agent that cannot reach it still installs fine
+		* through the model-distributor relay. Nothing is downloaded here — this is
+		* a tree read plus a HEAD, so the operator sees the size, the quantization
+		* and the mmproj BEFORE approving a multi-GB pull.
+		*/
+		resolveModelRef: method(object({
+			/** `https://huggingface.co/<org>/<repo>/resolve/main/<f>.gguf`,
+			*  `<org>/<repo>/<f>.gguf`, `<org>/<repo>` or `<org>/<repo>:<QUANT>`. */
+			ref: string(),
+			/** Explicit ceiling override, in bytes. Absent = the built-in ceiling. */
+			maxBytes: number$1().positive().optional()
+		}), HfModelResolutionSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
 		installModel: method(object({
 			nodeId: string(),
 			model: ManagedModelRefSchema
@@ -17941,6 +18043,17 @@ var maxSessionHoldMsField = {
 	default: 12e4,
 	step: 5e3
 };
+/**
+* Quiet period that closes an `audioMode: 'on-motion'` audio window. Floor of
+* 5s so a rearm can never degenerate into per-event stream churn; default 90s
+* comfortably outlives the gap between two PIR wakes on a battery camera.
+*/
+var audioMotionWindowMsField = {
+	min: 5e3,
+	max: 6e5,
+	default: 9e4,
+	step: 5e3
+};
 var motionFpsField = {
 	min: 1,
 	max: 30,
@@ -18117,6 +18230,27 @@ var RunnerCameraConfigSchema = object({
 	* resolved `CameraDetectionConfig`.
 	*/
 	maxSessionHoldMs: number$1().min(maxSessionHoldMsField.min).max(maxSessionHoldMsField.max).optional(),
+	/**
+	* Orchestrator-side quiet period (ms) that closes an `audioMode:
+	* 'on-motion'` audio window, measured from the LAST motion event.
+	*
+	* This exists because the falling edge cannot be relied on. Camera-native
+	* providers emit motion as a RISING EDGE ONLY (Reolink's Baichuan push and
+	* its email-push SMTP path both emit `detected: true` and never the
+	* counterpart); only the frame-diff analyzer emits falls. So on an
+	* onboard-only camera a window that closed only on `detected: false` never
+	* closed at all, and `on-motion` silently behaved as `always-on` — on a
+	* battery camera, the one failure mode the mode exists to prevent.
+	*
+	* Every motion event rearms this timer WITHOUT restarting the stream, so a
+	* burst of re-fires costs nothing. A falling edge, when one does arrive,
+	* still closes earlier via `motionCooldownMs` — whichever comes first wins.
+	*
+	* Not consumed by the runner: carried here so it shares the per-camera
+	* device-settings surface with `motionCooldownMs`, exactly like
+	* `maxSessionHoldMs`.
+	*/
+	audioMotionWindowMs: number$1().min(audioMotionWindowMsField.min).max(audioMotionWindowMsField.max).optional(),
 	motionFps: number$1().min(motionFpsField.min).max(motionFpsField.max).default(motionFpsField.default),
 	detectionFps: number$1().min(detectionFpsField.min).max(detectionFpsField.max).default(detectionFpsField.default),
 	motionStreamId: string(),
@@ -18212,7 +18346,7 @@ var RunnerCameraConfigSchema = object({
 	*/
 	inferenceDevices: array(RunnerInferenceDeviceSchema).readonly().optional()
 });
-motionFpsField.min, motionFpsField.max, motionFpsField.step, motionFpsField.default, detectionFpsField.min, detectionFpsField.max, detectionFpsField.step, detectionFpsField.default, motionCooldownMsField.min, motionCooldownMsField.max, motionCooldownMsField.step, motionCooldownMsField.default, maxSessionHoldMsField.min, maxSessionHoldMsField.max, maxSessionHoldMsField.step, maxSessionHoldMsField.default, occupancyRecheckSecField.min, occupancyRecheckSecField.max, occupancyRecheckSecField.step, occupancyRecheckSecField.default, occupancyRecheckFramesField.min, occupancyRecheckFramesField.max, occupancyRecheckFramesField.step, occupancyRecheckFramesField.default;
+motionFpsField.min, motionFpsField.max, motionFpsField.step, motionFpsField.default, detectionFpsField.min, detectionFpsField.max, detectionFpsField.step, detectionFpsField.default, motionCooldownMsField.min, motionCooldownMsField.max, motionCooldownMsField.step, motionCooldownMsField.default, maxSessionHoldMsField.min, maxSessionHoldMsField.max, maxSessionHoldMsField.step, maxSessionHoldMsField.default, audioMotionWindowMsField.min, audioMotionWindowMsField.max, audioMotionWindowMsField.step, audioMotionWindowMsField.default, occupancyRecheckSecField.min, occupancyRecheckSecField.max, occupancyRecheckSecField.step, occupancyRecheckSecField.default, occupancyRecheckFramesField.min, occupancyRecheckFramesField.max, occupancyRecheckFramesField.step, occupancyRecheckFramesField.default;
 /**
 * Runtime load summary returned by `getLocalLoad`. Used by the orchestrator's
 * load-balancing levels (L2 capacity-based, L3 hardware-aware) to decide
@@ -28059,6 +28193,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"llm.resolveModelRef": {
+		capName: "llm",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"llm.setDefault": {
 		capName: "llm",
 		capScope: "system",
@@ -45767,7 +45907,7 @@ function inferDocMediaType(uriOrName) {
 	for (const [ext, media] of Object.entries(KNOWN_DOC_EXTENSIONS)) if (lower.endsWith(`.${ext}`)) return media;
 	return "application/octet-stream";
 }
-function basename$1(uriOrName) {
+function basename$2(uriOrName) {
 	const parts = uriOrName.split("/");
 	const last = parts[parts.length - 1];
 	return last && last.length > 0 ? last : void 0;
@@ -45797,7 +45937,7 @@ function annotationToSource({ annotation, generateId: generateId3 }) {
 				url: uri,
 				...fileCitation.file_name != null ? { title: fileCitation.file_name } : {}
 			};
-			const filename = (_c = fileCitation.file_name) != null ? _c : basename$1(uri);
+			const filename = (_c = fileCitation.file_name) != null ? _c : basename$2(uri);
 			const mediaType = inferDocMediaType(uri);
 			return {
 				type: "source",
@@ -45886,7 +46026,7 @@ function builtinToolResultToSources({ block, generateId: generateId3 }) {
 					});
 					continue;
 				}
-				const filename = (_h = entry.file_name) != null ? _h : basename$1(uri);
+				const filename = (_h = entry.file_name) != null ? _h : basename$2(uri);
 				const mediaType = inferDocMediaType(uri);
 				sources.push({
 					type: "source",
@@ -70093,6 +70233,469 @@ function resolveProfile(profiles, defaults, input) {
 	};
 }
 //#endregion
+//#region src/runtime/hf-ref.ts
+/**
+* Hugging Face model references — parse, then resolve against the HF API.
+*
+* The operator types ONE string and gets a fully-pinned download plan. That is
+* the whole surface: this is not an HF browser, and it deliberately cannot
+* discover a model for you — it can only turn a reference you already have
+* into something the node can fetch and verify.
+*
+* ## Why resolution can REFUSE
+*
+* A GGUF repo is not one model. `unsloth/Qwen3.6-35B-A3B-GGUF` ships 25
+* quantizations between 10 GB and 50 GB, and none of them is named `Q4_K_M`
+* (they are `UD-Q4_K_M`, Unsloth's dynamic quant). Any code that "defaults to
+* Q4_K_M" would either fail or, worse, pick a neighbouring file and hand the
+* operator a model they did not ask for after a 20 GB download. So: a repo
+* with more than one candidate is an ERROR that NAMES the candidates, never a
+* guess. The only silent pick is the mmproj precision (F16 over F32) — that
+* choice costs a few hundred MB of projector, not a different model, and the
+* file it picked is reported back.
+*
+* ## The error taxonomy is read from headers, not from the status
+*
+* Probed live on 2026-08-15: huggingface.co answers **401** both for a gated
+* repo and for a repo that does not exist (it refuses to leak whether a
+* private repo is there). The two are distinguishable only by
+* `x-error-code: GatedRepo`. Reading the status alone would tell a
+* typo'd repo name that it needs a token, which is the wrong instruction.
+*
+* ## What is verified before a byte is downloaded
+*
+* host is huggingface.co · extension is `.gguf` · every file exists in the
+* tree · the split-GGUF shard set is COMPLETE · the total (main + shards +
+* mmproj) is under the ceiling · a HEAD confirms the file is reachable with
+* the credentials at hand and that its size agrees with the tree. The sha256
+* comes free: HF's LFS `oid` IS the sha256 of the file, and `x-linked-etag`
+* repeats it on the HEAD.
+*/
+/** The only hosts a reference may point at. */
+var HF_HOSTS = ["huggingface.co", "www.huggingface.co"];
+var HF_API = "https://huggingface.co/api/models";
+var HF_RESOLVE = "https://huggingface.co";
+/** Where an operator puts a Hugging Face token, named in the gated error. */
+var HF_TOKEN_ENV = "HF_TOKEN";
+var SEGMENT_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function fail(code, message, candidates) {
+	return {
+		code,
+		message,
+		...candidates !== void 0 ? { candidates } : {}
+	};
+}
+function badParse(code, message, candidates) {
+	return {
+		ok: false,
+		error: fail(code, message, candidates)
+	};
+}
+var EXPECTED = "expected https://huggingface.co/<org>/<repo>/resolve/main/<file>.gguf, or <org>/<repo>/<file>.gguf, or <org>/<repo>[:<QUANT>]";
+/**
+* Reference string → a repo/file reference. Pure: no network, no environment.
+* Every rejection names the form that WAS expected, because the operator is
+* pasting from a browser and a bare "invalid" tells them nothing.
+*/
+function parseHfRef(input) {
+	const raw = input.trim();
+	if (raw === "") return badParse("malformed", `empty model reference — ${EXPECTED}`);
+	return raw.includes("://") ? parseUrlForm(raw) : parseBareForm(raw);
+}
+function parseUrlForm(raw) {
+	let url;
+	try {
+		url = new URL(raw);
+	} catch {
+		return badParse("malformed", `not a URL: ${raw} — ${EXPECTED}`);
+	}
+	if (!HF_HOSTS.includes(url.hostname)) return badParse("not-huggingface", `only huggingface.co models can be installed this way; got host "${url.hostname}"`);
+	const parts = url.pathname.split("/").filter((p) => p !== "");
+	const marker = parts.findIndex((p) => p === "resolve" || p === "blob");
+	if (marker !== 2 || parts.length < marker + 3) return badParse("malformed", `unrecognised Hugging Face URL: ${raw} — ${EXPECTED}`);
+	return finishParse(`${String(parts[0])}/${String(parts[1])}`, String(parts[marker + 1]), parts.slice(marker + 2).join("/"), raw);
+}
+function parseBareForm(raw) {
+	const [beforeTag, ...tagRest] = raw.split(":");
+	const body = String(beforeTag);
+	if (tagRest.length > 1) return badParse("malformed", `too many ":" in ${raw} — ${EXPECTED}`);
+	const quant = tagRest[0]?.trim();
+	const parts = body.split("/");
+	if (parts.length < 2) return badParse("malformed", `not an <org>/<repo> reference: ${raw} — ${EXPECTED}`);
+	if (parts.some((p) => p === "" || p === "." || p === "..")) return badParse("malformed", `illegal path segment in ${raw} — ${EXPECTED}`);
+	const org = String(parts[0]);
+	const name = String(parts[1]);
+	if (!SEGMENT_RE.test(org) || !SEGMENT_RE.test(name)) return badParse("malformed", `illegal repo name in ${raw} — ${EXPECTED}`);
+	const repo = `${org}/${name}`;
+	if (parts.length === 2) {
+		if (quant !== void 0 && quant === "") return badParse("malformed", `empty quantization tag in ${raw} — ${EXPECTED}`);
+		return {
+			ok: true,
+			ref: {
+				kind: "repo",
+				repo,
+				revision: "main",
+				...quant !== void 0 ? { quant } : {}
+			}
+		};
+	}
+	if (quant !== void 0) return badParse("malformed", `a quantization tag cannot follow an explicit file: ${raw}`);
+	return finishParse(repo, "main", parts.slice(2).join("/"), raw);
+}
+function finishParse(repo, revision, filePath, raw) {
+	if (filePath.split("/").some((p) => p === "" || p === "." || p === "..")) return badParse("malformed", `illegal path segment in ${raw} — ${EXPECTED}`);
+	if (!filePath.toLowerCase().endsWith(".gguf")) return badParse("not-gguf", `the managed local runtime loads GGUF only; "${filePath}" is not a .gguf file`);
+	return {
+		ok: true,
+		ref: {
+			kind: "file",
+			repo,
+			revision,
+			filePath
+		}
+	};
+}
+/** `-00001-of-00002` — llama.cpp's split-GGUF naming. */
+var SHARD_RE = /^(.*)-(\d{5})-of-(\d{5})$/;
+/**
+* One `-`-delimited segment that is a quantization, e.g. `Q4_K_M`, `IQ2_XXS`,
+* `BF16`, `fp16`. The `FP` spellings are not cosmetic: `Qwen/*-GGUF` names its
+* unquantized file `…-fp16.gguf`, and a tag list that cannot name it offers
+* the operator a suggestion that does not parse.
+*/
+var QUANT_RE = /^(?:I?Q\d[A-Z0-9_]*|TQ\d_\d|BF16|FP?16|FP?32|FP8|MXFP4(?:_MOE)?)$/i;
+/** Shard coordinates of a split GGUF filename, or `null` when unsharded. */
+function shardInfoOf(filename) {
+	const m = SHARD_RE.exec(stripGguf(filename));
+	if (m === null) return null;
+	return {
+		stem: String(m[1]),
+		index: Number(m[2]),
+		total: Number(m[3])
+	};
+}
+function stripGguf(filename) {
+	return filename.replace(/\.gguf$/i, "");
+}
+/**
+* The quantization tag of a GGUF filename, uppercased, `UD-` prefix kept —
+* `''` when the name carries no recognisable tag. Shard coordinates are
+* stripped first so `X-BF16-00001-of-00002.gguf` reads as `BF16`.
+*/
+function quantizationOf(filename) {
+	const segments = (shardInfoOf(filename)?.stem ?? stripGguf(filename)).split("-");
+	for (let i = segments.length - 1; i >= 0; i--) {
+		const seg = String(segments[i]);
+		if (!QUANT_RE.test(seg)) continue;
+		return (i > 0 ? String(segments[i - 1]) : "").toUpperCase() === "UD" ? `UD-${seg.toUpperCase()}` : seg.toUpperCase();
+	}
+	return "";
+}
+function isMmproj(filePath) {
+	return basename$1(filePath).toLowerCase().startsWith("mmproj");
+}
+function basename$1(filePath) {
+	return filePath.slice(filePath.lastIndexOf("/") + 1);
+}
+function dirname(filePath) {
+	const i = filePath.lastIndexOf("/");
+	return i < 0 ? "" : filePath.slice(0, i);
+}
+function headersFor(token) {
+	return {
+		"User-Agent": "CamStack/1.0",
+		...token !== void 0 && token !== "" ? { Authorization: `Bearer ${token}` } : {}
+	};
+}
+/** HF's 401-for-everything is only decodable through `x-error-code`. */
+function authError(response, repo) {
+	const code = response.headers.get("x-error-code") ?? "";
+	if (code === "GatedRepo" || code === "GatedRepoAccessDenied") return fail("gated", `${repo} is a gated Hugging Face repo: accept its licence with your HF account, then set a token in the ${HF_TOKEN_ENV} environment variable on the hub and on the runtime node (${HF_TOKEN_ENV} or HUGGING_FACE_HUB_TOKEN), and restart them.`);
+	return fail("repo-not-found", `${repo} does not exist on huggingface.co, or is private (Hugging Face answers 401 for both). Check the org/repo spelling.`);
+}
+async function readTree(ref, fetchFn, token) {
+	const url = `${HF_API}/${ref.repo}/tree/${ref.revision}?recursive=1`;
+	let response;
+	try {
+		response = await fetchFn(url, {
+			method: "GET",
+			headers: headersFor(token)
+		});
+	} catch (err) {
+		return {
+			ok: false,
+			error: fail("network", `could not reach huggingface.co: ${message(err)}`)
+		};
+	}
+	if (response.status === 401 || response.status === 403) return {
+		ok: false,
+		error: authError(response, ref.repo)
+	};
+	if (response.status === 404) return {
+		ok: false,
+		error: fail("repo-not-found", `${ref.repo} has no revision "${ref.revision}"`)
+	};
+	if (!response.ok) return {
+		ok: false,
+		error: fail("network", `huggingface.co answered ${String(response.status)} for ${ref.repo}`)
+	};
+	let body;
+	try {
+		body = await response.json();
+	} catch (err) {
+		return {
+			ok: false,
+			error: fail("network", `unreadable tree for ${ref.repo}: ${message(err)}`)
+		};
+	}
+	if (!Array.isArray(body)) return {
+		ok: false,
+		error: fail("network", `unexpected tree payload for ${ref.repo}`)
+	};
+	return {
+		ok: true,
+		files: body.map(toTreeEntry).filter((e) => e !== null)
+	};
+}
+function toTreeEntry(raw) {
+	if (typeof raw !== "object" || raw === null) return null;
+	const record = { ...raw };
+	if (record["type"] !== "file") return null;
+	const filePath = record["path"];
+	if (typeof filePath !== "string" || !filePath.toLowerCase().endsWith(".gguf")) return null;
+	const lfs = typeof record["lfs"] === "object" && record["lfs"] !== null ? { ...record["lfs"] } : {};
+	const lfsSize = lfs["size"];
+	const oid = lfs["oid"];
+	const plainSize = record["size"];
+	return {
+		path: filePath,
+		sizeBytes: typeof lfsSize === "number" ? lfsSize : typeof plainSize === "number" ? plainSize : 0,
+		...typeof oid === "string" && oid.length === 64 ? { sha256: oid } : {}
+	};
+}
+function message(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/** Files that can be THE model: not a projector, not a follow-on shard. */
+function modelCandidates(files) {
+	return files.filter((f) => {
+		if (isMmproj(f.path)) return false;
+		const shard = shardInfoOf(basename$1(f.path));
+		return shard === null || shard.index === 1;
+	});
+}
+function labelFor(file) {
+	const quant = quantizationOf(basename$1(file.path));
+	return quant === "" ? basename$1(file.path) : quant;
+}
+function selectMain(ref, files) {
+	const candidates = modelCandidates(files);
+	if (ref.kind === "file") {
+		const wanted = ref.filePath.toLowerCase();
+		const hit = files.find((f) => f.path.toLowerCase() === wanted);
+		if (hit === void 0) return {
+			ok: false,
+			error: fail("file-not-found", `${ref.repo} has no file "${ref.filePath}" at revision ${ref.revision}`, candidates.map(labelFor))
+		};
+		return {
+			ok: true,
+			file: hit
+		};
+	}
+	if (candidates.length === 0) return {
+		ok: false,
+		error: fail("not-gguf", `${ref.repo} publishes no GGUF weights (only projectors or no GGUF at all)`)
+	};
+	if (ref.quant !== void 0) {
+		const wanted = ref.quant.toUpperCase();
+		const wantedFile = stripGguf(ref.quant).toUpperCase();
+		const matches = candidates.filter((f) => quantizationOf(basename$1(f.path)) === wanted || stripGguf(basename$1(f.path)).toUpperCase() === wantedFile);
+		if (matches.length === 0) return {
+			ok: false,
+			error: fail("file-not-found", `${ref.repo} has no "${ref.quant}" quantization. Available: ${candidates.map(labelFor).join(", ")}`, dedupe(candidates.map(labelFor)))
+		};
+		const only = matches[0];
+		if (matches.length > 1 || only === void 0) return {
+			ok: false,
+			error: fail("ambiguous", `"${ref.quant}" matches ${String(matches.length)} files in ${ref.repo}: ${matches.map((f) => basename$1(f.path)).join(", ")}. Name the file explicitly.`, matches.map((f) => basename$1(f.path)))
+		};
+		return {
+			ok: true,
+			file: only
+		};
+	}
+	const solo = candidates[0];
+	if (candidates.length > 1 || solo === void 0) {
+		const tags = dedupe(candidates.map(labelFor));
+		return {
+			ok: false,
+			error: fail("ambiguous", `${ref.repo} publishes ${String(candidates.length)} quantizations and picking one for you would be a guess. Re-enter it as ${ref.repo}:<TAG>, or paste the full file URL. Available: ${tags.join(", ")}`, tags)
+		};
+	}
+	return {
+		ok: true,
+		file: solo
+	};
+}
+function dedupe(values) {
+	return [...new Set(values)];
+}
+/** Shards 2..N of `main`, or an error naming the first one that is missing. */
+function collectShards(main, files) {
+	const shard = shardInfoOf(basename$1(main.path));
+	if (shard === null || shard.total <= 1) return {
+		ok: true,
+		shards: []
+	};
+	const dir = dirname(main.path);
+	const out = [];
+	for (let i = 2; i <= shard.total; i++) {
+		const wanted = `${shard.stem}-${String(i).padStart(5, "0")}-of-${String(shard.total).padStart(5, "0")}.gguf`;
+		const full = dir === "" ? wanted : `${dir}/${wanted}`;
+		const hit = files.find((f) => f.path === full);
+		if (hit === void 0) return {
+			ok: false,
+			error: fail("incomplete-shards", `split GGUF is incomplete: ${wanted} is missing from the repo (llama.cpp needs all ${String(shard.total)} shards)`)
+		};
+		out.push(hit);
+	}
+	return {
+		ok: true,
+		shards: out
+	};
+}
+/** F16 over BF16 over F32 over whatever came first — reported, never hidden. */
+var MMPROJ_PREFERENCE = [
+	"F16",
+	"BF16",
+	"F32"
+];
+function selectMmproj(files) {
+	const projectors = files.filter((f) => isMmproj(f.path));
+	if (projectors.length === 0) return null;
+	for (const want of MMPROJ_PREFERENCE) {
+		const hit = projectors.find((f) => quantizationOf(basename$1(f.path)) === want);
+		if (hit !== void 0) return hit;
+	}
+	return projectors[0] ?? null;
+}
+function resolveUrl(repo, revision, filePath) {
+	return `${HF_RESOLVE}/${repo}/resolve/${revision}/${filePath}`;
+}
+async function verifyHead(url, repo, declaredBytes, fetchFn, token) {
+	let response;
+	try {
+		response = await fetchFn(url, {
+			method: "HEAD",
+			redirect: "manual",
+			headers: headersFor(token)
+		});
+	} catch (err) {
+		return {
+			ok: false,
+			error: fail("network", `HEAD ${url} failed: ${message(err)}`)
+		};
+	}
+	if (response.status === 401 || response.status === 403) return {
+		ok: false,
+		error: authError(response, repo)
+	};
+	if (response.status === 404) return {
+		ok: false,
+		error: fail("file-not-found", `${url} is gone (404)`)
+	};
+	if (response.status >= 400) return {
+		ok: false,
+		error: fail("network", `HEAD ${url} answered ${String(response.status)}`)
+	};
+	const linked = response.headers.get("x-linked-size") ?? response.headers.get("content-length");
+	const headBytes = linked === null ? void 0 : Number(linked);
+	if (headBytes !== void 0 && Number.isFinite(headBytes) && headBytes !== declaredBytes) return {
+		ok: false,
+		error: fail("size-mismatch", `huggingface.co reports ${String(headBytes)} bytes for ${url} but its tree declared ${String(declaredBytes)} — refusing to download a file that changed under the reference`)
+	};
+	const etag = response.headers.get("x-linked-etag")?.replace(/"/g, "");
+	return {
+		ok: true,
+		...etag !== void 0 && etag.length === 64 ? { sha256: etag } : {}
+	};
+}
+function toResolved(repo, revision, entry) {
+	return {
+		url: resolveUrl(repo, revision, entry.path),
+		filename: basename$1(entry.path),
+		sizeBytes: entry.sizeBytes,
+		...entry.sha256 !== void 0 ? { sha256: entry.sha256 } : {}
+	};
+}
+function gb$1(bytes) {
+	return `${(bytes / 1e9).toFixed(1)} GB`;
+}
+/** Reference → a pinned, size-checked, HEAD-verified download plan. */
+async function resolveHfRef(ref, deps) {
+	const fetchFn = deps.fetchFn ?? fetch;
+	const maxBytes = deps.maxBytes ?? 21474836480;
+	const tree = await readTree(ref, fetchFn, deps.token);
+	if (!tree.ok) return {
+		ok: false,
+		error: tree.error
+	};
+	const picked = selectMain(ref, tree.files);
+	if (!picked.ok) return {
+		ok: false,
+		error: picked.error
+	};
+	const main = picked.file;
+	const shards = collectShards(main, tree.files);
+	if (!shards.ok) return {
+		ok: false,
+		error: shards.error
+	};
+	const projector = isMmproj(main.path) ? null : selectMmproj(tree.files);
+	const extraEntries = [...shards.shards, ...projector === null ? [] : [projector]];
+	const totalBytes = [main, ...extraEntries].reduce((sum, f) => sum + f.sizeBytes, 0);
+	if (totalBytes > maxBytes) return {
+		ok: false,
+		error: {
+			...fail("too-large", `this install is ${String(totalBytes)} bytes (${gb$1(totalBytes)}), over the ${String(maxBytes)} byte ceiling (${gb$1(maxBytes)}). Raise the ceiling explicitly if the node really has the disk and RAM for it.`),
+			requiredBytes: totalBytes
+		}
+	};
+	const head = await verifyHead(resolveUrl(ref.repo, ref.revision, main.path), ref.repo, main.sizeBytes, fetchFn, deps.token);
+	if (!head.ok) return {
+		ok: false,
+		error: head.error
+	};
+	const mainResolved = toResolved(ref.repo, ref.revision, {
+		...main,
+		...main.sha256 === void 0 && head.sha256 !== void 0 ? { sha256: head.sha256 } : {}
+	});
+	const quantization = quantizationOf(mainResolved.filename);
+	const repoName = ref.repo.slice(ref.repo.indexOf("/") + 1);
+	return {
+		ok: true,
+		resolution: {
+			repo: ref.repo,
+			revision: ref.revision,
+			label: quantization === "" ? repoName : `${repoName} · ${quantization}`,
+			quantization,
+			purpose: projector === null ? "text" : "vision",
+			main: mainResolved,
+			extras: extraEntries.map((e) => toResolved(ref.repo, ref.revision, e)),
+			totalBytes
+		}
+	};
+}
+/** `parseHfRef` then {@link resolveHfRef} — the form the cap method calls. */
+async function resolveHfReference(input, deps) {
+	const parsed = parseHfRef(input);
+	if (!parsed.ok) return {
+		ok: false,
+		error: parsed.error
+	};
+	return resolveHfRef(parsed.ref, deps);
+}
+//#endregion
 //#region src/secrets.ts
 /** Same marker as addon-notifiers/src/secrets.ts — UI contract. */
 var REDACTED_MARKER = "__redacted__";
@@ -70316,6 +70919,64 @@ function createLlmProvider(deps) {
 			}));
 		},
 		listNodeModels: async ({ nodeId }) => requireRuntime(deps.runtime).listLocalModels(nodeId),
+		/**
+		* Hugging Face reference → a pinned `ManagedModelRef`, on the HUB.
+		*
+		* Never throws: a refusal ("this repo has 24 quantizations", "this is
+		* gated", "23 GB is over the ceiling") is an ANSWER the operator has to
+		* read and act on, and turning it into a tRPC error would reduce all of
+		* them to a red toast with no candidate list and no override.
+		*/
+		resolveModelRef: async ({ ref, maxBytes }) => {
+			const token = deps.hfToken?.();
+			const outcome = await resolveHfReference(ref, {
+				...maxBytes !== void 0 ? { maxBytes } : {},
+				...token !== void 0 && token !== "" ? { token } : {}
+			});
+			if (!outcome.ok) {
+				deps.logger?.info("llm model reference refused", { meta: {
+					ref,
+					code: outcome.error.code
+				} });
+				return {
+					ok: false,
+					code: outcome.error.code,
+					message: outcome.error.message,
+					...outcome.error.candidates !== void 0 ? { candidates: [...outcome.error.candidates] } : {},
+					...outcome.error.requiredBytes !== void 0 ? { requiredBytes: outcome.error.requiredBytes } : {}
+				};
+			}
+			const { resolution } = outcome;
+			deps.logger?.info("llm model reference resolved", { meta: {
+				ref,
+				repo: resolution.repo,
+				quantization: resolution.quantization,
+				purpose: resolution.purpose,
+				totalBytes: resolution.totalBytes
+			} });
+			return {
+				ok: true,
+				model: {
+					kind: "url",
+					url: resolution.main.url,
+					...resolution.main.sha256 !== void 0 ? { sha256: resolution.main.sha256 } : {},
+					label: resolution.label,
+					sizeBytes: resolution.main.sizeBytes,
+					extraFiles: resolution.extras.map((e) => ({
+						url: e.url,
+						filename: e.filename,
+						sizeBytes: e.sizeBytes,
+						...e.sha256 !== void 0 ? { sha256: e.sha256 } : {}
+					}))
+				},
+				label: resolution.label,
+				repo: resolution.repo,
+				quantization: resolution.quantization,
+				purpose: resolution.purpose,
+				totalBytes: resolution.totalBytes,
+				extraFilenames: resolution.extras.map((e) => e.filename)
+			};
+		},
 		installModel: async ({ nodeId, model }) => {
 			const runtime = requireRuntime(deps.runtime);
 			try {
@@ -70349,13 +71010,29 @@ function createLlmProvider(deps) {
 //#endregion
 //#region src/runtime/llm-model-catalog.ts
 /**
-* Curated managed-model catalog (operator decision #4): ~2 small text GGUFs
-* (2-4B, Q4) + 1 small vision GGUF with its companion mmproj, sized to the
-* weakest runtime node (the N100 agent). Each entry carries BOTH the LLM-facing
-* picker view (`meta`) and the REUSED download-plane `ModelCatalogEntry`
-* (`entry`) so GGUFs ride `ensureModel` + `model-distributor` untouched — no
-* bespoke fetcher (spec §4.2). Digests/sizes pinned via
-* scratchpad/pin-llm-models.mjs (HF LFS `lfs.oid`).
+* Curated managed-model catalog (operator decision #4). Each entry carries BOTH
+* the LLM-facing picker view (`meta`) and the REUSED download-plane
+* `ModelCatalogEntry` (`entry`) so GGUFs ride `ensureModel` +
+* `model-distributor` untouched — no bespoke fetcher (spec §4.2).
+* Digests/sizes pinned via scratchpad/pin-llm-models.mjs (HF LFS `lfs.oid`,
+* which IS the file's sha256).
+*
+* ## Two tiers, and `minRamBytes` is what separates them
+*
+* The first three entries are sized to the WEAKEST runtime node (the N100
+* agent): 1-4 GB, Q4. `QWEN36_35B` is not — it is 23 GB and only a big node
+* can hold it. The catalog does not refuse to show it; `minRamBytes` is the
+* guidance, and the picker prints the size. Keeping the tiers in one list is
+* deliberate: an operator with a 64 GB box should not have to discover the
+* free-text field to run something real.
+*
+* ## This list is no longer the boundary of what can run
+*
+* Anything on Hugging Face is installable through `llm.resolveModelRef` +
+* `installModel` without a code change ({@link ./hf-ref.ts}). An entry here
+* buys exactly two things over typing the reference: a pinned digest nobody
+* has to re-verify, and a `contextSizeDefault`/`minRamBytes` somebody checked.
+* Add one only when both are true.
 */
 var GIB = 1024 * 1024 * 1024;
 function mb(bytes) {
@@ -70407,30 +71084,117 @@ var LLAMA = textEntry({
 var SMOLVLM_MODEL_BYTES = 1112602656;
 var SMOLVLM_MMPROJ_BYTES = 872303680;
 var SMOLVLM_MMPROJ_URL = "https://huggingface.co/ggml-org/SmolVLM2-2.2B-Instruct-GGUF/resolve/main/mmproj-SmolVLM2-2.2B-Instruct-f16.gguf";
+var SMOLVLM = {
+	meta: {
+		id: "llm-smolvlm2-2.2b-instruct-q4",
+		label: "SmolVLM2 2.2B Instruct (vision)",
+		family: "smolvlm2",
+		purpose: "vision",
+		url: "https://huggingface.co/ggml-org/SmolVLM2-2.2B-Instruct-GGUF/resolve/main/SmolVLM2-2.2B-Instruct-Q4_K_M.gguf",
+		sha256: "0cf76814555b8665149075b74ab6b5c1d428ea1d3d01c1918c12012e8d7c9f58",
+		sizeBytes: SMOLVLM_MODEL_BYTES,
+		quantization: "Q4_K_M",
+		minRamBytes: 4 * GIB,
+		contextSizeDefault: 4096,
+		mmprojUrl: SMOLVLM_MMPROJ_URL
+	},
+	entry: {
+		id: "llm-smolvlm2-2.2b-instruct-q4",
+		name: "SmolVLM2 2.2B Instruct (vision)",
+		description: "smolvlm2 · Q4_K_M · +mmproj",
+		formats: { gguf: {
+			url: "https://huggingface.co/ggml-org/SmolVLM2-2.2B-Instruct-GGUF/resolve/main/SmolVLM2-2.2B-Instruct-Q4_K_M.gguf",
+			sizeMB: mb(SMOLVLM_MODEL_BYTES)
+		} },
+		inputSize: {
+			width: 0,
+			height: 0
+		},
+		labels: [],
+		extraFiles: [{
+			url: SMOLVLM_MMPROJ_URL,
+			filename: "mmproj-SmolVLM2-2.2B-Instruct-f16.gguf",
+			sizeMB: mb(SMOLVLM_MMPROJ_BYTES)
+		}]
+	}
+};
+var QWEN3VL2B_MODEL_BYTES = 1107410624;
+var QWEN3VL2B_MMPROJ_BYTES = 819395232;
+var QWEN3VL2B_BASE = "https://huggingface.co/unsloth/Qwen3-VL-2B-Instruct-GGUF/resolve/main";
+var QWEN3VL2B_MMPROJ_URL = `${QWEN3VL2B_BASE}/mmproj-F16.gguf`;
+var QWEN3VL2B_URL = `${QWEN3VL2B_BASE}/Qwen3-VL-2B-Instruct-Q4_K_M.gguf`;
+/**
+* The light vision tier the operator asked for by weight class (~2 GB all in):
+* same Qwen3-VL family as the LM Studio 8B profile already in daily use, so
+* prompts and behaviour carry over — at a tenth of the 35B's disk and a RAM
+* floor a hub-adjacent node can always afford. This is the sensible default
+* for the NC confirm gates and summary judges.
+*/
+var QWEN3VL_2B = {
+	meta: {
+		id: "llm-qwen3-vl-2b-instruct-q4",
+		label: "Qwen3-VL 2B Instruct (vision, light)",
+		family: "qwen3-vl",
+		purpose: "vision",
+		url: QWEN3VL2B_URL,
+		sha256: "858fcf2a39dc73b26dd86592cb0a5f949b59d1edb365d1dea98e46b02e955e56",
+		sizeBytes: QWEN3VL2B_MODEL_BYTES,
+		quantization: "Q4_K_M",
+		minRamBytes: 3 * GIB,
+		contextSizeDefault: 8192,
+		mmprojUrl: QWEN3VL2B_MMPROJ_URL
+	},
+	entry: {
+		id: "llm-qwen3-vl-2b-instruct-q4",
+		name: "Qwen3-VL 2B Instruct (vision, light)",
+		description: "qwen3-vl · Q4_K_M · +mmproj",
+		formats: { gguf: {
+			url: QWEN3VL2B_URL,
+			sizeMB: mb(QWEN3VL2B_MODEL_BYTES)
+		} },
+		inputSize: {
+			width: 0,
+			height: 0
+		},
+		labels: [],
+		extraFiles: [{
+			url: QWEN3VL2B_MMPROJ_URL,
+			filename: "mmproj-F16.gguf",
+			sizeMB: mb(QWEN3VL2B_MMPROJ_BYTES)
+		}]
+	}
+};
+var QWEN36_MODEL_BYTES = 22134528992;
+var QWEN36_MMPROJ_BYTES = 899283680;
+var QWEN36_BASE = "https://huggingface.co/unsloth/Qwen3.6-35B-A3B-GGUF/resolve/main";
+var QWEN36_MMPROJ_URL = `${QWEN36_BASE}/mmproj-F16.gguf`;
+var QWEN36_URL = `${QWEN36_BASE}/Qwen3.6-35B-A3B-UD-Q4_K_M.gguf`;
 var LLM_MODEL_CATALOG = [
 	QWEN,
 	LLAMA,
+	SMOLVLM,
+	QWEN3VL_2B,
 	{
 		meta: {
-			id: "llm-smolvlm2-2.2b-instruct-q4",
-			label: "SmolVLM2 2.2B Instruct (vision)",
-			family: "smolvlm2",
+			id: "llm-qwen3.6-35b-a3b-ud-q4",
+			label: "Qwen3.6 35B-A3B (vision)",
+			family: "qwen3.6",
 			purpose: "vision",
-			url: "https://huggingface.co/ggml-org/SmolVLM2-2.2B-Instruct-GGUF/resolve/main/SmolVLM2-2.2B-Instruct-Q4_K_M.gguf",
-			sha256: "0cf76814555b8665149075b74ab6b5c1d428ea1d3d01c1918c12012e8d7c9f58",
-			sizeBytes: SMOLVLM_MODEL_BYTES,
-			quantization: "Q4_K_M",
-			minRamBytes: 4 * GIB,
-			contextSizeDefault: 4096,
-			mmprojUrl: SMOLVLM_MMPROJ_URL
+			url: QWEN36_URL,
+			sha256: "ac0e2c1189e055faa36eff361580e79c5bd6f8e76bffb4ce547f167d53e31a61",
+			sizeBytes: QWEN36_MODEL_BYTES,
+			quantization: "UD-Q4_K_M",
+			minRamBytes: 26 * GIB,
+			contextSizeDefault: 32768,
+			mmprojUrl: QWEN36_MMPROJ_URL
 		},
 		entry: {
-			id: "llm-smolvlm2-2.2b-instruct-q4",
-			name: "SmolVLM2 2.2B Instruct (vision)",
-			description: "smolvlm2 · Q4_K_M · +mmproj",
+			id: "llm-qwen3.6-35b-a3b-ud-q4",
+			name: "Qwen3.6 35B-A3B (vision)",
+			description: "qwen3.6 · UD-Q4_K_M · +mmproj",
 			formats: { gguf: {
-				url: "https://huggingface.co/ggml-org/SmolVLM2-2.2B-Instruct-GGUF/resolve/main/SmolVLM2-2.2B-Instruct-Q4_K_M.gguf",
-				sizeMB: mb(SMOLVLM_MODEL_BYTES)
+				url: QWEN36_URL,
+				sizeMB: mb(QWEN36_MODEL_BYTES)
 			} },
 			inputSize: {
 				width: 0,
@@ -70438,9 +71202,9 @@ var LLM_MODEL_CATALOG = [
 			},
 			labels: [],
 			extraFiles: [{
-				url: SMOLVLM_MMPROJ_URL,
-				filename: "mmproj-SmolVLM2-2.2B-Instruct-f16.gguf",
-				sizeMB: mb(SMOLVLM_MMPROJ_BYTES)
+				url: QWEN36_MMPROJ_URL,
+				filename: "mmproj-F16.gguf",
+				sizeMB: mb(QWEN36_MMPROJ_BYTES)
 			}]
 		}
 	}
@@ -70457,19 +71221,25 @@ function entryForRef(ref) {
 	}
 	if (ref.kind === "url") {
 		const id = `llm-custom-${(0, node_crypto.createHash)("sha1").update(ref.url).digest("hex").slice(0, 12)}`;
+		const extraFiles = (ref.extraFiles ?? []).map((f) => ({
+			url: f.url,
+			filename: f.filename,
+			sizeMB: mb(f.sizeBytes)
+		}));
 		return { entry: {
 			id,
-			name: id,
+			name: ref.label ?? id,
 			description: "custom GGUF",
 			formats: { gguf: {
 				url: ref.url,
-				sizeMB: 0
+				sizeMB: ref.sizeBytes === void 0 ? 0 : mb(ref.sizeBytes)
 			} },
 			inputSize: {
 				width: 0,
 				height: 0
 			},
-			labels: []
+			labels: [],
+			...extraFiles.length > 0 ? { extraFiles } : {}
 		} };
 	}
 	const id = `llm-path-${(0, node_crypto.createHash)("sha1").update(ref.path).digest("hex").slice(0, 12)}`;
@@ -70507,10 +71277,6 @@ function isNonEmptyFile(filePath) {
 function siblingFilesFor(formatEntry) {
 	return formatEntry.isDirectory ? [] : formatEntry.files ?? [];
 }
-/** Resolve a sibling's remote URL relative to the main file's directory. */
-function siblingUrl(mainUrl, sibling) {
-	return mainUrl.replace(/[^/]+$/, sibling);
-}
 /** Build fetch headers, including HF auth token for huggingface.co URLs */
 function buildHeaders(url) {
 	const headers = { "User-Agent": "CamStack/1.0" };
@@ -70563,77 +71329,6 @@ async function downloadFile(url, destPath, onProgress) {
 		throw err;
 	}
 }
-/**
-* Download every file in a HuggingFace directory bundle (e.g.,
-* `.mlpackage` / OpenVINO IR pair) atomically. `knownFiles` lists the
-* relative paths inside the directory; the function fetches each from
-* `${url}/${file}` and renames the staging directory only on full
-* success. Mirrors `ModelDownloadService.downloadDirectory` but
-* exposed as a standalone for catalog-less callers.
-*/
-async function downloadDirectory(url, destDir, knownFiles, onProgress) {
-	const match = url.match(/huggingface\.co\/([^/]+\/[^/]+)\/resolve\/main\/(.+)/);
-	if (!match) throw new Error(`Cannot parse HuggingFace URL: ${url}`);
-	const [, repo, dirPath] = match;
-	const files = (knownFiles ?? []).map((f) => ({
-		relativePath: f,
-		fileUrl: `https://huggingface.co/${repo}/resolve/main/${dirPath}/${f}`
-	}));
-	if (files.length === 0) throw new Error(`Directory bundle requires explicit \`files\` list (got none for ${url})`);
-	const tmpDir = destDir + ".downloading";
-	node_fs.rmSync(tmpDir, {
-		recursive: true,
-		force: true
-	});
-	node_fs.mkdirSync(tmpDir, { recursive: true });
-	let totalDownloaded = 0;
-	try {
-		for (const file of files) {
-			const destPath = node_path$1.join(tmpDir, file.relativePath);
-			node_fs.mkdirSync(node_path$1.dirname(destPath), { recursive: true });
-			await downloadFile(file.fileUrl, destPath, (downloaded, _total) => {
-				onProgress?.(totalDownloaded + downloaded, void 0);
-			});
-			totalDownloaded += node_fs.statSync(destPath).size;
-		}
-		node_fs.rmSync(destDir, {
-			recursive: true,
-			force: true
-		});
-		node_fs.renameSync(tmpDir, destDir);
-	} catch (err) {
-		node_fs.rmSync(tmpDir, {
-			recursive: true,
-			force: true
-		});
-		throw err;
-	}
-}
-/**
-* Resolve a `ModelCatalogEntry` against `modelsDir`: download model file
-* (or directory bundle) + extra files (labels JSON, charset dict, …),
-* skip if already on disk. Returns the local model path.
-*/
-async function ensureModel(modelsDir, entry, format, onProgress) {
-	const formatEntry = entry.formats[format];
-	if (!formatEntry) throw new Error(`Model "${entry.id}" has no ${format} format. Available: ${Object.keys(entry.formats).join(", ")}`);
-	if (entry.extraFiles) for (const extra of entry.extraFiles) await downloadFile(extra.url, node_path$1.join(modelsDir, extra.filename));
-	const filename = formatEntry.url.split("/").pop() ?? `${entry.id}.${format}`;
-	const modelPath = node_path$1.join(modelsDir, filename);
-	const siblings = siblingFilesFor(formatEntry);
-	if (node_fs.existsSync(modelPath)) if (formatEntry.isDirectory && !node_fs.existsSync(node_path$1.join(modelPath, "Manifest.json"))) node_fs.rmSync(modelPath, {
-		recursive: true,
-		force: true
-	});
-	else if (siblings.some((f) => !isNonEmptyFile(node_path$1.join(modelsDir, f)))) {} else return modelPath;
-	node_fs.mkdirSync(modelsDir, { recursive: true });
-	if (formatEntry.isDirectory) await downloadDirectory(formatEntry.url, modelPath, formatEntry.files, onProgress);
-	else {
-		await downloadFile(formatEntry.url, modelPath, (downloaded, total) => onProgress?.(downloaded, total === 0 ? void 0 : total));
-		for (const sibling of siblings) await downloadFile(siblingUrl(formatEntry.url, sibling), node_path$1.join(modelsDir, sibling));
-	}
-	return modelPath;
-}
 /** Compute the on-disk path for a given model + format, even when not yet downloaded. */
 function getModelFilePath(modelsDir, entry, format) {
 	const formatEntry = entry.formats[format];
@@ -70677,13 +71372,79 @@ function deleteModelFromDisk(modelsDir, entry, format) {
 * Default `RuntimeModelOps` — the ONLY place the reused object-detection model
 * mechanism is imported (the documented `@camstack/system/addon-utils`
 * build-time-dep waiver that addon-post-analysis/addon-pipeline already use).
-* GGUFs ride `ensureModel`/`isModelDownloaded`/`deleteModelFromDisk` untouched
-* (spec §4.2) — no bespoke fetcher.
+* GGUFs ride the SHARED `downloadFile` (atomic `.downloading` + rename, HF
+* token headers, redirect following) — no bespoke fetcher (spec §4.2).
+*
+* ## Why this drives the file loop instead of calling `ensureModel`
+*
+* `ensureModel` downloads `extraFiles` FIRST and passes them NO progress
+* callback. That is invisible for a 40 kB labels JSON and unacceptable here: a
+* GGUF install is a 22 GB main file, up to N shards, and a 0.9 GB mmproj, and
+* under `ensureModel` every byte outside the main file moves in silence. A
+* multi-GB download that reports nothing reads as a hung node — the repo rule
+* is that a branch doing real work says so.
+*
+* So the loop is here, over the SAME `downloadFile`. What is gained: bytes
+* aggregated across the whole install, the name of the file currently moving,
+* and files already on disk excluded from the total rather than counted as
+* instantly-complete.
 */
 var GGUF = "gguf";
+var BYTES_PER_MB = 1024 * 1024;
+/**
+* Main file first, then shards/mmproj. Deliberate: a gated or mistyped URL
+* fails on the file that matters before 0.9 GB of projector is spent on it.
+*/
+function planFiles(modelsDir, entry) {
+	const out = [];
+	const formatEntry = entry.formats[GGUF];
+	if (formatEntry !== void 0) {
+		const filename = formatEntry.url.split("/").pop() ?? `${entry.id}.${GGUF}`;
+		out.push({
+			url: formatEntry.url,
+			destPath: node_path.join(modelsDir, filename),
+			filename,
+			expectedBytes: formatEntry.sizeMB * BYTES_PER_MB
+		});
+	}
+	for (const extra of entry.extraFiles ?? []) out.push({
+		url: extra.url,
+		destPath: node_path.join(modelsDir, extra.filename),
+		filename: extra.filename,
+		expectedBytes: extra.sizeMB * BYTES_PER_MB
+	});
+	return out;
+}
 function createDefaultModelOps(modelsDir) {
 	return {
-		ensure: (entry, onProgress) => ensureModel(modelsDir, entry, GGUF, (downloaded, total) => onProgress(total !== void 0 && total > 0 ? downloaded / total : 0)),
+		ensure: async (entry, onProgress) => {
+			if (entry.formats[GGUF] === void 0) throw new Error(`model ${entry.id} declares no gguf format`);
+			const missing = planFiles(modelsDir, entry).filter((f) => !(0, node_fs.existsSync)(f.destPath));
+			const totalBytes = missing.reduce((sum, f) => sum + f.expectedBytes, 0);
+			let carried = 0;
+			for (const [index, file] of missing.entries()) {
+				onProgress({
+					file: file.filename,
+					fileIndex: index + 1,
+					fileCount: missing.length,
+					downloadedBytes: carried,
+					...totalBytes > 0 ? { totalBytes } : {}
+				});
+				await downloadFile(file.url, file.destPath, (downloaded) => {
+					onProgress({
+						file: file.filename,
+						fileIndex: index + 1,
+						fileCount: missing.length,
+						downloadedBytes: carried + downloaded,
+						...totalBytes > 0 ? { totalBytes } : {}
+					});
+				});
+				carried += (0, node_fs.existsSync)(file.destPath) ? (0, node_fs.statSync)(file.destPath).size : file.expectedBytes;
+			}
+			const main = getModelFilePath(modelsDir, entry, GGUF);
+			if (main === null) throw new Error(`no gguf path for model ${entry.id}`);
+			return main;
+		},
 		isDownloaded: (entry) => isModelDownloaded(modelsDir, entry, GGUF),
 		pathFor: (entry) => {
 			const p = getModelFilePath(modelsDir, entry, GGUF);
@@ -70697,318 +71458,6 @@ function createDefaultModelOps(modelsDir) {
 	};
 }
 //#endregion
-//#region src/runtime/sha256.ts
-/**
-* File sha256 — a local copy of the private `computeSha256` at
-* model-downloader.ts (not exported from @camstack/system), streamed so it
-* never buffers a multi-GB artifact.
-*/
-function fileSha256(filePath) {
-	return new Promise((resolve, reject) => {
-		const hash = (0, node_crypto.createHash)("sha256");
-		const stream = (0, node_fs.createReadStream)(filePath);
-		stream.on("error", reject);
-		stream.on("data", (chunk) => hash.update(chunk));
-		stream.on("end", () => resolve(hash.digest("hex")));
-	});
-}
-//#endregion
-//#region src/runtime/runtime-provider.ts
-/**
-* `llm-runtime` provider — the node-side managed executor. Reuses the
-* object-detection model plane (ensureModel/isModelDownloaded/delete via the
-* injected `RuntimeModelOps`) for GGUF artifacts, the `LlamaSupervisor` for the
-* llama-server child, and the SHARED {@link LlmClient} for the local inference
-* wire (only lifecycle + locality differ — spec §2). GGUFs are
-* multi-GB, so a missing model is an EXPLICIT-install error, never an auto-pull.
-* Usage rows are written hub-side only (single accounting point).
-*/
-function basename(url) {
-	const clean = url.split("?")[0] ?? url;
-	return clean.slice(clean.lastIndexOf("/") + 1);
-}
-function catalogIdForFile(file) {
-	return LLM_MODEL_CATALOG.find((m) => basename(m.meta.url) === file)?.meta.id;
-}
-function mmprojFilename(entry) {
-	return entry.extraFiles?.[0]?.filename;
-}
-function createLlmRuntimeProvider(deps) {
-	let downloadProgress;
-	async function resolvePaths(runtime) {
-		const resolution = entryForRef(runtime.model);
-		if (resolution === null) throw new Error("unknown model reference");
-		const { entry, localPathOverride } = resolution;
-		const modelPath = localPathOverride ?? deps.modelOps.pathFor(entry);
-		const mmproj = mmprojFilename(entry);
-		return {
-			modelId: entry.id,
-			modelPath,
-			...mmproj !== void 0 ? { mmprojPath: deps.modelOps.extraFilePath(entry, mmproj) } : {}
-		};
-	}
-	function installedGuard(runtime) {
-		const resolution = entryForRef(runtime.model);
-		if (resolution === null) return {
-			ok: false,
-			message: "unknown model reference"
-		};
-		if (resolution.localPathOverride !== void 0) return { ok: true };
-		if (!deps.modelOps.isDownloaded(resolution.entry)) return {
-			ok: false,
-			message: `model ${resolution.entry.id} not installed on node ${deps.nodeId}`
-		};
-		return { ok: true };
-	}
-	async function ensureStartedInternal(runtime) {
-		const binaryPath = await deps.ensureBinary();
-		const paths = await resolvePaths(runtime);
-		const startCfg = {
-			nodeId: deps.nodeId,
-			modelId: paths.modelId,
-			modelPath: paths.modelPath,
-			...paths.mmprojPath !== void 0 ? { mmprojPath: paths.mmprojPath } : {},
-			contextSize: runtime.contextSize,
-			gpuLayers: runtime.gpuLayers,
-			...runtime.threads !== void 0 ? { threads: runtime.threads } : {},
-			parallel: runtime.parallel,
-			...runtime.batchSize !== void 0 ? { batchSize: runtime.batchSize } : {},
-			...runtime.ubatchSize !== void 0 ? { ubatchSize: runtime.ubatchSize } : {},
-			flashAttention: runtime.flashAttention,
-			mlock: runtime.mlock,
-			noMmap: runtime.noMmap,
-			...runtime.cacheTypeK !== void 0 ? { cacheTypeK: runtime.cacheTypeK } : {},
-			...runtime.cacheTypeV !== void 0 ? { cacheTypeV: runtime.cacheTypeV } : {},
-			idleStopMinutes: runtime.idleStopMinutes,
-			binaryPath
-		};
-		return deps.supervisor.start(startCfg);
-	}
-	function status() {
-		return {
-			...deps.supervisor.status(),
-			nodeId: deps.nodeId,
-			...downloadProgress !== void 0 ? { downloadProgress } : {}
-		};
-	}
-	return {
-		complete: async (input) => {
-			const guard = installedGuard(input.runtime);
-			if (!guard.ok) return {
-				ok: false,
-				code: "unavailable",
-				message: guard.message
-			};
-			await ensureStartedInternal(input.runtime);
-			const port = deps.supervisor.port;
-			if (port === void 0) return {
-				ok: false,
-				code: "unavailable",
-				message: "llama-server has no port"
-			};
-			const paths = await resolvePaths(input.runtime);
-			const timeoutMs = input.timeoutMs ?? 12e4;
-			const localProfile = {
-				id: "managed-local",
-				name: "managed-local",
-				kind: "openai-compatible",
-				addonId: "ai",
-				enabled: true,
-				model: paths.modelId,
-				baseUrl: `http://127.0.0.1:${String(port)}/v1`,
-				supportsVision: paths.mmprojPath !== void 0,
-				timeoutMs,
-				connectTimeoutMs: LlmTimeoutDefaults.connectMs,
-				firstTokenTimeoutMs: LlmTimeoutDefaults.firstTokenMs,
-				idleTimeoutMs: LlmTimeoutDefaults.idleMs,
-				retry: {
-					enabled: false,
-					maxAttempts: 1
-				},
-				toolsEnabled: false
-			};
-			const result = await deps.client.generate({
-				profile: localProfile,
-				...input.system !== void 0 ? { system: input.system } : {},
-				prompt: input.prompt,
-				...input.images !== void 0 ? { images: input.images } : {},
-				...input.jsonSchema !== void 0 ? { jsonSchema: input.jsonSchema } : {},
-				...input.maxTokens !== void 0 ? { maxTokens: input.maxTokens } : {},
-				...input.temperature !== void 0 ? { temperature: input.temperature } : {},
-				...input.topP !== void 0 ? { topP: input.topP } : {},
-				...input.topK !== void 0 ? { topK: input.topK } : {},
-				signal: new AbortController().signal
-			}, timeoutMs);
-			deps.supervisor.noteActivity();
-			return result;
-		},
-		ensureStarted: async ({ runtime }) => {
-			const guard = installedGuard(runtime);
-			if (!guard.ok) return {
-				nodeId: deps.nodeId,
-				state: "stopped",
-				lastError: guard.message,
-				crashesInWindow: 0
-			};
-			return ensureStartedInternal(runtime);
-		},
-		stop: async () => {
-			await deps.supervisor.stop();
-		},
-		status: async () => status(),
-		installModel: async ({ model }) => {
-			const resolution = entryForRef(model);
-			if (resolution === null) throw new Error("unknown model reference");
-			if (resolution.localPathOverride !== void 0) return;
-			downloadProgress = 0;
-			try {
-				await deps.modelOps.ensure(resolution.entry, (frac) => {
-					downloadProgress = frac;
-				});
-				if (model.kind === "url" && model.sha256 !== void 0) {
-					const filePath = deps.modelOps.pathFor(resolution.entry);
-					if (await (deps.fileSha256 ?? fileSha256)(filePath) !== model.sha256) {
-						await deps.modelOps.delete(resolution.entry);
-						throw new Error(`sha256 mismatch for ${model.url}`);
-					}
-				}
-			} finally {
-				downloadProgress = void 0;
-			}
-		},
-		deleteModel: async ({ file }) => {
-			const loaded = deps.supervisor.status().modelPath;
-			if (loaded !== void 0 && basename(loaded) === file) throw new Error(`cannot delete ${file}: loaded by the running runtime`);
-			await node_fs_promises.rm(node_path.join(deps.modelsDir, file), { force: true });
-		},
-		listLocalModels: async () => {
-			return (await listGgufFiles(deps.modelsDir)).map((f) => {
-				const catalogId = catalogIdForFile(f.file);
-				return {
-					file: f.file,
-					sizeBytes: f.sizeBytes,
-					...catalogId !== void 0 ? { catalogId } : {}
-				};
-			});
-		},
-		getDiskUsage: async () => {
-			const modelsBytes = (await listGgufFiles(deps.modelsDir)).reduce((sum, f) => sum + f.sizeBytes, 0);
-			return {
-				nodeId: deps.nodeId,
-				modelsBytes
-			};
-		}
-	};
-}
-async function listGgufFiles(dir) {
-	let names;
-	try {
-		names = await node_fs_promises.readdir(dir);
-	} catch {
-		return [];
-	}
-	const out = [];
-	for (const name of names) {
-		if (!name.endsWith(".gguf")) continue;
-		try {
-			const stat = await node_fs_promises.stat(node_path.join(dir, name));
-			out.push({
-				file: name,
-				sizeBytes: stat.size
-			});
-		} catch {}
-	}
-	return out;
-}
-//#endregion
-//#region src/runtime-client.ts
-/**
-* `RuntimeClient` over the cap plane — every verb pins the target node with
-* `nodePin(nodeId)` (transport-level, never a hand-rolled routing field). The
-* CapRouteResolver classifies the pin into hub-local-uds / remote-moleculer /
-* agent-child-forward transparently (spec §4.1; the model-studio cross-node
-* convert precedent). Node enumeration is the `nodes.topology` roster filtered
-* to nodes advertising the `llm-runtime` cap — never a shadow registry.
-*/
-var LLM_RUNTIME_CAP = "llm-runtime";
-function createRuntimeClient(api) {
-	return {
-		complete: (nodeId, input) => api.llmRuntime.complete.mutate(input, nodePin(nodeId)),
-		ensureStarted: (nodeId, runtime) => api.llmRuntime.ensureStarted.mutate({ runtime }, nodePin(nodeId)),
-		stopRuntime: (nodeId) => api.llmRuntime.stop.mutate({}, nodePin(nodeId)),
-		status: (nodeId) => api.llmRuntime.status.query({}, nodePin(nodeId)),
-		installModel: (nodeId, model) => api.llmRuntime.installModel.mutate({ model }, nodePin(nodeId)),
-		deleteModel: (nodeId, file) => api.llmRuntime.deleteModel.mutate({ file }, nodePin(nodeId)),
-		listLocalModels: (nodeId) => api.llmRuntime.listLocalModels.query({}, nodePin(nodeId)),
-		getDiskUsage: (nodeId) => api.llmRuntime.getDiskUsage.query({}, nodePin(nodeId)),
-		listRuntimeNodeIds: async () => {
-			const topology = await api.nodes.topology.query();
-			const ids = /* @__PURE__ */ new Set();
-			for (const node of topology) if (node.addons.some((a) => a.capabilities.includes(LLM_RUNTIME_CAP))) ids.add(node.id);
-			return [...ids];
-		}
-	};
-}
-//#endregion
-//#region src/assembly.ts
-/**
-* Registration assembly (the hub/agent split, spec §1). Every node running
-* addon-ai registers `llm-runtime`; ONLY the hub also registers the consumer
-* `llm` surface (profiles/usage need outbound internet + API keys).
-* Extracted from the addon class so the split + seeding is unit-testable
-* without a full AddonContext.
-*/
-async function assembleAi(deps) {
-	const client = deps.client ?? createLlmClient();
-	const runtimeProvider = createLlmRuntimeProvider({
-		nodeId: deps.nodeId,
-		modelsDir: deps.modelsDir,
-		ensureBinary: deps.ensureBinary,
-		supervisor: deps.supervisor,
-		modelOps: createDefaultModelOps(deps.modelsDir),
-		client,
-		logger: deps.logger.child("llm-runtime")
-	});
-	const registrations = [{
-		capability: llmRuntimeCapability,
-		provider: runtimeProvider
-	}];
-	if (!deps.isHub) return {
-		registrations,
-		runtimeProvider
-	};
-	const { UsageStore } = await Promise.resolve().then(() => require("./usage-store-Q34FDPSq.js")).then((n) => n.usage_store_exports);
-	const store = new ProfileStore(deps.settingsPort);
-	const defaults = new DefaultsStore(deps.settingsPort);
-	const usage = new UsageStore(deps.settingsPort, Date.now, deps.logger.child("llm-usage"));
-	await store.init();
-	await defaults.init();
-	await usage.init();
-	await store.ensureSeeded();
-	const llmProvider = createLlmProvider({
-		store,
-		defaults,
-		usage,
-		client,
-		...deps.runtimeApi !== void 0 ? { runtime: createRuntimeClient(deps.runtimeApi) } : {},
-		...deps.distributeModel !== void 0 ? { distributeModel: deps.distributeModel } : {},
-		catalog: LLM_MODEL_CATALOG.map((m) => m.meta),
-		logger: deps.logger.child("llm")
-	});
-	registrations.push({
-		capability: llmCapability,
-		provider: llmProvider
-	});
-	return {
-		registrations,
-		runtimeProvider,
-		llmProvider,
-		store,
-		usage,
-		prune: (retentionDays) => usage.prune(retentionDays)
-	};
-}
-//#endregion
 //#region src/runtime/crash-policy.ts
 var CrashPolicy = class {
 	opts;
@@ -71058,6 +71507,63 @@ var DEFAULT_CRASH_POLICY = {
 * v1: at most one running child. Resource ceiling = llama-server flags +
 * idleStopMinutes ONLY (no RSS watchdog — operator decision #3).
 */
+/**
+* Every llama-server flag a TYPED field above already owns, mapped to the
+* field that owns it.
+*
+* This map is the whole reconciliation between the typed tuning surface and
+* the free-text "additional arguments" box. Both exist because neither is
+* sufficient — the typed fields give the common knobs a validated control and
+* a default, and llama.cpp has a hundred flags nobody is going to model — but
+* a flag settable from BOTH is a bug generator: whichever one loses is a
+* control the operator watched do nothing. So the box is an escape hatch for
+* what is NOT modelled, and reaching into it for something that is gets
+* rejected by name.
+*/
+var OWNED_FLAGS = {
+	"-m": "model",
+	"--model": "model",
+	"--host": "fixed to 127.0.0.1",
+	"--port": "assigned by the supervisor",
+	"-c": "contextSize",
+	"--ctx-size": "contextSize",
+	"-ngl": "gpuLayers",
+	"--gpu-layers": "gpuLayers",
+	"--n-gpu-layers": "gpuLayers",
+	"-t": "threads",
+	"--threads": "threads",
+	"--parallel": "parallel",
+	"-np": "parallel",
+	"-b": "batchSize",
+	"--batch-size": "batchSize",
+	"-ub": "ubatchSize",
+	"--ubatch-size": "ubatchSize",
+	"-fa": "flashAttention",
+	"--flash-attn": "flashAttention",
+	"--mlock": "mlock",
+	"--no-mmap": "noMmap",
+	"-ctk": "cacheTypeK",
+	"--cache-type-k": "cacheTypeK",
+	"-ctv": "cacheTypeV",
+	"--cache-type-v": "cacheTypeV",
+	"--mmproj": "the vision model’s projector"
+};
+/**
+* Reject an `extraArgs` list that reaches for a flag a typed field owns.
+* `--flag=value` counts as `--flag`.
+*/
+function checkExtraArgs(extraArgs) {
+	for (const token of extraArgs) {
+		if (!token.startsWith("-")) continue;
+		const flag = token.split("=")[0] ?? token;
+		const owner = OWNED_FLAGS[flag];
+		if (owner !== void 0) return {
+			ok: false,
+			message: `"${flag}" is already set by the runtime field "${owner}" — set it there, not in additional arguments (a flag with two owners is a control that silently does nothing)`
+		};
+	}
+	return { ok: true };
+}
 var HEALTH_GATE_INTERVAL_MS = 500;
 function defaultPickPort() {
 	return new Promise((resolve, reject) => {
@@ -71108,6 +71614,7 @@ function buildLlamaArgs(cfg, port) {
 	if (cfg.cacheTypeK !== void 0) args.push("--cache-type-k", cfg.cacheTypeK);
 	if (cfg.cacheTypeV !== void 0) args.push("--cache-type-v", cfg.cacheTypeV);
 	if (cfg.mmprojPath !== void 0) args.push("--mmproj", cfg.mmprojPath);
+	args.push(...cfg.extraArgs ?? []);
 	return args;
 }
 var LlamaSupervisor = class {
@@ -71332,6 +71839,463 @@ var LlamaSupervisor = class {
 	}
 };
 //#endregion
+//#region src/runtime/sha256.ts
+/**
+* File sha256 — a local copy of the private `computeSha256` at
+* model-downloader.ts (not exported from @camstack/system), streamed so it
+* never buffers a multi-GB artifact.
+*/
+function fileSha256(filePath) {
+	return new Promise((resolve, reject) => {
+		const hash = (0, node_crypto.createHash)("sha256");
+		const stream = (0, node_fs.createReadStream)(filePath);
+		stream.on("error", reject);
+		stream.on("data", (chunk) => hash.update(chunk));
+		stream.on("end", () => resolve(hash.digest("hex")));
+	});
+}
+//#endregion
+//#region src/runtime/runtime-provider.ts
+/**
+* `llm-runtime` provider — the node-side managed executor. Reuses the
+* object-detection model plane (ensureModel/isModelDownloaded/delete via the
+* injected `RuntimeModelOps`) for GGUF artifacts, the `LlamaSupervisor` for the
+* llama-server child, and the SHARED {@link LlmClient} for the local inference
+* wire (only lifecycle + locality differ — spec §2). GGUFs are
+* multi-GB, so a missing model is an EXPLICIT-install error, never an auto-pull.
+* Usage rows are written hub-side only (single accounting point).
+*/
+function basename(url) {
+	const clean = url.split("?")[0] ?? url;
+	return clean.slice(clean.lastIndexOf("/") + 1);
+}
+function catalogIdForFile(file) {
+	return LLM_MODEL_CATALOG.find((m) => basename(m.meta.url) === file)?.meta.id;
+}
+/**
+* The projector among the extra files — matched by NAME, not by position.
+*
+* `extraFiles[0]` was safe while the only extra a GGUF entry ever had was an
+* mmproj. A split GGUF puts shards 2..N in the same list, so index 0 is now
+* routinely a weights shard, and passing one to `--mmproj` starts llama-server
+* against a file that is not a projector.
+*/
+function mmprojFilename(entry) {
+	return entry.extraFiles?.find((f) => f.filename.toLowerCase().startsWith("mmproj"))?.filename;
+}
+function gb(bytes) {
+	return `${(bytes / 1e9).toFixed(2)} GB`;
+}
+function createLlmRuntimeProvider(deps) {
+	let downloadProgress;
+	let download;
+	async function resolvePaths(runtime) {
+		const resolution = entryForRef(runtime.model);
+		if (resolution === null) throw new Error("unknown model reference");
+		const { entry, localPathOverride } = resolution;
+		const modelPath = localPathOverride ?? deps.modelOps.pathFor(entry);
+		const mmproj = mmprojFilename(entry);
+		return {
+			modelId: entry.id,
+			modelPath,
+			...mmproj !== void 0 ? { mmprojPath: deps.modelOps.extraFilePath(entry, mmproj) } : {}
+		};
+	}
+	function installedGuard(runtime) {
+		const resolution = entryForRef(runtime.model);
+		if (resolution === null) return {
+			ok: false,
+			message: "unknown model reference"
+		};
+		if (resolution.localPathOverride !== void 0) return { ok: true };
+		if (!deps.modelOps.isDownloaded(resolution.entry)) return {
+			ok: false,
+			message: `model ${resolution.entry.id} not installed on node ${deps.nodeId}`
+		};
+		return { ok: true };
+	}
+	async function ensureStartedInternal(runtime) {
+		const argCheck = checkExtraArgs(runtime.extraArgs);
+		if (!argCheck.ok) throw new Error(argCheck.message);
+		const binaryPath = await deps.ensureBinary();
+		const paths = await resolvePaths(runtime);
+		const startCfg = {
+			nodeId: deps.nodeId,
+			modelId: paths.modelId,
+			modelPath: paths.modelPath,
+			...paths.mmprojPath !== void 0 ? { mmprojPath: paths.mmprojPath } : {},
+			contextSize: runtime.contextSize,
+			gpuLayers: runtime.gpuLayers,
+			...runtime.threads !== void 0 ? { threads: runtime.threads } : {},
+			parallel: runtime.parallel,
+			...runtime.batchSize !== void 0 ? { batchSize: runtime.batchSize } : {},
+			...runtime.ubatchSize !== void 0 ? { ubatchSize: runtime.ubatchSize } : {},
+			flashAttention: runtime.flashAttention,
+			mlock: runtime.mlock,
+			noMmap: runtime.noMmap,
+			...runtime.cacheTypeK !== void 0 ? { cacheTypeK: runtime.cacheTypeK } : {},
+			...runtime.cacheTypeV !== void 0 ? { cacheTypeV: runtime.cacheTypeV } : {},
+			extraArgs: runtime.extraArgs,
+			idleStopMinutes: runtime.idleStopMinutes,
+			binaryPath
+		};
+		return deps.supervisor.start(startCfg);
+	}
+	/**
+	* sha256 every artifact whose digest the reference pinned — the main file
+	* AND the extras.
+	*
+	* Verifying only the main file was the gap: a truncated or swapped mmproj is
+	* exactly as fatal to llama-server as a bad weights file, and a resolved HF
+	* reference carries a digest for every artifact (LFS `oid`) so there is no
+	* reason to check one and trust the rest.
+	*
+	* This pass reads tens of GB and takes minutes; it is a REPORTED phase, not
+	* a silent tail, because a progress bar frozen at 100% is the shape of a
+	* hang.
+	*/
+	async function verifyDigests(entry, model, startedAt) {
+		if (model.kind !== "url") return;
+		const targets = [];
+		if (model.sha256 !== void 0) targets.push({
+			filePath: deps.modelOps.pathFor(entry),
+			sha256: model.sha256,
+			name: basename(model.url)
+		});
+		for (const extra of model.extraFiles ?? []) {
+			if (extra.sha256 === void 0) continue;
+			targets.push({
+				filePath: deps.modelOps.extraFilePath(entry, extra.filename),
+				sha256: extra.sha256,
+				name: extra.filename
+			});
+		}
+		if (targets.length === 0) return;
+		const sha256 = deps.fileSha256 ?? fileSha256;
+		for (const [index, target] of targets.entries()) {
+			download = {
+				phase: "verifying",
+				file: target.name,
+				fileIndex: index + 1,
+				fileCount: targets.length,
+				downloadedBytes: 0
+			};
+			deps.logger.info("llm model verifying digest", { meta: {
+				nodeId: deps.nodeId,
+				modelId: entry.id,
+				file: target.name
+			} });
+			const digest = await sha256(target.filePath);
+			if (digest !== target.sha256) {
+				deps.logger.error("llm model digest mismatch; discarding the download", { meta: {
+					nodeId: deps.nodeId,
+					modelId: entry.id,
+					file: target.name,
+					expected: target.sha256,
+					actual: digest,
+					elapsedMs: Date.now() - startedAt
+				} });
+				await deps.modelOps.delete(entry);
+				await node_fs_promises.rm(target.filePath, { force: true });
+				throw new Error(`sha256 mismatch for ${target.name}: expected ${target.sha256}, got ${digest}`);
+			}
+		}
+	}
+	function status() {
+		return {
+			...deps.supervisor.status(),
+			nodeId: deps.nodeId,
+			...downloadProgress !== void 0 ? { downloadProgress } : {},
+			...download !== void 0 ? { download } : {}
+		};
+	}
+	return {
+		complete: async (input) => {
+			const guard = installedGuard(input.runtime);
+			if (!guard.ok) return {
+				ok: false,
+				code: "unavailable",
+				message: guard.message
+			};
+			await ensureStartedInternal(input.runtime);
+			const port = deps.supervisor.port;
+			if (port === void 0) return {
+				ok: false,
+				code: "unavailable",
+				message: "llama-server has no port"
+			};
+			const paths = await resolvePaths(input.runtime);
+			const timeoutMs = input.timeoutMs ?? 12e4;
+			const localProfile = {
+				id: "managed-local",
+				name: "managed-local",
+				kind: "openai-compatible",
+				addonId: "ai",
+				enabled: true,
+				model: paths.modelId,
+				baseUrl: `http://127.0.0.1:${String(port)}/v1`,
+				supportsVision: paths.mmprojPath !== void 0,
+				timeoutMs,
+				connectTimeoutMs: LlmTimeoutDefaults.connectMs,
+				firstTokenTimeoutMs: LlmTimeoutDefaults.firstTokenMs,
+				idleTimeoutMs: LlmTimeoutDefaults.idleMs,
+				retry: {
+					enabled: false,
+					maxAttempts: 1
+				},
+				toolsEnabled: false
+			};
+			const result = await deps.client.generate({
+				profile: localProfile,
+				...input.system !== void 0 ? { system: input.system } : {},
+				prompt: input.prompt,
+				...input.images !== void 0 ? { images: input.images } : {},
+				...input.jsonSchema !== void 0 ? { jsonSchema: input.jsonSchema } : {},
+				...input.maxTokens !== void 0 ? { maxTokens: input.maxTokens } : {},
+				...input.temperature !== void 0 ? { temperature: input.temperature } : {},
+				...input.topP !== void 0 ? { topP: input.topP } : {},
+				...input.topK !== void 0 ? { topK: input.topK } : {},
+				signal: new AbortController().signal
+			}, timeoutMs);
+			deps.supervisor.noteActivity();
+			return result;
+		},
+		ensureStarted: async ({ runtime }) => {
+			const guard = installedGuard(runtime);
+			if (!guard.ok) return {
+				nodeId: deps.nodeId,
+				state: "stopped",
+				lastError: guard.message,
+				crashesInWindow: 0
+			};
+			return ensureStartedInternal(runtime);
+		},
+		stop: async () => {
+			await deps.supervisor.stop();
+		},
+		status: async () => status(),
+		/**
+		* Install a model on THIS node.
+		*
+		* Loud on purpose. This is the longest-running operation the addon has —
+		* tens of minutes for a 23 GB vision model — and until now it emitted not
+		* one log line, so an install that stalled on a gated URL or a full disk
+		* was indistinguishable from one that was simply slow. Every phase
+		* transition is a line, and every line carries the node.
+		*/
+		installModel: async ({ model }) => {
+			const resolution = entryForRef(model);
+			if (resolution === null) throw new Error("unknown model reference");
+			if (resolution.localPathOverride !== void 0) {
+				deps.logger.info("llm model is pre-provisioned; nothing to download", { meta: {
+					nodeId: deps.nodeId,
+					path: resolution.localPathOverride
+				} });
+				return;
+			}
+			const { entry } = resolution;
+			const declaredBytes = model.kind === "url" ? model.sizeBytes : void 0;
+			const startedAt = Date.now();
+			deps.logger.info("llm model install started", { meta: {
+				nodeId: deps.nodeId,
+				modelId: entry.id,
+				url: entry.formats.gguf?.url,
+				extraFiles: (entry.extraFiles ?? []).map((f) => f.filename),
+				...declaredBytes !== void 0 ? {
+					declaredBytes,
+					declaredSize: gb(declaredBytes)
+				} : {}
+			} });
+			downloadProgress = 0;
+			download = {
+				phase: "downloading",
+				file: "",
+				fileIndex: 0,
+				fileCount: 0,
+				downloadedBytes: 0
+			};
+			let lastLoggedDecile = -1;
+			try {
+				await deps.modelOps.ensure(entry, (progress) => {
+					const fraction = progress.totalBytes !== void 0 && progress.totalBytes > 0 ? Math.min(1, progress.downloadedBytes / progress.totalBytes) : void 0;
+					downloadProgress = fraction;
+					download = {
+						phase: "downloading",
+						file: progress.file,
+						fileIndex: progress.fileIndex,
+						fileCount: progress.fileCount,
+						downloadedBytes: progress.downloadedBytes,
+						...progress.totalBytes !== void 0 ? { totalBytes: progress.totalBytes } : {}
+					};
+					const decile = fraction === void 0 ? -1 : Math.floor(fraction * 10);
+					if (decile > lastLoggedDecile) {
+						lastLoggedDecile = decile;
+						deps.logger.info("llm model download progress", { meta: {
+							nodeId: deps.nodeId,
+							modelId: entry.id,
+							file: progress.file,
+							fileIndex: progress.fileIndex,
+							fileCount: progress.fileCount,
+							downloadedBytes: progress.downloadedBytes,
+							downloaded: gb(progress.downloadedBytes),
+							...progress.totalBytes !== void 0 ? { total: gb(progress.totalBytes) } : {}
+						} });
+					}
+				});
+				await verifyDigests(entry, model, startedAt);
+				deps.logger.info("llm model install complete", { meta: {
+					nodeId: deps.nodeId,
+					modelId: entry.id,
+					elapsedMs: Date.now() - startedAt
+				} });
+			} catch (err) {
+				deps.logger.error("llm model install failed", { meta: {
+					nodeId: deps.nodeId,
+					modelId: entry.id,
+					elapsedMs: Date.now() - startedAt,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+				throw err;
+			} finally {
+				downloadProgress = void 0;
+				download = void 0;
+			}
+		},
+		deleteModel: async ({ file }) => {
+			const loaded = deps.supervisor.status().modelPath;
+			if (loaded !== void 0 && basename(loaded) === file) throw new Error(`cannot delete ${file}: loaded by the running runtime`);
+			await node_fs_promises.rm(node_path.join(deps.modelsDir, file), { force: true });
+		},
+		listLocalModels: async () => {
+			return (await listGgufFiles(deps.modelsDir)).map((f) => {
+				const catalogId = catalogIdForFile(f.file);
+				return {
+					file: f.file,
+					sizeBytes: f.sizeBytes,
+					path: node_path.join(deps.modelsDir, f.file),
+					...catalogId !== void 0 ? { catalogId } : {}
+				};
+			});
+		},
+		getDiskUsage: async () => {
+			const modelsBytes = (await listGgufFiles(deps.modelsDir)).reduce((sum, f) => sum + f.sizeBytes, 0);
+			return {
+				nodeId: deps.nodeId,
+				modelsBytes
+			};
+		}
+	};
+}
+async function listGgufFiles(dir) {
+	let names;
+	try {
+		names = await node_fs_promises.readdir(dir);
+	} catch {
+		return [];
+	}
+	const out = [];
+	for (const name of names) {
+		if (!name.endsWith(".gguf")) continue;
+		try {
+			const stat = await node_fs_promises.stat(node_path.join(dir, name));
+			out.push({
+				file: name,
+				sizeBytes: stat.size
+			});
+		} catch {}
+	}
+	return out;
+}
+//#endregion
+//#region src/runtime-client.ts
+/**
+* `RuntimeClient` over the cap plane — every verb pins the target node with
+* `nodePin(nodeId)` (transport-level, never a hand-rolled routing field). The
+* CapRouteResolver classifies the pin into hub-local-uds / remote-moleculer /
+* agent-child-forward transparently (spec §4.1; the model-studio cross-node
+* convert precedent). Node enumeration is the `nodes.topology` roster filtered
+* to nodes advertising the `llm-runtime` cap — never a shadow registry.
+*/
+var LLM_RUNTIME_CAP = "llm-runtime";
+function createRuntimeClient(api) {
+	return {
+		complete: (nodeId, input) => api.llmRuntime.complete.mutate(input, nodePin(nodeId)),
+		ensureStarted: (nodeId, runtime) => api.llmRuntime.ensureStarted.mutate({ runtime }, nodePin(nodeId)),
+		stopRuntime: (nodeId) => api.llmRuntime.stop.mutate({}, nodePin(nodeId)),
+		status: (nodeId) => api.llmRuntime.status.query({}, nodePin(nodeId)),
+		installModel: (nodeId, model) => api.llmRuntime.installModel.mutate({ model }, nodePin(nodeId)),
+		deleteModel: (nodeId, file) => api.llmRuntime.deleteModel.mutate({ file }, nodePin(nodeId)),
+		listLocalModels: (nodeId) => api.llmRuntime.listLocalModels.query({}, nodePin(nodeId)),
+		getDiskUsage: (nodeId) => api.llmRuntime.getDiskUsage.query({}, nodePin(nodeId)),
+		listRuntimeNodeIds: async () => {
+			const topology = await api.nodes.topology.query();
+			const ids = /* @__PURE__ */ new Set();
+			for (const node of topology) if (node.addons.some((a) => a.capabilities.includes(LLM_RUNTIME_CAP))) ids.add(node.id);
+			return [...ids];
+		}
+	};
+}
+//#endregion
+//#region src/assembly.ts
+/**
+* Registration assembly (the hub/agent split, spec §1). Every node running
+* addon-ai registers `llm-runtime`; ONLY the hub also registers the consumer
+* `llm` surface (profiles/usage need outbound internet + API keys).
+* Extracted from the addon class so the split + seeding is unit-testable
+* without a full AddonContext.
+*/
+async function assembleAi(deps) {
+	const client = deps.client ?? createLlmClient();
+	const runtimeProvider = createLlmRuntimeProvider({
+		nodeId: deps.nodeId,
+		modelsDir: deps.modelsDir,
+		ensureBinary: deps.ensureBinary,
+		supervisor: deps.supervisor,
+		modelOps: createDefaultModelOps(deps.modelsDir),
+		client,
+		logger: deps.logger.child("llm-runtime")
+	});
+	const registrations = [{
+		capability: llmRuntimeCapability,
+		provider: runtimeProvider
+	}];
+	if (!deps.isHub) return {
+		registrations,
+		runtimeProvider
+	};
+	const { UsageStore } = await Promise.resolve().then(() => require("./usage-store-Q34FDPSq.js")).then((n) => n.usage_store_exports);
+	const store = new ProfileStore(deps.settingsPort);
+	const defaults = new DefaultsStore(deps.settingsPort);
+	const usage = new UsageStore(deps.settingsPort, Date.now, deps.logger.child("llm-usage"));
+	await store.init();
+	await defaults.init();
+	await usage.init();
+	await store.ensureSeeded();
+	const llmProvider = createLlmProvider({
+		store,
+		defaults,
+		usage,
+		client,
+		...deps.runtimeApi !== void 0 ? { runtime: createRuntimeClient(deps.runtimeApi) } : {},
+		...deps.distributeModel !== void 0 ? { distributeModel: deps.distributeModel } : {},
+		catalog: LLM_MODEL_CATALOG.map((m) => m.meta),
+		hfToken: () => process.env["HF_TOKEN"] ?? process.env["HUGGING_FACE_HUB_TOKEN"],
+		logger: deps.logger.child("llm")
+	});
+	registrations.push({
+		capability: llmCapability,
+		provider: llmProvider
+	});
+	return {
+		registrations,
+		runtimeProvider,
+		llmProvider,
+		store,
+		usage,
+		prune: (retentionDays) => usage.prune(retentionDays)
+	};
+}
+//#endregion
 //#region src/settings-store-port.ts
 function createApiSettingsStorePort(api) {
 	return {