dsh-plugin-local-infer 0.1.2 → 0.1.4

package/packages/providers/lib/adapters.d.ts

@@ -1,38 +1,31 @@
 /**
- * The concrete engine adapters: NInfer (docker and local) and Hyper-Qwen
- * (compose). Each composes the provider `ParameterSpec` data into a
- * `LaunchPlan` and drives its deploy, health-check, and stop steps through an
- * injectable `LifecycleHost`, so the tests stub the host and never run a real
- * build, docker, or network in CI. The node implementation
- * (`nodeLifecycleHost`) is what the service wires in on a live host.
+ * The shared engine-adapter helpers: the spec-to-argv and spec-to-env
+ * translators the concrete adapters (the `engines/<engine>/<engine>Adapter.ts`
+ * files) compose
+ * into a `LaunchPlan`, the card's Custom Arguments translators, the
+ * `LifecycleHost` the deploy, health-check, and stop steps drive, and the
+ * health poll. The node implementation (`nodeLifecycleHost`) is what the
+ * service wires in on a live host.
  * @module dsh-plugin-local-infer/providers/adapters
  */
-import { EngineAdapter } from '../../core/lib/index.js';
-import type { Config, DebugLogger, DeployOptions, DeployResult, EngineLaunchSignature, EnginePlatformConfig, HealthCheckOptions, HealthResult, HardwareProfile, LaunchPlan, LaunchProgress, LifecycleHost, ParameterSpec } from '../../core/lib/index.js';
-export { INFERNIX_MODEL_ARTIFACTS } from './infernix.ts';
+import type { CommandLogger, CommandOutcome, Config, DebugLogger, HealthCheckOptions, HealthResult, LaunchPlan, LifecycleHost, ParameterDeploy, ParameterSpec, ProcessHandle, RunOptions } from '../../core/lib/index.js';
 /**
- * NInferModelArtifact is the per-model deploy data: the `.ninfer` artifact
- * file, the Hugging Face repo the model download pulls it from, and the
- * `--model-id` alias the server advertises. The data is the surface; adding a
- * model is a data edit here, never an adapter rewire.
+ * deployTargets normalizes a spec's `deploy` declaration into a target list: a
+ * single target wraps in a one-element list, a list passes through, and an
+ * absent `deploy` reads as an empty list (the un-migrated fallback). The
+ * spec-to-spelling helpers key off this list, so a multi-target spec
+ * (cli + env, the Strata shared specs) contributes to every matching helper.
  */
-export interface NInferModelArtifact {
-    file: string;
-    repo: string;
-    modelId: string;
-}
-/**
- * The NInfer model artifacts, keyed by the model registry id. The 27B entry
- * is the default the DEFAULT_MODELS list names; the 35B-A3B entries are the
- * Qwen3.8 measured artifact (`qwen3-35b`) and the Qwen3.6 default
- * (`qwen36-35b`).
- */
-export declare const NINFER_MODEL_ARTIFACTS: Record<string, NInferModelArtifact>;
+export declare function deployTargets(spec: ParameterSpec): readonly ParameterDeploy[];
 /**
  * flagsFromSpecs turns a spec surface and a config into the CLI flag list: each
  * spec's `toArgv` runs over the config value (falling back to the spec
  * default), and empty results are skipped. A spec with no `toArgv` contributes
- * nothing.
+ * nothing. A declared `deploy` target gates the spelling: a `cli` target in the
+ * spec's target list (or no target, the un-migrated fallback that reads the
+ * `toArgv` presence) spells CLI flags, so a spec that deploys only to the env
+ * or a config file contributes no flag even when it carries a `toArgv`
+ * spelling.
  */
 export declare function flagsFromSpecs(specs: readonly ParameterSpec[], config: Config): string[];
 /**
@@ -55,20 +48,72 @@ export declare function customArgFlags(config: Config): string[];
 export declare function customArgEnv(config: Config): Record<string, string>;
 /**
  * envFromSpecs turns a spec surface and a config into the environment map: each
- * spec's `toEnv` runs over the config value (falling back to the spec
- * default). A spec with no `toEnv` contributes nothing.
+ * spec's `toEnv` runs over the config value (falling back to the spec default).
+ * A spec with no `toEnv` contributes nothing. A declared `deploy` target gates
+ * the spelling: an `env` target in the spec's target list (or no target, the
+ * un-migrated fallback that reads the `toEnv` presence) spells env vars, so a
+ * spec that deploys only to the CLI or a config file contributes no var even
+ * when it carries a `toEnv` spelling.
  */
 export declare function envFromSpecs(specs: readonly ParameterSpec[], config: Config): Record<string, string>;
+/**
+ * ConfigFileFormat is the on-disk format a `config` deploy target renders to:
+ * JSON (the built-in stringify), a flat `.env` file, or YAML.
+ */
+export type ConfigFileFormat = 'json' | 'yaml' | 'env';
+/**
+ * configFileFromSpecs turns a spec surface and a config into the content of the
+ * config file the deploy step writes: every spec whose target list carries a
+ * `config` target resolves its value (`toConfig(value) ?? value`, falling back
+ * to the spec default) and nests it under that target's `block` / `key` (the
+ * key defaults to the spec key), then the result renders in the requested
+ * format. A spec with no `deploy`, or no `config` target, contributes nothing.
+ *
+ * A `block` ending in `[]` (e.g. `models[]`) follows the array-entry
+ * convention: the key lands inside the single object of a one-element array
+ * named by the prefix, and every spec sharing that block merges into that one
+ * entry. A plain block name nests as before, into one top-level object.
+ *
+ * A spec that carries both a `config` and a `cli` target contributes nothing
+ * here: the launch spells the CLI flag and leaves the on-disk config file (and
+ * any hand edits in it) untouched. Only a spec whose sole deploy path is the
+ * config file writes it.
+ *
+ * The YAML format loads the `yaml` package lazily (a root devDependency, so the
+ * JSON and env paths never touch it at runtime); a missing package throws only
+ * when the YAML format is requested.
+ */
+export declare function configFileFromSpecs(specs: readonly ParameterSpec[], config: Config, format: ConfigFileFormat): string;
+/**
+ * SudoHook is the optional sudo wiring createNodeLifecycleHost takes: `notify`
+ * announces a guarded command the probe found waiting for a password on the
+ * launching CLI (the service's sudo observer turns it into the Logs note), and
+ * `timeoutMs` overrides the 60 s password deadline. A host built without the
+ * hook never probes, announces, or caps a run.
+ */
+export interface SudoHook {
+    notify: (command: string) => void;
+    timeoutMs?: number;
+}
 /**
  * createNodeLifecycleHost builds the node `LifecycleHost`: `run` through the
  * system shell (a 10-minute cap, so a hung CUDA build cannot hang the panel),
- * `spawn` a detached child the stop step can signal, and `fetch` the health
- * URL. A fetch that throws (no route, connection refused) reads as status 0,
+ * `spawn` a detached child the stop step can signal, `writeFile` the config
+ * file the deploy step renders (creating the parent directory), and `fetch`
+ * the health URL. A fetch that throws (no route, connection refused) reads as status 0,
  * which the poll treats as not-ready. When `debug` is provided, the host logs
  * every command it issues (each `run` line and each `spawn` argv) through it,
- * so a DSH debug-mode host captures the full build-to-launch sequence.
- */
-export declare function createNodeLifecycleHost(debug?: DebugLogger): LifecycleHost;
+ * so a DSH debug-mode host captures the full build-to-launch sequence. A
+ * `RunOptions.shell` (the engine OS profile's shell, e.g. pwsh.exe for
+ * the Windows vcpkg route) runs the command line in that shell instead of the
+ * system default. A `RunOptions.graceMs` overrides the 5 s SIGTERM escalation
+ * window of the abort path for that run. The optional `sudo` hook wires the
+ * sudo-prompt rule: a run whose `RunOptions.needsSudo` declares sudo probes
+ * cached credentials first, announces a waiting prompt through the hook once,
+ * and dies at the password deadline with the `sudoFailureDetail` outcome. A
+ * host built without the hook never probes, announces, or caps a run.
+ */
+export declare function createNodeLifecycleHost(debug?: DebugLogger, sudo?: SudoHook): LifecycleHost;
 /**
  * nodeLifecycleHost is the default live host the service wires in: the node
  * implementation with no debug logger, so a normal (non-debug) run logs no
@@ -76,194 +121,83 @@ export declare function createNodeLifecycleHost(debug?: DebugLogger): LifecycleH
  * in debug mode.
  */
 export declare const nodeLifecycleHost: LifecycleHost;
+/**
+ * trackChild stores a spawned handle in the adapter's children map and ties
+ * the entry's lifetime to the child's: when the child ends (a crash, a pkill,
+ * or the adapter's own stop kill) the entry is dropped, so a later stop never
+ * signals a pid a recycled process has taken over. A handle whose host cannot
+ * watch (onExit absent) stays tracked until stop removes it.
+ */
+export declare function trackChild(children: Map<string, ProcessHandle>, key: string, handle: ProcessHandle): void;
+/**
+ * resolveLaunchArgv resolves a plan's launch argv against the engine
+ * directory the spawn runs in: a relative path that carries a separator (a
+ * build-tree binary, the NInfer Windows tree) is joined into an absolute
+ * path, and a bare name (a binary on the path after the rebuild's symlink
+ * step) is left as-is, so the spawn resolves the right command on every
+ * platform.
+ */
+export declare function resolveLaunchArgv(engineDir: string | undefined, argv: readonly string[] | undefined): string[];
+/**
+ * auditRun runs one mutating host command through the run's log sink: the
+ * `$ <command>` line reaches the sink before the child spawns, and the
+ * outcome's success output tail reaches it after the child settles, so the
+ * launch or stop run reads the command ahead of its result (the URL-query
+ * rule applied to execs: line first, settled outcome after). No sink (a
+ * headless call) and the command runs as before. A failed outcome lands no
+ * output here: the caller's own failure line carries the detail's output
+ * tail. The deploy and stop steps share this one audit rule for their direct
+ * `host.run` calls; the git and build steps run through the acquire step's
+ * own command-first echo.
+ */
+export declare function auditRun(host: LifecycleHost, command: string, log?: CommandLogger, options?: RunOptions): Promise<CommandOutcome>;
+/**
+ * stopProcessPlan signals the engine process a stop targets when the adapter
+ * tracks no child handle for it: an engine a DSH restart re-adopted from a
+ * stored launch record carries no in-memory handle, so the stop signals the
+ * pid the record stamped on the plan (kill on Linux and macOS, taskkill on a
+ * Windows plan). The optional `log` is the stop run's log sink: the signal
+ * command's `$ <command>` line reaches it before the child runs. A plan that
+ * names no pid is a no-op (nothing to signal), and a kill the host reports as
+ * failed throws with the host's detail, so the stop route names the broken
+ * step in the card's Logs section.
+ */
+export declare function stopProcessPlan(host: LifecycleHost, plan: LaunchPlan, log?: CommandLogger): Promise<void>;
+/**
+ * The health poll's defaults: the interval between attempts in ms and the
+ * attempt cap. The service passes the config's healthPollMs and
+ * healthMaxAttempts through, and an adapter that polls without options (or
+ * with a partial one) reads these, so the defaults have one home.
+ */
+export declare const HEALTH_POLL_DEFAULT_MS = 1000;
+export declare const HEALTH_POLL_MAX_ATTEMPTS = 120;
+/**
+ * logHealthPoll brackets a health poll with the URL-query logging rule (the
+ * exec rule's URL twin): the one `> GET <url>` line reaches the run's log
+ * sink before the first request, the retries stay silent, and the settled
+ * verdict line (`> GET <url> ready`, Strata's still-downloading line, or the
+ * `!!` failure with the last detail) lands after the poll returns. The
+ * shared poll and the Strata poll both wrap their loop in this, so the rule
+ * has one home. `log` absent (a headless poll) runs the poll unlogged.
+ */
+export declare function logHealthPoll(log: CommandLogger | undefined, url: string, poll: () => Promise<HealthResult>): Promise<HealthResult>;
 /**
  * pollHealth polls a plan's health URL until a 200 or the attempt cap, the
  * same loop the qwen-ninfer launcher runs. A poll interval of 0 skips the
- * delay, which the tests use to run the loop without a real sleep.
- */
-export declare function pollHealth(host: LifecycleHost, plan: LaunchPlan, options?: HealthCheckOptions): Promise<HealthResult>;
-/**
- * The NInfer docker image the adapter pulls and runs. The engineFork platform
- * config overrides the git source for a local build; the image stays the
- * upstream ghcr artifact.
- */
-export declare const NINFER_DOCKER_IMAGE = "ghcr.io/iamwavecut/ninfer-all";
-/**
- * NInferAdapter is the canonical both-capable engine. `renderLaunch` renders a
- * local `ninfer-serve` process or a `docker run` of the ghcr image from the
- * same spec surface; `deploy` builds the engine in the engine directory (or
- * pulls the image), downloads the model into the model directory, and starts
- * the engine; `healthCheck` polls the health URL; `stop` signals the tracked
- * process and stops the named container.
- */
-export declare class NInferAdapter extends EngineAdapter {
-    readonly id = "ninfer";
-    readonly supports: {
-        docker: boolean;
-        local: boolean;
-    };
-    private readonly host;
-    private readonly children;
-    constructor(host?: LifecycleHost);
-    parameters(): readonly ParameterSpec[];
-    modelRef(config: Config): {
-        id: string;
-        name: string;
-    };
-    launchSignature(config?: Config): EngineLaunchSignature;
-    renderLaunch(config: Config, _hw: HardwareProfile): LaunchPlan;
-    deploy(plan: LaunchPlan, platform?: EnginePlatformConfig, onProgress?: LaunchProgress, options?: DeployOptions): Promise<DeployResult>;
-    healthCheck(plan: LaunchPlan, options?: HealthCheckOptions): Promise<HealthResult>;
-    stop(plan: LaunchPlan): Promise<void>;
-    private buildMode;
-    private port;
-    private planKey;
-    private downloadModel;
-    /**
-     * resolveChatTemplate rewrites a --chat-template flag that carries an HF repo
-     * reference into the local file the engine reads. A value with a slash that
-     * is not an absolute path (the combo control's known choices) is a repo the
-     * deploy step downloads into the model directory; an already-local path is
-     * left as-is. The download is best-effort: a template that is already on
-     * disk is used without a re-fetch, and a missing hf CLI leaves the flag
-     * untouched so the engine reports the missing template itself.
-     */
-    private resolveChatTemplate;
-}
-/**
- * HyperQwenAdapter is the docker-compose engine. `renderLaunch` renders a
- * compose plan (the compose file, the profile, and the `.env` the spec surface
- * maps to); `deploy` runs `docker compose up`; `healthCheck` polls the health
- * URL; `stop` runs `docker compose down`.
- */
-export declare class HyperQwenAdapter extends EngineAdapter {
-    readonly id = "hyperqwen";
-    readonly supports: {
-        docker: boolean;
-        local: boolean;
-    };
-    private readonly host;
-    constructor(host?: LifecycleHost);
-    parameters(): readonly ParameterSpec[];
-    modelRef(_config: Config): {
-        id: string;
-        name: string;
-    };
-    launchSignature(config?: Config): EngineLaunchSignature;
-    renderLaunch(config: Config, _hw: HardwareProfile): LaunchPlan;
-    deploy(plan: LaunchPlan, platform?: EnginePlatformConfig, onProgress?: LaunchProgress, _options?: DeployOptions): Promise<DeployResult>;
-    healthCheck(plan: LaunchPlan, options?: HealthCheckOptions): Promise<HealthResult>;
-    stop(plan: LaunchPlan): Promise<void>;
-    private port;
-    private profile;
-}
-/**
- * The llama.cpp docker image the adapter pulls and runs. The engineFork
- * platform config overrides the git source for a local build; the image stays
- * the upstream ggml artifact.
- */
-export declare const LLAMACPP_DOCKER_IMAGE = "ghcr.io/ggml-org/llama.cpp";
-/**
- * LlamaCppAdapter is the llama.cpp engine, both-capable like NInfer.
- * `renderLaunch` renders a local `llama-server` process or a `docker run` of the
- * ggml image from the same `LLAMACPP_PARAMETERS` surface; `deploy` builds the
- * engine in the engine directory (or pulls the image), downloads the GGUF model
- * into the model directory, and starts the engine; `healthCheck` polls the health
- * URL; `stop` signals the tracked process and stops the named container.
- */
-export declare class LlamaCppAdapter extends EngineAdapter {
-    readonly id = "llamacpp";
-    readonly supports: {
-        docker: boolean;
-        local: boolean;
-    };
-    private readonly host;
-    private readonly children;
-    constructor(host?: LifecycleHost);
-    parameters(): readonly ParameterSpec[];
-    modelRef(config: Config): {
-        id: string;
-        name: string;
-    };
-    launchSignature(config?: Config): EngineLaunchSignature;
-    renderLaunch(config: Config, _hw: HardwareProfile): LaunchPlan;
-    deploy(plan: LaunchPlan, platform?: EnginePlatformConfig, onProgress?: LaunchProgress, options?: DeployOptions): Promise<DeployResult>;
-    healthCheck(plan: LaunchPlan, options?: HealthCheckOptions): Promise<HealthResult>;
-    stop(plan: LaunchPlan): Promise<void>;
-    private buildMode;
-    private port;
-    private planKey;
-    private downloadModel;
-}
-/**
- * The Strata docker image the adapter pulls and runs. Strata is the
- * placeholder engine: the image and the parameter data land when the engine
- * is available, and the adapter renders a bare docker plan until then.
- */
-export declare const STRATA_DOCKER_IMAGE = "ghcr.io/strata/strata";
-/**
- * StrataAdapter is the placeholder docker-only engine. `renderLaunch` renders
- * a `docker run` of the Strata image (no spec surface yet, so no flags);
- * `deploy` pulls the image and starts the container; `healthCheck` polls the
- * health URL; `stop` stops the named container. The parameter surface and the
- * per-model data land with the engine, as data edits, never an adapter rewire.
- */
-export declare class StrataAdapter extends EngineAdapter {
-    readonly id = "strata";
-    readonly supports: {
-        docker: boolean;
-        local: boolean;
-    };
-    private readonly host;
-    private readonly children;
-    constructor(host?: LifecycleHost);
-    parameters(): readonly ParameterSpec[];
-    modelRef(_config: Config): {
-        id: string;
-        name: string;
-    };
-    launchSignature(config?: Config): EngineLaunchSignature;
-    renderLaunch(config: Config, _hw: HardwareProfile): LaunchPlan;
-    deploy(plan: LaunchPlan, _platform?: EnginePlatformConfig, onProgress?: LaunchProgress, _options?: DeployOptions): Promise<DeployResult>;
-    healthCheck(plan: LaunchPlan, options?: HealthCheckOptions): Promise<HealthResult>;
-    stop(plan: LaunchPlan): Promise<void>;
-    private port;
-    private planKey;
-}
-/**
- * InfernixAdapter is the local-only engine for Infernix, the C++/CUDA fork
- * of NInfer (https://github.com/wallawalla47/infernix) tuned for Qwen models
- * on a single RTX 50-series GPU. `renderLaunch` renders a local
- * `infernix-serve` process from the `INFERNIX_PARAMETERS` surface (the
- * Infernix-only fields, from `--ngram-volume` to the quality routes, spell
- * onto the argv only for this engine); `deploy` builds the engine in the
- * engine directory (the engine's own cmake preset), downloads the model
- * artifact (and the n-gram volume, for the multi-file Flash-Next repo) into
- * the model directory, and starts the engine; `healthCheck` polls the health
- * URL; `stop` signals the tracked process. The engine ships no docker image,
- * so the adapter supports the local build mode only.
- */
-export declare class InfernixAdapter extends EngineAdapter {
-    readonly id = "infernix";
-    readonly supports: {
-        docker: boolean;
-        local: boolean;
-    };
-    private readonly host;
-    private readonly children;
-    constructor(host?: LifecycleHost);
-    parameters(): readonly ParameterSpec[];
-    modelRef(config: Config): {
-        id: string;
-        name: string;
-    };
-    launchSignature(config?: Config): EngineLaunchSignature;
-    renderLaunch(config: Config, _hw: HardwareProfile): LaunchPlan;
-    deploy(plan: LaunchPlan, platform?: EnginePlatformConfig, onProgress?: LaunchProgress, options?: DeployOptions): Promise<DeployResult>;
-    healthCheck(plan: LaunchPlan, options?: HealthCheckOptions): Promise<HealthResult>;
-    stop(plan: LaunchPlan): Promise<void>;
-    private port;
-    private planKey;
-    private downloadModel;
-}
-//# sourceMappingURL=adapters.d.ts.map
+ * delay, which the tests use to run the loop without a real sleep. `handle`
+ * is the tracked child the deploy step spawned: when it reports it has
+ * exited (hasExited true), the poll ends immediately with a failed result
+ * instead of running the full attempt cap, so a crash reports at once. A
+ * handle that cannot report its exit state (a stub) keeps the full poll.
+ * The poll's URL logging (the one `> GET` line ahead of the settled verdict)
+ * rides the shared logHealthPoll wrap when options.onLog carries the run's
+ * log sink.
+ */
+export declare function pollHealth(host: LifecycleHost, plan: LaunchPlan, options?: HealthCheckOptions, handle?: ProcessHandle): Promise<HealthResult>;
+/**
+ * delay waits `ms` milliseconds. The health polls use it between attempts; a
+ * poll interval of 0 skips the wait, which the tests use to run the loop
+ * without a real sleep.
+ */
+export declare function delay(ms: number): Promise<void>;
+//# sourceMappingURL=adapters.d.ts.map