@cyrilmarin/dsh-lemonade 0.2.1

package/lib/index.js

@@ -0,0 +1,263 @@
+import { INVALID_CREDENTIAL_CODE, LlmError, RetryPolicySchema, assertUsableApiKey, normalizeApiKey, resolveRetryPolicy, } from '@deepseek-ai/dsh-llm';
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment';
+import { deepEqualJson, installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings';
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout';
+import z from '@deepseek-ai/schemastery';
+import { DEFAULT_BASE_URL, DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, LemonadeAdapter, discoverModels, } from './adapter.js';
+import { API_ROUTE, createLemonadeApiHandler } from './server-api.js';
+/** Short plugin name used in logs and configuration surfaces. */
+export const name = 'llm-lemonade';
+/** The provider route this plugin registers. */
+export const PROVIDER = 'lemonade';
+/** Hard service dependency: the LLM registry seat. */
+export const inject = ['llm'];
+/** Settings namespace this plugin owns. */
+export const NS = settingsNamespace('llm-lemonade');
+/** Environment variable naming this server's endpoint, honored from trusted layers only. */
+export const BASE_URL_ENV = 'LEMONADE_BASE_URL';
+/** Default environment variable naming the optional API key. */
+export const DEFAULT_API_KEY_ENV = 'LEMONADE_API_KEY';
+/** Default environment variable naming the optional admin API key (internal endpoints). */
+export const DEFAULT_ADMIN_API_KEY_ENV = 'LEMONADE_ADMIN_API_KEY';
+/** The static advisory model catalog schema (user-pinned entries). */
+export const catalogModel = z.object({
+    id: z.string().required(),
+    name: z.string(),
+    description: z.string(),
+    contextWindow: z.number().step(1).min(1),
+    maxTokens: z.number().step(1).min(1),
+    vision: z.boolean(),
+});
+/**
+ * Resolved plugin configuration schema. All fields except `baseURL` have
+ * defaults; `baseURL` itself can come from `LEMONADE_BASE_URL` when unset.
+ */
+export const Config = z.object({
+    baseURL: z.string(),
+    apiKeyEnv: z.string().role('credential-ref').default(DEFAULT_API_KEY_ENV),
+    adminApiKeyEnv: z.string().role('credential-ref').default(DEFAULT_ADMIN_API_KEY_ENV),
+    requireAuth: z.boolean().default(false),
+    defaultContextWindow: z.number().step(1).min(1).default(DEFAULT_CONTEXT_WINDOW),
+    maxTokens: z.number().step(1).min(1).default(DEFAULT_MAX_TOKENS),
+    models: z.array(catalogModel).default([]),
+    streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
+    retryPolicy: RetryPolicySchema,
+});
+/** Validate and detach the advisory model catalog. */
+export function resolveModels(models) {
+    const seen = new Set();
+    return (models ?? []).map((model) => {
+        if (model.id.length === 0)
+            throw new Error('llm-lemonade: catalog model ids must be non-empty');
+        if (model.name !== undefined && model.name.length === 0) {
+            throw new Error(`llm-lemonade: catalog model "${model.id}" has an empty name`);
+        }
+        if (model.contextWindow !== undefined && (!Number.isInteger(model.contextWindow) || model.contextWindow <= 0)) {
+            throw new Error(`llm-lemonade: catalog model "${model.id}" contextWindow must be a positive integer`);
+        }
+        if (model.maxTokens !== undefined && (!Number.isInteger(model.maxTokens) || model.maxTokens <= 0)) {
+            throw new Error(`llm-lemonade: catalog model "${model.id}" maxTokens must be a positive integer`);
+        }
+        if (seen.has(model.id))
+            throw new Error(`llm-lemonade: duplicate catalog model "${model.id}"`);
+        seen.add(model.id);
+        return {
+            id: model.id,
+            ...(model.name !== undefined ? { name: model.name } : {}),
+            ...(model.description !== undefined ? { description: model.description } : {}),
+            ...(model.contextWindow !== undefined ? { contextWindow: model.contextWindow } : {}),
+            ...(model.maxTokens !== undefined ? { maxTokens: model.maxTokens } : {}),
+            ...(model.vision !== undefined ? { vision: model.vision } : {}),
+        };
+    });
+}
+function normalizeBaseURL(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        throw new Error('llm-lemonade: baseURL must not be empty');
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        throw new Error(`llm-lemonade: baseURL cannot be parsed: "${trimmed}"`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`llm-lemonade: baseURL must use http or https, got "${trimmed}"`);
+    }
+    // The path prefix is ALWAYS /api: any configured path (including a
+    // root base or a legacy trailing /v1) is normalized to scheme://host/api,
+    // and every endpoint builder appends exactly one /v1 on top.
+    return url.protocol + '//' + url.host + '/api';
+}
+/**
+ * The explicit step from raw config to validated connection facts.
+ * Programmatic construction may bypass Schemastery normalization, so every
+ * default and bound is re-judged here — for the composition entry at load
+ * (fail loud) and for each settings snapshot at its first use.
+ *
+ * @param config - raw plugin config or resolved settings snapshot.
+ * @param environment - this run's environment layers, when the product CLI provided them.
+ * @returns validated connection facts plus the credential reference.
+ */
+export function resolveAdapterOptions(config, environment) {
+    if (config.defaultContextWindow !== undefined && (!Number.isInteger(config.defaultContextWindow) || config.defaultContextWindow <= 0)) {
+        throw new Error('llm-lemonade: defaultContextWindow must be a positive integer');
+    }
+    if (config.maxTokens !== undefined && (!Number.isSafeInteger(config.maxTokens) || config.maxTokens <= 0)) {
+        throw new Error('llm-lemonade: maxTokens must be a positive safe integer');
+    }
+    const streamIdleTimeoutMs = config.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+    if (!Number.isFinite(streamIdleTimeoutMs) || streamIdleTimeoutMs <= 0 || streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) {
+        throw new Error(`llm-lemonade: streamIdleTimeoutMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+    }
+    const rawBase = config.baseURL ?? environment?.get(BASE_URL_ENV)?.value ?? DEFAULT_BASE_URL;
+    return {
+        apiKeyEnv: credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV),
+        adminApiKeyEnv: credentialRef(config.adminApiKeyEnv ?? DEFAULT_ADMIN_API_KEY_ENV),
+        baseURL: normalizeBaseURL(rawBase),
+        requireAuth: config.requireAuth === true,
+        defaultContextWindow: config.defaultContextWindow ?? DEFAULT_CONTEXT_WINDOW,
+        maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS,
+        models: resolveModels(config.models),
+        streamIdleTimeoutMs,
+        retryPolicy: resolveRetryPolicy(config.retryPolicy, 'llm-lemonade: retryPolicy'),
+    };
+}
+/** Resolve the optional bearer token, enforcing `requireAuth` when configured. */
+function makeResolveApiKey(ctx, options) {
+    return async () => {
+        const connection = options();
+        const ref = connection.apiKeyEnv;
+        let value;
+        const credentials = ctx.get('credentials');
+        if (credentials !== undefined)
+            value = (await credentials.resolve(ref))?.value;
+        if (value === undefined)
+            value = launchEnvironmentOf(ctx).get(ref)?.value;
+        if (value === undefined || value.length === 0) {
+            if (connection.requireAuth) {
+                throw new LlmError(`llm-lemonade: no API key for provider route "${PROVIDER}"; store ${String(ref)} through the credentials service (the web Models page writes it), or export ${String(ref)} in the launching environment`, 'MISSING_CREDENTIAL');
+            }
+            return undefined;
+        }
+        return assertUsableApiKey(value, 'llm-lemonade', String(ref));
+    };
+}
+/**
+ * Register a {@link LemonadeAdapter} for the `lemonade` provider route.
+ * See the module header for the layering story.
+ */
+export function apply(ctx, config) {
+    let current = () => config;
+    let lastRaw;
+    let lastGood;
+    const options = () => {
+        const raw = current();
+        if (raw === lastRaw && lastGood !== undefined)
+            return lastGood;
+        try {
+            const next = resolveAdapterOptions(raw, launchEnvironmentOf(ctx));
+            lastRaw = raw;
+            lastGood = next;
+            return next;
+        }
+        catch (error) {
+            if (lastGood === undefined)
+                throw error;
+            lastRaw = raw;
+            ctx.logger.error('llm-lemonade: keeping the last good configuration after an invalid settings section');
+            ctx.logger.error(error);
+            return lastGood;
+        }
+    };
+    options();
+    const resolveApiKey = makeResolveApiKey(ctx, options);
+    const adapter = new LemonadeAdapter({
+        options,
+        resolveApiKey,
+        resolveAttachments: () => ctx.get('attachments'),
+    });
+    ctx.llm.registerConfigurableProviders([
+        { provider: PROVIDER, displayName: 'Lemonade', settingsNs: NS, settingsPath: [] },
+    ]);
+    const registration = ctx.llm.registerAdapter([PROVIDER], adapter);
+    let registeredPolicy = options().retryPolicy;
+    const ensureRegistrationFacts = () => {
+        const policy = options().retryPolicy;
+        if (deepEqualJson(policy, registeredPolicy))
+            return;
+        registration.replace([PROVIDER]);
+        registeredPolicy = policy;
+    };
+    ctx.llm.registerModelDiscovery(NS, async (request) => {
+        const baseURL = request.baseURL !== undefined && request.baseURL.length > 0 ? normalizeBaseURL(request.baseURL) : options().baseURL;
+        let apiKey;
+        if (request.apiKey !== undefined) {
+            const checked = normalizeApiKey(request.apiKey);
+            if (!checked.ok) {
+                throw new LlmError(checked.reason === 'empty'
+                    ? 'this server\'s API key is blank; enter it on the Models page, or clear it to probe unauthenticated'
+                    : 'this server\'s API key contains characters no HTTP header can carry; paste the raw key only', INVALID_CREDENTIAL_CODE);
+            }
+            apiKey = checked.value;
+        }
+        else {
+            apiKey = await resolveApiKey();
+        }
+        return discoverModels(baseURL, apiKey, request.signal);
+    });
+    // Lemonade-specific API proxy: browser client half calls these routes
+    // same-origin; the keys are resolved host-side and never reach the browser.
+    // Per-endpoint key selection (regular vs admin) lives in server-api.ts.
+    const resolveKey = async (ref) => {
+        let value;
+        const credentials = ctx.get('credentials');
+        if (credentials !== undefined)
+            value = (await credentials.resolve(ref))?.value;
+        if (value === undefined)
+            value = launchEnvironmentOf(ctx).get(ref)?.value;
+        if (value === undefined || value.length === 0)
+            return undefined;
+        return assertUsableApiKey(value, 'llm-lemonade', String(ref));
+    };
+    const apiCfg = {
+        baseURL: () => options().baseURL,
+        requireAuth: () => options().requireAuth,
+        apiKeyRef: () => options().apiKeyEnv,
+        adminApiKeyRef: () => options().adminApiKeyEnv,
+        resolveKey,
+    };
+    // Register the proxy route once the webServer service is available. It is
+    // mounted late (after the llm service this plugin depends on), so a strict
+    // ctx.get() at apply time is usually undefined; instead grab it eagerly
+    // (non-strict) and fall back to binding the route when 'webServer' is
+    // provided. Absent webServer (headless profile), nothing is registered and
+    // the host half keeps working as a plain model provider.
+    let routesRegistered = false;
+    const registerRoutes = () => {
+        if (routesRegistered)
+            return;
+        const server = ctx.get('webServer', false);
+        if (server === undefined)
+            return;
+        routesRegistered = true;
+        ctx.effect(() => server.register({ kind: 'prefix', path: API_ROUTE, handler: createLemonadeApiHandler(apiCfg) }));
+    };
+    registerRoutes();
+    if (!routesRegistered) {
+        ctx.on('internal/service', (name) => {
+            if (name === 'webServer')
+                registerRoutes();
+        });
+    }
+    installSettingsSection(ctx, NS, Config, config, {
+        setSource: (source) => {
+            current = source;
+        },
+        onChange: ensureRegistrationFacts,
+    });
+}
+export { LemonadeAdapter };
+//# sourceMappingURL=index.js.map

package/lib/serialize.js

@@ -0,0 +1,113 @@
+import { contentHasImage, LlmError } from '@deepseek-ai/dsh-llm';
+/** Join the text blocks of a message (user and tool-result content). */
+function flattenText(blocks) {
+    return blocks
+        .filter((block) => block.type === 'text')
+        .map((block) => block.text)
+        .join('');
+}
+/**
+ * Serialize a user message's content. Text-only messages stay a plain string;
+ * a message carrying one or more image blocks becomes an array of parts that
+ * preserves block order.
+ */
+async function serializeUserContent(blocks, resolveImage, signal) {
+    const parts = [];
+    let hasImage = false;
+    for (const block of blocks) {
+        if (block.type === 'text') {
+            parts.push({ type: 'text', text: block.text });
+        }
+        else if (block.type === 'image') {
+            hasImage = true;
+            parts.push({ type: 'image_url', image_url: { url: await resolveImage(block.attachment, signal) } });
+        }
+        // tool-result blocks are expanded into standalone tool messages by the caller.
+    }
+    if (!hasImage)
+        return parts.map((part) => (part.type === 'text' ? part.text : '')).join('');
+    return parts;
+}
+/** Serialize one assistant message (text + tool calls; reasoning dropped). */
+function serializeAssistant(message) {
+    const text = flattenText(message.content);
+    const toolCalls = message.content
+        .filter((block) => block.type === 'tool-call')
+        .map((block) => ({
+        id: block.id,
+        type: 'function',
+        function: { name: block.name, arguments: block.arguments },
+    }));
+    if (toolCalls.length === 0)
+        return { role: 'assistant', content: text };
+    // OpenAI canonical form: content is null when the turn is tool calls only.
+    return { role: 'assistant', content: text.length > 0 ? text : null, tool_calls: toolCalls };
+}
+/**
+ * Serialize the conversation in order. A mixed user message contributes its
+ * text/image content first and each tool result as a standalone wire message
+ * after it.
+ *
+ * @param messages - the harness conversation, in order.
+ * @param resolveImage - resolves image blocks; required whenever one is present.
+ * @param signal - cancellation forwarded to attachment reads.
+ */
+async function serializeMessages(messages, resolveImage, signal) {
+    const wire = [];
+    for (const message of messages) {
+        if (message.role === 'system') {
+            wire.push({ role: 'system', content: flattenText(message.content) });
+            continue;
+        }
+        if (message.role === 'assistant') {
+            wire.push(serializeAssistant(message));
+            continue;
+        }
+        const toolResults = message.content.filter((block) => block.type === 'tool-result');
+        const content = await serializeUserContent(message.content, resolveImage, signal);
+        const hasText = typeof content === 'string' ? content.length > 0 : true;
+        if (hasText || toolResults.length === 0)
+            wire.push({ role: 'user', content });
+        for (const result of toolResults) {
+            wire.push({ role: 'tool', tool_call_id: result.toolCallId, content: flattenText(result.content) || '(no output)' });
+        }
+    }
+    return wire;
+}
+/**
+ * Build the full wire request body. Always streaming with usage reporting on
+ * (Lemonade's llamacpp backends honor `stream_options.include_usage`; servers
+ * that ignore it simply never send a usage chunk, and the translate step
+ * tolerates that). Optional sampling fields are omitted rather than sent as
+ * null so provider defaults apply.
+ *
+ * @param options - the harness request (model, history, system, tools, sampling).
+ * @param resolveImage - resolves image blocks; `undefined` when no attachment
+ *   service is available, in which case image content is refused up front.
+ */
+export async function serializeRequest(options, resolveImage) {
+    if (resolveImage === undefined && options.messages.some((message) => contentHasImage(message.content))) {
+        throw new LlmError('The Lemonade adapter requires the attachment service to send image content.', 'UNSUPPORTED_CONTENT');
+    }
+    const messages = [];
+    if (options.system !== undefined)
+        messages.push({ role: 'system', content: options.system });
+    messages.push(...(await serializeMessages(options.messages, resolveImage ?? (() => { throw new LlmError('no image resolver', 'UNSUPPORTED_CONTENT'); }), options.signal)));
+    const tools = options.tools?.length
+        ? options.tools.map((tool) => ({
+            type: 'function',
+            function: { name: tool.name, description: tool.description, parameters: tool.parameters },
+        }))
+        : undefined;
+    return {
+        model: options.model,
+        messages,
+        stream: true,
+        stream_options: { include_usage: true },
+        ...(tools !== undefined ? { tools } : {}),
+        ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+        ...(options.maxTokens === undefined ? {} : { max_tokens: options.maxTokens }),
+        ...(options.stop !== undefined ? { stop: options.stop } : {}),
+    };
+}
+//# sourceMappingURL=serialize.js.map