dsh-plugin-local-infer 0.1.3 → 0.1.4

package/packages/core/lib/models.js

@@ -1,3 +1,4 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 /**
  * repoIdFromUrl turns a Hugging Face repo URL into the `owner/name` repo id
@@ -21,26 +22,81 @@ export function repoNameFromUrl(url) {
     return slash >= 0 ? repo.slice(slash + 1) : repo;
 }
 /**
- * modelArtifactPath is the path the presence check looks for in the model
- * directory: the entry's artifact file when it names one, else the repo-name
- * directory a whole-repo download leaves behind.
+ * hubCacheModelDirectory is the per-model directory the hf CLI creates in the
+ * hub cache for one repo id: `models--{namespace}--{name}`. A repo id without
+ * an owner/name pair reads as an empty directory name, which the callers
+ * handle as an absent model.
  */
-export function modelArtifactPath(entry, directory) {
+export function hubCacheModelDirectory(repoId) {
+    const slash = repoId.lastIndexOf('/');
+    if (slash <= 0)
+        return '';
+    return `models--${repoId.slice(0, slash)}--${repoId.slice(slash + 1)}`;
+}
+/**
+ * isModelDirectoryOverridden reports whether a model directory field (the
+ * config's or a download request's) names a path (a non-blank string), the
+ * one rule every download route and view model shares to decide the layout:
+ * a named directory targets that directory flat (`--local-dir`), an unnamed
+ * one takes the hub-cache layout (no `--local-dir`, the
+ * `models--{ns}--{name}` directories the hf CLI writes into the hub cache).
+ * The predicate form lets callers narrow the field to a string without
+ * restating the blank check.
+ */
+export function isModelDirectoryOverridden(modelDirectory) {
+    return typeof modelDirectory === 'string' && modelDirectory.trim() !== '';
+}
+/**
+ * modelArtifactPath is the path a model download's artifact lands at in the
+ * model directory: the entry's artifact file when it names one, else the
+ * repo-name directory a whole-repo download leaves behind. With the hub-cache
+ * layout (`useHubCache`), it resolves into the per-model cache directory's
+ * `blobs` folder, the content-addressed store the hf CLI writes without
+ * `--local-dir`; the `directory` is then the hub cache root, not the per-model
+ * folder. Every presence decision (the card-facing checks and the engines'
+ * deploy re-fetch gates) resolves the deterministic snapshot instead
+ * (modelArtifactPresent); the hub-cache form here stays the blobs-store path.
+ */
+export function modelArtifactPath(entry, directory, useHubCache = false) {
+    if (useHubCache) {
+        const modelDir = hubCacheModelDirectory(repoIdFromUrl(entry.url));
+        if (modelDir !== '')
+            return join(directory, modelDir, 'blobs');
+    }
     if (entry.file !== undefined && entry.file !== '') {
         return join(directory, entry.file);
     }
     return join(directory, repoNameFromUrl(entry.url));
 }
 /**
- * hfDownloadCommand renders the hf CLI download for one default model: the
- * repo, the artifact file when the entry names one, and the `--local-dir`
- * target. The string is the single source the download route runs and the
- * card shows beside its Download button.
+ * hfDownloadFileCommand renders the hf CLI download for one repo and file
+ * pair: the repo, the file (omitted when blank, a whole-repo download), the
+ * `--local-dir` target when the hub-cache layout does not apply, and the
+ * `--format human` flag. The flag overrides the non-TTY default (`auto` picks
+ * `agent`, which prints no progress) so the hf CLI prints tqdm progress
+ * lines to stderr, which the progress streaming tasks consume. The string is
+ * the single source every hf download command renders through: the model and
+ * chat-template builders below, and the Infernix extra-download commands the
+ * Get step streams.
+ */
+export function hfDownloadFileCommand(repo, file, directory, useHubCache = false) {
+    const filePart = file !== '' ? ` ${file}` : '';
+    const localDir = useHubCache ? '' : ` --local-dir ${directory}`;
+    return `hf download ${repo}${filePart}${localDir} --format human`;
+}
+/**
+ * hfDownloadCommand renders the hf CLI download for one model download
+ * source: the repo, the artifact file when the entry names one, and the
+ * `--local-dir` target. With the hub-cache layout (`useHubCache`), the `--local-dir` is
+ * dropped so the hf CLI writes into the hub cache's `models--{ns}--{name}`
+ * directory (the content-addressed `blobs/` plus the `snapshots/`). The
+ * string is the single source the download route runs and the card shows
+ * beside its Download button, rendered through hfDownloadFileCommand.
  */
-export function hfDownloadCommand(entry, directory) {
+export function hfDownloadCommand(entry, directory, useHubCache = false) {
     const repo = repoIdFromUrl(entry.url);
-    const file = entry.file !== undefined && entry.file !== '' ? ` ${entry.file}` : '';
-    return `hf download ${repo}${file} --local-dir ${directory}`;
+    const file = entry.file !== undefined && entry.file !== '' ? entry.file : '';
+    return hfDownloadFileCommand(repo, file, directory, useHubCache);
 }
 /**
  * The chat template file the hf CLI pulls into the model directory. The
@@ -51,12 +107,115 @@ export const CHAT_TEMPLATE_FILE = 'chat_template.jinja';
 /**
  * hfChatTemplateCommand renders the hf CLI download for one chat template repo
  * reference into the model directory: the repo, the template file, and the
- * `--local-dir` target. The string is the single source the template download
- * route runs and the card shows beside its Download button and in the System
- * dependencies box when the auto-download is unavailable.
+ * `--local-dir` target. With the hub-cache layout (`useHubCache`), the
+ * `--local-dir` is dropped so the template lands in the hub cache's
+ * `models--{ns}--{name}` directory. The string is the single source the
+ * template download route runs and the card shows beside its Download button
+ * and in the System dependencies box when the auto-download is unavailable,
+ * rendered through hfDownloadFileCommand.
+ */
+export function hfChatTemplateCommand(repo, directory, useHubCache = false) {
+    return hfDownloadFileCommand(repo, CHAT_TEMPLATE_FILE, directory, useHubCache);
+}
+/**
+ * chatTemplateArtifactPath is the path the flat-layout chat-template presence
+ * check looks for: the template file joined onto the model directory. The
+ * hub-cache layout resolves through chatTemplatePresent instead (the
+ * deterministic snapshot pick), not through this join.
+ */
+export function chatTemplateArtifactPath(directory) {
+    return join(directory, CHAT_TEMPLATE_FILE);
+}
+/**
+ * modelArtifactPresent reports whether a model download source's artifact is
+ * on disk. With the hub-cache layout it resolves the deterministic hub-cache
+ * snapshot holding the file (the same pick the model-directory display uses),
+ * so a `blobs` folder left by any download never reads as present on its
+ * own; a blank `file` (a whole-repo download) reads the repo's snapshot
+ * directories. With the flat layout it checks the artifact path joined onto
+ * the base directory. `baseDir` is the hub cache root under the cache layout,
+ * the flat override otherwise.
+ */
+export function modelArtifactPresent(entry, baseDir, useHubCache = false) {
+    if (useHubCache) {
+        return hubCacheSnapshotFilePath(baseDir, repoIdFromUrl(entry.url), entry.file ?? '') !== null;
+    }
+    return existsSync(modelArtifactPath(entry, baseDir));
+}
+/**
+ * chatTemplatePresent reports whether a chat template repo's template file is
+ * on disk: the deterministic hub-cache snapshot pick under the hub-cache
+ * layout (a per-repo `snapshots` folder alone never reads as present), the
+ * flat file join otherwise. `baseDir` follows the modelArtifactPresent rule.
  */
-export function hfChatTemplateCommand(repo, directory) {
-    return `hf download ${repo} ${CHAT_TEMPLATE_FILE} --local-dir ${directory}`;
+export function chatTemplatePresent(repo, baseDir, useHubCache = false) {
+    if (useHubCache) {
+        return hubCacheSnapshotFilePath(baseDir, repo, CHAT_TEMPLATE_FILE) !== null;
+    }
+    return existsSync(chatTemplateArtifactPath(baseDir));
+}
+/**
+ * hubCacheSnapshotFilePath resolves the concrete file path of one file in the
+ * hub cache's snapshots, matching what the hf CLI treats as the active
+ * revision: the commit recorded in `refs/main` wins when its directory under
+ * `models--{ns}--{name}/snapshots/` holds the file; otherwise the snapshot
+ * with the newest mtime wins, covering a repo with no ref and a ref naming a
+ * commit that lacks the file. Ties break on readdir order. Returns null when
+ * no snapshot holds the file (the file is not downloaded), which the caller
+ * reads as absent. The `hubCache` is the hub cache root.
+ */
+export function hubCacheSnapshotFilePath(hubCache, repoId, file) {
+    const modelDir = hubCacheModelDirectory(repoId);
+    if (modelDir === '')
+        return null;
+    const modelRoot = join(hubCache, modelDir);
+    const snapshots = join(modelRoot, 'snapshots');
+    // The hf CLI writes the revision it last downloaded into refs/main; that
+    // commit is the cache's active one, so it outranks mtime.
+    const active = readHubCacheRef(join(modelRoot, 'refs', 'main'));
+    if (active !== '') {
+        const activePath = join(snapshots, active, file);
+        if (existsSync(activePath))
+            return activePath;
+    }
+    let commits;
+    try {
+        commits = readdirSync(snapshots);
+    }
+    catch {
+        return null;
+    }
+    let newestPath = null;
+    let newestMtime = -Infinity;
+    for (const commit of commits) {
+        const path = join(snapshots, commit, file);
+        if (!existsSync(path))
+            continue;
+        const snapshotDir = join(snapshots, commit);
+        let mtime;
+        try {
+            mtime = statSync(snapshotDir).mtimeMs;
+        }
+        catch {
+            // A directory that cannot be stat'ed mid-scan cannot win the pick.
+            continue;
+        }
+        if (mtime > newestMtime) {
+            newestMtime = mtime;
+            newestPath = path;
+        }
+    }
+    return newestPath;
+}
+// readHubCacheRef returns the commit the hf CLI ref file names, or '' when
+// the ref is absent or unreadable (a cache written by an older CLI).
+function readHubCacheRef(refPath) {
+    try {
+        return readFileSync(refPath, 'utf8').trim();
+    }
+    catch {
+        return '';
+    }
 }
 /**
  * modelEntriesForEngine filters a model directory listing down to the model
@@ -98,4 +257,37 @@ export function modelEntriesForEngine(entries, engineId) {
     }
     return names.sort();
 }
-//# sourceMappingURL=models.js.map
+/**
+ * modelCacheEntriesForEngine filters the hub cache's `models--*` directories
+ * down to the models the engine's Model dropdown offers, by the artifact types
+ * each engine serves: Basalt `.basalt`, NInfer `.ninfer`, Infernix
+ * `.ninfer`/`.infernix`, llama.cpp `.gguf`, Hyper-Qwen a repo holding a
+ * `.safetensors` weight file, and Strata `.gguf`/`.safetensors`. An engine with
+ * no matching cached model lists none. The result is the repo ids the
+ * dropdown shows, sorted for a stable order across summary fetches.
+ */
+export function modelCacheEntriesForEngine(entries, engineId) {
+    const serves = (files) => {
+        switch (engineId) {
+            case 'basalt':
+                return files.some((file) => file.endsWith('.basalt'));
+            case 'ninfer':
+                return files.some((file) => file.endsWith('.ninfer'));
+            case 'infernix':
+                return files.some((file) => file.endsWith('.ninfer') || file.endsWith('.infernix'));
+            case 'llamacpp':
+                return files.some((file) => file.endsWith('.gguf'));
+            case 'hyperqwen':
+                return files.some((file) => file.endsWith('.safetensors'));
+            case 'strata':
+                return files.some((file) => file.endsWith('.gguf') || file.endsWith('.safetensors'));
+            default:
+                return false;
+        }
+    };
+    return entries
+        .filter((entry) => serves(entry.files))
+        .map((entry) => entry.repoId)
+        .sort();
+}
+//# sourceMappingURL=models.js.map

package/packages/core/lib/parameter.d.ts

@@ -68,6 +68,29 @@ export type ParameterForm = {
     kind: 'combo';
     options: ComboOption[];
 };
+/**
+ * ParameterDeploy declares where a parameter's value lands at deploy time:
+ * on the command line, in the process environment, or in a config file the
+ * deploy step writes. A `config` target names the file format and the
+ * nesting path: `block` is the top-level key, `key` the leaf. The config-file
+ * renderer nests `toConfig(value)` (or the raw value) under that path. A
+ * `block` ending in `[]` (e.g. `models[]`) is the array-entry convention: the
+ * key lands inside the single object of a one-element array named by the
+ * prefix, and specs sharing that block merge into that one entry. A spec
+ * declares one target, or a list of targets when the value lands in more than
+ * one place (a Strata shared spec lands on the CLI in the binary mode and in
+ * the env in the docker mode).
+ */
+export type ParameterDeploy = {
+    target: 'cli';
+} | {
+    target: 'env';
+} | {
+    target: 'config';
+    format: 'json' | 'yaml' | 'env';
+    block?: string;
+    key?: string;
+};
 /**
  * ParameterSpec is the unit of parameter management: a declarative description
  * of one engine parameter. It is the object that makes the parameter-to-
@@ -77,8 +100,11 @@ export type ParameterForm = {
  * of adding these specs, never rewiring the core.
  *
  * `description` is behavior-first: it says what the parameter does to the run,
- * not what it is. `toArgv` and `toEnv` are the engine-specific spellings that
- * turn a value into a CLI flag or an environment variable.
+ * not what it is. `toArgv`, `toEnv`, and `toConfig` are the engine-specific
+ * spellings that turn a value into a CLI flag, an environment variable, or a
+ * config-file entry. `deploy` declares which spelling the deploy step uses;
+ * a list declares several, so one spec can serve more than one build mode
+ * (the flags in the binary mode and the env vars in the docker mode).
  */
 export interface ParameterSpec {
     key: string;
@@ -92,5 +118,7 @@ export interface ParameterSpec {
     requires?: (config: Config) => string | null;
     toArgv?: (value: unknown) => string[];
     toEnv?: (value: unknown) => [string, string];
+    toConfig?: (value: unknown) => unknown;
+    deploy?: ParameterDeploy | readonly ParameterDeploy[];
 }
-//# sourceMappingURL=parameter.d.ts.map
+//# sourceMappingURL=parameter.d.ts.map

package/packages/core/lib/parameter.js

@@ -1,2 +1,2 @@
 export {};
-//# sourceMappingURL=parameter.js.map
+//# sourceMappingURL=parameter.js.map

package/packages/core/lib/progress.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The pure hf (huggingface_hub) tqdm progress parser the get and launch routes
+ * share: it turns the raw tqdm stderr lines into a structured HfProgress
+ * state, so a route's onChunk sink (the download runner's streamed stderr)
+ * feeds the card's progress events without a node import. The parser
+ * recognizes the two tqdm bar shapes the hf CLI emits with `--format human`:
+ * the file-count bar (`Fetching 102 files: 42%|...| 43/102 [00:01<00:02,
+ * 20.5it/s]`, where the done/total fields carry file counts, not bytes) and
+ * the byte bar (`Downloading x.safetensors: 12% | 5.2G/43.5G [01:23<10:11,
+ * 72.3MB/s]`, where the done/total fields carry human byte sizes). It
+ * converts the human byte sizes to bytes and the `[elapsed<remaining, rate]`
+ * tail to remaining seconds, and marks the unit the done/total amounts carry
+ * (`'files'` for the file-count bar, `'bytes'` for the byte bar), so a
+ * readout renders the amounts in the unit the bar measured. The client
+ * package mirrors this parser in
+ * `packages/client/src/store/progress.ts` (the TASK-006 browser-side copy):
+ * the core package is not browser-safe, so the client bundle keeps its own
+ * copy and the two shapes (`HfProgress` and the client's `HfProgressShape`)
+ * must stay in sync when a tqdm bar shape changes.
+ * @module dsh-plugin-local-infer/core/progress
+ */
+/**
+ * HfProgress is the structured state one tqdm bar update folds to: the step
+ * label the bar names (the file, or the file-count fetch), the percent
+ * complete, the done and total amounts (bytes for the byte bar, file counts
+ * for the file-count bar), the remaining time in seconds (0 when the bar
+ * carries no tail), and the unit the done/total amounts carry ('bytes' for
+ * the byte bar, 'files' for the file-count bar), so a readout renders the
+ * amounts in the unit the bar measured.
+ */
+export interface HfProgress {
+    step: string;
+    percent: number;
+    doneBytes: number;
+    totalBytes: number;
+    etaSeconds: number;
+    unit: 'bytes' | 'files';
+}
+/**
+ * parseHfProgressLine parses one tqdm bar line into an HfProgress state, or
+ * undefined when the line is not a bar update (a plain log line, a command
+ * echo). It recognizes the file-count and byte shapes above.
+ */
+export declare function parseHfProgressLine(line: string): HfProgress | undefined;
+/**
+ * foldHfProgressChunk folds a raw stderr chunk into the latest HfProgress
+ * state it carries: the chunk splits on the line separators tqdm writes
+ * (carriage returns between bar redraws, newlines between steps), each line
+ * parses through parseHfProgressLine, and the last parseable line wins. A
+ * chunk with no bar update returns the prior state, so a caller threads the
+ * fold across chunks and always holds the newest state.
+ */
+export declare function foldHfProgressChunk(chunk: string, prior: HfProgress | undefined): HfProgress | undefined;
+//# sourceMappingURL=progress.d.ts.map

package/packages/core/lib/progress.js

@@ -0,0 +1,120 @@
+/**
+ * The pure hf (huggingface_hub) tqdm progress parser the get and launch routes
+ * share: it turns the raw tqdm stderr lines into a structured HfProgress
+ * state, so a route's onChunk sink (the download runner's streamed stderr)
+ * feeds the card's progress events without a node import. The parser
+ * recognizes the two tqdm bar shapes the hf CLI emits with `--format human`:
+ * the file-count bar (`Fetching 102 files: 42%|...| 43/102 [00:01<00:02,
+ * 20.5it/s]`, where the done/total fields carry file counts, not bytes) and
+ * the byte bar (`Downloading x.safetensors: 12% | 5.2G/43.5G [01:23<10:11,
+ * 72.3MB/s]`, where the done/total fields carry human byte sizes). It
+ * converts the human byte sizes to bytes and the `[elapsed<remaining, rate]`
+ * tail to remaining seconds, and marks the unit the done/total amounts carry
+ * (`'files'` for the file-count bar, `'bytes'` for the byte bar), so a
+ * readout renders the amounts in the unit the bar measured. The client
+ * package mirrors this parser in
+ * `packages/client/src/store/progress.ts` (the TASK-006 browser-side copy):
+ * the core package is not browser-safe, so the client bundle keeps its own
+ * copy and the two shapes (`HfProgress` and the client's `HfProgressShape`)
+ * must stay in sync when a tqdm bar shape changes.
+ * @module dsh-plugin-local-infer/core/progress
+ */
+// The file-count bar: `Fetching 102 files: 42%|...| 43/102 [00:01<00:02, ...]`.
+// The bar glyph run between the pipes is skipped, and the counts are plain
+// integers.
+const FILES_LINE = /^Fetching (\d+) files:\s*(\d+(?:\.\d+)?)%\|[^|]*\|\s*(\d+)\s*\/\s*(\d+)(?:\s*\[([^\]]*)\])?/;
+// The byte bar: `Downloading x.safetensors: 12% | 5.2G/43.5G [01:23<10:11, ...]`.
+// The sizes carry an optional K/M/G/T/P unit (decimal, or binary with an
+// `i`), and the tail is optional (a finished bar drops it).
+const BYTES_LINE = /^(?:Downloading|Fetching)\s+([^:]+):\s*(\d+(?:\.\d+)?)%\s*\|\s*(\d+(?:\.\d+)?[KMGTP]?i?B?)\s*\/\s*(\d+(?:\.\d+)?[KMGTP]?i?B?)\s*(?:\[([^\]]*)\])?/;
+// The unit exponents for the decimal (1000-based) sizes the hf CLI's tqdm
+// renders; a binary `i` suffix (Gi, Mi, ...) switches the base to 1024.
+const UNIT_EXPONENTS = { K: 1, M: 2, G: 3, T: 4, P: 5 };
+// parseHumanSize converts one human byte size (`5.2G`) to bytes: the decimal
+// base the hf CLI's tqdm uses, with a 1024 base when the unit carries the
+// binary `i` suffix. A size with no unit is a plain byte count.
+function parseHumanSize(text) {
+    const match = /^(\d+(?:\.\d+)?)([KMGTP]?)i?B?$/.exec(text);
+    if (match === null)
+        return 0;
+    const exponent = UNIT_EXPONENTS[match[2]] ?? 0;
+    const base = text.includes('i') ? 1024 : 1000;
+    return Number(match[1]) * base ** exponent;
+}
+// durationSeconds converts a `MM:SS`, `H:MM:SS`, or `D:H:MM:SS` clock string
+// to seconds, the tqdm tail's remaining-time format.
+function durationSeconds(text) {
+    let seconds = 0;
+    for (const part of text.split(':')) {
+        seconds = seconds * 60 + Number(part);
+    }
+    return seconds;
+}
+// etaSecondsFromTail reads the remaining time out of a tqdm tail
+// (`01:23<10:11, 72.3MB/s`): the clock string after the `<`, 0 when the tail
+// is absent or carries no remaining time.
+function etaSecondsFromTail(tail) {
+    if (tail === undefined)
+        return 0;
+    const match = /<\s*(\d+(?::\d+)+)/.exec(tail);
+    if (match === null)
+        return 0;
+    return durationSeconds(match[1]);
+}
+/**
+ * parseHfProgressLine parses one tqdm bar line into an HfProgress state, or
+ * undefined when the line is not a bar update (a plain log line, a command
+ * echo). It recognizes the file-count and byte shapes above.
+ */
+export function parseHfProgressLine(line) {
+    const trimmed = line.trim();
+    if (trimmed === '')
+        return undefined;
+    const files = FILES_LINE.exec(trimmed);
+    if (files !== null) {
+        // The file-count bar carries counts, not bytes: the done/total fields
+        // hold the file numbers, the step label names the fetch, and the unit
+        // marks the amounts as file counts, so a readout renders them as files.
+        return {
+            step: `Fetching ${files[1]} files`,
+            percent: Number(files[2]),
+            doneBytes: Number(files[3]),
+            totalBytes: Number(files[4]),
+            etaSeconds: etaSecondsFromTail(files[5]),
+            unit: 'files',
+        };
+    }
+    const bytes = BYTES_LINE.exec(trimmed);
+    if (bytes !== null) {
+        const verb = trimmed.startsWith('Fetching') ? 'Fetching' : 'Downloading';
+        // The byte bar carries human byte sizes: the done/total fields hold the
+        // parsed byte counts, and the unit marks the amounts as bytes.
+        return {
+            step: `${verb} ${bytes[1].trim()}`,
+            percent: Number(bytes[2]),
+            doneBytes: parseHumanSize(bytes[3]),
+            totalBytes: parseHumanSize(bytes[4]),
+            etaSeconds: etaSecondsFromTail(bytes[5]),
+            unit: 'bytes',
+        };
+    }
+    return undefined;
+}
+/**
+ * foldHfProgressChunk folds a raw stderr chunk into the latest HfProgress
+ * state it carries: the chunk splits on the line separators tqdm writes
+ * (carriage returns between bar redraws, newlines between steps), each line
+ * parses through parseHfProgressLine, and the last parseable line wins. A
+ * chunk with no bar update returns the prior state, so a caller threads the
+ * fold across chunks and always holds the newest state.
+ */
+export function foldHfProgressChunk(chunk, prior) {
+    let folded = prior;
+    for (const line of chunk.split(/\r\n|\r|\n/)) {
+        const parsed = parseHfProgressLine(line);
+        if (parsed !== undefined)
+            folded = parsed;
+    }
+    return folded;
+}
+//# sourceMappingURL=progress.js.map

package/packages/core/lib/registrar.d.ts

@@ -2,8 +2,9 @@ import type { BuildMode, LaunchPlan } from './adapter.ts';
 /**
  * DshModelEntry is the shape of the model row the registrar writes into the
  * dsh-llm-pi-ai provider: the provider id, the model id and display name, the
- * context window, the engine's base URL, and the env-var name the provider
- * reads its optional API key from.
+ * context window, the engine's base URL, the env-var name the provider reads
+ * its optional API key from, and the placeholder API key value the engine
+ * ships with so a model the user has not keyed still activates.
  */
 export interface DshModelEntry {
     providerId: string;
@@ -12,6 +13,7 @@ export interface DshModelEntry {
     contextWindow: number;
     baseURL: string;
     apiKeyEnv: string;
+    apiKey: string;
     input?: string[];
 }
 /**
@@ -94,13 +96,22 @@ export declare function providerIdFor(engineId: string, modelId: string, buildMo
  * underscores, plus _LOCAL_API_KEY.
  */
 export declare function apiKeyEnvFor(engineId: string): string;
+/**
+ * defaultApiKeyFor derives the placeholder API key value a local engine ships
+ * with: the engine id, uppercased and non-alphanumerics mapped to underscores,
+ * wrapped in double braces plus _LOCAL_API_KEY. The double braces mark the
+ * value as a placeholder, not a real key, so a model the user has not keyed
+ * still activates the pi-ai OpenAI route. A user-added key replaces it in a
+ * future turn.
+ */
+export declare function defaultApiKeyFor(engineId: string): string;
 /**
  * buildModelEntry turns a launch plan and a model row into the DshModelEntry
  * the registrar writes. The provider id is the engine, build mode, and model
  * slug; the display name is the engine, the build mode in parentheses, and
  * the model name (falling back to the slug when the row carries none). The
- * API-key env name derives from the engine id, and the base URL is the
- * engine's OpenAI endpoint on its port.
+ * API-key env name and the placeholder API key value derive from the engine
+ * id, and the base URL is the engine's OpenAI endpoint on its port.
  */
 export declare function buildModelEntry(plan: LaunchPlan, model: ModelRow): DshModelEntry;
 /**
@@ -118,10 +129,10 @@ export declare function upsertModelRow(rows: readonly ModelRow[], row: ModelRow)
 export declare function removeModelRow(rows: readonly ModelRow[], modelId: string): ModelRow[];
 /**
  * providerRegistrationOps computes the settings ops that upsert a provider
- * entry: the API-key env name, the openai-completions api, the base URL, and
- * the models list with the entry's row upserted. The ops write the provider
- * fields by path, so a provider the user edited by hand keeps every field
- * the registrar does not own.
+ * entry: the API-key env name, the openai-completions api, the base URL, the
+ * placeholder Authorization header, and the models list with the entry's row
+ * upserted. The ops write the provider fields by path, so a provider the user
+ * edited by hand keeps every field the registrar does not own.
  */
 export declare function providerRegistrationOps(entry: DshModelEntry, rows: readonly ModelRow[]): SettingsOp[];
 /**
@@ -154,4 +165,4 @@ export declare function modelRowsFrom(value: unknown, providerId: string): reado
  * when it names the removed pair.
  */
 export declare function agentDefaultPointsAt(value: unknown, providerId: string, modelId: string): boolean;
-//# sourceMappingURL=registrar.d.ts.map
+//# sourceMappingURL=registrar.d.ts.map

package/packages/core/lib/registrar.js

@@ -42,6 +42,17 @@ export function providerIdFor(engineId, modelId, buildMode) {
 export function apiKeyEnvFor(engineId) {
     return `${engineId.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_LOCAL_API_KEY`;
 }
+/**
+ * defaultApiKeyFor derives the placeholder API key value a local engine ships
+ * with: the engine id, uppercased and non-alphanumerics mapped to underscores,
+ * wrapped in double braces plus _LOCAL_API_KEY. The double braces mark the
+ * value as a placeholder, not a real key, so a model the user has not keyed
+ * still activates the pi-ai OpenAI route. A user-added key replaces it in a
+ * future turn.
+ */
+export function defaultApiKeyFor(engineId) {
+    return `{{${engineId.toUpperCase().replace(/[^A-Z0-9]/g, '_')}}}_LOCAL_API_KEY`;
+}
 /**
  * engineDisplayName capitalizes the first letter of an engine id for the
  * display name: `ninfer` reads as `Ninfer`, `hyperqwen` as `Hyperqwen`.
@@ -54,8 +65,8 @@ function engineDisplayName(engineId) {
  * the registrar writes. The provider id is the engine, build mode, and model
  * slug; the display name is the engine, the build mode in parentheses, and
  * the model name (falling back to the slug when the row carries none). The
- * API-key env name derives from the engine id, and the base URL is the
- * engine's OpenAI endpoint on its port.
+ * API-key env name and the placeholder API key value derive from the engine
+ * id, and the base URL is the engine's OpenAI endpoint on its port.
  */
 export function buildModelEntry(plan, model) {
     const buildMode = plan.kind === 'docker' ? 'docker' : 'local';
@@ -68,6 +79,7 @@ export function buildModelEntry(plan, model) {
         contextWindow: model.contextWindow,
         baseURL: `http://127.0.0.1:${plan.port}/v1`,
         apiKeyEnv: apiKeyEnvFor(plan.engineId),
+        apiKey: defaultApiKeyFor(plan.engineId),
     };
     // exactOptionalPropertyTypes: carry the input modalities only when the row
     // names them, so a text-only registration never writes an empty list.
@@ -101,10 +113,10 @@ export function removeModelRow(rows, modelId) {
 }
 /**
  * providerRegistrationOps computes the settings ops that upsert a provider
- * entry: the API-key env name, the openai-completions api, the base URL, and
- * the models list with the entry's row upserted. The ops write the provider
- * fields by path, so a provider the user edited by hand keeps every field
- * the registrar does not own.
+ * entry: the API-key env name, the openai-completions api, the base URL, the
+ * placeholder Authorization header, and the models list with the entry's row
+ * upserted. The ops write the provider fields by path, so a provider the user
+ * edited by hand keeps every field the registrar does not own.
  */
 export function providerRegistrationOps(entry, rows) {
     const providerPath = ['providers', entry.providerId];
@@ -119,10 +131,18 @@ export function providerRegistrationOps(entry, rows) {
     if (entry.input !== undefined) {
         row.input = entry.input;
     }
+    // The pi-ai OpenAI route requires an API key or an Authorization header, so
+    // a keyless local server ships the placeholder key as a Bearer header. The
+    // profile schema has no literal apiKey field; headers carry the value.
     return [
         { op: 'set', path: [...providerPath, 'apiKeyEnv'], value: entry.apiKeyEnv },
         { op: 'set', path: [...providerPath, 'api'], value: 'openai-completions' },
         { op: 'set', path: [...providerPath, 'baseURL'], value: entry.baseURL },
+        {
+            op: 'set',
+            path: [...providerPath, 'headers', 'Authorization'],
+            value: `Bearer ${entry.apiKey}`,
+        },
         { op: 'set', path: [...providerPath, 'models'], value: upsertModelRow(rows, row) },
     ];
 }
@@ -205,4 +225,4 @@ export function agentDefaultPointsAt(value, providerId, modelId) {
     const section = value;
     return section.provider === providerId && section.model === modelId;
 }
-//# sourceMappingURL=registrar.js.map
+//# sourceMappingURL=registrar.js.map

package/packages/core/lib/reserve.d.ts

@@ -25,6 +25,13 @@ export declare function parseNvidiaSmiGpuUsage(output: string): GpuUsageProbe |
 export interface EngineLaunchSignature {
     binary: string;
     port?: number;
+    /**
+     * When false the engine binds its port from a file (Basalt's
+     * basalt_config.json server block), so the matcher never sees the number
+     * in the command line and must skip the port element. Undefined reads as
+     * true: the port must appear as a standalone number, the current rule.
+     */
+    portInArgv?: boolean;
     envKeys?: readonly string[];
 }
 /**
@@ -44,8 +51,9 @@ export interface ProcessLine {
  * signature. The binary marker must appear in the command line (the image
  * name for a docker plan, the engine binary for a local one); a declared port
  * must appear as a standalone number (the `--port N` flag or the docker
- * `-p host:port:port` mapping); a declared env key must be set when the line
- * carries env data, and is neutral when it does not.
+ * `-p host:port:port` mapping) unless `portInArgv` is false, which means the
+ * engine binds its port from a file; a declared env key must be set when the
+ * line carries env data, and is neutral when it does not.
  */
 export declare function matchLaunchSignature(line: ProcessLine, signature: EngineLaunchSignature): boolean;
 /**
@@ -86,4 +94,4 @@ export declare function resolveOsReserve(input: {
     foreignProcess?: boolean;
     gpuUsage?: GpuUsageProbe | null;
 }): ReserveResolution;
-//# sourceMappingURL=reserve.d.ts.map
+//# sourceMappingURL=reserve.d.ts.map