dsh-plugin-local-infer 0.1.2 → 0.1.4

package/packages/service/lib/index.js

@@ -17,7 +17,7 @@
  * mod-search bridge.
  * @module dsh-plugin-local-infer/service
  */
-import { exec, execFile, spawn } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { availableParallelism, cpus, homedir, platform, release, totalmem } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -25,7 +25,10 @@ import { Service } from '@deepseek-ai/cordis';
 // Relative, not the root package subpath: a self-referencing bare specifier
 // only resolves when the package sits inside a node_modules tree, so a
 // local-path or pnpm-linked install of this repo would fail the import.
-import { AGENT_DEFAULT_MODEL_NAMESPACE, agentDefaultOps, agentDefaultPointsAt, agentDefaultUnsetOps, buildModelEntry, detectHardware as detectHardwareFromProbes, detectPackageManager, evaluateGuidelines, estimateVram, hfChatTemplateCommand, hfDownloadCommand, isGpuBusy, LLM_PI_AI_NAMESPACE, matchLaunchSignature, modelGuidelines, reLinkRecord, computeProviderStatuses, modelRowsFrom, parseNvidiaSmiGpu, parseNvidiaSmiGpuUsage, presetFromFetch, providerRegistrationOps, providerRemovalOps, removeModelRow, renderInstallString, resolveDefaults as resolveDefaultsFromPresets, resolveOsReserve, runInstall, } from '../../core/lib/index.js';
+import { AGENT_DEFAULT_MODEL_NAMESPACE, agentDefaultOps, agentDefaultPointsAt, agentDefaultUnsetOps, buildModelEntry, commandLogLine, detectHardware as detectHardwareFromProbes, detectPackageManager, evaluateGuidelines, estimateVram, guardSudoCommand, hfChatTemplateCommand, hfDatasetsCacheDirectory, hfDownloadCommand, hfHubCacheDirectory, isGpuBusy, LLM_PI_AI_NAMESPACE, matchLaunchSignature, modelGuidelines, reLinkRecord, computeProviderStatuses, modelRowsFrom, parseNvidiaSmiGpu, parseNvidiaSmiGpuUsage, presetFromFetch, providerRegistrationOps, providerRemovalOps, removeModelRow, renderInstallString, resolveDefaults as resolveDefaultsFromPresets, resolveOsReserve, runInstall, SUDO_PROBE_COMMAND, sudoFailureDetail, } from '../../core/lib/index.js';
+import { RunLogStore, runLogKey } from "./run-logs.js";
+import { findLaunchTarget } from "./launch-target.js";
+export { RunLogStore, runLogKey, findLaunchTarget };
 /**
  * Local-inference failure. Extends Error with a stable `code`
  * (`LOCAL_INFER_CONFLICT`, `LOCAL_INFER_INVALID_ENGINE`,
@@ -46,6 +49,13 @@ export class LocalInferError extends Error {
  * "not available" instead.
  */
 const PROBE_TIMEOUT_MS = 5000;
+/**
+ * The page-fetch deadline the modsearch CLI is told to cap itself with (its
+ * --deadline argument, milliseconds as text): the CLI kills its own fetch
+ * past this, so the spawned bridge process returns instead of sitting on an
+ * unreachable URL.
+ */
+const MODSEARCH_DEADLINE_ARG = '60000';
 /**
  * The adopted-process poll interval. A re-adopted engine (a surviving process
  * with no ChildProcess after a DSH restart) is watched for death through a
@@ -77,8 +87,8 @@ export class LocalInfer extends Service {
     // confirm which model a live engine serves: a port the plugin launched reads
     // as that model, a port it did not launch (a foreign engine) has no entry and
     // reads as "engine running, model unknown". The map resets on a host
-    // restart, so a fresh start tracks only the launches it made itself. See
-    // PLAN.md for the PID-cache note: a full PID cache is a future refinement.
+    // restart, so a fresh start tracks only the launches it made itself. A full
+    // PID cache is a future refinement.
     launchedModels = new Map();
     // The live ports tracked per launched engine (launches and adopted re-links
     // both register). The death handler clears the engine's plugin-launched flag
@@ -94,11 +104,37 @@ export class LocalInfer extends Service {
     // handle. A summary re-link that adopts this DSH's own launch record must
     // not stack a poll watcher on top of the handle's close event.
     handledPids = new Set();
+    // The engine keys (engineId:port) whose launch this service is in flight
+    // for: the deploy has started and the health poll has not settled. While a
+    // key is here the provider-status detector keeps the provider's linked read
+    // (running, not unsure), so an engine that sizes its own model (Strata, no
+    // model tie) or a launch mid-poll never flashes the "Unable to link" banner.
+    // The key clears when the launch settles (a healthy poll, a failed deploy).
+    launchingEngines = new Set();
+    // The engine keys (engineId:port) whose stop this service is in flight for:
+    // the stop step signalled the engine and the process has not died yet. While
+    // a key is here the detector keeps the linked read, so a stop never reads as
+    // an unlinked provider for the moment the engine takes to shut down. The key
+    // clears when the process dies (the death observer) or the detector sees the
+    // process down (a stop of an engine it cannot watch).
+    stoppingEngines = new Set();
     // The route-registered hook for engine process deaths (a crash, a pkill, or
     // a poll-detected death of an adopted process). The observer persists the
     // provider entry's cleared state; a headless profile registers none and the
     // service still settles its own live state.
     deathObserver;
+    // The run-registered hooks for sudo commands the guard found waiting for a
+    // password on the CLI, one slot per run key (the runLogKey rule every run
+    // path shares). A guarded command announces through notifySudoNeeded to
+    // every registered observer (one CLI password wait blocks every plugin
+    // run), so concurrent runs keep their own note routing and a settle
+    // clears only its own slot. A headless profile registers none and the
+    // guard still announces internally and caps the wait.
+    sudoObservers = new Map();
+    // The shared per-run live log hub every provider process writes its output
+    // to, keyed by the runLogKey rule so the run paths and the streaming logs
+    // route predict one key per provider.
+    runLogs = new RunLogStore();
     constructor(ctx) {
         super(ctx, 'localInfer');
     }
@@ -352,17 +388,41 @@ export class LocalInfer extends Service {
             const port = signatures[index]?.port;
             return port !== undefined ? { ...provider, port } : provider;
         });
-        return computeProviderStatuses({ providers: priced, running, gpuBusy: isGpuBusy(gpuUsage) });
+        const statuses = computeProviderStatuses({ providers: priced, running, gpuBusy: isGpuBusy(gpuUsage) });
+        // The in-flight launch and stop state machine: a provider the launch or
+        // stop step is in flight for keeps its linked read (running, not unsure)
+        // while the engine process is still up, so neither a stop (the record is
+        // cleared but the process is still shutting down) nor a launch (an engine
+        // that sizes its own model carries no model tie) flashes the "Unable to
+        // link" banner. A stopped provider whose process is down reads as stopped,
+        // and the stopping flag clears with it, so a stop of an engine the service
+        // cannot watch (no death event) never leaves a stale flag behind.
+        for (const provider of priced) {
+            const key = this.engineKey(provider.engine, provider.port);
+            const launching = this.launchingEngines.has(key);
+            const stopping = this.stoppingEngines.has(key);
+            if (!launching && !stopping)
+                continue;
+            if (statuses[provider.id] === 'unsure') {
+                statuses[provider.id] = 'running';
+            }
+            else if (stopping) {
+                this.stoppingEngines.delete(key);
+            }
+        }
+        return statuses;
     }
     /**
-     * unsureBannerKillCommands returns the bash kill commands for the engine
+     * unsureBannerKillCommands returns the stop commands for the engine
      * processes the detector saw holding VRAM, for the "unsure" banner the card
      * shows when no provider is confirmed running but at least one reads as
      * unsure. A process is included when its command line carries an engine
      * binary marker and the card's VRAM usage is above 30% of the total (the
      * threshold below which a foreign engine is not considered to be holding
-     * the card). The commands are one `kill <pid>` per matching process, in
-     * pid order. An empty list means no matching process was seen, so the
+     * the card). The command form switches on the host OS: one
+     * `Stop-Process -Id <pid>` per matching process on Windows (the PowerShell
+     * cmdlet the banner's text area runs), one `kill <pid>` on Linux and macOS,
+     * in pid order. An empty list means no matching process was seen, so the
      * banner's text area renders empty.
      */
     async unsureBannerKillCommands(options) {
@@ -382,10 +442,13 @@ export class LocalInfer extends Service {
             gpuUsage.usedMiB / gpuUsage.totalMiB < 0.3) {
             return [];
         }
+        // The stop command form follows the host OS: Stop-Process on Windows,
+        // kill on Linux and macOS.
+        const isWindows = platform() === 'win32';
         const commands = [];
         for (const line of processes) {
             if (markers.some((marker) => line.command.includes(marker))) {
-                commands.push(`kill ${line.pid}`);
+                commands.push(isWindows ? `Stop-Process -Id ${line.pid}` : `kill ${line.pid}`);
             }
         }
         return commands;
@@ -415,14 +478,27 @@ export class LocalInfer extends Service {
      * deps resolves the host deps an engine's deploy step needs for a build
      * mode. A registered adapter that declares systemDeps wins; the provider-
      * registered plan for the engine id is the fallback, and an engine with
-     * neither plans an empty list (nothing to install, the gate passes).
+     * neither plans an empty list (nothing to install, the gate passes). The
+     * local list is per-OS: a Windows host reads the plan's windows entry (the
+     * winget toolchain the providers sourced from the Windows profile), every
+     * other host reads the linux entry, so the System dependencies section
+     * shows the right toolchain for the host.
      */
     async deps(engineId, buildMode, hw) {
         const adapter = this.engineRegistry.get(engineId);
         if (adapter !== undefined && typeof adapter.systemDeps === 'function') {
             return adapter.systemDeps(buildMode, hw);
         }
-        return this.depPlanRegistry.get(engineId)?.[buildMode] ?? [];
+        const plan = this.depPlanRegistry.get(engineId);
+        if (plan === undefined)
+            return [];
+        if (buildMode === 'local') {
+            // A Windows host reads the windows entry; every other host (linux,
+            // macos) reads the linux entry, which the providers source from the
+            // shared Linux profile.
+            return plan.local?.[hw.os] ?? plan.local?.linux ?? [];
+        }
+        return plan[buildMode] ?? [];
     }
     /**
      * installString renders the copy/paste block for the resolved dep plan,
@@ -435,12 +511,29 @@ export class LocalInfer extends Service {
     }
     /**
      * runInstall is the Play/Run path: it runs the resolved dep plan's commands
-     * through the shell runner and re-probes each dep. The runner captures the
-     * per-command exit, so a failure names the command that broke.
+     * through the guarded shell runner and re-probes each dep. The runner
+     * captures the per-command exit, so a failure names the command that broke,
+     * and a declared-sudo command whose probe finds no cached credentials
+     * announces the CLI prompt through the sudo observer and fails at the
+     * sudo deadline. options.onLog is the install run's log sink: the command
+     * line reaches it as a `$ <command>` line before the guarded runner spawns
+     * the child (and before the sudo guard's probe announces), so the run text
+     * carries the command ahead of the per-dep results. options.runner injects
+     * the command runner so a test reads the command lines without a real shell.
      */
-    async runInstall(engineId, buildMode, hw) {
+    async runInstall(engineId, buildMode, hw, options) {
         const deps = await this.deps(engineId, buildMode, hw);
-        return runInstall(deps, hw, shellRunCommand);
+        // The guarded runner is built per call so every sudo announcement
+        // reaches the observers registered when this call runs.
+        const runner = options?.runner ?? guardedShellRunner((command) => this.notifySudoNeeded(command));
+        // The audit wrapper logs each command the core provisioner actually runs
+        // (a satisfied dep never runs, so it never logs) before delegating to the
+        // runner. Keeping the wrapper here leaves the core provisioner pure.
+        const loggedRunner = (command, runOptions) => {
+            options?.onLog?.(commandLogLine(command));
+            return runner(command, runOptions);
+        };
+        return runInstall(deps, hw, loggedRunner);
     }
     /**
      * launch is the lifecycle entry point: it resolves the adapter that rendered
@@ -465,15 +558,26 @@ export class LocalInfer extends Service {
         // whether the git sync (fetch, rebase, rebuild) runs at all.
         // exactOptionalPropertyTypes: only pass the option object when a key is
         // present.
-        const hasDeployOptions = options?.allowRunDeps !== undefined || options?.autoRebuild !== undefined;
+        const hasDeployOptions = options?.allowRunDeps !== undefined ||
+            options?.autoRebuild !== undefined ||
+            options?.onLog !== undefined;
         const deployOptions = hasDeployOptions
             ? {
                 ...(options?.allowRunDeps !== undefined ? { allowRunDeps: options.allowRunDeps } : {}),
                 ...(options?.autoRebuild !== undefined ? { autoRebuild: options.autoRebuild } : {}),
+                ...(options?.onLog !== undefined ? { onLog: options.onLog } : {}),
             }
             : undefined;
+        // The in-flight launch flag: the provider-status detector keeps this
+        // provider's linked read while the deploy and health poll run, so an engine
+        // that sizes its own model (no model tie) never flashes "Unable to link".
+        const launchKey = this.engineKey(plan.engineId, plan.port);
+        this.launchingEngines.add(launchKey);
         const deployResult = await adapter.deploy(plan, platform, onProgress, deployOptions);
         if (!deployResult.ok) {
+            // A failed deploy settles the launch: clear the in-flight flag so the
+            // provider reads from the process state (stopped), not a stuck launch.
+            this.launchingEngines.delete(launchKey);
             // exactOptionalPropertyTypes: only write the detail key when it is present.
             const result = { plan, healthy: false };
             if (deployResult.detail !== undefined) {
@@ -517,10 +621,20 @@ export class LocalInfer extends Service {
         // "Launching..." while it waits for the engine to report ready.
         onProgress?.('launch');
         const health = await adapter.healthCheck(plan, options);
+        // The launch has settled (a healthy poll, a failed one, or a download that
+        // the card re-polls): clear the in-flight flag so the provider reads from
+        // the model tie (a healthy launch) or the process state (a failed one).
+        this.launchingEngines.delete(launchKey);
         const launchResult = { plan, healthy: health.healthy };
         if (health.detail !== undefined) {
             launchResult.detail = health.detail;
         }
+        // The start phase the poll observed (downloading, starting, ready, failed)
+        // rides the result so the card reads a long model download as in progress
+        // instead of a broken launch.
+        if (health.state !== undefined) {
+            launchResult.state = health.state;
+        }
         // The launch record the route persists for the provider config entry: the
         // engine's pid and the DSH process pid that launched it. The parent pid is
         // only written when the host process identifies as DSH, so a non-DSH host
@@ -611,6 +725,86 @@ export class LocalInfer extends Service {
     setEngineDeathObserver(observer) {
         this.deathObserver = observer;
     }
+    /**
+     * registerSudoObserver reserves `key`'s slot (the runLogKey rule every run
+     * path shares) for one run's hook for commands the sudo guard found
+     * waiting for a password on the launching CLI: the observer lands core's
+     * SUDO_CLI_NOTE line while the command waits. Registering a key that is
+     * taken replaces the old hook (a re-launch under the same key owns the
+     * note), and the disposer removes only its own hook, so a stale run's
+     * settle never clears a live one's routing. The run calls the disposer in
+     * a finally.
+     */
+    registerSudoObserver(key, observer) {
+        this.sudoObservers.set(key, observer);
+        return () => {
+            if (this.sudoObservers.get(key) === observer) {
+                this.sudoObservers.delete(key);
+            }
+        };
+    }
+    /**
+     * notifySudoNeeded announces one guarded command to every registered sudo
+     * observer (the shared CLI password wait can block any run, and the
+     * announce seam does not name the run that triggered it). A throwing
+     * observer is isolated per announce: the note is a log courtesy, and a
+     * broken route must not fail the install that is already racing the sudo
+     * deadline. Published on the service surface so a command runner outside
+     * this package (the providers' lifecycle host) reports through the same
+     * seam.
+     */
+    notifySudoNeeded(command) {
+        for (const observer of [...this.sudoObservers.values()]) {
+            try {
+                observer(command);
+            }
+            catch {
+                // The sudo deadline still settles a passwordless wait.
+            }
+        }
+    }
+    /**
+     * beginRun starts one provider process's live run-log run under the key
+     * runLogKey names: the buffer resets to the seed separator line, the
+     * running flag goes true, the seq restarts, and subscribers get the reset
+     * notice a mid-run attached reader needs to replace its display.
+     */
+    beginRun(key, seed) {
+        this.runLogs.begin(key, seed);
+    }
+    /**
+     * appendRunLog appends one chunk to the key's live log (tail-capped to
+     * LOG_TAIL_BYTES) and notifies subscribers. Appending with no open run
+     * opens one lazily without a seed, so a late note (an engine-death line)
+     * still lands.
+     */
+    appendRunLog(key, text) {
+        this.runLogs.append(key, text);
+    }
+    /**
+     * readRunLog answers the key's catch-up snapshot: the seq reached, the
+     * bounded tail text, and the running flag, the data a mid-run page
+     * refresh or a late-opened Logs pane renders from.
+     */
+    readRunLog(key) {
+        return this.runLogs.read(key);
+    }
+    /**
+     * subscribeRunLog registers a listener for the key's run-log events and
+     * returns the disposer (the route calls it when its stream closes).
+     * Listeners are independent per connection; none can block a writer.
+     */
+    subscribeRunLog(key, listener) {
+        return this.runLogs.subscribe(key, listener);
+    }
+    /**
+     * endRun settles the key's run: the running flag clears and subscribers
+     * get the end event. The text stays readable until the next beginRun, so
+     * a late Logs pane still shows the finished run.
+     */
+    endRun(key) {
+        this.runLogs.end(key);
+    }
     /**
      * watchLaunchedHandle ties a launched child's one-shot exit to the live
      * state: the host's close/error event (a crash, a pkill, or the stop kill)
@@ -671,6 +865,15 @@ export class LocalInfer extends Service {
         timer.unref();
         this.engineWatchers.set(port, { pid: record.pid, timer });
     }
+    /**
+     * engineKey is the in-flight state machine's key for one engine: the engine
+     * id plus its port when the plan names one, so two configs of one engine on
+     * different ports are distinct engines. A plan with no port keys on the
+     * engine id alone.
+     */
+    engineKey(engineId, port) {
+        return port !== undefined ? `${engineId}:${port}` : engineId;
+    }
     /**
      * stopEngineWatcher cancels one port's adopted-process poll, if it has one.
      */
@@ -693,6 +896,10 @@ export class LocalInfer extends Service {
      */
     observeEngineDeath(event) {
         if (event.port !== undefined) {
+            // The process is down: the in-flight stop (if one was in flight) has
+            // settled, so drop the flag and the deferred port-to-model tie the stop
+            // step kept for the provider's linked read.
+            this.stoppingEngines.delete(this.engineKey(event.engineId, event.port));
             const tracked = this.launchedModels.get(event.port);
             if (tracked !== undefined && tracked.engineId === event.engineId) {
                 this.launchedModels.delete(event.port);
@@ -715,19 +922,39 @@ export class LocalInfer extends Service {
     /**
      * stop signals the engine a launch started: it resolves the adapter by the
      * plan's engineId and runs the adapter's stop step (kill the tracked process,
-     * stop the named container, or compose down).
+     * stop the named container, or compose down). The optional `log` is the
+     * stop run's log sink: the adapter writes the `$ <command>` line of every
+     * command it runs (compose down, docker stop, a pid signal) through it
+     * before the child runs, so the stop's live run reads the command first.
      */
-    async stop(plan) {
+    async stop(plan, log) {
         const adapter = this.engineRegistry.get(plan.engineId);
         if (adapter === undefined) {
             throw new LocalInferError(`no engine adapter is registered for "${plan.engineId}"`, 'LOCAL_INFER_INVALID_ENGINE');
         }
-        await adapter.stop(plan);
-        // Clear the port-to-model entry too, so the provider-status detector no
-        // longer ties this port to the model the plugin launched it with, and
-        // cancel any adopted-process watcher standing on the port.
+        // The in-flight stop flag: the provider-status detector keeps this
+        // provider's linked read while the engine shuts down, so a stop never
+        // flashes the "Unable to link" banner for the moment the process takes to
+        // die. The flag clears when the process dies (the death observer) or the
+        // detector sees the process down (a stop of an engine it cannot watch).
+        const stopKey = this.engineKey(plan.engineId, plan.port);
+        this.stoppingEngines.add(stopKey);
+        try {
+            await adapter.stop(plan, log);
+        }
+        catch (error) {
+            // A stop that failed (a kill the host could not deliver) settles the
+            // in-flight state: the flag clears, so the provider reads from the
+            // process state, not a stop stuck in flight.
+            this.stoppingEngines.delete(stopKey);
+            throw error;
+        }
+        // Clear the live-port ledger and the plugin-launched flag, and cancel any
+        // adopted-process watcher standing on the port. The port-to-model tie is
+        // deferred to the death observer, so the provider keeps its linked read
+        // (running, not unsure) for the moment the engine is still shutting down;
+        // the observer drops it the instant the process is down.
         if (plan.port !== undefined) {
-            this.launchedModels.delete(plan.port);
             this.stopEngineWatcher(plan.port);
             const ports = this.launchedPorts.get(plan.engineId);
             if (ports !== undefined) {
@@ -836,7 +1063,10 @@ export class LocalInfer extends Service {
                 preset: undefined,
                 stored: false,
                 degraded: true,
-                detail: `the modsearch fetch failed: ${detail}; the built-in presets apply`,
+                // The URL rides the caller-visible detail: fetchPreset is not a
+                // provider process (no run-log key to write a `> GET` line into), so
+                // the audited rule is served by naming the queried URL here instead.
+                detail: `the modsearch fetch failed for ${source.url}: ${detail}; the built-in presets apply`,
             };
         }
         const preset = presetFromFetch(source, content, todayIso());
@@ -845,13 +1075,26 @@ export class LocalInfer extends Service {
         return { preset, stored: true, degraded: false };
     }
     /**
-     * defaultModelDirectory is the plugin's model download directory: under
-     * the dsh home so a web user and a CLI user share one location, the way the
-     * config file does. The directory is created when absent, so the field's
-     * default is always a real path the deploy step can target.
+     * defaultModelDirectory is the plugin's model download directory: the
+     * Hugging Face hub cache the hf CLI and huggingface_hub share (HF_HUB_CACHE
+     * when set, then $HF_HOME/hub, then ~/.cache/huggingface/hub), so a model
+     * the plugin pulls lands where every other HF tooling looks. The directory
+     * is created when absent, so the field's default is always a real path the
+     * deploy step can target.
      */
     defaultModelDirectory() {
-        const directory = join(homedir(), '.dsh', 'models');
+        const directory = hfHubCacheDirectory();
+        mkdirSync(directory, { recursive: true });
+        return directory;
+    }
+    /**
+     * defaultDatasetDirectory is the plugin's dataset download directory: the
+     * Hugging Face datasets cache (HF_DATASETS_CACHE when set, then
+     * $HF_HOME/datasets, then ~/.cache/huggingface/datasets). Created when
+     * absent, for the same reason the model directory is.
+     */
+    defaultDatasetDirectory() {
+        const directory = hfDatasetsCacheDirectory();
         mkdirSync(directory, { recursive: true });
         return directory;
     }
@@ -864,7 +1107,10 @@ export class LocalInfer extends Service {
         const injected = options?.cliPath;
         if (injected !== undefined && injected.trim() !== '')
             return injected;
-        const which = await runCommand('which', ['hf']);
+        // The presence probe is `which` on Linux/macOS and `where` on Windows, so
+        // an installed hf CLI is found on every host.
+        const probe = platform() === 'win32' ? 'where' : 'which';
+        const which = await runCommand(probe, ['hf']);
         if (which.ok && which.stdout.trim() !== '')
             return which.stdout.trim();
         return null;
@@ -873,7 +1119,10 @@ export class LocalInfer extends Service {
      * downloadModel runs the hf CLI download for one default model into the
      * model directory: it creates the target directory when absent (the
      * recursive flag covers the parents too), renders the command through the
-     * core builder (the single source the card shows), and runs it through the
+     * core builder (the single source the card shows), logs the rendered
+     * command's `$ <command>` line through options.onLog before the runner
+     * spawns the child (so every caller's run reads command first, output
+     * after, and the line is written once, here), and runs it through the
      * injected runner when one is given, so a test captures the command without
      * a live hf. A failure keeps the runner's detail, so the card names the
      * broken step.
@@ -881,7 +1130,9 @@ export class LocalInfer extends Service {
     async downloadModel(entry, directory, options) {
         mkdirSync(directory, { recursive: true });
         const runner = options?.runner ?? downloadRunner;
-        const result = await runner(hfDownloadCommand(entry, directory));
+        const command = hfDownloadCommand(entry, directory, options?.useHubCache === true);
+        options?.onLog?.(commandLogLine(command));
+        const result = await runner(command, options?.signal, options?.onChunk);
         if (result.ok)
             return { ok: true };
         return { ok: false, detail: `model download failed: ${result.detail ?? 'unknown'}` };
@@ -890,13 +1141,16 @@ export class LocalInfer extends Service {
      * downloadChatTemplate pulls the chat template file for one HF repo
      * reference into the model directory, so a selected template (the Froggeric
      * set, a custom repo) works out of the box. It shares the model download's
-     * recursive directory creation, runner, and long timeout: a template is a
-     * small file, but the hf CLI's cold start and auth are the same cost.
+     * recursive directory creation, runner, log line before the spawn, and long
+     * timeout: a template is a small file, but the hf CLI's cold start and auth
+     * are the same cost.
      */
     async downloadChatTemplate(repo, directory, options) {
         mkdirSync(directory, { recursive: true });
         const runner = options?.runner ?? downloadRunner;
-        const result = await runner(hfChatTemplateCommand(repo, directory));
+        const command = hfChatTemplateCommand(repo, directory, options?.useHubCache === true);
+        options?.onLog?.(commandLogLine(command));
+        const result = await runner(command, options?.signal, options?.onChunk);
         if (result.ok)
             return { ok: true };
         return { ok: false, detail: `chat template download failed: ${result.detail ?? 'unknown'}` };
@@ -946,6 +1200,71 @@ export class LocalInfer extends Service {
         }
         return entries;
     }
+    /**
+     * listModelCache lists the hub cache's `models--*` directories, the data the
+     * per-engine model dropdown's cache scan draws from when the model directory
+     * is the plugin default (the hub cache). Each entry carries the repo id the
+     * directory names (the `{namespace}/{name}` decoded from the
+     * `models--{ns}--{name}` form) and the artifact file names its snapshots
+     * hold (the union across every commit). A missing or unreadable cache reads
+     * as an empty list, which the route renders as "no cached models".
+     */
+    listModelCache() {
+        const hub = hfHubCacheDirectory();
+        let dirents;
+        try {
+            dirents = readdirSync(hub, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        const entries = [];
+        for (const dirent of dirents) {
+            if (!dirent.isDirectory() || !dirent.name.startsWith('models--'))
+                continue;
+            // Decode models--{ns}--{name} back to {ns}/{name}: the name is the
+            // segment after the last --, the namespace everything before it.
+            const body = dirent.name.slice('models--'.length);
+            const separator = body.lastIndexOf('--');
+            if (separator <= 0)
+                continue;
+            const repoId = `${body.slice(0, separator)}/${body.slice(separator + 2)}`;
+            entries.push({ repoId, files: this.snapshotFiles(hub, dirent.name) });
+        }
+        return entries;
+    }
+    /**
+     * snapshotFiles unions the file names across every commit directory under a
+     * `models--*` dir's `snapshots/`, the artifact set the per-engine cache scan
+     * filters. A missing snapshots folder reads as an empty set.
+     */
+    snapshotFiles(hub, modelDir) {
+        const snapshots = join(hub, modelDir, 'snapshots');
+        let commits;
+        try {
+            commits = readdirSync(snapshots, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        const files = new Set();
+        for (const commit of commits) {
+            if (!commit.isDirectory())
+                continue;
+            let commitFiles;
+            try {
+                commitFiles = readdirSync(join(snapshots, commit.name), { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const file of commitFiles) {
+                if (file.isFile())
+                    files.add(file.name);
+            }
+        }
+        return [...files];
+    }
     /**
      * specsForEngine reads the parameter surface of the registered adapter for
      * an engine id, so the defaults resolver floors the result on that engine's
@@ -970,7 +1289,9 @@ export class LocalInfer extends Service {
         const env = process.env.MODSEARCH_CLI;
         if (env !== undefined && env.trim() !== '')
             return env;
-        const which = await runCommand('which', ['modsearch']);
+        // The presence probe is `which` on Linux/macOS and `where` on Windows.
+        const probe = platform() === 'win32' ? 'where' : 'which';
+        const which = await runCommand(probe, ['modsearch']);
         if (which.ok && which.stdout.trim() !== '')
             return which.stdout.trim();
         return null;
@@ -983,7 +1304,7 @@ export class LocalInfer extends Service {
      */
     fetchPage(url, cliPath) {
         return new Promise((resolve, reject) => {
-            const child = spawn('node', [cliPath, 'search', '-u', url, '--deadline', '60000'], { stdio: ['ignore', 'pipe', 'pipe'] });
+            const child = spawn('node', [cliPath, 'search', '-u', url, '--deadline', MODSEARCH_DEADLINE_ARG], { stdio: ['ignore', 'pipe', 'pipe'] });
             let stdout = '';
             let stderr = '';
             child.stdout.on('data', (chunk) => {
@@ -1239,36 +1560,132 @@ function runCommand(cmd, args) {
  */
 const INSTALL_OUTPUT_TAIL = 1024;
 /**
- * shellRunCommand is the Play/Run runner: it runs one command line through
- * the system shell and reports the exit. stdin is closed, so a sudo password
- * prompt that cannot read a terminal fails fast instead of hanging the panel;
- * the copy/paste path is the fallback the plan names for exactly this.
+ * The high-water mark the streaming output trims to: the collected output
+ * passes the mark only for a chatty command, and the trim keeps the last
+ * kilobyte the failure detail shows, the same rule the providers' streaming
+ * host applies.
  */
-const shellRunCommand = (command) => new Promise(resolve => {
-    const child = spawn(command, { shell: true, stdio: ['ignore', 'pipe', 'pipe'] });
+const INSTALL_OUTPUT_HIGH_WATER = INSTALL_OUTPUT_TAIL * 2;
+/**
+ * tailOutput keeps a bounded tail of a streamed command's combined output:
+ * append grows the buffer and trims it to the high-water mark, and tail
+ * returns the trimmed last kilobyte a failure detail shows. The install and
+ * download runners share it, so a chatty failure stays readable without
+ * growing the host's memory.
+ */
+function tailOutput() {
     let output = '';
-    const append = (chunk) => {
-        output += chunk.toString('utf8');
-        if (output.length > INSTALL_OUTPUT_TAIL * 2) {
-            output = output.slice(-INSTALL_OUTPUT_TAIL * 2);
-        }
+    return {
+        append: (text) => {
+            output += text;
+            if (output.length > INSTALL_OUTPUT_HIGH_WATER) {
+                output = output.slice(-INSTALL_OUTPUT_HIGH_WATER);
+            }
+        },
+        tail: () => output.trim().slice(-INSTALL_OUTPUT_TAIL),
     };
-    child.stdout.on('data', append);
-    child.stderr.on('data', append);
-    // Without a listener, a child that fails to start (a missing shell) emits
-    // an unlistened 'error' and throws it as an uncaughtException through the
-    // host. Read it as a failed command instead.
-    child.on('error', (error) => {
-        resolve({ ok: false, detail: error.message });
+}
+/**
+ * sudoProbe answers whether sudo already holds cached (or NOPASSWD)
+ * credentials: it runs SUDO_PROBE_COMMAND non-interactively through the
+ * probe timeout and reads a clean exit as "no prompt is coming". A refused
+ * -n, a missing sudo, and a hung probe all read as "a prompt is coming",
+ * the safe side: the run announces and caps instead of dead-locking on a
+ * TTY the card user cannot see.
+ */
+export async function sudoProbe() {
+    const [command, ...args] = SUDO_PROBE_COMMAND;
+    if (command === undefined)
+        return false;
+    const { ok } = await runCommand(command, [...args]);
+    return ok;
+}
+/**
+ * sudoGuardFor is the service-side binding of core's guardSudoCommand: it
+ * supplies sudoProbe, so this package's install runner and the providers'
+ * lifecycle host drive one probe and one rule from one function. Calling
+ * it is itself the sudo declaration (needsSudo is true); callers gate on
+ * their own needsSudo fact first and never run a plain command through it.
+ */
+export function sudoGuardFor(command, notify, kill, timeoutMs) {
+    return guardSudoCommand({
+        needsSudo: true,
+        command,
+        probe: sudoProbe,
+        notify,
+        kill,
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
     });
-    child.on('close', code => {
-        if (code === 0) {
-            resolve({ ok: true });
-            return;
+}
+/**
+ * guardedShellRunner builds the Play/Run runner: it runs one command line
+ * through the system shell and reports the exit. stdin stays closed. When
+ * core hands the command the dep's sudo declaration and sudoProbe finds no
+ * cached credentials, core's guard announces the CLI prompt through notify
+ * and arms the password deadline; its fire signals the child through the
+ * shared signalChild rule (SIGINT, then SIGTERM; the group signal reaches a
+ * sudo survivor of a compound line) and the run settles with
+ * sudoFailureDetail instead of the shell's bare signal exit. The guard adds
+ * only probe, notify, and deadline to the existing spawn; the copy/paste
+ * path stays the fallback for a passwordless host.
+ */
+export function guardedShellRunner(notify) {
+    return async (command, options) => {
+        let child;
+        const guard = options?.needsSudo === true
+            ? await sudoGuardFor(command, notify, () => {
+                if (child !== undefined)
+                    signalChild(child);
+            })
+            : undefined;
+        try {
+            const outcome = await new Promise((resolve) => {
+                // The local keeps the spawn overload's non-null stream typing; the
+                // outer child exists for the guard's kill. The shell spawns detached
+                // so it leads its own process group and signalChild's negative-pid
+                // signal reaches the whole line. libuv's detached spawn only changes
+                // the process group (Node >= 22 ships libuv >= 1.48, which does not
+                // create a session), so a sudo prompt still reaches the launching
+                // terminal and the guard's whole point survives the detach.
+                const started = spawn(command, {
+                    shell: true,
+                    detached: true,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                });
+                child = started;
+                detachedChildren.add(started);
+                const tail = tailOutput();
+                const append = (chunk) => {
+                    tail.append(chunk.toString('utf8'));
+                };
+                started.stdout.on('data', append);
+                started.stderr.on('data', append);
+                // Without a listener, a child that fails to start (a missing shell) emits
+                // an unlistened 'error' and throws it as an uncaughtException through the
+                // host. Read it as a failed command instead.
+                started.on('error', (error) => {
+                    resolve({ ok: false, detail: error.message });
+                });
+                started.on('close', code => {
+                    if (code === 0) {
+                        resolve({ ok: true });
+                        return;
+                    }
+                    resolve({ ok: false, detail: `exit ${code}: ${tail.tail()}` });
+                });
+            });
+            if (guard !== undefined && guard.timedOut() && !outcome.ok) {
+                // The password deadline killed the child: name the missed sudo
+                // prompt instead of the shell's signal exit.
+                return { ok: false, detail: sudoFailureDetail(command) };
+            }
+            return outcome;
         }
-        resolve({ ok: false, detail: `exit ${code}: ${output.trim().slice(-INSTALL_OUTPUT_TAIL)}` });
-    });
-});
+        finally {
+            guard?.disarm();
+        }
+    };
+}
 /**
  * The download timeout. A model download moves tens of GiB, so the cap is
  * hours, not the probe's seconds; a hung download must not kill the panel,
@@ -1276,20 +1693,126 @@ const shellRunCommand = (command) => new Promise(resolve => {
  */
 const DOWNLOAD_TIMEOUT_MS = 7_200_000;
 /**
- * downloadRunner is the model-download runner: it runs the rendered hf CLI
- * command through the system shell and reports the exit. The output tail keeps
- * the last kilobyte, the same rule the install runner uses, so a failure names
- * the broken line.
+ * The cancel grace period in ms: an aborted download gets SIGINT first, and a
+ * child still alive after the grace period gets SIGTERM, so a stuck hf CLI
+ * cannot keep the run open.
  */
-const downloadRunner = (command) => new Promise(resolve => {
-    exec(command, { timeout: DOWNLOAD_TIMEOUT_MS }, (error, stdout, stderr) => {
-        if (error === null) {
+const DOWNLOAD_ABORT_GRACE_MS = 5_000;
+/**
+ * The install shells the guarded runner spawned detached (process-group
+ * leaders). signalProcess reads the set so the negative-pid group signal
+ * only ever targets a child that actually leads its group; a child that
+ * stays in the host's group (the download runner's shell) gets the direct
+ * signal, so a stray negative pid can never fan out beyond the child.
+ */
+const detachedChildren = new WeakSet();
+/**
+ * signalProcess delivers one signal to one child: a process-group leader
+ * gets it through its negative pid, so a compound command line
+ * (`a && sudo b`) dies whole instead of leaving sudo as a group survivor;
+ * every other child gets the direct signal. A group that is already gone
+ * (ESRCH) or a platform that rejects negative pids falls back to the direct
+ * signal, which reaches the shell itself.
+ */
+function signalProcess(child, signal) {
+    if (child.pid !== undefined && detachedChildren.has(child)) {
+        try {
+            process.kill(-child.pid, signal);
+            return;
+        }
+        catch {
+            // Group gone or unsupported: the direct signal below still reaches the
+            // shell, and a child that already exited no-ops the way ChildProcess
+            // .kill always does.
+        }
+    }
+    child.kill(signal);
+}
+/**
+ * signalChild applies the cancel rule: SIGINT first, SIGTERM after the grace
+ * period if the child is still alive. The child already marked killed or
+ * exited is left alone. The optional graceMs overrides the 5 s constant so a
+ * test can exercise the escalation without waiting. The abort watch and the
+ * sudo deadline kill share this one rule, the mirror of the providers'
+ * lifecycle host copy (packages/providers/src/adapters.ts, signalChild):
+ * each package owns its child-process wiring, so a change to the escalation
+ * rule lands in two places by design.
+ */
+function signalChild(child, graceMs) {
+    if (child.killed || child.exitCode !== null)
+        return;
+    signalProcess(child, 'SIGINT');
+    const escalate = setTimeout(() => {
+        // A group signal never marks ChildProcess.kill, so the guard reads the
+        // exit state: a child that has neither exited nor been signalled is
+        // still alive and gets SIGTERM.
+        if (child.exitCode === null && child.signalCode === null)
+            signalProcess(child, 'SIGTERM');
+    }, graceMs ?? DOWNLOAD_ABORT_GRACE_MS);
+    escalate.unref();
+}
+/**
+ * watchChildAbort kills the in-flight child when the signal aborts (the card's
+ * cancel): SIGINT first, SIGTERM after the grace period if the child is still
+ * alive, through the shared signalChild rule. A signal that is already
+ * aborted kills immediately. A near-identical copy lives in the providers
+ * package (packages/providers/src/adapters.ts, the lifecycle host's run and
+ * runStream abort path): each package owns its own child-process wiring, and
+ * the guard fix (the SIGTERM escalation) was applied to both copies, so a
+ * change to the escalation rule lands in two places by design.
+ */
+function watchChildAbort(child, signal, graceMs) {
+    if (signal === undefined)
+        return;
+    const onAbort = () => {
+        signalChild(child, graceMs);
+    };
+    if (signal.aborted) {
+        onAbort();
+        return;
+    }
+    signal.addEventListener('abort', onAbort, { once: true });
+}
+/**
+ * downloadRunner is the model-download runner: it spawns the rendered hf CLI
+ * command through the system shell and reports the exit. The spawned child's
+ * stdout and stderr chunks stream to onChunk as they land (the hf CLI's tqdm
+ * progress), while the output tail keeps the last kilobyte, the same rule the
+ * install runner uses, so a failure names the broken line. An abort on the
+ * optional signal interrupts the in-flight child (SIGINT, then SIGTERM), so a
+ * canceled download stops instead of running to the timeout. The optional
+ * graceMs overrides the 5 s SIGTERM escalation window for the abort path.
+ */
+export const downloadRunner = (command, signal, onChunk, graceMs) => new Promise(resolve => {
+    const child = spawn(command, {
+        shell: true,
+        timeout: DOWNLOAD_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const tail = tailOutput();
+    const append = (chunk) => {
+        const text = chunk.toString('utf8');
+        tail.append(text);
+        onChunk?.(text);
+    };
+    child.stdout.on('data', append);
+    child.stderr.on('data', append);
+    // Without a listener, a child that fails to start (a missing shell) emits
+    // an unlistened 'error' and throws it as an uncaughtException through the
+    // host. Read it as a failed command instead.
+    child.on('error', (error) => {
+        resolve({ ok: false, detail: error.message });
+    });
+    child.on('close', (code, killSignal) => {
+        if (code === 0) {
             resolve({ ok: true });
             return;
         }
-        const detail = `${stderr ?? ''}${stdout ?? ''}`.trim().slice(-INSTALL_OUTPUT_TAIL);
-        resolve({ ok: false, detail: detail === '' ? String(error) : detail });
+        const detail = tail.tail();
+        const label = code !== null ? `exit ${code}` : `killed by ${killSignal ?? 'a signal'}`;
+        resolve({ ok: false, detail: detail === '' ? label : `${label}: ${detail}` });
     });
+    watchChildAbort(child, signal, graceMs);
 });
 /**
  * hasSafetensorsIn reports whether one directory holds a `.safetensors`
@@ -1331,15 +1854,21 @@ async function probeGpuUsage() {
     return result.ok ? parseNvidiaSmiGpuUsage(result.stdout) : null;
 }
 /**
- * probeProcesses reads the running process table (`ps -eo pid,args`) into
- * process lines the launch-signature matcher consumes. The env element of a
- * line is read from the Linux /proc environ, and only for a pid whose command
- * line carries one of the engine markers: a full table of env reads is slow,
- * and the matcher's env-key element only fires on a marker-matched process
- * anyway. A host without /proc (macOS) degrades to env-less lines, which the
- * matcher reads as a neutral env element.
+ * probeProcesses reads the running process table into process lines the
+ * launch-signature matcher consumes. The path switches on the host OS:
+ * Windows reads the table through PowerShell's Win32_Process CIM class (the
+ * pid and the full command line), and Linux and macOS read it through
+ * `ps -eo pid,args`. The env element of a line is read from the Linux /proc
+ * environ, and only for a pid whose command line carries one of the engine
+ * markers: a full table of env reads is slow, and the matcher's env-key
+ * element only fires on a marker-matched process anyway. A host without /proc
+ * (macOS, Windows) degrades to env-less lines, which the matcher reads as a
+ * neutral env element.
  */
 async function probeProcesses(markers) {
+    if (platform() === 'win32') {
+        return probeWindowsProcesses();
+    }
     const result = await runCommand('ps', ['-eo', 'pid,args']);
     if (!result.ok)
         return [];
@@ -1362,6 +1891,51 @@ async function probeProcesses(markers) {
     }
     return lines;
 }
+/**
+ * parseWindowsProcessTable reads the `pid<TAB>commandLine` rows PowerShell's
+ * Win32_Process probe emits into process lines the launch-signature matcher
+ * consumes. Each row is split on its first tab: the pid is the left field, the
+ * command line the right. A row with no tab (a system process with an empty
+ * command line, trimmed to its pid alone) is skipped, and a non-numeric pid is
+ * dropped. The env element stays undefined: Windows has no /proc environ to
+ * read, and the matcher reads a missing env as neutral.
+ */
+export function parseWindowsProcessTable(stdout) {
+    const lines = [];
+    for (const raw of stdout.split('\n')) {
+        const trimmed = raw.trim();
+        if (trimmed === '')
+            continue;
+        const tab = trimmed.indexOf('\t');
+        if (tab <= 0)
+            continue;
+        const pid = Number(trimmed.slice(0, tab));
+        const command = trimmed.slice(tab + 1).trim();
+        if (!Number.isFinite(pid) || command === '')
+            continue;
+        lines.push({ pid, command });
+    }
+    return lines;
+}
+/**
+ * probeWindowsProcesses reads the running process table through PowerShell's
+ * Win32_Process CIM class (the pid and the full command line), the Windows
+ * binding for probeProcesses. The probe emits one `pid<TAB>commandLine` row
+ * per process, which parseWindowsProcessTable turns into lines. A host without
+ * the CIM service (a hung WMI) or a missing powershell degrades to an empty
+ * table, which the detector reads as "no foreign engine" rather than a crash.
+ */
+async function probeWindowsProcesses() {
+    const result = await runCommand('powershell', [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        'Get-CimInstance Win32_Process | ForEach-Object { "{0}`t{1}" -f $_.ProcessId, $_.CommandLine }',
+    ]);
+    if (!result.ok)
+        return [];
+    return parseWindowsProcessTable(result.stdout);
+}
 /**
  * readProcEnviron reads one process's environment out of its /proc environ
  * file (NUL-separated KEY=VALUE entries). Any failure (no /proc, the process
@@ -1445,12 +2019,14 @@ async function probeDocker() {
     return result.ok;
 }
 /**
- * probePackageManager checks which of the four package-manager binaries exist
- * on the host. `which` is a read-only probe, so each answer is a plain
- * presence flag the pure detectPackageManager mapping turns into the winner.
+ * probePackageManager checks whether a package-manager binary exists on the
+ * host. The probe is `which` on Linux and macOS and `where` on Windows (the
+ * OS's own presence probe), so each answer is a plain presence flag the pure
+ * detectPackageManager mapping turns into the winner.
  */
-async function probePackageManager(binary) {
-    const result = await runCommand('which', [binary]);
+async function probePackageManager(binary, os) {
+    const probe = os === 'windows' ? 'where' : 'which';
+    const result = await runCommand(probe, [binary]);
     return result.ok;
 }
 /**
@@ -1467,13 +2043,14 @@ export async function runHardwareProbes() {
         darwin: 'macos',
     };
     const os = osMap[platform()] ?? 'linux';
-    const [gpu, dockerAvailable, apt, dnf, pacman, brew] = await Promise.all([
+    const [gpu, dockerAvailable, apt, dnf, pacman, brew, winget] = await Promise.all([
         probeGpu(),
         probeDocker(),
-        probePackageManager('apt-get'),
-        probePackageManager('dnf'),
-        probePackageManager('pacman'),
-        probePackageManager('brew'),
+        probePackageManager('apt-get', os),
+        probePackageManager('dnf', os),
+        probePackageManager('pacman', os),
+        probePackageManager('brew', os),
+        probePackageManager('winget', os),
     ]);
     return {
         os,
@@ -1482,8 +2059,8 @@ export async function runHardwareProbes() {
         wsl2: os === 'linux' && release().toLowerCase().includes('wsl'),
         hostRamGiB: totalmem() / 2 ** 30,
         gpu,
-        packageManager: detectPackageManager({ os, apt, dnf, pacman, brew }) ?? null,
+        packageManager: detectPackageManager({ os, apt, dnf, pacman, brew, winget }) ?? null,
     };
 }
 export default LocalInfer;
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map