@cyrilmarin/dsh-lemonade 0.2.1

package/lib/types/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * ✨ Lemonade Server LLM provider plugin for the DeepSeek Harness.
+ *
+ * Registers a `LemonadeAdapter` for the `lemonade` provider route on
+ * `ctx.llm`, speaking the OpenAI-compatible Chat Completions API at a local
+ * (or remote) Lemonade Server. Connection facts resolve per request instead of
+ * at load: the plugin layers its `cordis.yml` entry config under the optional
+ * `llm-lemonade` user-settings section (`ctx.settings`) and resolves the
+ * optional API key through the credential seam (`ctx.credentials`) or the
+ * launch environment, so a changed base URL, catalog, or key reaches the next
+ * request without a restart, while an in-flight stream keeps the facts it
+ * started with. The one registration-captured fact — the retry policy —
+ * re-registers the route in place when it changes.
+ *
+ * @module dsh-lemonade-provider
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { RetryPolicyConfig } from '@deepseek-ai/dsh-llm';
+import type { LaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment';
+import z from '@deepseek-ai/schemastery';
+import { LemonadeAdapter } from './adapter.js';
+import type { LemonadeCatalogModel, LemonadeOptions } from './adapter.js';
+/** Short plugin name used in logs and configuration surfaces. */
+export declare const name = "llm-lemonade";
+/** The provider route this plugin registers. */
+export declare const PROVIDER = "lemonade";
+/** Hard service dependency: the LLM registry seat. */
+export declare const inject: string[];
+/** Settings namespace this plugin owns. */
+export declare const NS: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+/** Environment variable naming this server's endpoint, honored from trusted layers only. */
+export declare const BASE_URL_ENV = "LEMONADE_BASE_URL";
+/** Default environment variable naming the optional API key. */
+export declare const DEFAULT_API_KEY_ENV = "LEMONADE_API_KEY";
+/** Default environment variable naming the optional admin API key (internal endpoints). */
+export declare const DEFAULT_ADMIN_API_KEY_ENV = "LEMONADE_ADMIN_API_KEY";
+/** The static advisory model catalog schema (user-pinned entries). */
+export declare const catalogModel: z<Schemastery.ObjectS<{
+    id: z<string, string>;
+    name: z<string, string>;
+    description: z<string, string>;
+    contextWindow: z<number, number>;
+    maxTokens: z<number, number>;
+    vision: z<boolean, boolean>;
+}>, Schemastery.ObjectT<{
+    id: z<string, string>;
+    name: z<string, string>;
+    description: z<string, string>;
+    contextWindow: z<number, number>;
+    maxTokens: z<number, number>;
+    vision: z<boolean, boolean>;
+}>>;
+/**
+ * Resolved plugin configuration schema. All fields except `baseURL` have
+ * defaults; `baseURL` itself can come from `LEMONADE_BASE_URL` when unset.
+ */
+export declare const Config: z<LemonadeResolvedConfig>;
+/** Resolved plugin configuration (what the schema produces). */
+export interface LemonadeResolvedConfig {
+    baseURL: string;
+    apiKeyEnv: string;
+    adminApiKeyEnv: string;
+    requireAuth: boolean;
+    defaultContextWindow: number;
+    maxTokens: number;
+    models: LemonadeCatalogModel[];
+    streamIdleTimeoutMs: number;
+    retryPolicy?: RetryPolicyConfig;
+}
+/** Raw composition entry: every field optional (schema defaults apply on resolution). */
+export type LemonadeRawConfig = Partial<LemonadeResolvedConfig>;
+/** Validate and detach the advisory model catalog. */
+export declare function resolveModels(models: readonly LemonadeCatalogModel[] | undefined): LemonadeCatalogModel[];
+/**
+ * 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 declare function resolveAdapterOptions(config: LemonadeRawConfig, environment?: LaunchEnvironmentSnapshot): LemonadeOptions;
+/**
+ * Register a {@link LemonadeAdapter} for the `lemonade` provider route.
+ * See the module header for the layering story.
+ */
+export declare function apply(ctx: Context, config: LemonadeRawConfig): void;
+export { LemonadeAdapter };
+export type { LemonadeOptions } from './adapter.js';

package/lib/types/serialize.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Serialize harness messages into Lemonade's OpenAI-compatible chat
+ * completions wire format.
+ *
+ * User text is joined; user image blocks become OpenAI `image_url` data-URL
+ * parts (Lemonade serves vision models through the same endpoint); assistant
+ * text becomes `content`, tool calls become `tool_calls`, and tool results
+ * become standalone `{role: 'tool'}` messages. Reasoning blocks are not
+ * replayed on the wire: Lemonade's OpenAI route has no reasoning passback
+ * field (unlike DeepSeek's `reasoning_content`), and re-sending thinking
+ * text as plain content would corrupt the conversation.
+ *
+ * @module dsh-lemonade-provider/serialize
+ */
+import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import type { GenerateOptions } from '@deepseek-ai/dsh-llm';
+/** One OpenAI function tool call as sent on the wire. */
+export interface WireToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** OpenAI content parts for user messages that carry images. */
+export type WireContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+    };
+};
+/** One OpenAI chat-completions wire message. */
+export type WireMessage = {
+    role: 'system';
+    content: string;
+} | {
+    role: 'user';
+    content: string | WireContentPart[];
+} | {
+    role: 'assistant';
+    content: string | null;
+    tool_calls?: WireToolCall[];
+} | {
+    role: 'tool';
+    tool_call_id: string;
+    content: string;
+};
+/**
+ * Resolve one durable image reference into the data: URL sent as an
+ * `image_url` part. Provided by the adapter from the attachment service.
+ */
+export type ResolveImage = (attachment: ImageAttachmentRef, signal?: AbortSignal) => Promise<string>;
+/**
+ * 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 declare function serializeRequest(options: GenerateOptions, resolveImage: ResolveImage | undefined): Promise<Record<string, unknown>>;

package/lib/types/server-api.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Host proxy for the Lemonade-specific API (https://lemonade-server.ai/docs/api/lemonade/),
+ * mounted by src/index.ts on the dsh web server under the /dsh-lemonade/api
+ * prefix route (ctx.webServer.register). The browser client half calls these
+ * routes same-origin; the host resolves the base URL from the llm-lemonade
+ * settings section and the optional API key through the credentials seam, so
+ * the key never reaches the browser.
+ *
+ * @module dsh-lemonade-provider/server-api
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { CredentialRef } from '@deepseek-ai/dsh-credentials';
+/** Route prefix registered on ctx.webServer. */
+export declare const API_ROUTE = "/dsh-lemonade/api";
+/** Maximum accepted request body and proxied response body in bytes. */
+export declare const MAX_BODY_BYTES = 1000000;
+/** Fetch timeout for proxied Lemonade calls. */
+export declare const API_TIMEOUT_MS = 10000;
+/** Host-side connection facts the proxy resolves per request. */
+export interface LemonadeApiConfig {
+    baseURL(): string;
+    requireAuth(): boolean;
+    /** Credential reference for the regular API key (LEMONADE_API_KEY). */
+    apiKeyRef(): CredentialRef;
+    /** Credential reference for the admin API key (LEMONADE_ADMIN_API_KEY). */
+    adminApiKeyRef(): CredentialRef;
+    /**
+     * Resolve one credential reference to its current value (never throws).
+     * @param ref - the reference to resolve through the credentials seam / env.
+     * @returns the usable key, or undefined when unconfigured.
+     */
+    resolveKey(ref: CredentialRef): Promise<string | undefined>;
+}
+/** Successful wire result. */
+export interface LemonadeWireOk {
+    ok: true;
+    value: unknown;
+}
+/** Failed wire result. */
+export interface LemonadeWireError {
+    ok: false;
+    error: {
+        message: string;
+        code: string;
+        status?: number;
+    };
+}
+export type LemonadeWireResult = LemonadeWireOk | LemonadeWireError;
+/** Map a Lemonade HTTP status to a stable harness-style code. */
+export declare function mapLemonadeStatus(status: number): string;
+/**
+ * Dispatch one proxied Lemonade API call.
+ * @param cfg - connection facts (thunks resolved per call).
+ * @param method - HTTP method from the client (GET/POST/DELETE).
+ * @param op - first path segment after the route prefix.
+ * @param segments - remaining path segments after the route prefix.
+ * @param query - parsed query string.
+ * @param body - parsed request body (undefined when none).
+ * @param signal - optional caller cancellation.
+ */
+export declare function serveLemonadeApi(cfg: LemonadeApiConfig, method: string, op: string, args: readonly string[], query: URLSearchParams, body: unknown, signal?: AbortSignal): Promise<LemonadeWireResult>;
+/**
+ * Stream the Lemonade server logs (WS /logs/stream) as newline-delimited JSON
+ * to the browser. The spec: the log WebSocket shares the Realtime Audio port,
+ * discovered via /v1/health (websocket_port) — not the main HTTP port — then
+ * `ws://<host>:<port>/logs/stream`, subscribe with `{ type: 'logs.subscribe',
+ * after_seq: <int|null> }`, and the server answers `logs.snapshot` (up to
+ * 5000 retained entries) then `logs.entry` lines. Messages are relayed as-is
+ * (`{ type: 'logs.snapshot' | 'logs.entry' | 'error', ... }`); the response is
+ * held open and closed when the browser disconnects.
+ */
+/**
+ * Build the node:http handler mounting the Lemonade-specific API proxy at the
+ * /dsh-lemonade/api prefix route (ctx.webServer.register). Never throws out:
+ * every outcome is normalized to a JSON wire result.
+ */
+export declare function createLemonadeApiHandler(cfg: LemonadeApiConfig): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/lib/types/translate.d.ts

@@ -0,0 +1,10 @@
+import type { StreamChunk } from '@deepseek-ai/dsh-llm';
+/** Parse an SSE byte stream into its `data` payloads. */
+export declare function parseSse(stream: ReadableStream<Uint8Array>, onComment?: (comment: string) => void): AsyncGenerator<string>;
+/**
+ * Consume SSE data payloads (optionally ending with `[DONE]`) and yield
+ * harness StreamChunks. Malformed JSON payloads abort the stream with
+ * `MALFORMED_RESPONSE`. A `stop` (or absent) finish with no opened blocks is a
+ * degenerate provider completion and maps to an `EMPTY_RESPONSE` error finish.
+ */
+export declare function translate(payloads: AsyncIterable<string>): AsyncGenerator<StreamChunk>;

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@cyrilmarin/dsh-lemonade",
+  "description": "Lemonade Server (OpenAI-compatible) LLM provider plugin for the DeepSeek Harness",
+  "version": "0.2.1",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json",
+    "./client": {
+      "default": "./lib/client.js"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/*.js",
+    "lib/types/**/*.d.ts",
+    "src",
+    "lib/client.js"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-attachment": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.7",
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.0-rc.7"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "eventsource-parser": "^3.1.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-attachment": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.7",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@types/node": "^24.0.0",
+    "eventsource-parser": "^3.1.0",
+    "typescript": "^5.5.0",
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.0-rc.7",
+    "@types/react": "~18.3.1"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/copy-client.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node test/adapter.test.mjs && node test/server-api.test.mjs && node test/client-bundle.test.mjs lib/client.js",
+    "release": "node scripts/release.mjs",
+    "release:dry": "node scripts/release.mjs --dry-run",
+    "release:major": "node scripts/release.mjs --bump major",
+    "release:minor": "node scripts/release.mjs --bump minor",
+    "release:patch": "node scripts/release.mjs --bump patch"
+  }
+}