@fusionkit/adapter-ai-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @fusionkit/adapter-ai-sdk — the AI SDK side of Warrant for app-owned loops.
+ *
+ * The application keeps its own `generateText`/`streamText` loop and its own
+ * model; Warrant governs the execution boundary. `remoteTools(...)` returns
+ * AI SDK-compatible tools whose calls run as signed contracts in governed
+ * runner sessions and return with offline-verifiable receipts. The model
+ * surfaces (`withModel`, `routedModel`, `mlxServer`) route the caller's own
+ * loop across local and cloud models with every decision recorded.
+ */
+export { remoteTools } from "./remote-tools.js";
+export type { RemoteToolCallRecord, RemoteTools, RemoteToolsConfig, RemoteToolsContextConfig } from "./remote-tools.js";
+export { swarmTools } from "./swarm-tools.js";
+export type { DispatchInput, DispatchOutput, EscalateInput, EscalateOutput, PullInput, PullOutput, StatusInput, StatusOutput, SwarmPlane, SwarmRunRecord, SwarmTools, SwarmToolsConfig, SwarmToolsContextConfig, SwarmToolSet, WorkerTaskInput } from "./swarm-tools.js";
+export { handoffModel, withModel } from "./model.js";
+export type { EscalationReason, HandoffModelConfig } from "./model.js";
+export { loadRouterCard, routedModel, withRoutedModel } from "./routed-model.js";
+export type { RouteDecision, RoutedModelConfig, RouterCard } from "./routed-model.js";
+export { runWorktreeAgent, worktreeDiff } from "./worktree-agent.js";
+export type { TrajectoryStep, TrajectoryStepType, WorktreeAgentInput, WorktreeAgentResult } from "./worktree-agent.js";
+export { defaultMlxDir, MlxCapabilityError, MlxEnv } from "./mlx-env.js";
+export { managedModelServer, mlxServer } from "./managed-server.js";
+export type { ManagedModelServerOptions, ManagedServerEvent, MlxServerOptions } from "./managed-server.js";

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @fusionkit/adapter-ai-sdk — the AI SDK side of Warrant for app-owned loops.
+ *
+ * The application keeps its own `generateText`/`streamText` loop and its own
+ * model; Warrant governs the execution boundary. `remoteTools(...)` returns
+ * AI SDK-compatible tools whose calls run as signed contracts in governed
+ * runner sessions and return with offline-verifiable receipts. The model
+ * surfaces (`withModel`, `routedModel`, `mlxServer`) route the caller's own
+ * loop across local and cloud models with every decision recorded.
+ */
+export { remoteTools } from "./remote-tools.js";
+export { swarmTools } from "./swarm-tools.js";
+export { handoffModel, withModel } from "./model.js";
+export { loadRouterCard, routedModel, withRoutedModel } from "./routed-model.js";
+export { runWorktreeAgent, worktreeDiff } from "./worktree-agent.js";
+export { defaultMlxDir, MlxCapabilityError, MlxEnv } from "./mlx-env.js";
+export { managedModelServer, mlxServer } from "./managed-server.js";

package/dist/managed-server.d.ts

@@ -0,0 +1,102 @@
+import type { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3GenerateResult, LanguageModelV3StreamResult } from "@ai-sdk/provider";
+import { MlxEnv } from "./mlx-env.js";
+import type { MlxEnvOptions, SpawnSpec } from "./mlx-env.js";
+export type ManagedServerEvent = {
+    type: "starting";
+    port: number;
+} | {
+    type: "ready";
+    baseURL: string;
+    pid: number;
+    startupMs: number;
+} | {
+    type: "stopped";
+    reason: "idle" | "explicit";
+} | {
+    type: "crashed";
+    exitCode: number | null;
+};
+export type ManagedServerStatus = "stopped" | "starting" | "running";
+export type ManagedModelServerOptions = {
+    /** Produce the spawn spec for a given port (env provisioning included). */
+    prepare: (port: number) => Promise<SpawnSpec>;
+    /** Model id requests are made with (and reported as `modelId`). */
+    modelId: string;
+    /** Fixed port; defaults to a free port picked per start. */
+    port?: number;
+    /** Health endpoint polled until the server answers. */
+    healthPath?: string;
+    startupTimeoutMs?: number;
+    /** Idle period after which the process is stopped; 0 disables. */
+    idleShutdownMs?: number;
+    shutdownGraceMs?: number;
+    onEvent?: (event: ManagedServerEvent) => void;
+    /** Whether the OpenAI-compatible endpoint enforces schema response formats. */
+    supportsStructuredOutputs?: boolean;
+    /** Build the inner model once the server is up. */
+    createModel?: (baseURL: string, modelId: string) => LanguageModelV3;
+};
+export declare class ManagedModelServer implements LanguageModelV3 {
+    readonly specificationVersion: "v3";
+    readonly provider = "warrant-managed-server";
+    readonly modelId: string;
+    private readonly options;
+    private state;
+    private child;
+    private inner;
+    private currentBaseURL;
+    private startPromise;
+    private leases;
+    private lastUsedMs;
+    private idleTimer;
+    private outputTail;
+    private stopping;
+    constructor(options: ManagedModelServerOptions);
+    get supportedUrls(): LanguageModelV3["supportedUrls"];
+    status(): ManagedServerStatus;
+    /** The server's base URL while running (changes across restarts). */
+    baseURL(): string | undefined;
+    /** Eagerly start (optional — calls start lazily on their own). */
+    start(): Promise<void>;
+    /** Stop the process and scale to zero. In-flight calls will fail. */
+    stop(): Promise<void>;
+    private ensureStarted;
+    private startProcess;
+    private openLog;
+    private armIdleTimer;
+    private clearRunning;
+    private killChild;
+    private stopProcess;
+    private acquire;
+    private release;
+    private requireInner;
+    doGenerate(options: LanguageModelV3CallOptions): Promise<LanguageModelV3GenerateResult>;
+    doStream(options: LanguageModelV3CallOptions): Promise<LanguageModelV3StreamResult>;
+}
+/** Create a managed local model server from a prepare hook. */
+export declare function managedModelServer(options: ManagedModelServerOptions): ManagedModelServer;
+export type MlxServerOptions = {
+    /** Hugging Face repo id the server loads (e.g. mlx-community/...). */
+    model: string;
+    /** Owned-environment configuration, or a pre-built MlxEnv. */
+    env?: MlxEnvOptions | MlxEnv;
+    /** Extra mlx_lm server flags (e.g. --max-tokens). */
+    extraArgs?: string[];
+    /**
+     * Enable structured decoding (`response_format`, `guided_json`,
+     * `guided_regex`, `guided_choice`): the env installs the velum-labs
+     * mlx-lm fork with its [structured] extra, which is self-contained
+     * (see the fork's STRUCTURED.md). With this set the AI SDK's JSON output
+     * modes (generateObject, responseFormat) are actually enforced by the
+     * server.
+     */
+    structured?: boolean;
+} & Omit<ManagedModelServerOptions, "prepare" | "modelId" | "createModel"> & Pick<Partial<ManagedModelServerOptions>, "createModel">;
+/**
+ * The MLX preset: a managed server whose Python environment is owned by
+ * Warrant (see MlxEnv) and whose process is spawned from that env's own
+ * interpreter. `handle.env` exposes verify/info/destroy for the footprint.
+ */
+export declare function mlxServer(options: MlxServerOptions): ManagedModelServer & {
+    env: MlxEnv;
+};

package/dist/managed-server.js

@@ -0,0 +1,348 @@
+import { spawn } from "node:child_process";
+import { createWriteStream, mkdirSync } from "node:fs";
+import { createServer } from "node:net";
+import { dirname } from "node:path";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { MLX_LM_STRUCTURED_PIN, MlxEnv } from "./mlx-env.js";
+/**
+ * A managed local model server: a LanguageModelV3 whose backing process is
+ * owned by this object. The first generate/stream call starts the server
+ * (prepare → spawn → health), concurrent calls share one process, and an
+ * idle period with no in-flight calls scales it to zero; the next call
+ * transparently restarts it.
+ *
+ * Composes as the `local` leg of handoffModel: a provisioning failure,
+ * cold-start timeout, or crash surfaces as a failed local call, which the
+ * routing layer escalates to cloud.
+ *
+ * This is the app-process, local-first path. Runner/plane-side model-server
+ * pools (governed, receipt-producing model serving) are a separate feature.
+ */
+/** Defaults; every one is overridable per server. */
+const DEFAULT_STARTUP_TIMEOUT_MS = 120_000;
+const DEFAULT_IDLE_SHUTDOWN_MS = 5 * 60 * 1000;
+const DEFAULT_SHUTDOWN_GRACE_MS = 5_000;
+const HEALTH_POLL_MS = 250;
+/** Last bytes of server output kept for diagnostics. */
+const OUTPUT_TAIL_BYTES = 64 * 1024;
+function defaultCreateModel(baseURL, modelId, supportsStructuredOutputs) {
+    return createOpenAICompatible({
+        name: "warrant-managed-server",
+        // The provider appends route paths (e.g. /chat/completions) directly,
+        // so the OpenAI-compatible API prefix belongs on the base URL.
+        baseURL: `${baseURL}/v1`,
+        apiKey: "not-needed",
+        supportsStructuredOutputs
+    })(modelId);
+}
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const probe = createServer();
+        probe.once("error", reject);
+        probe.listen(0, "127.0.0.1", () => {
+            const address = probe.address();
+            const port = typeof address === "object" && address ? address.port : 0;
+            probe.close(() => resolve(port));
+        });
+    });
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class ManagedModelServer {
+    specificationVersion = "v3";
+    provider = "warrant-managed-server";
+    modelId;
+    options;
+    state = "stopped";
+    child;
+    inner;
+    currentBaseURL;
+    startPromise;
+    leases = 0;
+    lastUsedMs = 0;
+    idleTimer;
+    outputTail = "";
+    stopping = false;
+    constructor(options) {
+        this.options = options;
+        this.modelId = options.modelId;
+    }
+    get supportedUrls() {
+        return this.inner?.supportedUrls ?? {};
+    }
+    status() {
+        return this.state;
+    }
+    /** The server's base URL while running (changes across restarts). */
+    baseURL() {
+        return this.currentBaseURL;
+    }
+    /** Eagerly start (optional — calls start lazily on their own). */
+    async start() {
+        await this.ensureStarted();
+    }
+    /** Stop the process and scale to zero. In-flight calls will fail. */
+    async stop() {
+        await this.stopProcess("explicit");
+    }
+    // ---- lifecycle ----
+    ensureStarted() {
+        if (this.state === "running")
+            return Promise.resolve();
+        if (!this.startPromise) {
+            this.startPromise = this.startProcess().finally(() => {
+                this.startPromise = undefined;
+            });
+        }
+        return this.startPromise;
+    }
+    async startProcess() {
+        const startedAt = Date.now();
+        this.state = "starting";
+        try {
+            const port = this.options.port ?? (await freePort());
+            this.options.onEvent?.({ type: "starting", port });
+            const spec = await this.options.prepare(port);
+            this.outputTail = "";
+            const child = spawn(spec.cmd, spec.args, {
+                env: spec.env,
+                ...(spec.cwd ? { cwd: spec.cwd } : {}),
+                stdio: ["ignore", "pipe", "pipe"]
+            });
+            this.child = child;
+            const log = spec.logFile ? this.openLog(spec.logFile) : undefined;
+            const capture = (chunk) => {
+                this.outputTail = (this.outputTail + chunk.toString("utf8")).slice(-OUTPUT_TAIL_BYTES);
+                log?.write(chunk);
+            };
+            child.stdout?.on("data", capture);
+            child.stderr?.on("data", capture);
+            let exited = false;
+            let exitCode = null;
+            child.on("exit", (code) => {
+                exited = true;
+                exitCode = code;
+                log?.end();
+                // A process that dies while we believe it is running is a crash:
+                // reset so the next call respawns instead of hitting a dead URL.
+                if (this.state === "running" && this.child === child && !this.stopping) {
+                    this.clearRunning();
+                    this.options.onEvent?.({ type: "crashed", exitCode: code });
+                }
+            });
+            child.on("error", (error) => {
+                capture(Buffer.from(`spawn error: ${error.message}\n`, "utf8"));
+                exited = true;
+            });
+            const baseURL = `http://127.0.0.1:${port}`;
+            const healthURL = `${baseURL}${this.options.healthPath ?? "/v1/models"}`;
+            const deadline = startedAt + (this.options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS);
+            for (;;) {
+                if (exited) {
+                    throw new Error(`server exited during startup (code ${exitCode}): ${this.outputTail.slice(-2000)}`);
+                }
+                if (Date.now() > deadline) {
+                    throw new Error(`server did not become healthy within ${this.options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS}ms: ${this.outputTail.slice(-2000)}`);
+                }
+                try {
+                    const response = await fetch(healthURL);
+                    await response.arrayBuffer();
+                    if (response.ok)
+                        break;
+                }
+                catch {
+                    // not up yet
+                }
+                await sleep(HEALTH_POLL_MS);
+            }
+            this.currentBaseURL = baseURL;
+            this.inner = this.options.createModel
+                ? this.options.createModel(baseURL, this.options.modelId)
+                : defaultCreateModel(baseURL, this.options.modelId, this.options.supportsStructuredOutputs ?? false);
+            this.state = "running";
+            this.lastUsedMs = Date.now();
+            this.armIdleTimer();
+            this.options.onEvent?.({
+                type: "ready",
+                baseURL,
+                pid: child.pid ?? -1,
+                startupMs: Date.now() - startedAt
+            });
+        }
+        catch (error) {
+            await this.killChild();
+            this.clearRunning();
+            throw error;
+        }
+    }
+    openLog(path) {
+        mkdirSync(dirname(path), { recursive: true });
+        return createWriteStream(path, { flags: "a" });
+    }
+    armIdleTimer() {
+        const idleMs = this.options.idleShutdownMs ?? DEFAULT_IDLE_SHUTDOWN_MS;
+        if (idleMs <= 0)
+            return;
+        const interval = Math.max(25, Math.floor(idleMs / 4));
+        this.idleTimer = setInterval(() => {
+            if (this.state === "running" &&
+                this.leases === 0 &&
+                Date.now() - this.lastUsedMs >= idleMs) {
+                void this.stopProcess("idle");
+            }
+        }, interval);
+        this.idleTimer.unref?.();
+    }
+    clearRunning() {
+        if (this.idleTimer) {
+            clearInterval(this.idleTimer);
+            this.idleTimer = undefined;
+        }
+        this.state = "stopped";
+        this.child = undefined;
+        this.inner = undefined;
+        this.currentBaseURL = undefined;
+    }
+    async killChild() {
+        const child = this.child;
+        if (!child || child.exitCode !== null)
+            return;
+        const graceMs = this.options.shutdownGraceMs ?? DEFAULT_SHUTDOWN_GRACE_MS;
+        const exited = new Promise((resolve) => {
+            child.once("exit", () => resolve());
+        });
+        child.kill("SIGTERM");
+        const timer = setTimeout(() => child.kill("SIGKILL"), graceMs);
+        timer.unref?.();
+        await exited;
+        clearTimeout(timer);
+    }
+    async stopProcess(reason) {
+        if (this.state === "stopped" || this.stopping)
+            return;
+        this.stopping = true;
+        try {
+            await this.killChild();
+            this.clearRunning();
+            this.options.onEvent?.({ type: "stopped", reason });
+        }
+        finally {
+            this.stopping = false;
+        }
+    }
+    // ---- leases ----
+    acquire() {
+        this.leases++;
+        this.lastUsedMs = Date.now();
+    }
+    release() {
+        this.leases = Math.max(0, this.leases - 1);
+        this.lastUsedMs = Date.now();
+    }
+    requireInner() {
+        if (!this.inner) {
+            throw new Error("managed server is not running (it may have crashed)");
+        }
+        return this.inner;
+    }
+    // ---- LanguageModelV3 ----
+    async doGenerate(options) {
+        this.acquire();
+        try {
+            await this.ensureStarted();
+            return await this.requireInner().doGenerate(options);
+        }
+        finally {
+            this.release();
+        }
+    }
+    async doStream(options) {
+        this.acquire();
+        let released = false;
+        const releaseOnce = () => {
+            if (released)
+                return;
+            released = true;
+            this.release();
+        };
+        try {
+            await this.ensureStarted();
+            const result = await this.requireInner().doStream(options);
+            // The lease is held until the stream settles — close, error, or
+            // cancel — so the idle timer can never scale the server to zero
+            // while tokens are still flowing.
+            const reader = result.stream.getReader();
+            const stream = new ReadableStream({
+                pull: async (controller) => {
+                    try {
+                        const { done, value } = await reader.read();
+                        if (done) {
+                            controller.close();
+                            releaseOnce();
+                            return;
+                        }
+                        controller.enqueue(value);
+                    }
+                    catch (error) {
+                        releaseOnce();
+                        controller.error(error);
+                    }
+                },
+                cancel: (cause) => {
+                    releaseOnce();
+                    return reader.cancel(cause);
+                }
+            });
+            return { ...result, stream };
+        }
+        catch (error) {
+            releaseOnce();
+            throw error;
+        }
+    }
+}
+/** Create a managed local model server from a prepare hook. */
+export function managedModelServer(options) {
+    return new ManagedModelServer(options);
+}
+/**
+ * Env options for structured decoding: the self-contained mlx-lm fork as
+ * the main spec. The stock `mlx_lm server` entry point is unchanged; the
+ * hooks activate because the [structured] extra's dependencies import.
+ */
+function structuredEnvOptions() {
+    return {
+        packageSpec: MLX_LM_STRUCTURED_PIN,
+        extraImportNames: ["mlx_lm.structured.integration"]
+    };
+}
+/**
+ * The MLX preset: a managed server whose Python environment is owned by
+ * Warrant (see MlxEnv) and whose process is spawned from that env's own
+ * interpreter. `handle.env` exposes verify/info/destroy for the footprint.
+ */
+export function mlxServer(options) {
+    const { model, env: envOption, extraArgs, structured, ...serverOptions } = options;
+    let env;
+    if (envOption instanceof MlxEnv) {
+        if (structured) {
+            throw new Error("structured cannot be combined with a pre-built MlxEnv: configure " +
+                "extraPackageSpecs/extraImportNames/serverModule on the env instead");
+        }
+        env = envOption;
+    }
+    else {
+        // Structured mode supplies defaults; explicit env options win (e.g. a
+        // custom packageSpec pointing at another fork revision).
+        env = new MlxEnv({
+            ...(structured ? structuredEnvOptions() : {}),
+            ...(envOption ?? {})
+        });
+    }
+    const server = new ManagedModelServer({
+        ...serverOptions,
+        modelId: model,
+        prepare: (port) => env.prepare(model, port, extraArgs ?? []),
+        supportsStructuredOutputs: structured === true || serverOptions.supportsStructuredOutputs === true
+    });
+    return Object.assign(server, { env });
+}

package/dist/mlx-env.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Warrant-owned MLX environment.
+ *
+ * The managed MLX backend does not shell out to whatever `mlx_lm.server`
+ * happens to be on PATH — it owns the entire stack. This provisioner
+ * materializes and maintains a dedicated directory containing:
+ *
+ *   <dir>/venv/      a private Python venv with mlx-lm at an exact pin
+ *   <dir>/env.json   a manifest of what was provisioned (and from where)
+ *   <dir>/hf-cache/  HF_HOME, so model weights live inside the owned dir
+ *   <dir>/logs/      server stdout/stderr
+ *
+ * The whole footprint is one directory: inspectable (info), verifiable
+ * (verify), repairable (re-provision on pin mismatch), and removable
+ * (destroy). The server process is always spawned via the venv's own
+ * interpreter — never a PATH lookup.
+ *
+ * The mlx-lm pin follows the same trusted-pin policy as the repo's npm
+ * allowlist: exact version, bumped only as a reviewed code change.
+ *
+ * Toolchain: provisioning prefers `uv` when available (an explicit path,
+ * WARRANT_UV, or PATH discovery) — it is much faster and can supply its own
+ * managed CPython, removing even the system-python requirement. Without uv
+ * it falls back to stdlib `python3 -m venv` + pip, so uv is an upgrade,
+ * never a dependency. uv's caches and managed interpreters are contained
+ * inside the owned directory, so destroy() removes them too.
+ */
+/** Exact-pinned mlx-lm version this provisioner installs. */
+export declare const MLX_LM_PIN = "0.31.3";
+/**
+ * The velum-labs/mlx-lm fork installed in structured mode: upstream mlx-lm
+ * plus the self-contained mlx_lm.structured package (see the fork's
+ * STRUCTURED.md). Pinned to the current reviewed head of the fork's main
+ * branch; refresh this SHA when we intentionally pick up fork fixes.
+ */
+export declare const MLX_LM_STRUCTURED_PIN = "mlx-lm[structured] @ git+https://github.com/velum-labs/mlx-lm@2ee2d570d365a1fcee9ba90a298f1bae865fccda";
+/** Python version requested from uv (which can download it if absent). */
+export declare const PYTHON_PIN = "3.12";
+/** Default owned directory for the MLX stack. */
+export declare function defaultMlxDir(): string;
+export type MlxEnvManifest = {
+    version: "warrant.mlxenv.v1";
+    /** What was installed (e.g. "mlx-lm==0.31.3"). */
+    packageSpec: string;
+    /** Additional specs installed after the main one (e.g. the structured
+     * decoding overlay). Absent in manifests written before this field
+     * existed, which reads as []. */
+    extraPackageSpecs?: string[];
+    /** Module whose import proves the install is usable. */
+    importName: string;
+    /** What built the env: "uv <version>" or "venv+pip via <interpreter>". */
+    toolchain: string;
+    /** The venv interpreter every spawn uses. */
+    interpreterPath: string;
+    pythonVersion: string;
+    createdAt: string;
+};
+/** Everything the process layer needs to spawn the server. */
+export type SpawnSpec = {
+    cmd: string;
+    args: string[];
+    env: Record<string, string>;
+    cwd?: string;
+    /** Append server output here (inside the owned dir). */
+    logFile?: string;
+};
+/** A capability the current host cannot satisfy (wrong OS, no Python). */
+export declare class MlxCapabilityError extends Error {
+    readonly code: "capability_mismatch";
+    constructor(message: string);
+}
+export type MlxEnvOptions = {
+    /** Owned directory. Defaults to ~/.warrant/mlx. */
+    dir?: string;
+    /** Requirement to install. Defaults to the MLX_LM_PIN pin. */
+    packageSpec?: string;
+    /**
+     * Additional requirements installed after the main spec — pinned PyPI
+     * specs or local package directories (e.g. the structured decoding
+     * overlay). Part of the manifest: changing them re-provisions.
+     */
+    extraPackageSpecs?: string[];
+    /** Import that must succeed after install. Defaults to "mlx_lm". */
+    importName?: string;
+    /** Additional imports that must succeed (one per extra package). */
+    extraImportNames?: string[];
+    /**
+     * Python module spawned by prepare(). Defaults to the stock
+     * `mlx_lm server`; the structured overlay uses STRUCTURED_SERVER_MODULE.
+     */
+    serverModule?: string;
+    /**
+     * Explicit base interpreter. Setting this forces the stdlib venv+pip
+     * toolchain with exactly that interpreter (an escape hatch from uv).
+     */
+    python?: string;
+    /**
+     * uv binary to provision with, or `false` to disable uv entirely.
+     * Default: WARRANT_UV if set, otherwise "uv" discovered on PATH,
+     * otherwise the stdlib venv+pip fallback.
+     */
+    uv?: string | false;
+    /** Python version requested from uv. Defaults to PYTHON_PIN. */
+    pythonVersion?: string;
+    /**
+     * Enforce the MLX platform gate (macOS on Apple Silicon). Defaults to
+     * true; tests provisioning stub packages on other hosts disable it.
+     */
+    requirePlatform?: boolean;
+    /**
+     * Override the install step (default: install <packageSpec> plus any
+     * <extraPackageSpecs> into the venv with the resolved toolchain). Tests
+     * inject an offline installer.
+     */
+    install?: (venvPython: string, packageSpec: string, extraPackageSpecs: string[]) => void;
+};
+export declare class MlxEnv {
+    readonly dir: string;
+    private readonly packageSpec;
+    private readonly extraPackageSpecs;
+    private readonly importName;
+    private readonly extraImportNames;
+    private readonly serverModule;
+    private readonly requirePlatform;
+    private readonly explicitPython;
+    private readonly uvOption;
+    private readonly pythonVersion;
+    private readonly installHook;
+    private provisionPromise;
+    constructor(options?: MlxEnvOptions);
+    get manifestPath(): string;
+    get venvDir(): string;
+    get venvPython(): string;
+    get hfCacheDir(): string;
+    get logsDir(): string;
+    /** uv's caches and managed interpreters, contained in the owned dir. */
+    private get uvEnv();
+    private readManifest;
+    private assertPlatform;
+    /**
+     * Pick the provisioning toolchain. An explicit `python` option forces
+     * stdlib venv+pip with that interpreter; otherwise uv is preferred
+     * (explicit path, WARRANT_UV, or PATH discovery) with venv+pip as the
+     * no-extra-requirements fallback.
+     */
+    private resolveToolchain;
+    /** Sanity-check a base interpreter for the stdlib venv+pip path. */
+    private checkPython;
+    /** Does the venv interpreter exist and import the managed packages? */
+    private importWorks;
+    private extrasMatch;
+    /** Manifest matches the current pins and the env actually works. */
+    verify(): boolean;
+    /** Manifest plus on-disk footprint of the owned directory. */
+    info(): {
+        dir: string;
+        provisioned: boolean;
+        manifest?: MlxEnvManifest;
+        diskBytes: number;
+    };
+    /** Remove the entire owned footprint: venv, manifest, weights, logs. */
+    destroy(): void;
+    /**
+     * Idempotently provision the env. A matching manifest plus a passing
+     * import check is a no-op; anything else (fresh host, pin bump, broken
+     * venv) provisions in place. Concurrent callers share one provision run.
+     */
+    ensureProvisioned(): Promise<MlxEnvManifest>;
+    private provision;
+    private createVenv;
+    private installPackages;
+    /**
+     * Provision (if needed) and produce the spawn spec for the server:
+     * the venv's interpreter running `-m mlx_lm server` with a minimal,
+     * explicit environment whose caches live inside the owned dir.
+     */
+    prepare(model: string, port: number, extraArgs?: string[]): Promise<SpawnSpec>;
+}