@alisio/plugin-deepseek 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,54 @@
+# @alisio/plugin-deepseek
+
+**The built-in DeepSeek model provider for [Alisio](https://github.com/GustavoGutierrez/alisio).**
+Select it in `/connect`, discover models from the DeepSeek catalog, and talk to the Chat
+Completions or Responses API.
+
+## What it is
+
+A `model-provider` plugin that registers the `deepseek` provider with the Alisio host. It ships as a
+built-in of the `alisio` CLI and is enabled by default. Credentials are managed by Alisio and are
+never persisted by this plugin: keys live in the global credentials store or an environment
+variable.
+
+## 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 **DeepSeek**.
+2. Fields: **API key** (secret, required), **API key environment variable** (default
+   `DEEPSEEK_API_KEY`), **API mode** (`chat` or `responses`), **base URL** (default
+   `https://api.deepseek.com`; change only for a DeepSeek-compatible proxy).
+3. Pick a model from the discovered catalog — for example `deepseek/deepseek-chat`.
+
+The key is read from the stored credential first, then from `process.env[apiKeyEnv]` — usually:
+
+```sh
+export DEEPSEEK_API_KEY=...   # never put the key in config files, profiles or READMEs
+```
+
+## Features
+
+- Model discovery from the DeepSeek catalog (`GET /models`) with honest context windows.
+- Chat Completions and Responses modes (default `chat`); bearer auth, `max_tokens` output budget.
+- Provider-side usage reporting while streaming (`streamUsage: true`).
+- Credentials never leave the Alisio credentials store or the named environment variable.
+
+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 createDeepSeekPlugin(): Plugin;
+export type { DeepSeekConfig } from "./provider.ts";
+export { DeepSeekProvider } from "./provider.ts";
+declare const _default: Plugin;
+export default _default;

package/dist/index.js

@@ -0,0 +1,89 @@
+import { definePlugin } from "@alisio/sdk";
+import { DeepSeekProvider } from "./provider.js";
+import { loadVersion } from "./version.js";
+const DEFAULT_BASE_URL = "https://api.deepseek.com";
+const DEFAULT_API_KEY_ENV = "DEEPSEEK_API_KEY";
+const profileString = (request, key, fallback) => typeof request.profile[key] === "string" && String(request.profile[key]).trim()
+    ? String(request.profile[key]).trim()
+    : typeof request.legacy?.[key] === "string" && String(request.legacy[key]).trim()
+        ? String(request.legacy[key]).trim()
+        : fallback;
+export function createDeepSeekPlugin() {
+    return definePlugin({
+        id: "deepseek",
+        name: "DeepSeek",
+        description: "Dedicated DeepSeek Chat Completions and Responses provider",
+        categories: ["model-provider"],
+        version: loadVersion(import.meta.url),
+        apiVersion: 1,
+        setup(api) {
+            api.providers.register({
+                id: "deepseek",
+                name: "DeepSeek",
+                description: "DeepSeek Chat Completions and Responses APIs",
+                fields: [
+                    {
+                        key: "apiKey",
+                        label: "API key",
+                        kind: "secret",
+                        required: true,
+                        description: "Stored only in the global credentials file",
+                    },
+                    {
+                        key: "apiKeyEnv",
+                        label: "API key environment variable",
+                        kind: "text",
+                        required: false,
+                        defaultValue: DEFAULT_API_KEY_ENV,
+                        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: "baseURL",
+                        label: "DeepSeek API base URL",
+                        kind: "url",
+                        required: true,
+                        defaultValue: DEFAULT_BASE_URL,
+                        description: "Change only for a DeepSeek-compatible proxy",
+                    },
+                ],
+                create(request) {
+                    const apiKey = request.credentials.apiKey;
+                    const apiKeyEnv = profileString(request, "apiKeyEnv", DEFAULT_API_KEY_ENV);
+                    if (!apiKey && !process.env[apiKeyEnv])
+                        throw new Error(`DeepSeek API key is required (set it in /connect or export ${apiKeyEnv})`);
+                    const baseURL = profileString(request, "baseURL", DEFAULT_BASE_URL);
+                    const url = new URL(baseURL);
+                    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
+                        throw new Error("DeepSeek base URL must be HTTP(S) and must not contain credentials");
+                    const apiMode = profileString(request, "apiMode", "chat");
+                    if (apiMode !== "chat" && apiMode !== "responses")
+                        throw new Error(`Unsupported DeepSeek API mode: ${apiMode}`);
+                    const config = {
+                        baseURL,
+                        ...(apiKey ? { apiKey } : {}),
+                        apiKeyEnv,
+                        model: profileString(request, "model", ""),
+                        apiMode,
+                        auth: "bearer",
+                        tokenParameter: "max_tokens",
+                        streamUsage: true,
+                    };
+                    return new DeepSeekProvider(config);
+                },
+            });
+        },
+    });
+}
+export { DeepSeekProvider } from "./provider.js";
+export default createDeepSeekPlugin();

package/dist/provider.d.ts

@@ -0,0 +1,23 @@
+import type { ModelInfo, ModelProvider, ProviderEvent } from "@alisio/sdk";
+import OpenAI from "openai";
+export interface DeepSeekConfig {
+    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 DeepSeekProvider implements ModelProvider {
+    #private;
+    readonly id: string;
+    readonly model: string;
+    constructor(config: DeepSeekConfig, client?: OpenAI);
+    /** Lists models using DeepSeek's official GET /models response fields. */
+    listModels(signal: AbortSignal): Promise<ModelInfo[]>;
+    stream(request: Parameters<ModelProvider["stream"]>[0]): AsyncIterable<ProviderEvent>;
+    private responses;
+}

package/dist/provider.js

@@ -0,0 +1,322 @@
+import OpenAI from "openai";
+const dataUrl = (a) => `data:${a.mimeType};base64,${a.data}`;
+export class DeepSeekProvider {
+    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 = `deepseek:${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 using DeepSeek's official GET /models response fields. */
+    async listModels(signal) {
+        const models = [];
+        for await (const m of this.#client.models.list({ signal })) {
+            const extra = m;
+            const window = extra.context_window;
+            const maxOutput = extra.max_output_tokens;
+            const inputModalities = Array.isArray(extra.input_modalities)
+                ? extra.input_modalities.filter((v) => typeof v === "string")
+                : undefined;
+            const outputModalities = Array.isArray(extra.output_modalities)
+                ? extra.output_modalities.filter((v) => typeof v === "string")
+                : undefined;
+            const apiCapabilities = extra.api_capabilities &&
+                typeof extra.api_capabilities === "object" &&
+                !Array.isArray(extra.api_capabilities)
+                ? structuredClone(extra.api_capabilities)
+                : undefined;
+            const effortSource = extra.effort && typeof extra.effort === "object"
+                ? extra.effort
+                : undefined;
+            const supportedLevels = Array.isArray(effortSource?.supported_levels)
+                ? effortSource.supported_levels.filter((v) => typeof v === "string")
+                : [];
+            const defaultLevel = effortSource?.default_level;
+            models.push({
+                id: m.id,
+                ...(typeof extra.owned_by === "string" ? { ownedBy: extra.owned_by } : {}),
+                ...(typeof extra.name === "string" ? { name: extra.name } : {}),
+                ...(typeof window === "number" && Number.isFinite(window) && window > 0
+                    ? { contextWindow: window }
+                    : {}),
+                ...(typeof maxOutput === "number" && maxOutput > 0 ? { maxOutputTokens: maxOutput } : {}),
+                ...(inputModalities?.length ? { inputModalities } : {}),
+                ...(outputModalities?.length ? { outputModalities } : {}),
+                ...(apiCapabilities ? { apiCapabilities } : {}),
+                ...(supportedLevels.length
+                    ? {
+                        effort: {
+                            supportedLevels,
+                            ...(typeof defaultLevel === "string" ? { defaultLevel } : {}),
+                        },
+                    }
+                    : {}),
+            });
+            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 };
+        // `reasoning_effort` is provider-declared (DeepSeek's catalog `effort.supported_levels`); the
+        // SDK type is a fixed union, so the value is carried through the params type of `create`.
+        const reasoningEffort = request.reasoningEffort
+            ? {
+                reasoning_effort: request.reasoningEffort,
+            }
+            : {};
+        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 } } : {}),
+            ...reasoningEffort,
+            ...(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);
+        if (completed.some((c) => !c.id || !c.name))
+            throw new Error("Incomplete tool call");
+        if (finish === "length" && !text.trim())
+            throw new Error("Provider response cut off by max output tokens before any usable content; raise limits.maxOutputTokens (/settings → Agent max output tokens)");
+        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,
+            ...(request.reasoningEffort
+                ? {
+                    reasoning: {
+                        effort: request.reasoningEffort,
+                    },
+                }
+                : {}),
+            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) {
+            const officialEvent = event;
+            if (event.type === "response.output_text.delta")
+                yield { type: "text_delta", delta: event.delta };
+            if ((officialEvent.type === "response.reasoning_text.delta" ||
+                officialEvent.type === "response.reasoning_summary_text.delta") &&
+                typeof officialEvent.delta === "string")
+                yield { type: "reasoning_delta", delta: officialEvent.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("");
+                if (!text.trim())
+                    throw new Error("Provider response cut off by max output tokens before any usable content; raise limits.maxOutputTokens (/settings → Agent max output tokens)");
+                if (calls.some((c) => !c.id || !c.name))
+                    throw new Error("Incomplete tool call");
+                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-deepseek",
+  "version": "0.1.0-alpha.10",
+  "description": "Built-in DeepSeek 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.8"
+  },
+  "devDependencies": {
+    "@alisio/sdk": "0.1.0-alpha.8"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.com/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
+}