@bendyline/gezel-inference 0.0.0-stage → 0.1.0

package/dist/providers/types.js

@@ -0,0 +1,42 @@
+/**
+ * Thrown by `LLMProvider.resumeSession` when the underlying provider can't
+ * restore the given session (Copilot session expired, etc.). Caller should
+ * fall back to a fresh `createSession` and surface a warning.
+ */
+export class SessionResumeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SessionResumeError';
+    }
+}
+/**
+ * Thrown by a provider's `createSession` (or first `sendAndWait`) when
+ * `externalTools` was set on the session opts but the provider doesn't
+ * yet implement external tool calling. The route maps this to
+ * `400 tools_not_supported_for_provider` so the caller knows the
+ * gezel's backend can't honor the request and what to do (pick a
+ * different provider, or omit `tools`).
+ */
+export class ExternalToolsUnsupportedError extends Error {
+    constructor(providerName) {
+        super(`Provider "${providerName}" does not support external tool calling.`);
+        this.name = 'ExternalToolsUnsupportedError';
+    }
+}
+/**
+ * Thrown when a request names a local-engine model id that isn't
+ * installed on this machine. Routes map it to `404 model_not_found`.
+ * Deliberately NOT auto-resolved by downloading: a chat request must
+ * never trigger a multi-GB pull — the job-based `POST /v1/models/ensure`
+ * endpoint exists for explicit, consented installs.
+ */
+export class ModelNotInstalledError extends Error {
+    providerName;
+    modelId;
+    constructor(providerName, modelId) {
+        super(`Model "${modelId}" is not available locally for provider "${providerName}". List local models via GET /v1/models, or download it first via POST /v1/models/ensure.`);
+        this.name = 'ModelNotInstalledError';
+        this.providerName = providerName;
+        this.modelId = modelId;
+    }
+}

package/dist/providers/usage-builder.d.ts

@@ -0,0 +1 @@
+export * from '@bendyline/gezel/local-loop';

package/dist/providers/usage-builder.js

@@ -0,0 +1,2 @@
+// Moved to core so the portable runtime runs the same loop; see core/src/local-loop.
+export * from '@bendyline/gezel/local-loop';

package/dist/providers/vision-capability.d.ts

@@ -0,0 +1,109 @@
+import type { ProviderName } from '@bendyline/gezel';
+/**
+ * Can this model actually see the image the user just pasted, and if not, what
+ * should we do about it?
+ *
+ * This is the first real capability gate in the codebase. Before it existed,
+ * `send()` hydrated every embedded image to base64 and shipped it to whatever
+ * provider was active — so a screenshot pasted at ds4 became megabytes of
+ * payload that ds4-server discards, followed by a confident answer about an
+ * image the model never saw.
+ *
+ * Split deliberately into two pure functions:
+ *
+ *   - {@link resolveVisionCapability} — capability only. "Can it see?"
+ *   - {@link applyRecognitionPolicy}  — policy only. "Given that, what do we do?"
+ *
+ * Keeping them apart means ~40 combinations are exhaustively table-testable
+ * without constructing a config for each, and the reason strings stay honest
+ * about which layer made the call.
+ */
+/**
+ * How a turn's images should be delivered.
+ *
+ *   - `native`        — the model reads pixels. Ship the bytes, inject nothing.
+ *   - `preprocess`    — describe locally, inject text, and do NOT ship bytes.
+ *   - `unavailable`   — nobody can see it. Static metadata plus an honest note.
+ */
+export type VisionVerdict = 'native' | 'preprocess' | 'unavailable';
+export interface VisionPlan {
+    verdict: VisionVerdict;
+    /** Human-readable justification, surfaced in logs and session telemetry. */
+    reason: string;
+}
+/**
+ * MLX vision uses the complete installed vision tower and a separate uncached
+ * serial path. The bound session, rather than a catalog tag, must confirm it;
+ * the engine may still be text-only until the first image arrives.
+ */
+export declare const MLX_VISION_SUPPORTED = true;
+export interface VisionCapabilityInput {
+    provider: ProviderName;
+    modelId?: string;
+    /**
+     * Resolved projector path for the *installed* model, i.e. exactly what
+     * decides whether `--mmproj` reaches the llama-server command line.
+     *
+     * This is authoritative and catalog tags are not: 16 gilde chat models carry
+     * a `vision`/`multimodal` tag while only a couple ship a projector, so the
+     * majority install text-only. A model whose server was launched without
+     * `--mmproj` is blind no matter what its weights could do.
+     */
+    mmprojPath?: string;
+    /** Resolved ds4 encoder path that decides whether launch receives `--vision`. */
+    visionEncoderPath?: string;
+    /** Whether the user opted this model into native vision. */
+    nativeVisionEnabled?: boolean;
+    mlxVisionAvailable?: boolean;
+}
+/**
+ * Whether native vision is on for `modelId`, given `config.nativeVision`.
+ *
+ * **Absent means ON.** The projector is downloaded with the model, memory
+ * planning already prices it in, and a model that ships one can see — so
+ * having to discover a hidden switch before your screenshot works was the
+ * wrong default. `false` is an explicit opt-OUT, and it buys something
+ * concrete: the projector's bytes leave the memory budget, which on a tight
+ * card is more context (see `mmprojBudgetBytes`).
+ *
+ * Every reader of `config.nativeVision` must go through here or through
+ * {@link nativeVisionPreferenceFor}. Three call sites already decide this —
+ * the engine launch, the per-turn image plan, and the model list the UI
+ * renders — and a default that lives in three expressions is a default that
+ * will disagree with itself.
+ *
+ * MLX is the exception to "absent means ON": its vision tower slows every
+ * text turn, so an unset preference there means "load it when an image
+ * arrives" (see `mlx/vision-mode.ts`), and only an explicit `true` keeps it
+ * loaded.
+ */
+export declare function nativeVisionEnabledFor(nativeVision: Record<string, boolean> | undefined, modelId: string | undefined): boolean;
+/** The explicit per-model choice in `config.nativeVision`, or `default` when there is none. */
+export type NativeVisionPreference = 'on' | 'off' | 'default';
+export declare function nativeVisionPreferenceFor(nativeVision: Record<string, boolean> | undefined, modelId: string | undefined): NativeVisionPreference;
+/**
+ * Projector bytes to charge against the memory budget.
+ *
+ * Zero when vision is off, because the launch then omits `--mmproj` and the
+ * weights genuinely are not resident. Reserving for a file we chose not to
+ * load would silently shrink the context window the user could otherwise
+ * have had — which is exactly the trade someone turns vision off to make.
+ */
+export declare function mmprojBudgetBytes(mmprojSizeBytes: number | undefined, visionEnabled: boolean): number;
+export declare function resolveVisionCapability(input: VisionCapabilityInput): {
+    native: boolean;
+    reason: string;
+};
+export type RecognitionMode = 'auto' | 'always' | 'off';
+export interface RecognitionPolicy {
+    /** Effective mode after the per-gezel override has been layered on config. */
+    mode: RecognitionMode;
+    /** Whether a recognition model is installed and its engine is usable. */
+    recognitionAvailable: boolean;
+}
+export declare function applyRecognitionPolicy(capability: {
+    native: boolean;
+    reason: string;
+}, policy: RecognitionPolicy): VisionPlan;
+/** Convenience for the chat path, which always has both halves to hand. */
+export declare function resolveImageStrategy(input: VisionCapabilityInput, policy: RecognitionPolicy): VisionPlan;

package/dist/providers/vision-capability.js

@@ -0,0 +1,137 @@
+/**
+ * Per-provider vision support.
+ *
+ * A total `Record` rather than a `switch` on purpose: adding an arm to
+ * `ProviderNameSchema` fails typecheck here until someone classifies it, so a
+ * new provider can never silently inherit "assume it can see" and start
+ * dropping user images on the floor. Same trick as `ENGINE_ENV_VAR` in
+ * `engines/resolver.ts`.
+ */
+const VISION_NATIVE = {
+    copilot: 'always',
+    openai: 'always',
+    anthropic: 'always',
+    // Both drive a CLI over stdin/stdout with no attachment channel of their own.
+    'anthropic-cli': 'never',
+    'codex-cli': 'never',
+    /**
+     * Shape is right on the wire, but there's no reliable per-tag capability
+     * signal without an extra `/api/show` round-trip. Conservative until there
+     * is; cheap to flip.
+     */
+    ollama: 'never',
+    'llama-cpp': 'per-model',
+    'apple-foundation-models': 'never',
+    'android-mlkit': 'never',
+    mlx: 'per-model',
+    /**
+     * ds4 accepts OpenAI image content only when its model-matched encoder was
+     * installed and the supervised server was launched with `--vision`.
+     */
+    ds4: 'per-model',
+    /** The far side's capability is unknown, and text is cheaper to relay. */
+    remote: 'never',
+};
+/**
+ * MLX vision uses the complete installed vision tower and a separate uncached
+ * serial path. The bound session, rather than a catalog tag, must confirm it;
+ * the engine may still be text-only until the first image arrives.
+ */
+export const MLX_VISION_SUPPORTED = true;
+/**
+ * Whether native vision is on for `modelId`, given `config.nativeVision`.
+ *
+ * **Absent means ON.** The projector is downloaded with the model, memory
+ * planning already prices it in, and a model that ships one can see — so
+ * having to discover a hidden switch before your screenshot works was the
+ * wrong default. `false` is an explicit opt-OUT, and it buys something
+ * concrete: the projector's bytes leave the memory budget, which on a tight
+ * card is more context (see `mmprojBudgetBytes`).
+ *
+ * Every reader of `config.nativeVision` must go through here or through
+ * {@link nativeVisionPreferenceFor}. Three call sites already decide this —
+ * the engine launch, the per-turn image plan, and the model list the UI
+ * renders — and a default that lives in three expressions is a default that
+ * will disagree with itself.
+ *
+ * MLX is the exception to "absent means ON": its vision tower slows every
+ * text turn, so an unset preference there means "load it when an image
+ * arrives" (see `mlx/vision-mode.ts`), and only an explicit `true` keeps it
+ * loaded.
+ */
+export function nativeVisionEnabledFor(nativeVision, modelId) {
+    if (!modelId)
+        return false;
+    return nativeVisionPreferenceFor(nativeVision, modelId) !== 'off';
+}
+export function nativeVisionPreferenceFor(nativeVision, modelId) {
+    const choice = modelId ? nativeVision?.[modelId] : undefined;
+    return choice === true ? 'on' : choice === false ? 'off' : 'default';
+}
+/**
+ * Projector bytes to charge against the memory budget.
+ *
+ * Zero when vision is off, because the launch then omits `--mmproj` and the
+ * weights genuinely are not resident. Reserving for a file we chose not to
+ * load would silently shrink the context window the user could otherwise
+ * have had — which is exactly the trade someone turns vision off to make.
+ */
+export function mmprojBudgetBytes(mmprojSizeBytes, visionEnabled) {
+    return visionEnabled ? (mmprojSizeBytes ?? 0) : 0;
+}
+export function resolveVisionCapability(input) {
+    const mode = VISION_NATIVE[input.provider];
+    if (mode === 'always')
+        return { native: true, reason: `${input.provider} accepts images` };
+    if (mode === 'never')
+        return { native: false, reason: `${input.provider} cannot accept images` };
+    if (input.provider === 'mlx') {
+        return input.mlxVisionAvailable && input.nativeVisionEnabled
+            ? { native: true, reason: 'the bound MLX engine loads its vision tower for images' }
+            : { native: false, reason: 'the bound MLX engine has no enabled vision tower' };
+    }
+    const visionSidecarPath = input.provider === 'ds4' ? input.visionEncoderPath : input.mmprojPath;
+    if (!visionSidecarPath) {
+        return {
+            native: false,
+            reason: input.modelId
+                ? `${input.modelId} is installed without a ${input.provider === 'ds4' ? 'vision encoder' : 'vision projector'}`
+                : `no ${input.provider === 'ds4' ? 'vision encoder' : 'vision projector'} is installed for this model`,
+        };
+    }
+    if (!input.nativeVisionEnabled) {
+        return {
+            native: false,
+            reason: 'native image support is off for this model',
+        };
+    }
+    return {
+        native: true,
+        reason: `${input.modelId ?? 'this model'} runs with a ${input.provider === 'ds4' ? 'vision encoder' : 'vision projector'}`,
+    };
+}
+export function applyRecognitionPolicy(capability, policy) {
+    // An explicit `always` outranks native support — that's the whole point of
+    // the lever. A local pass costs a few seconds and keeps pixels on the
+    // machine; a frontier model's vision tokens cost money on every turn.
+    if (policy.mode === 'always' && policy.recognitionAvailable) {
+        return { verdict: 'preprocess', reason: 'local image scanning is set to always' };
+    }
+    if (capability.native) {
+        return { verdict: 'native', reason: capability.reason };
+    }
+    if (policy.mode === 'off') {
+        return { verdict: 'unavailable', reason: `${capability.reason}; local scanning is off` };
+    }
+    if (policy.recognitionAvailable) {
+        return { verdict: 'preprocess', reason: capability.reason };
+    }
+    return {
+        verdict: 'unavailable',
+        reason: `${capability.reason}, and no local image reader is installed`,
+    };
+}
+/** Convenience for the chat path, which always has both halves to hand. */
+export function resolveImageStrategy(input, policy) {
+    return applyRecognitionPolicy(resolveVisionCapability(input), policy);
+}

package/dist/python/mlx-runtime-status-bus.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Lifecycle of the lazy `mlx` Python venv that backs the MLX chat provider.
+ *
+ *   - `idle`: nothing happening yet — either MLX has never been picked,
+ *     or the venv exists and no work is in flight.
+ *   - `provisioning`: a chat turn just hit `buildMlxProvider`, the venv
+ *     was missing or stale, and `uvRuntime.ensureVenv(...)` is currently
+ *     running (uv resolving + downloading torch / mlx-vlm wheels).
+ *     First-install on a clean machine takes 1–5 minutes; the user sees
+ *     no chat output until this finishes.
+ *   - `ready`: the venv is provisioned and the provider is usable.
+ *   - `error`: the last `ensureVenv` attempt threw; chat will keep
+ *     surfacing the same actionable error until it succeeds.
+ *
+ * Surfaced as a single header pill in the UI so users get a visible
+ * "MLX is still warming up" signal instead of staring at a hung chat.
+ */
+export type MlxRuntimePhase = 'idle' | 'provisioning' | 'ready' | 'error';
+export interface MlxRuntimeStatus {
+    phase: MlxRuntimePhase;
+    /** Optional human-readable message for the pill / tooltip. */
+    message?: string;
+    /** Populated when `phase === 'error'`. */
+    error?: string;
+    /** ISO timestamp of the latest transition. */
+    updatedAt: string;
+}
+/**
+ * Tiny pub-sub for the MLX venv lifecycle. Same shape as
+ * `SystemStatusBus` so the SSE endpoint and client can mirror that
+ * pattern. Subscribers receive the current state on subscription.
+ */
+export declare class MlxRuntimeStatusBus {
+    private readonly emitter;
+    private state;
+    get current(): MlxRuntimeStatus;
+    publish(next: Omit<MlxRuntimeStatus, 'updatedAt'>): void;
+    subscribe(listener: (status: MlxRuntimeStatus) => void): () => void;
+}

package/dist/python/mlx-runtime-status-bus.js

@@ -0,0 +1,27 @@
+import { EventEmitter } from 'node:events';
+/**
+ * Tiny pub-sub for the MLX venv lifecycle. Same shape as
+ * `SystemStatusBus` so the SSE endpoint and client can mirror that
+ * pattern. Subscribers receive the current state on subscription.
+ */
+export class MlxRuntimeStatusBus {
+    emitter = new EventEmitter();
+    state = {
+        phase: 'idle',
+        updatedAt: new Date().toISOString(),
+    };
+    get current() {
+        return this.state;
+    }
+    publish(next) {
+        this.state = { ...next, updatedAt: new Date().toISOString() };
+        this.emitter.emit('status', this.state);
+    }
+    subscribe(listener) {
+        listener(this.state);
+        this.emitter.on('status', listener);
+        return () => {
+            this.emitter.off('status', listener);
+        };
+    }
+}

package/dist/python/uv-runtime.d.ts

@@ -0,0 +1,176 @@
+/**
+ * UvRuntime — provisions Python virtualenvs for Gezel features that
+ * need to run Python tools (MLX, future Whisper / STT engines, etc.).
+ *
+ * Detection order on first `ensureVenv`:
+ *
+ *   1. **Bundled uv** at `process.env.GEZEL_UV_BIN` — packaged Gezel
+ *      owns the Python bootstrap and never invokes the macOS
+ *      `/usr/bin/python3` developer-tools shim.
+ *   2. **System `uv`** on PATH — development / bare-service fallback
+ *      when no bundled binary is available. uv installs its own Python.
+ *   3. **System `python3`** (or `python`) on PATH with version ≥
+ *      `minPythonVersion` (default 3.10) — create the venv with
+ *      stock `python -m venv` + pip. This is a last-resort fallback
+ *      for non-packaged installs only.
+ *
+ * The selected source is recorded per-venv in `uv.json`; subsequent
+ * `ensureVenv` calls for the same name with the same package list
+ * reuse the existing venv without re-probing.
+ *
+ * Storage layout:
+ *
+ *   <home>/engines/uv/
+ *   └── venvs/
+ *       └── <name>/
+ *           ├── uv.json                (this module's manifest)
+ *           ├── bin/python | Scripts\python.exe
+ *           └── lib/python3.x/...      (standard venv contents)
+ *
+ * Intentionally engine-agnostic — callers ask `ensureVenv('mlx',
+ * ['mlx-lm==X'])` and get a `VenvHandle` with the Python binary path
+ * and a `binPath(name)` helper for console scripts. How the venv got
+ * there is hidden behind the `source` field for Settings to display.
+ */
+import { exec as nodeExec, spawn as nodeSpawn } from 'node:child_process';
+/** Source-of-truth for where the Python interpreter came from. */
+export type UvRuntimeSource = 'system-uv' | 'system-python' | 'bundled-uv';
+export interface VenvHandle {
+    /** Venv name as passed to `ensureVenv` (and the directory basename). */
+    name: string;
+    /** Absolute path to the venv root directory. */
+    venvRoot: string;
+    /** Absolute path to the venv's `python` binary (correct per platform). */
+    pythonPath: string;
+    /** The installer route that provisioned this venv. */
+    source: UvRuntimeSource;
+    /** Python version inside the venv, e.g. '3.11.7'. */
+    pythonVersion: string;
+    /** uv version that created this venv (only when `source` used uv). */
+    uvVersion?: string;
+    /** Packages requested at install/ensure time. */
+    packages: string[];
+    /** ISO timestamp of the last install (create or package refresh). */
+    installedAt: string;
+    /**
+     * Resolve the path to a console script installed into this venv
+     * (e.g. `binPath('mlx_lm.server')`). Handles the bin/ vs Scripts/
+     * split and the `.exe` suffix on Windows. Does not check that the
+     * script exists — callers that care should `existsSync` the result.
+     */
+    binPath(name: string): string;
+}
+export interface EnsureVenvOptions {
+    /** Short identifier used as the venv directory name. Must match `/^[a-z0-9][a-z0-9._-]{0,63}$/i`. */
+    name: string;
+    /**
+     * Pip-style package specs — ideally pinned (`mlx-lm==0.25.3`) for
+     * reproducibility. Unpinned specs are allowed but log a warning.
+     */
+    packages: string[];
+    /**
+     * Minimum acceptable Python version as `major.minor`. Default `3.10`.
+     * Checked against both system Python (for the system-python branch)
+     * and the venv's Python (reported after creation).
+     */
+    minPythonVersion?: string;
+    /**
+     * Exact Python version to request from uv (the `--python` flag) when
+     * uv is the installer. Ignored on the system-python branch —
+     * there's no way to tell `python -m venv` to download a different
+     * version. Default `3.11`.
+     */
+    preferredPythonVersion?: string;
+    /**
+     * Replace the primary package index (the `--index-url` flag). Rarely
+     * needed — prefer {@link extraIndexUrls} so PyPI stays the default.
+     */
+    indexUrl?: string;
+    /**
+     * Additional package indexes searched alongside PyPI (one
+     * `--extra-index-url` per entry). The video engine uses this to pull
+     * the platform-matched PyTorch CUDA wheel from
+     * `https://download.pytorch.org/whl/cu124` while keeping PyPI primary
+     * for `diffusers`/`transformers`/etc. Folded into the manifest
+     * fast-path key so switching accelerators (cpu → cuda) reinstalls
+     * instead of silently reusing the wrong torch build.
+     */
+    extraIndexUrls?: string[];
+}
+export interface UvRuntimeOptions {
+    /** GEZEL_HOME — venvs land under `<home>/engines/uv/venvs/`. */
+    home: string;
+    /**
+     * Override the bundled-uv binary path lookup. Real code reads
+     * `process.env.GEZEL_UV_BIN`; tests can inject without touching env.
+     * Pass `null` to disable bundled-uv fallback entirely.
+     */
+    bundledUvBin?: string | null;
+    /** Test seam — defaults to node's `child_process.spawn`. */
+    spawn?: typeof nodeSpawn;
+    /** Test seam — defaults to node's `child_process.exec`. */
+    exec?: typeof nodeExec;
+    onLog?: (line: string) => void;
+}
+export declare class UvRuntime {
+    private readonly home;
+    private readonly venvsRoot;
+    private readonly bundledUvBinOverride;
+    private readonly readBundledUvFromEnv;
+    private readonly spawn;
+    private readonly exec;
+    private readonly onLog;
+    /** Cached probe result so repeated `ensureVenv` calls skip the re-probe. */
+    private probed;
+    /**
+     * Per-venv-name serialization tail. The MLX venv is now provisioned
+     * by two concurrent callers — the parallel warm fired when a model
+     * install starts, and the lazy first-chat `ensureVenv` — and on a
+     * cold machine both can miss the manifest fast-path and call
+     * `createVenv()`, which `rm -rf`s the venv dir. Two of those racing
+     * clobber each other's install. We chain same-name calls so the
+     * second observes the first's finished venv via the fast-path
+     * instead of rebuilding it.
+     */
+    private readonly venvLocks;
+    constructor(opts: UvRuntimeOptions);
+    /**
+     * Idempotent: return a handle to the named venv with the requested
+     * packages installed. Creates the venv if missing; installs/upgrades
+     * packages when the recorded set differs from the request.
+     */
+    ensureVenv(opts: EnsureVenvOptions): Promise<VenvHandle>;
+    private ensureVenvSerial;
+    /** Delete a venv entirely. No-op when it doesn't exist. */
+    removeVenv(name: string): Promise<void>;
+    /** List every venv with a valid manifest under `venvs/`. Sorted by name. */
+    listVenvs(): Promise<VenvHandle[]>;
+    /**
+     * Report on the current runtime without creating a venv — powers the
+     * Settings "Python runtime" status block.
+     *   - `source`: `null` when no suitable runtime exists on this host.
+     *   - `pythonVersion`: the interpreter version we'd use (system Python
+     *     or uv-managed; empty string for uv when no venv created yet).
+     */
+    describeRuntime(minPythonVersion?: string): Promise<{
+        source: UvRuntimeSource | null;
+        installerPath?: string;
+        uvVersion?: string;
+        pythonVersion?: string;
+        bundledUvAvailable: boolean;
+        reason?: string;
+    }>;
+    private resolveInstaller;
+    private resolveBundledUvBin;
+    private createVenv;
+    private installPackages;
+    private readPythonVersion;
+    private probeCommandVersion;
+    /**
+     * Run a command inheriting env + piping output through onLog.
+     * Rejects on non-zero exit. Uses the injected `spawn` so tests can
+     * drive the lifecycle without real subprocesses.
+     */
+    private run;
+}
+export declare function versionGte(actual: string, minimum: string): boolean;