@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/memory/embeddings.js

@@ -0,0 +1,467 @@
+/**
+ * Public embedding API. Generates 384-dimensional vectors from text using a
+ * local transformers.js model (all-MiniLM-L6-v2) — runs entirely on-device, no
+ * API keys. The model downloads on first use (~23 MB) and is cached in the OS
+ * cache directory.
+ *
+ * Two robustness properties live here, both added after an out-of-memory in the
+ * model crashed the whole Electron app (a many-chunk file made ONNX attempt a
+ * multi-gigabyte allocation in `BFCArena::Extend`, which trapped — SIGTRAP — on
+ * the main thread):
+ *
+ *   1. Inference runs in BOUNDED sub-batches (see `embed-core`) so no single
+ *      ONNX `Run` can balloon, regardless of how many texts a caller passes.
+ *   2. Inference runs in a WORKER THREAD (`embed-worker`), keeping the heavy
+ *      synchronous native call off the Electron main/UI thread. When the worker
+ *      can't be created — under vitest there's no built worker file, and a raw
+ *      `new Worker('*.ts')` wouldn't load through vitest's transform — we
+ *      degrade to in-process inference, which is still bounded by (1).
+ */
+import { Worker } from 'node:worker_threads';
+import { createLogger, sameVectorSpace } from '@bendyline/gezel';
+import { retireModelWorker } from '../utils/retire-model-worker.js';
+import { findServiceWorkerEntry } from '../utils/service-worker-entry.js';
+import { PipelineLoadError, daemonEmbedderPin, daemonEmbedderVerified, passageInstruction, queryInstruction, runEmbed, runProfileQueryEmbed, } from './embed-core.js';
+const log = createLogger('memory');
+/**
+ * Marker class so callers can tell "the indexer is off on purpose" apart from a
+ * new failure worth logging. The extractor uses this to stay silent after the
+ * first failure.
+ */
+export class EmbeddingsDisabledError extends Error {
+    code = 'EMBEDDINGS_DISABLED';
+    retryable = false;
+    constructor(reason) {
+        super(`memory embeddings disabled: ${reason}`);
+        this.name = 'EmbeddingsDisabledError';
+    }
+}
+/** A recoverable model-load outage currently held behind a retry cooldown. */
+export class EmbeddingsUnavailableError extends EmbeddingsDisabledError {
+    code = 'EMBEDDINGS_UNAVAILABLE';
+    retryable = true;
+    constructor(reason) {
+        super(reason);
+        this.name = 'EmbeddingsUnavailableError';
+        this.message = `memory embeddings temporarily unavailable: ${reason}`;
+    }
+}
+// Once the model fails to load, we permanently flip into a disabled state.
+// Every subsequent call throws the short marker error instead of re-attempting
+// the import and re-printing the full model-load error on every chat turn.
+let disabledReason = null;
+let unavailableReason = null;
+let unavailableUntil = 0;
+// Interactive callers need to know whether a query is about to pay the model's
+// one-time load cost. Keep this deliberately coarse: it is process-local
+// readiness, not durable health state. A cold/warming caller can fail open and
+// let the already-started load finish in the background.
+let pipelineStatus = 'cold';
+/** Avoid hammering the model registry when a first-use download is offline. */
+const EMBEDDING_RETRY_COOLDOWN_MS = 60_000;
+const ENV_DISABLED_REASON = 'disabled by GEZEL_DISABLE_EMBEDDINGS';
+function disabledByEnv() {
+    const raw = process.env.GEZEL_DISABLE_EMBEDDINGS;
+    return raw === '1' || raw?.toLowerCase() === 'true';
+}
+export function embeddingsDisabledReason() {
+    return disabledByEnv() ? ENV_DISABLED_REASON : (disabledReason ?? currentUnavailableReason());
+}
+export function embeddingPipelineStatus() {
+    if (disabledByEnv() || disabledReason)
+        return 'disabled';
+    if (currentUnavailableReason())
+        return 'unavailable';
+    return pipelineStatus;
+}
+/**
+ * The status + reason pair as one wire-ready object — what `/api/health` and
+ * every project's `/index/status` surface so a dead embedder is
+ * distinguishable from an index that is merely still building.
+ */
+export function embeddingsHealth() {
+    const reason = embeddingsDisabledReason();
+    return { status: embeddingPipelineStatus(), ...(reason ? { reason } : {}) };
+}
+let worker = null;
+// Flips false once we give up on the worker path (no built file, spawn error,
+// or a crash loop) and fall back to in-process inference for good.
+let workerUsable = true;
+/** Set by service shutdown: no new worker, request, or in-process load until reopened. */
+let closed = false;
+let crashCount = 0;
+let nextId = 1;
+const pending = new Map();
+/**
+ * Locate the built worker from either service bundle shape. Under vitest there
+ * is no dist build, so let the caller fall back to in-process.
+ */
+function workerEntry() {
+    if (process.env.VITEST)
+        return null;
+    return findServiceWorkerEntry(import.meta.url, 'embeddings');
+}
+function ensureWorker() {
+    if (closed || !workerUsable)
+        return null;
+    if (worker)
+        return worker;
+    const entry = workerEntry();
+    if (!entry) {
+        workerUsable = false;
+        return null;
+    }
+    try {
+        const w = new Worker(entry);
+        w.on('message', onMessage);
+        w.on('error', (err) => onWorkerDown(err instanceof Error ? err.message : String(err)));
+        w.on('exit', (code) => {
+            if (code !== 0)
+                onWorkerDown(`worker exited with code ${code}`);
+        });
+        // An idle embedder must never hold the event loop open; sendToWorker refs
+        // it only while a request is in flight.
+        w.unref();
+        worker = w;
+        return w;
+    }
+    catch (err) {
+        log.warn(`[memory] embed worker failed to start; using in-process inference: ${describe(err)}`);
+        workerUsable = false;
+        return null;
+    }
+}
+function onMessage(msg) {
+    const p = pending.get(msg.id);
+    if (!p)
+        return;
+    if (msg.progress) {
+        p.onDownloadProgress?.(msg.progress);
+        return;
+    }
+    pending.delete(msg.id);
+    if (pending.size === 0)
+        worker?.unref();
+    if (msg.error) {
+        if (p.profileId) {
+            if (!p.localFilesOnly && (msg.fatal || msg.retryable))
+                markProfileUnavailable(p.profileId, msg.error, msg.fatal ?? false);
+            p.reject(msg.fatal || msg.retryable
+                ? new EmbeddingsUnavailableError(`profile ${p.profileId}: ${firstLine(msg.error)}`)
+                : new Error(msg.error));
+            return;
+        }
+        if (msg.fatal)
+            markDisabled(msg.error, msg.optionalPeerMissing ?? false);
+        if (msg.retryable) {
+            markTemporarilyUnavailable(msg.error);
+            p.reject(new EmbeddingsUnavailableError(unavailableReason ?? msg.error));
+        }
+        else {
+            p.reject(new Error(msg.error));
+        }
+        return;
+    }
+    p.resolve(msg.vectors ?? []);
+}
+function onWorkerDown(reason) {
+    const dead = worker;
+    worker = null;
+    if (dead)
+        void dead.terminate().catch(() => { });
+    // Reject everything still in flight — those requests died with the worker.
+    const inflight = Array.from(pending.values());
+    pending.clear();
+    for (const p of inflight)
+        p.reject(new Error(`embed worker stopped: ${reason}`));
+    crashCount++;
+    // A crash loop (model genuinely broken on this box) → stop spawning workers
+    // and degrade to in-process. We don't disable outright: in-process is still
+    // bounded by the sub-batching, so search keeps working.
+    if (crashCount >= 3) {
+        workerUsable = false;
+        log.warn(`[memory] embed worker crashed ${crashCount}×; falling back to in-process inference. Last: ${reason}`);
+    }
+}
+function sendToWorker(w, texts, profile, onDownloadProgress, localFilesOnly = false) {
+    const id = nextId++;
+    return new Promise((resolve, reject) => {
+        pending.set(id, {
+            localFilesOnly,
+            resolve,
+            reject,
+            ...(profile ? { profileId: profile.id } : {}),
+            ...(onDownloadProgress ? { onDownloadProgress } : {}),
+        });
+        // A request in flight must keep the process alive. The daemon's listener
+        // always did; the in-process inference host has none, so an embedding
+        // awaited from a plain Node process exited mid-await (same failure as the
+        // knowledge worker, see knowledge/worker-host.ts).
+        w.ref();
+        w.postMessage(profile
+            ? {
+                id,
+                texts,
+                profile,
+                localFilesOnly,
+                ...(onDownloadProgress ? { reportProgress: true } : {}),
+            }
+            : { id, texts });
+    });
+}
+async function embedInProcess(texts) {
+    try {
+        return await runEmbed(texts);
+    }
+    catch (err) {
+        if (err instanceof PipelineLoadError) {
+            if (err.retryable) {
+                markTemporarilyUnavailable(err.message);
+                throw new EmbeddingsUnavailableError(unavailableReason ?? err.message);
+            }
+            markDisabled(err.message, err.optionalPeerMissing);
+            throw new EmbeddingsDisabledError(disabledReason ?? err.message);
+        }
+        throw err;
+    }
+}
+function currentUnavailableReason() {
+    if (!unavailableReason)
+        return null;
+    if (Date.now() < unavailableUntil)
+        return unavailableReason;
+    unavailableReason = null;
+    unavailableUntil = 0;
+    return null;
+}
+function markTemporarilyUnavailable(message) {
+    unavailableReason = firstLine(message);
+    unavailableUntil = Date.now() + EMBEDDING_RETRY_COOLDOWN_MS;
+    log.warn(`[memory] embedding model load failed; semantic search will retry after ${Math.ceil(EMBEDDING_RETRY_COOLDOWN_MS / 1_000)}s.`);
+    log.warn('[memory] underlying transient error:', message);
+}
+function markDisabled(message, optionalPeerMissing = false) {
+    if (disabledReason)
+        return;
+    disabledReason = firstLine(message);
+    if (optionalPeerMissing) {
+        // Not a fault: the base npm install deliberately omits the ML peers and the
+        // README documents that as supported. Reporting it as an error made every
+        // lean install look damaged on its first chat, so state it once and move on.
+        log.info(`[memory] vector memory is off — ${disabledReason}`);
+        return;
+    }
+    // Loud once with the underlying model/runtime error. Subsequent callers get
+    // the short `EmbeddingsDisabledError`.
+    log.error('[memory] failed to load embedding pipeline; vector memory is now disabled for this process.');
+    log.error('[memory] underlying error:', message);
+}
+const SHUTTING_DOWN = 'the service is shutting down';
+/**
+ * Close for service shutdown: refuse new work (it would start a worker, or
+ * load the model in-process, as the process exits), then terminate the worker
+ * once its in-flight work has finished, waiting at most `drainMs`.
+ */
+export async function shutdownEmbeddings(drainMs) {
+    closed = true;
+    const w = worker;
+    if (!w)
+        return;
+    if (await retireModelWorker(w, () => pending.size === 0, drainMs)) {
+        if (worker === w)
+            worker = null;
+        return;
+    }
+    log.warn('[memory] an embedding was still running at shutdown; leaving its worker to exit');
+}
+/** Reopen after shutdown — an embedded service can be started again in the same process. */
+export function openEmbeddings() {
+    closed = false;
+}
+/** Embed `texts`, preferring the worker and degrading to in-process. */
+async function embedMany(texts) {
+    if (closed)
+        throw new EmbeddingsUnavailableError(SHUTTING_DOWN);
+    if (disabledByEnv())
+        throw new EmbeddingsDisabledError(ENV_DISABLED_REASON);
+    if (disabledReason)
+        throw new EmbeddingsDisabledError(disabledReason);
+    const temporaryReason = currentUnavailableReason();
+    if (temporaryReason)
+        throw new EmbeddingsUnavailableError(temporaryReason);
+    if (pipelineStatus === 'cold')
+        pipelineStatus = 'warming';
+    try {
+        const w = ensureWorker();
+        if (w) {
+            try {
+                const vectors = await sendToWorker(w, texts);
+                pipelineStatus = 'ready';
+                return vectors;
+            }
+            catch (err) {
+                // A retryable pipeline-load failure already has a cooldown and should not
+                // immediately repeat the same download in-process.
+                if (err instanceof EmbeddingsUnavailableError)
+                    throw err;
+                // The model is unloadable — the worker tagged it fatal and we've already
+                // set disabledReason. Surface the canonical error.
+                if (disabledReason)
+                    throw new EmbeddingsDisabledError(disabledReason);
+                // Transient worker failure (it crashed mid-request and we rejected the
+                // in-flight call). Fall through so this call still completes in-process.
+                log.warn(`[memory] embed via worker failed; retrying in-process: ${describe(err)}`);
+            }
+        }
+        const vectors = await embedInProcess(texts);
+        pipelineStatus = 'ready';
+        return vectors;
+    }
+    catch (err) {
+        if (!disabledReason && !currentUnavailableReason())
+            pipelineStatus = 'cold';
+        throw err;
+    }
+}
+// ── knowledge-catalog profiles ─────────────────────────────────────────────
+/** Per-profile outages; a public catalog's model failing to download must not disable memory. */
+const profileOutages = new Map();
+function markProfileUnavailable(profileId, message, permanent) {
+    profileOutages.set(profileId, {
+        reason: firstLine(message),
+        until: permanent ? Number.POSITIVE_INFINITY : Date.now() + EMBEDDING_RETRY_COOLDOWN_MS,
+        permanent,
+    });
+    log.warn(`[memory] knowledge profile ${profileId} failed to load${permanent ? '' : `; semantic search for its catalogs retries after ${Math.ceil(EMBEDDING_RETRY_COOLDOWN_MS / 1_000)}s`}: ${firstLine(message)}`);
+}
+function profileOutage(profileId) {
+    const outage = profileOutages.get(profileId);
+    if (!outage)
+        return null;
+    if (Date.now() < outage.until)
+        return outage.reason;
+    profileOutages.delete(profileId);
+    return null;
+}
+/**
+ * True when a catalog's profile IS the daemon's own embedder — the same
+ * pinned model files, tokenizer, pooling, instruction and width — so query
+ * vectors from `embedQuery` can be reused without loading a second model.
+ * A bare repo-string match is not enough: an instruction-prefix or precision
+ * difference silently changes vectors. This is the declarative half; whether
+ * the daemon's cached files really are those bytes is `daemonEmbedderVerified`'s
+ * call, made once the pipeline has run.
+ */
+export function sharesDaemonEmbedder(profile) {
+    const pin = daemonEmbedderPin();
+    return (pin !== null &&
+        sameVectorSpace(pin, profile) &&
+        profile.queryInstruction === queryInstruction() &&
+        profile.dimensions === (Number(process.env.GEZEL_EMBED_DIM) || 384));
+}
+/**
+ * Embed a knowledge-catalog QUERY in the catalog's own vector space. Reuses
+ * the daemon pipeline when the profile matches it; otherwise loads the
+ * profile's model (worker-first, in-process fallback) under a per-profile
+ * outage cooldown, so one catalog's missing model never darkens the others.
+ */
+export async function embedKnowledgeQuery(text, profile, opts = {}) {
+    const { onDownloadProgress, localFilesOnly = false } = opts;
+    if (closed)
+        throw new EmbeddingsUnavailableError(SHUTTING_DOWN);
+    // The default daemon pipeline may fetch weights on a cold load.
+    if (!localFilesOnly && sharesDaemonEmbedder(profile)) {
+        const vector = await embedQuery(text);
+        if (await daemonEmbedderVerified())
+            return vector;
+        // The daemon's copy of the model is not provably the profile's bytes;
+        // fall through to the profile's own pinned, verified load.
+    }
+    if (disabledByEnv())
+        throw new EmbeddingsDisabledError(ENV_DISABLED_REASON);
+    const outage = profileOutage(profile.id);
+    if (outage)
+        throw new EmbeddingsUnavailableError(`profile ${profile.id}: ${outage}`);
+    const w = ensureWorker();
+    if (w) {
+        try {
+            const [vector] = await sendToWorker(w, [text], profile, onDownloadProgress, localFilesOnly);
+            return vector ?? [];
+        }
+        catch (err) {
+            if (err instanceof EmbeddingsUnavailableError)
+                throw err;
+            log.warn(`[memory] profile embed via worker failed; retrying in-process: ${describe(err)}`);
+        }
+    }
+    try {
+        const [vector] = await runProfileQueryEmbed([text], profile, onDownloadProgress, localFilesOnly);
+        return vector ?? [];
+    }
+    catch (err) {
+        if (err instanceof PipelineLoadError) {
+            if (!localFilesOnly)
+                markProfileUnavailable(profile.id, err.message, !err.retryable);
+            throw new EmbeddingsUnavailableError(`profile ${profile.id}: ${firstLine(err.message)}`);
+        }
+        throw err;
+    }
+}
+function firstLine(s) {
+    const idx = s.indexOf('\n');
+    return idx < 0 ? s : s.slice(0, idx);
+}
+function describe(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export async function embed(text) {
+    const [vector] = await embedMany([passageInstruction() + text]);
+    return vector ?? [];
+}
+/**
+ * Embed a SEARCH QUERY. Same pipeline as `embed`, but prepends the model's
+ * query-side retrieval instruction when it has one (bge-*: an English
+ * instruction sentence; e5-*: "query: "); for symmetric models this is
+ * identical to `embed`. Indexed passages go through `embed`/`embedBatch`,
+ * which apply the PASSAGE-side prefix where the family has one (e5 only) —
+ * the asymmetry is the whole point. Every query-side call site (content
+ * search, memory recall, unified search) routes here so the prefixes stay in
+ * exactly one place. NOTE: this must NOT delegate to `embed`, which would
+ * stack the passage prefix onto the query.
+ */
+export async function embedQuery(text) {
+    const [vector] = await embedMany([queryInstruction() + text]);
+    return vector ?? [];
+}
+export async function embedBatch(texts) {
+    if (texts.length === 0)
+        return [];
+    const prefix = passageInstruction();
+    return embedMany(prefix ? texts.map((text) => prefix + text) : texts);
+}
+/**
+ * Load the embedding pipeline ahead of the first real caller.
+ *
+ * The model loads lazily on first use, and that load was measured at ~41s on
+ * a fresh install. Whoever arrives first pays it — and the unified search sits
+ * in the titlebar, so it was routinely the user's first keystroke, with the
+ * search box appearing to ignore them. The first chat turn loads the same
+ * pipeline for memory extraction anyway, so warming moves the cost off an
+ * interactive path rather than adding one.
+ *
+ * Never throws: embeddings being disabled or unavailable is a supported
+ * configuration, and the callers already degrade to keyword-only search.
+ */
+export async function warmEmbeddings() {
+    if (disabledByEnv() || disabledReason)
+        return false;
+    if (pipelineStatus === 'ready')
+        return true;
+    try {
+        await embed('warm');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/model-profile/behaviors/tools-mlx-template-fix.d.ts

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

package/dist/model-profile/behaviors/tools-mlx-template-fix.js

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

package/dist/model-profile/behaviors/turn-ramble-detection.d.ts

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

package/dist/model-profile/behaviors/turn-ramble-detection.js

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

package/dist/model-profile/defaults.d.ts

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

package/dist/model-profile/defaults.js

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

package/dist/model-profile/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public surface of the model-profile package — every consumer
+ * imports from here, never from a deeper path.
+ */
+export type { Behavior, ModelCtx, NudgeVerdict, PromptCtx, ResolvedBehaviorEntry, ResolvedModelProfile, TurnCtx, } from './types.js';
+export { defaultStyleForProvider, TIER_DEFAULT_BEHAVIORS } from './defaults.js';
+export { listBehaviors, lookupBehavior, resolveProfile, resolveProfileForCatalogId, } from './registry.js';
+export { applyTuning, ANTHROPIC_TUNING_MAP, COPILOT_TUNING_MAP, LLAMA_CPP_TUNING_MAP, MLX_TUNING_MAP, OLLAMA_BODY_TUNING_MAP, OLLAMA_OPTIONS_TUNING_MAP, OLLAMA_TUNING_MAP, OPENAI_TUNING_MAP, isReasoningEngaged, resolveTuning, tuningMapFor, } from './tuning.js';
+export type { ResolveTuningInput, ResolvedTuning, TuningMap, TuningPath } from './tuning.js';

package/dist/model-profile/index.js

@@ -0,0 +1,7 @@
+/**
+ * Public surface of the model-profile package — every consumer
+ * imports from here, never from a deeper path.
+ */
+export { defaultStyleForProvider, TIER_DEFAULT_BEHAVIORS } from './defaults.js';
+export { listBehaviors, lookupBehavior, resolveProfile, resolveProfileForCatalogId, } from './registry.js';
+export { applyTuning, ANTHROPIC_TUNING_MAP, COPILOT_TUNING_MAP, LLAMA_CPP_TUNING_MAP, MLX_TUNING_MAP, OLLAMA_BODY_TUNING_MAP, OLLAMA_OPTIONS_TUNING_MAP, OLLAMA_TUNING_MAP, OPENAI_TUNING_MAP, isReasoningEngaged, resolveTuning, tuningMapFor, } from './tuning.js';

package/dist/model-profile/registry.d.ts

@@ -0,0 +1,15 @@
+import type { ModelTier, ProviderName } from '@bendyline/gezel';
+import type { CatalogService } from '@bendyline/gezel-catalog';
+import { type ResolvedModelProfile } from '@bendyline/gezel/local-loop';
+export * from '@bendyline/gezel/local-loop';
+/**
+ * Convenience helper for tests + prompt-build sites that need the
+ * resolved profile but don't already have a manifest in hand.
+ * Looks the manifest up via the catalog service and forwards.
+ */
+export declare function resolveProfileForCatalogId(args: {
+    catalog: CatalogService;
+    catalogId: string | undefined;
+    tier: ModelTier;
+    providerName: ProviderName;
+}): Promise<ResolvedModelProfile>;

package/dist/model-profile/registry.js

@@ -0,0 +1,18 @@
+import { resolveProfile } from '@bendyline/gezel/local-loop';
+// Resolution moved to core so the portable runtime resolves profiles the same
+// way; only the catalog-service lookup lives here.
+export * from '@bendyline/gezel/local-loop';
+/**
+ * Convenience helper for tests + prompt-build sites that need the
+ * resolved profile but don't already have a manifest in hand.
+ * Looks the manifest up via the catalog service and forwards.
+ */
+export async function resolveProfileForCatalogId(args) {
+    const { catalog, catalogId, tier, providerName } = args;
+    if (!catalogId) {
+        return resolveProfile({ manifest: undefined, tier, providerName });
+    }
+    const detail = await catalog.get('chat-model', catalogId).catch(() => null);
+    const manifest = detail?.manifest.kind === 'chat-model' ? detail.manifest : undefined;
+    return resolveProfile({ manifest, tier, providerName });
+}

package/dist/model-profile/runtime.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Helpers for the runtime points where local-model providers (Ollama,
+ * llama-cpp, mlx, ds4) gate features on the resolved profile. The bridge +
+ * chat-manager-side wiring composes hooks naturally; the providers
+ * have a different shape — they instantiate stateful machinery
+ * (RambleDetector class, foldPreToolPreamble call site, Gemma
+ * special-token salvage) that doesn't fit the hook surface. These
+ * helpers translate "is behavior X opted in?" + "what's its config?"
+ * into the data the providers actually need.
+ *
+ * Each helper accepts an optional profile and degrades gracefully
+ * (returns `false` / `null` / config defaults) when undefined, so
+ * legacy code paths that don't yet thread a profile keep working.
+ */
+import type { ResolvedModelProfile } from './types.js';
+export { extractReasoningWithProfile, profileBehaviorConfig, profileHasBehavior, } from '@bendyline/gezel/local-loop';
+/**
+ * Apply per-run behavior overrides from the environment to a resolved
+ * profile. Feature-agnostic and reusable for any A/B:
+ *
+ *   - `GEZEL_FORCE_BEHAVIORS` — comma-separated behavior ids to ADD
+ *     (e.g. `tools.gezels-as-roles`). Already-present ids are skipped;
+ *     unknown ids are logged and ignored; parameterized behaviors get
+ *     their validated `defaultConfig`.
+ *   - `GEZEL_REMOVE_BEHAVIORS` — comma-separated ids to remove.
+ *
+ * Returns the same profile reference when no override applies (so the
+ * common path is allocation-free), otherwise a shallow copy with a new
+ * `behaviors` array. The eval runner injects these env vars per-run via
+ * the daemon spawn `extraEnv`, so control vs treatment is one flag — no
+ * catalog edits or rebuilds between runs.
+ */
+export declare function applyBehaviorEnvOverrides(profile: ResolvedModelProfile): ResolvedModelProfile;
+/**
+ * Walk `numPredict` hooks on the profile and return the first
+ * non-null value. Used by Ollama / llama-cpp / mlx in place of the
+ * legacy `pickOllamaNumPredict` substring matcher; replicates the
+ * "verbose-family models bumped to 16384" behavior via the registered
+ * `turn.ollama-num-predict-bumped` behavior's `numPredict` hook.
+ *
+ * Returns `null` when no behavior fires; the caller falls back to its
+ * own default (`DEFAULT_OLLAMA_NUM_PREDICT`) or to a user-configured
+ * override.
+ */
+export declare function profileNumPredict(profile: ResolvedModelProfile | undefined, ctxArgs: {
+    modelId: string | undefined;
+    providerName: 'ollama' | 'llama-cpp' | 'mlx';
+}): number | null;