@alisio/plugin-openai-compatible 0.1.0-alpha.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Gutiérrez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @alisio/plugin-openai-compatible
+
+**The built-in OpenAI-compatible model provider for [Alisio](https://github.com/GustavoGutierrez/alisio).**
+Point it at any Chat Completions or Responses endpoint — OpenAI, a gateway, or a local server such
+as llama.cpp — and use it from `/connect`.
+
+## What it is
+
+A `model-provider` plugin that registers the `openai-compatible` provider with the Alisio host. It
+ships as a built-in of the `alisio` CLI and is enabled by default. Configuration and credentials
+are supplied by the Alisio provider registry; the plugin does not persist secrets itself.
+
+## Installation
+
+Preinstalled in the `alisio` CLI. For an embedded host, register it through `createApplication`'s
+`builtins` list.
+
+## Using it: `/connect`
+
+1. Run `alisio`, then `/connect` and choose **OpenAI compatible**.
+2. Fields: **Base URL** (default `https://api.openai.com/v1`), **API key** (secret, optional),
+   **API key environment variable** (default `OPENAI_API_KEY`), **API mode** (`chat` or
+   `responses`), **Authentication** (`bearer` or `none`), **Token parameter** (`max_tokens`,
+   `max_completion_tokens` or `omit`), **Stream usage** (boolean).
+3. Pick a model from the discovered catalog — or enter one manually when the endpoint exposes no
+   `GET /models` catalog (`/connect` then asks for an optional context window in tokens).
+
+The key is read from the stored credential first, then from `process.env[apiKeyEnv]`:
+
+```sh
+export OPENAI_API_KEY=...   # never put the key in config files, profiles or READMEs
+```
+
+## Features
+
+- Model discovery via `GET /models`; per-model context windows (overridable per profile).
+- Chat Completions and Responses modes; bearer or no authentication; configurable token parameter.
+- Tool calls, usage metadata, reasoning deltas and image attachments.
+- Provider-native web search available when the API mode is `responses`.
+- Legacy `provider` configuration (`baseURL`, `apiKeyEnv`, `model`, `apiMode`, `auth`,
+  `tokenParameter`, `streamUsage`) keeps working for startup and headless runs.
+
+While registered, the provider also appears in `/model` and `alisio doctor`.
+
+## Docs
+
+[Configuration](https://gustavogutierrez.github.io/alisio/configuration) ·
+[Plugins](https://gustavogutierrez.github.io/alisio/plugins).
+
+## Requirements
+
+Node.js **>= 22.16** or Bun **>= 1.4.2**.
+
+## License
+
+MIT. Maintained by Gustavo Gutiérrez Mercado. Source: <https://github.com/GustavoGutierrez/alisio> ·
+npm: <https://www.npmjs.com/settings/alisio/packages>.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { type Plugin } from "@alisio/sdk";
+export declare function createOpenAICompatiblePlugin(): Plugin;
+export type { OpenAICompatibleConfig } from "./provider.ts";
+export { OpenAICompatibleProvider } from "./provider.ts";
+declare const _default: Plugin;
+export default _default;

package/dist/index.js

@@ -0,0 +1,122 @@
+import { definePlugin, } from "@alisio/sdk";
+import { OpenAICompatibleProvider } from "./provider.js";
+import { loadVersion } from "./version.js";
+const defaults = {
+    baseURL: "https://api.openai.com/v1",
+    apiKeyEnv: "OPENAI_API_KEY",
+    model: "",
+    apiMode: "chat",
+    auth: "bearer",
+    tokenParameter: "max_tokens",
+    streamUsage: false,
+};
+const value = (request, key, fallback) => (request.profile[key] ?? request.legacy?.[key] ?? fallback);
+export function createOpenAICompatiblePlugin() {
+    return definePlugin({
+        id: "openai-compatible",
+        name: "OpenAI compatible",
+        description: "OpenAI Chat Completions or Responses compatible endpoint",
+        categories: ["model-provider"],
+        version: loadVersion(import.meta.url),
+        apiVersion: 1,
+        setup(api) {
+            api.providers.register({
+                id: "openai-compatible",
+                name: "OpenAI compatible",
+                description: "OpenAI Chat Completions or Responses compatible endpoint",
+                capabilities: { nativeWebSearch: { field: "apiMode", values: ["responses"] } },
+                fields: [
+                    {
+                        key: "baseURL",
+                        label: "Base URL",
+                        kind: "url",
+                        required: true,
+                        defaultValue: defaults.baseURL,
+                    },
+                    {
+                        key: "apiKey",
+                        label: "API key",
+                        kind: "secret",
+                        description: "Stored only in the global credentials file",
+                    },
+                    {
+                        key: "apiKeyEnv",
+                        label: "API key environment variable",
+                        kind: "text",
+                        defaultValue: defaults.apiKeyEnv,
+                        description: "Environment variable consulted when no stored API key exists; the connection remembers this name",
+                    },
+                    {
+                        key: "apiMode",
+                        label: "API mode",
+                        kind: "select",
+                        required: true,
+                        defaultValue: "chat",
+                        options: [
+                            { value: "chat", label: "Chat Completions" },
+                            { value: "responses", label: "Responses" },
+                        ],
+                    },
+                    {
+                        key: "auth",
+                        label: "Authentication",
+                        kind: "select",
+                        required: true,
+                        defaultValue: "bearer",
+                        options: [
+                            { value: "bearer", label: "Bearer token" },
+                            { value: "none", label: "None" },
+                        ],
+                    },
+                    {
+                        key: "tokenParameter",
+                        label: "Token parameter",
+                        kind: "select",
+                        required: true,
+                        defaultValue: "max_tokens",
+                        options: [
+                            { value: "max_tokens", label: "max_tokens" },
+                            { value: "max_completion_tokens", label: "max_completion_tokens" },
+                            { value: "omit", label: "Omit" },
+                        ],
+                    },
+                    {
+                        key: "streamUsage",
+                        label: "Request stream usage",
+                        kind: "boolean",
+                        defaultValue: false,
+                    },
+                ],
+                create(request) {
+                    const auth = value(request, "auth", defaults.auth);
+                    const apiKey = request.credentials.apiKey;
+                    const rawApiKeyEnv = value(request, "apiKeyEnv", defaults.apiKeyEnv);
+                    const apiKeyEnv = typeof rawApiKeyEnv === "string" && rawApiKeyEnv.trim()
+                        ? rawApiKeyEnv.trim()
+                        : defaults.apiKeyEnv;
+                    if (auth !== "none" && !apiKey && !process.env[apiKeyEnv])
+                        throw new Error("API key is required (enter one in /connect or set the configured environment variable)");
+                    const config = {
+                        baseURL: value(request, "baseURL", defaults.baseURL),
+                        apiKeyEnv,
+                        model: value(request, "model", defaults.model),
+                        apiMode: value(request, "apiMode", defaults.apiMode),
+                        auth,
+                        tokenParameter: value(request, "tokenParameter", defaults.tokenParameter),
+                        streamUsage: value(request, "streamUsage", defaults.streamUsage),
+                        ...(typeof request.profile.contextWindow === "number"
+                            ? { contextWindow: request.profile.contextWindow }
+                            : {}),
+                        ...(apiKey ? { apiKey } : {}),
+                    };
+                    const url = new URL(config.baseURL);
+                    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
+                        throw new Error("Base URL must be HTTP(S) and must not contain credentials");
+                    return new OpenAICompatibleProvider(config);
+                },
+            });
+        },
+    });
+}
+export { OpenAICompatibleProvider } from "./provider.js";
+export default createOpenAICompatiblePlugin();

package/dist/provider.d.ts

@@ -0,0 +1,23 @@
+import type { ModelInfo, ModelProvider, ProviderEvent } from "@alisio/sdk";
+import OpenAI from "openai";
+export interface OpenAICompatibleConfig {
+    baseURL: string;
+    apiKey?: string;
+    apiKeyEnv: string;
+    model: string;
+    apiMode: "chat" | "responses";
+    auth: "bearer" | "none";
+    tokenParameter: "max_tokens" | "max_completion_tokens" | "omit";
+    streamUsage: boolean;
+    contextWindow?: number;
+}
+export declare class OpenAICompatibleProvider implements ModelProvider {
+    #private;
+    readonly id: string;
+    readonly model: string;
+    constructor(config: OpenAICompatibleConfig, client?: OpenAI);
+    /** Lists models from GET /models. Context window fields are provider extensions. */
+    listModels(signal: AbortSignal): Promise<ModelInfo[]>;
+    stream(request: Parameters<ModelProvider["stream"]>[0]): AsyncIterable<ProviderEvent>;
+    private responses;
+}

package/dist/provider.js

@@ -0,0 +1,264 @@
+import OpenAI from "openai";
+const dataUrl = (a) => `data:${a.mimeType};base64,${a.data}`;
+export class OpenAICompatibleProvider {
+    id;
+    model;
+    #client;
+    #config;
+    constructor(config, client) {
+        this.model = config.model;
+        const { apiKey: _apiKey, ...safeConfig } = config;
+        this.#config = safeConfig;
+        const key = config.auth === "none" ? "unused" : (config.apiKey ?? process.env[config.apiKeyEnv]);
+        if (!client && !key)
+            throw new Error(`Missing API key environment variable: ${config.apiKeyEnv}`);
+        this.id = `openai-compatible:${config.apiMode}:${config.baseURL.replace(/\/$/, "")}`;
+        this.#client =
+            client ??
+                new OpenAI({
+                    baseURL: config.baseURL,
+                    apiKey: key,
+                    maxRetries: 0,
+                    timeout: 120_000,
+                    ...(config.auth === "none" ? { defaultHeaders: { Authorization: null } } : {}),
+                });
+    }
+    /** Lists models from GET /models. Context window fields are provider extensions. */
+    async listModels(signal) {
+        const models = [];
+        for await (const m of this.#client.models.list({ signal })) {
+            const extra = m;
+            const window = [extra.context_window, extra.context_length, extra.max_context_length].find((v) => typeof v === "number" && Number.isFinite(v) && v > 0);
+            models.push({ id: m.id, ...(window ? { contextWindow: window } : {}) });
+            if (models.length >= 1000)
+                break;
+        }
+        return models;
+    }
+    async *stream(request) {
+        if (this.#config.apiMode === "responses") {
+            yield* this.responses(request);
+            return;
+        }
+        const messages = [
+            { role: "system", content: request.instructions },
+        ];
+        for (const m of request.messages) {
+            if (m.role === "user") {
+                if (m.attachments?.length) {
+                    const parts = [];
+                    if (m.text.trim())
+                        parts.push({ type: "text", text: m.text });
+                    for (const a of m.attachments)
+                        parts.push({ type: "image_url", image_url: { url: dataUrl(a) } });
+                    messages.push({ role: "user", content: parts });
+                }
+                else
+                    messages.push({ role: "user", content: m.text });
+            }
+            else if (m.role === "tool")
+                messages.push({ role: "tool", tool_call_id: m.callId, content: JSON.stringify(m.result) });
+            else
+                messages.push({
+                    role: "assistant",
+                    content: m.text || null,
+                    ...(m.calls.length
+                        ? {
+                            tool_calls: m.calls.map((c) => ({
+                                id: c.id,
+                                type: "function",
+                                function: { name: c.name, arguments: c.arguments },
+                            })),
+                        }
+                        : {}),
+                });
+        }
+        const limit = this.#config.tokenParameter === "omit"
+            ? {}
+            : { [this.#config.tokenParameter]: request.maxOutputTokens };
+        const stream = await this.#client.chat.completions.create({
+            model: request.model || this.model,
+            messages,
+            stream: true,
+            ...limit,
+            ...(this.#config.streamUsage ? { stream_options: { include_usage: true } } : {}),
+            ...(request.tools.length || request.nativeTools?.length
+                ? {
+                    tools: [
+                        ...request.tools.map((t) => ({
+                            type: "function",
+                            function: { name: t.name, description: t.description, parameters: t.inputSchema },
+                        })),
+                        ...(request.nativeTools ?? []),
+                    ],
+                }
+                : {}),
+        }, { signal: request.signal });
+        let text = "", finish = null, usage;
+        const calls = new Map();
+        for await (const chunk of stream) {
+            if (chunk.usage) {
+                // DeepSeek reports prompt_cache_hit_tokens; OpenAI uses prompt_tokens_details.
+                const extra = chunk.usage;
+                const cached = chunk.usage.prompt_tokens_details?.cached_tokens ?? extra.prompt_cache_hit_tokens;
+                usage = {
+                    input: chunk.usage.prompt_tokens,
+                    output: chunk.usage.completion_tokens,
+                    ...(typeof cached === "number" ? { cachedInput: cached } : {}),
+                };
+            }
+            const choice = chunk.choices[0];
+            if (!choice)
+                continue;
+            const reasoning = choice.delta.reasoning_content;
+            if (typeof reasoning === "string" && reasoning)
+                yield { type: "reasoning_delta", delta: reasoning };
+            if (choice.delta.content) {
+                text += choice.delta.content;
+                yield { type: "text_delta", delta: choice.delta.content };
+            }
+            if (choice.delta.refusal)
+                throw new Error(`Provider refusal: ${choice.delta.refusal}`);
+            for (const part of choice.delta.tool_calls ?? []) {
+                const c = calls.get(part.index) ?? { id: "", name: "", arguments: "" };
+                if (part.id)
+                    c.id = part.id;
+                if (part.function?.name)
+                    c.name += part.function.name;
+                if (part.function?.arguments)
+                    c.arguments += part.function.arguments;
+                calls.set(part.index, c);
+            }
+            if (choice.finish_reason)
+                finish = choice.finish_reason;
+        }
+        if (finish !== "stop" && finish !== "tool_calls" && finish !== "length")
+            throw new Error(`Provider response incomplete: ${finish ?? "stream ended"}`);
+        const completed = [...calls.entries()].sort(([a], [b]) => a - b).map(([, c]) => c);
+        // A response cut by the output limit is reported as it is (`truncated: true`), even when it
+        // has no text or its tool calls are partial: the host decides whether to recover, and never
+        // executes a call whose arguments are incomplete.
+        if (finish !== "length" && completed.some((c) => !c.id || !c.name))
+            throw new Error("Incomplete tool call");
+        yield {
+            type: "completed",
+            message: {
+                role: "assistant",
+                text,
+                calls: completed,
+                ...(finish === "length" ? { truncated: true } : {}),
+            },
+            usage,
+        };
+    }
+    async *responses(request) {
+        const input = [];
+        for (const m of request.messages) {
+            if (m.role === "user") {
+                if (m.attachments?.length) {
+                    const content = [];
+                    if (m.text.trim())
+                        content.push({ type: "input_text", text: m.text });
+                    for (const a of m.attachments)
+                        content.push({ type: "input_image", image_url: dataUrl(a), detail: "auto" });
+                    input.push({ role: "user", content });
+                }
+                else
+                    input.push({ role: "user", content: m.text });
+            }
+            else if (m.role === "tool")
+                input.push({
+                    type: "function_call_output",
+                    call_id: m.callId,
+                    output: JSON.stringify(m.result),
+                });
+            else if (m.providerData)
+                input.push(...m.providerData);
+            else
+                throw new Error("Missing provider continuation data for Responses session");
+        }
+        const stream = await this.#client.responses.create({
+            model: request.model || this.model,
+            instructions: request.instructions,
+            input,
+            stream: true,
+            store: false,
+            include: ["reasoning.encrypted_content"],
+            max_output_tokens: request.maxOutputTokens,
+            tools: [
+                ...request.tools.map((t) => ({
+                    type: "function",
+                    name: t.name,
+                    description: t.description,
+                    parameters: t.inputSchema,
+                    strict: false,
+                })),
+                ...(request.nativeTools ?? []),
+            ],
+        }, { signal: request.signal });
+        let complete = false;
+        for await (const event of stream) {
+            if (event.type === "response.output_text.delta")
+                yield { type: "text_delta", delta: event.delta };
+            if (event.type === "response.reasoning_summary_text.delta")
+                yield { type: "reasoning_delta", delta: event.delta };
+            if (event.type === "response.failed" || event.type === "error")
+                throw new Error(`Provider response failed: ${event.type}`);
+            if (event.type === "response.incomplete") {
+                complete = true;
+                const r = event.response;
+                const calls = r.output
+                    .filter((x) => x.type === "function_call")
+                    .map((x) => ({ id: x.call_id, name: x.name, arguments: x.arguments }));
+                const text = r.output
+                    .filter((x) => x.type === "message")
+                    .flatMap((x) => x.content)
+                    .filter((x) => x.type === "output_text")
+                    .map((x) => x.text)
+                    .join("");
+                // Reported as truncated even when empty or with partial calls: the host recovers.
+                yield {
+                    type: "completed",
+                    message: { role: "assistant", text, calls, providerData: r.output, truncated: true },
+                    usage: r.usage
+                        ? {
+                            input: r.usage.input_tokens,
+                            output: r.usage.output_tokens,
+                            ...(typeof r.usage.input_tokens_details?.cached_tokens === "number"
+                                ? { cachedInput: r.usage.input_tokens_details.cached_tokens }
+                                : {}),
+                        }
+                        : undefined,
+                };
+            }
+            if (event.type === "response.completed") {
+                complete = true;
+                const r = event.response;
+                const calls = r.output
+                    .filter((x) => x.type === "function_call")
+                    .map((x) => ({ id: x.call_id, name: x.name, arguments: x.arguments }));
+                const text = r.output
+                    .filter((x) => x.type === "message")
+                    .flatMap((x) => x.content)
+                    .filter((x) => x.type === "output_text")
+                    .map((x) => x.text)
+                    .join("");
+                yield {
+                    type: "completed",
+                    message: { role: "assistant", text, calls, providerData: r.output },
+                    usage: r.usage
+                        ? {
+                            input: r.usage.input_tokens,
+                            output: r.usage.output_tokens,
+                            ...(typeof r.usage.input_tokens_details?.cached_tokens === "number"
+                                ? { cachedInput: r.usage.input_tokens_details.cached_tokens }
+                                : {}),
+                        }
+                        : undefined,
+                };
+            }
+        }
+        if (!complete)
+            throw new Error("Responses stream ended before completion");
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Reads this plugin package's version at runtime so plugin metadata, user-agent defaults and CLI
+ * reports stay in sync with the published package without a build-time constant to update.
+ * The manifest is resolved relative to the module (`src/version.ts` → `../package.json` in the
+ * source tree; `dist/version.js` → `../package.json` of the installed package). Standalone
+ * binaries inject the version at build time via ALISIO_PACKAGE_VERSION (scripts/binary-build.ts).
+ */
+export declare function loadVersion(fromHere: string): string;

package/dist/version.js

@@ -0,0 +1,28 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Fallback used when neither the build-time injection nor the package manifest is readable
+ * (e.g. an unpackaged embed). Keep it a development marker, never a publish literal, so it
+ * cannot silently desync from the published package.
+ */
+const FALLBACK = "dev";
+/**
+ * Reads this plugin package's version at runtime so plugin metadata, user-agent defaults and CLI
+ * reports stay in sync with the published package without a build-time constant to update.
+ * The manifest is resolved relative to the module (`src/version.ts` → `../package.json` in the
+ * source tree; `dist/version.js` → `../package.json` of the installed package). Standalone
+ * binaries inject the version at build time via ALISIO_PACKAGE_VERSION (scripts/binary-build.ts).
+ */
+export function loadVersion(fromHere) {
+    if (process.env.ALISIO_PACKAGE_VERSION)
+        return process.env.ALISIO_PACKAGE_VERSION;
+    try {
+        const manifest = join(dirname(fileURLToPath(fromHere)), "..", "package.json");
+        const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+        return typeof parsed.version === "string" && parsed.version ? parsed.version : FALLBACK;
+    }
+    catch {
+        return FALLBACK;
+    }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@alisio/plugin-openai-compatible",
+  "version": "0.1.0-alpha.10",
+  "description": "Built-in OpenAI-compatible model provider for Alisio.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.16"
+  },
+  "dependencies": {
+    "openai": "7.23.0"
+  },
+  "peerDependencies": {
+    "@alisio/sdk": "^0.1.0-alpha.20"
+  },
+  "devDependencies": {
+    "@alisio/sdk": "0.1.0-alpha.20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.com/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
+}