@bendyline/gezel-inference 0.0.0-stage → 0.1.0

package/dist/http/external-conversation-contract.d.ts

@@ -0,0 +1,49 @@
+import type { ProviderName } from '@bendyline/gezel';
+export interface ExternalTranscriptToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+export interface ExternalTranscriptMessage {
+    role: 'system' | 'developer' | 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCalls?: ExternalTranscriptToolCall[];
+    toolCallId?: string;
+}
+export interface BeginExternalConversationInput {
+    sourceId: string;
+    sourceName: string;
+    externalConversationId: string;
+    workingDirectory?: string;
+    projectHint?: string;
+    gezelId: string;
+    providerName: ProviderName;
+    model?: string;
+    messages: ExternalTranscriptMessage[];
+    /** Effective prompt and tool roster that were actually supplied this request. */
+    effectiveSystemMessage: string;
+    toolNames: string[];
+    /** Receipt block injected into the model-facing final tool result, when any. */
+    actionLedger?: string;
+}
+export interface ResolveExternalConversationInput {
+    sourceId: string;
+    gezelId: string;
+    messages: ExternalTranscriptMessage[];
+    /** Unique id for a genuinely new thread, normally the caller's request id. */
+    fallbackExternalConversationId: string;
+}
+export interface ExternalConversationFinish {
+    content: string;
+    reasoning?: string;
+    finishReason: 'stop' | 'tool_calls' | 'length';
+}
+export interface ExternalConversationTurn {
+    sessionId: string;
+    projectId: string;
+    onContentDelta(content: string): void;
+    onReasoningDelta(content: string): void;
+    onToolArgsDelta(name: string, content: string): void;
+    finish(result: ExternalConversationFinish): Promise<void>;
+    fail(error: unknown): Promise<void>;
+}

package/dist/http/external-conversation-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/http/external-conversation-headers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Opt-in provenance headers for caller-owned chat loops.
+ *
+ * A stable conversation id is the minimum required to mirror an external
+ * transcript into Gezel. The directory and project are optional routing hints;
+ * the recorder falls back to the default project when neither resolves to one
+ * unambiguous project.
+ */
+export declare const EXTERNAL_CONVERSATION_ID_HEADER = "x-gezel-external-conversation-id";
+export declare const EXTERNAL_WORKING_DIRECTORY_HEADER = "x-gezel-working-directory";
+export declare const EXTERNAL_PROJECT_HEADER = "x-gezel-project";

package/dist/http/external-conversation-headers.js

@@ -0,0 +1,11 @@
+/**
+ * Opt-in provenance headers for caller-owned chat loops.
+ *
+ * A stable conversation id is the minimum required to mirror an external
+ * transcript into Gezel. The directory and project are optional routing hints;
+ * the recorder falls back to the default project when neither resolves to one
+ * unambiguous project.
+ */
+export const EXTERNAL_CONVERSATION_ID_HEADER = 'x-gezel-external-conversation-id';
+export const EXTERNAL_WORKING_DIRECTORY_HEADER = 'x-gezel-working-directory';
+export const EXTERNAL_PROJECT_HEADER = 'x-gezel-project';

package/dist/http/inference-context.d.ts

@@ -0,0 +1,36 @@
+import type { GezelConfig, GezelDetail, GezelSummary, HistoryEvent, ProviderName } from '@bendyline/gezel';
+import type { CatalogService } from '@bendyline/gezel-catalog';
+import type { KnowledgeManager } from '../knowledge/manager.js';
+import type { EnsureModelOrchestrator } from '../models/ensure.js';
+import type { resolveModelSessionDefaults } from '../providers/session-defaults.js';
+import type { LLMProvider, ModelInfo, TurnUsage } from '../providers/types.js';
+import type { RelevanceModelManager } from '../relevance/manager.js';
+import type { BeginExternalConversationInput, ExternalConversationTurn, ResolveExternalConversationInput } from './external-conversation-contract.js';
+export interface InferenceContext {
+    store: {
+        readConfig(): Promise<GezelConfig>;
+        getGezel?(id: string): Promise<GezelDetail | null>;
+        listGezels?(): Promise<GezelSummary[]>;
+    };
+    catalog: CatalogService;
+    chat: {
+        getProviderForModel(name: ProviderName, model?: string): Promise<LLMProvider>;
+        /** Look a provider up without binding (and so possibly starting) a model. */
+        getProvider?(name: ProviderName): Promise<LLMProvider>;
+        listModelsForProvider(name: ProviderName): Promise<ModelInfo[]>;
+        resolveModelSessionDefaults(name: ProviderName, model: string | undefined, overrides?: Parameters<typeof resolveModelSessionDefaults>[4]): ReturnType<typeof resolveModelSessionDefaults>;
+        providerForGezel?(id: string): Promise<ProviderName>;
+        recordExternalUsage?(name: ProviderName, usage: TurnUsage): void;
+        resolveExternalConversationId?(input: ResolveExternalConversationInput): Promise<string>;
+        beginExternalConversation?(input: BeginExternalConversationInput): Promise<ExternalConversationTurn>;
+    };
+    history?: {
+        log(event: Omit<HistoryEvent, 'id' | 'at'> & {
+            at?: string;
+            id?: string;
+        }): Promise<void>;
+    };
+    knowledge?: KnowledgeManager;
+    relevance: RelevanceModelManager;
+    ensureModel: EnsureModelOrchestrator;
+}

package/dist/http/inference-context.js

@@ -0,0 +1 @@
+export {};

package/dist/http/model-inventory-cache.d.ts

@@ -0,0 +1,8 @@
+import type { ModelInfo, ProviderName } from '../providers/types.js';
+export declare const CACHE_TTL_MS: number;
+export interface CacheEntry {
+    at: number;
+    models: ModelInfo[];
+}
+export declare const cache: Map<"copilot" | "openai" | "anthropic" | "anthropic-cli" | "codex-cli" | "ollama" | "llama-cpp" | "mlx" | "ds4" | "apple-foundation-models" | "android-mlkit" | "remote", CacheEntry>;
+export declare function invalidateModelsCache(provider?: ProviderName): void;

package/dist/http/model-inventory-cache.js

@@ -0,0 +1,8 @@
+export const CACHE_TTL_MS = 5 * 60_000;
+export const cache = new Map();
+export function invalidateModelsCache(provider) {
+    if (provider)
+        cache.delete(provider);
+    else
+        cache.clear();
+}

package/dist/http/openai-compat/action-ledger.d.ts

@@ -0,0 +1,15 @@
+import type { TranslatedSessionInput } from './translate.js';
+export interface CallerOwnedActionLedgerResult {
+    input: TranslatedSessionInput;
+    /** Empty when this is not a tool-result continuation with file mutations. */
+    ledger?: string;
+    receiptCount: number;
+}
+/**
+ * Attach a compact, transcript-derived file-action receipt to the final tool
+ * result in a caller-owned loop. The receipt deliberately describes only
+ * structured calls for which the caller supplied a result. It does not infer
+ * filesystem state, promote assistant narration into action, or enumerate
+ * opaque shell-command side effects.
+ */
+export declare function appendCallerOwnedActionLedger(input: TranslatedSessionInput): CallerOwnedActionLedgerResult;

package/dist/http/openai-compat/action-ledger.js

@@ -0,0 +1,119 @@
+const LEDGER_HEADING = '[Gezel caller-owned action ledger]';
+const MAX_PATHS = 12;
+/**
+ * Attach a compact, transcript-derived file-action receipt to the final tool
+ * result in a caller-owned loop. The receipt deliberately describes only
+ * structured calls for which the caller supplied a result. It does not infer
+ * filesystem state, promote assistant narration into action, or enumerate
+ * opaque shell-command side effects.
+ */
+export function appendCallerOwnedActionLedger(input) {
+    const last = input.priorMessages.at(-1);
+    if (!last || last.role !== 'tool')
+        return { input, receiptCount: 0 };
+    let latestUserIndex = -1;
+    for (let index = input.priorMessages.length - 1; index >= 0; index -= 1) {
+        if (input.priorMessages[index]?.role === 'user') {
+            latestUserIndex = index;
+            break;
+        }
+    }
+    const calls = new Map();
+    const completed = new Set();
+    for (let index = latestUserIndex + 1; index < input.priorMessages.length; index += 1) {
+        const message = input.priorMessages[index];
+        if (message.role === 'assistant' && 'toolCalls' in message) {
+            for (const call of message.toolCalls)
+                calls.set(call.id, call);
+        }
+        else if (message.role === 'tool') {
+            completed.add(message.toolCallId);
+        }
+    }
+    const receipts = [];
+    for (const [id, call] of calls) {
+        if (!completed.has(id) || !isStructuredFileMutation(call.name))
+            continue;
+        receipts.push({ call, paths: extractPathArguments(call.arguments) });
+    }
+    if (receipts.length === 0)
+        return { input, receiptCount: 0 };
+    const lines = [
+        LEDGER_HEADING,
+        'The caller returned a result for these structured file-mutation calls in the current user turn:',
+    ];
+    for (const { call, paths } of receipts) {
+        const target = paths.length > 0
+            ? paths.map((path) => JSON.stringify(path)).join(', ')
+            : '(target not present in structured arguments)';
+        lines.push(`- ${call.name} (${call.id}) -> ${target}`);
+    }
+    lines.push('Each result confirms only that its matching call returned; use the result text to determine success or failure.', 'Planned or narrated actions are not receipts. Shell-command side effects are not enumerated here; inspect files when they matter.', 'Before claiming completion, compare the requested files with these receipts and make additional tool calls for anything not yet covered.');
+    const ledger = lines.join('\n');
+    const priorMessages = input.priorMessages.map((message, index) => {
+        if (index !== input.priorMessages.length - 1 || message.role !== 'tool')
+            return message;
+        if (message.content.includes(LEDGER_HEADING))
+            return message;
+        return {
+            ...message,
+            content: message.content ? `${message.content}\n\n${ledger}` : ledger,
+        };
+    });
+    return { input: { ...input, priorMessages }, ledger, receiptCount: receipts.length };
+}
+function isStructuredFileMutation(name) {
+    const normalized = name
+        .split(/[.:/]/u)
+        .at(-1)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, '');
+    return (/(?:write|edit|patch|replace|append|rename|move|copy|delete|remove|unlink|mkdir|touch)/u.test(normalized) || normalized === 'rm');
+}
+function extractPathArguments(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return [];
+    const pathKeys = new Set([
+        'path',
+        'filepath',
+        'filename',
+        'targetpath',
+        'destination',
+        'dest',
+        'sourcepath',
+        'oldpath',
+        'newpath',
+        'directory',
+        'dir',
+        'from',
+        'to',
+    ]);
+    const paths = [];
+    const visit = (value, depth) => {
+        if (!value || typeof value !== 'object' || depth > 3 || paths.length >= MAX_PATHS)
+            return;
+        for (const [key, nested] of Object.entries(value)) {
+            const normalizedKey = key.toLowerCase().replace(/[^a-z0-9]+/gu, '');
+            if (pathKeys.has(normalizedKey) &&
+                typeof nested === 'string' &&
+                nested.length > 0 &&
+                nested.length <= 4096) {
+                paths.push(nested);
+            }
+            else if (typeof nested === 'object') {
+                visit(nested, depth + 1);
+            }
+            if (paths.length >= MAX_PATHS)
+                break;
+        }
+    };
+    visit(parsed, 0);
+    return [...new Set(paths)];
+}

package/dist/http/openai-compat/apple-model.d.ts

@@ -0,0 +1,3 @@
+import type { AppModel } from '@bendyline/gezel/app-models';
+/** Inventory owns system readiness, so embedders never speak the native helper protocol. */
+export declare function appleSystemModel(created: number): Promise<AppModel[]>;

package/dist/http/openai-compat/apple-model.js

@@ -0,0 +1,44 @@
+import { appleFoundationModelsStatus } from '../../providers/apple-foundation-models/status.js';
+/** Inventory owns system readiness, so embedders never speak the native helper protocol. */
+export async function appleSystemModel(created) {
+    const status = await appleFoundationModelsStatus();
+    if (!status.supported || !status.installed)
+        return [];
+    return [
+        {
+            id: 'apple-foundation-models:apple-foundation-models',
+            object: 'model',
+            created,
+            owned_by: 'apple-foundation-models',
+            name: 'Apple Intelligence',
+            locality: 'on-device',
+            availability: status.available ? 'available' : 'unavailable',
+            preparation: 'system-settings',
+            ...(status.runtime
+                ? {
+                    context_window: status.runtime.contextTokens,
+                    // Every reply stops here (1,024 tokens) whatever `max_tokens`
+                    // asks for, which is also the cap with none: size work to it.
+                    max_output_tokens: status.runtime.maxOutputTokens,
+                    default_output_tokens: status.runtime.maxOutputTokens,
+                    capabilities: {
+                        text: true,
+                        tools: true,
+                        // `response_format: json_schema` runs on Apple's guided generation.
+                        structuredOutput: status.runtime.modelCapabilities?.guidedGeneration ?? true,
+                        // The helper carries text and tools only.
+                        images: false,
+                        foregroundOnly: false,
+                    },
+                }
+                : {}),
+            ...(!status.available
+                ? {
+                    unavailable_reason: status.reason ?? 'Apple Intelligence is not ready. Check System Settings.',
+                    reason_code: 'system_model_unavailable',
+                    recovery_actions: ['open-system-settings'],
+                }
+                : {}),
+        },
+    ];
+}

package/dist/http/openai-compat/caller-owned-profile.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedModelProfile } from '../../model-profile/types.js';
+/**
+ * Keep model/provider compatibility behaviors while removing interventions
+ * whose recovery contract only makes sense inside a persisted Gezel chat.
+ * Returns the original object when no filtering is necessary.
+ */
+export declare function profileForCallerOwnedInference(profile: ResolvedModelProfile): ResolvedModelProfile;

package/dist/http/openai-compat/caller-owned-profile.js

@@ -0,0 +1,18 @@
+/**
+ * Behaviors which assume Gezel owns the surrounding agent/tool loop.
+ *
+ * Connected-app inference is deliberately different: Codex, Pi, OpenCode, or
+ * an Ollama client owns its transcript, tools, retries, and completion policy.
+ * Provider compatibility behaviors remain valuable there, but Gezel must not
+ * abort a turn because the caller's model has not used a tool soon enough.
+ */
+const GEZEL_OWNED_LOOP_BEHAVIORS = new Set(['turn.ramble-detection']);
+/**
+ * Keep model/provider compatibility behaviors while removing interventions
+ * whose recovery contract only makes sense inside a persisted Gezel chat.
+ * Returns the original object when no filtering is necessary.
+ */
+export function profileForCallerOwnedInference(profile) {
+    const behaviors = profile.behaviors.filter((entry) => !GEZEL_OWNED_LOOP_BEHAVIORS.has(entry.id));
+    return behaviors.length === profile.behaviors.length ? profile : { ...profile, behaviors };
+}

package/dist/http/openai-compat/chat-progress.d.ts

@@ -0,0 +1,9 @@
+import type { AppChatProgress } from '@bendyline/gezel/app-models';
+import type { EnginePhaseEvent } from '@bendyline/gezel/local-loop';
+/** Phase changes and at most four activity/counter updates per second. */
+export declare function createChatProgressReporter(emit: (progress: AppChatProgress) => void, now?: () => number): {
+    start(): void;
+    flush(): void;
+    activity(phase: "reasoning" | "generating"): void;
+    engine(event: EnginePhaseEvent): void;
+};

package/dist/http/openai-compat/chat-progress.js

@@ -0,0 +1,69 @@
+function finite(value, max) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= max
+        ? value
+        : null;
+}
+/** Phase changes and at most four activity/counter updates per second. */
+export function createChatProgressReporter(emit, now = Date.now) {
+    let current = {
+        phase: 'starting',
+        percent: null,
+        outputTokens: null,
+        tokensPerSecond: null,
+    };
+    let last = null;
+    let lastAt = Number.NEGATIVE_INFINITY;
+    let activityPhase = null;
+    const flush = (force = false, activity = false) => {
+        if (!activity && JSON.stringify(last) === JSON.stringify(current))
+            return;
+        const at = now();
+        if (!force && current.phase === last?.phase && at - lastAt < 250)
+            return;
+        last = { ...current };
+        lastAt = at;
+        emit(last);
+    };
+    return {
+        start() {
+            flush(true);
+        },
+        flush() {
+            flush(true);
+        },
+        activity(phase) {
+            activityPhase = phase;
+            current = { ...current, phase, percent: null };
+            flush(false, true);
+        },
+        engine(event) {
+            let phase;
+            if (event.engineQueue?.state === 'waiting' || event.engineQueue?.state === 'paused') {
+                phase = 'queued';
+            }
+            else if (event.phase === 'generating') {
+                phase = activityPhase ?? 'generating';
+            }
+            else if (event.phase === 'starting' ||
+                event.phase === 'loading_model' ||
+                event.phase === 'prefill') {
+                phase = event.phase;
+                activityPhase = null;
+            }
+            else {
+                return;
+            }
+            const fraction = finite(event.progress, 1);
+            const count = finite(event.outputTokens, Number.MAX_SAFE_INTEGER);
+            current = {
+                phase,
+                percent: (phase === 'prefill' || phase === 'loading_model') && fraction !== null
+                    ? fraction * 100
+                    : null,
+                outputTokens: count !== null && Number.isSafeInteger(count) ? count : current.outputTokens,
+                tokensPerSecond: finite(event.tokensPerSec, 10_000_000) ?? current.tokensPerSecond,
+            };
+            flush(false, true);
+        },
+    };
+}

package/dist/http/openai-compat/chat-target.d.ts

@@ -0,0 +1,76 @@
+import { type GezelDetail } from '@bendyline/gezel';
+import type { ProviderName } from '../../providers/types.js';
+import type { InferenceContext as ServiceContext } from '../inference-context.js';
+/**
+ * Uniform target the `/v1/chat/completions` route uses to drive a
+ * session. Whether the caller supplied a raw `<provider>:<model>` id
+ * or a `gezel:<role>-<name>` reference, the route only deals with
+ * this shape after the resolve step.
+ */
+export interface ChatTarget {
+    provider: ProviderName;
+    /** Resolved persisted gezel identity, present only for persona-backed routes. */
+    gezelId?: string;
+    /** Provider-native model id; undefined for caller of `<provider>` bare default. */
+    model: string | undefined;
+    /**
+     * Text prepended to the system message before any caller-supplied
+     * `system` entries. Carries the gezel's persona (`about.md` body)
+     * for `gezel:` routes; an empty string for raw model routes.
+     */
+    systemPrefix: string;
+    /**
+     * The gezel's frontmatter tuning knobs, present only for `gezel:`
+     * routes. Fed into `ChatManager.resolveModelSessionDefaults` so a
+     * gezel-targeted `/v1` request applies the same per-gezel sampling
+     * overrides, tuning-profile pick, and reasoning effort a UI session
+     * on that gezel would.
+     */
+    tuningOverrides?: {
+        tuning?: NonNullable<GezelDetailForTarget['parsed']>['frontmatter']['tuning'];
+        tuningProfileId?: string;
+        suggestedProfileId?: string;
+        reasoningEffort?: string;
+    };
+}
+/** Structural slice of `Store.getGezel`'s return the target resolver reads. */
+type GezelDetailForTarget = GezelDetail;
+export type ChatTargetInput = {
+    kind: 'gezel';
+    ref: string;
+} | {
+    kind: 'model';
+    provider: ProviderName;
+    model: string | undefined;
+};
+/**
+ * Pick the gezel that guarantees a persona-backed fallback for public
+ * inference requests.
+ *
+ * The explicit Connected Apps choice wins. When it is unset or stale,
+ * the install's Meester is the natural front door; the first available
+ * gezel is the final recovery path for older or partially migrated
+ * homes. A healthy store always has at least a Meester, but returning
+ * `null` keeps callers honest if the home is temporarily empty.
+ */
+export declare function resolveFallbackGezelId(ctx: ServiceContext, preferredGezelId?: string): Promise<string | null>;
+/**
+ * Resolve a {@link ChatTargetInput} into a concrete {@link ChatTarget}.
+ *
+ * Gezel routing:
+ *   - The `ref` may be the advertised `<role>-<name>` alias, the gezel's
+ *     persisted id, or its name (case-insensitive). Id wins on collision.
+ *   - The gezel's frontmatter `provider` + `model` are honored when
+ *     present; otherwise we delegate to {@link ChatManager.providerForGezel}
+ *     so the install-level default applies (same path
+ *     {@link ChatManager.oneShotCompletion} uses).
+ *   - `about.md` becomes the system prefix so the gezel's voice steers
+ *     the response. Tools / MCP wiring are NOT attached today —
+ *     tool calling through `/v1` is out of scope until the ephemeral
+ *     MCP bridge phase lands.
+ *
+ * Throws when the gezel can't be found so the route can map to a
+ * `404 gezel_not_found`.
+ */
+export declare function resolveChatTarget(input: ChatTargetInput, ctx: ServiceContext): Promise<ChatTarget>;
+export {};

package/dist/http/openai-compat/chat-target.js

@@ -0,0 +1,97 @@
+import { externalGezelModelId } from '@bendyline/gezel';
+/**
+ * Pick the gezel that guarantees a persona-backed fallback for public
+ * inference requests.
+ *
+ * The explicit Connected Apps choice wins. When it is unset or stale,
+ * the install's Meester is the natural front door; the first available
+ * gezel is the final recovery path for older or partially migrated
+ * homes. A healthy store always has at least a Meester, but returning
+ * `null` keeps callers honest if the home is temporarily empty.
+ */
+export async function resolveFallbackGezelId(ctx, preferredGezelId) {
+    if (!ctx.store.getGezel || !ctx.store.listGezels)
+        return null;
+    const config = await ctx.store.readConfig().catch(() => ({}));
+    const candidates = [preferredGezelId, config.meesterGezelId].filter((id, index, ids) => Boolean(id) && ids.indexOf(id) === index);
+    for (const id of candidates) {
+        const gezel = await ctx.store.getGezel(id).catch(() => null);
+        if (gezel)
+            return gezel.id;
+    }
+    const gezels = await ctx.store.listGezels().catch(() => []);
+    return gezels[0]?.id ?? null;
+}
+/**
+ * Resolve a {@link ChatTargetInput} into a concrete {@link ChatTarget}.
+ *
+ * Gezel routing:
+ *   - The `ref` may be the advertised `<role>-<name>` alias, the gezel's
+ *     persisted id, or its name (case-insensitive). Id wins on collision.
+ *   - The gezel's frontmatter `provider` + `model` are honored when
+ *     present; otherwise we delegate to {@link ChatManager.providerForGezel}
+ *     so the install-level default applies (same path
+ *     {@link ChatManager.oneShotCompletion} uses).
+ *   - `about.md` becomes the system prefix so the gezel's voice steers
+ *     the response. Tools / MCP wiring are NOT attached today —
+ *     tool calling through `/v1` is out of scope until the ephemeral
+ *     MCP bridge phase lands.
+ *
+ * Throws when the gezel can't be found so the route can map to a
+ * `404 gezel_not_found`.
+ */
+export async function resolveChatTarget(input, ctx) {
+    if (input.kind === 'model') {
+        return { provider: input.provider, model: input.model, systemPrefix: '' };
+    }
+    const gezel = await loadGezelByRef(input.ref, ctx);
+    if (!gezel) {
+        throw new Error(`gezel "${input.ref}" not found`);
+    }
+    if (!ctx.chat.providerForGezel)
+        throw new Error('Persona routing is unavailable');
+    const provider = await ctx.chat.providerForGezel(gezel.id);
+    const config = await ctx.store
+        .readConfig()
+        .catch(() => ({}));
+    const model = gezel.parsed.frontmatter.model ?? config.defaultModel?.[provider];
+    const persona = gezel.about?.trim() ?? '';
+    const fm = gezel.parsed.frontmatter;
+    return {
+        provider,
+        gezelId: gezel.id,
+        model,
+        systemPrefix: persona,
+        tuningOverrides: {
+            ...(fm.tuning ? { tuning: fm.tuning } : {}),
+            ...(fm.tuningProfile ? { tuningProfileId: fm.tuningProfile } : {}),
+            ...(fm.suggestedTuningProfile ? { suggestedProfileId: fm.suggestedTuningProfile } : {}),
+            ...(fm.reasoningEffort ? { reasoningEffort: fm.reasoningEffort } : {}),
+        },
+    };
+}
+async function loadGezelByRef(ref, ctx) {
+    if (!ctx.store.listGezels || !ctx.store.getGezel)
+        return null;
+    // Resolve against the canonical roster before touching the filesystem.
+    // On a case-insensitive volume, getGezel("Bram") can otherwise open the
+    // directory whose real id is "bram" and hydrate the caller's spelling as
+    // the id. That leaks a display name into queue/session identity.
+    const list = await ctx.store.listGezels().catch(() => []);
+    const byId = list.find((g) => g.id === ref);
+    if (byId)
+        return ctx.store.getGezel(byId.id).catch(() => null);
+    // Fall back to a case-insensitive name match. Id still wins on collision.
+    const lower = ref.toLowerCase();
+    const summary = list.find((g) => g.name.toLowerCase() === lower);
+    if (summary)
+        return ctx.store.getGezel(summary.id).catch(() => null);
+    // Match the human-readable alias advertised by /v1/models and local
+    // harness integrations (for example, `gezel:developer-sipho`).
+    const byExternalModelId = list.find((g) => externalGezelModelId(g).slice('gezel:'.length) === lower);
+    if (byExternalModelId)
+        return ctx.store.getGezel(byExternalModelId.id).catch(() => null);
+    // Project-local gezels do not appear in the global roster. Preserve the
+    // existing explicit-id path for their encoded ids.
+    return ctx.store.getGezel(ref).catch(() => null);
+}

package/dist/http/openai-compat/embeddings.d.ts

@@ -0,0 +1,37 @@
+import type { InferenceContext } from '../inference-context.js';
+/**
+ * Names the on-device text embedder whichever model it is configured to run.
+ * Persona ids are `gezel:<role>-<name>` and always contain a hyphen, so this
+ * can never collide with one.
+ */
+export declare const LOCAL_EMBEDDING_MODEL_ALIAS = "gezel:embeddings";
+/** OpenAI's own per-request input limit; one caller must not monopolize the shared embed worker. */
+export declare const MAX_EMBEDDING_INPUTS = 2048;
+/**
+ * Whether `model` addresses the on-device embedder: the alias, the configured
+ * model id (`Xenova/bge-small-en-v1.5`), or its bare name (`bge-small-en-v1.5`,
+ * the form Ollama clients send).
+ */
+export declare function isLocalEmbeddingModel(model: string): boolean;
+export type EmbeddingsOutcome = {
+    ok: true;
+    vectors: number[][];
+    /** The model that produced the vectors: the embedder's id for the local path. */
+    model: string;
+    inputTokens: number;
+} | {
+    ok: false;
+    status: 400 | 404 | 500 | 503;
+    code: 'model_not_found' | 'embeddings_not_supported' | 'embeddings_unavailable' | 'provider_error';
+    message: string;
+};
+/**
+ * Embed `input` for the OpenAI and Ollama embedding routes.
+ *
+ * The local path uses passage-side embedding (`embedBatch`): these APIs do not
+ * say whether a text is a query or a document, and bge needs no passage prefix.
+ * A chat model is never silently swapped for the embedder — vectors from a
+ * different model would corrupt the caller's index — so a provider without
+ * `createEmbedding` gets an error that names the alias instead.
+ */
+export declare function createEmbeddings(ctx: Pick<InferenceContext, 'chat'>, model: string, input: string | string[]): Promise<EmbeddingsOutcome>;