@alisio/core 0.1.0-alpha.10

package/dist/plugins/install.js

@@ -0,0 +1,322 @@
+/**
+ * Installer for npm plugin packages: `alisio install npm:<package>[@<version>]`.
+ *
+ * One shared routine (`installPlugin`) backs both the CLI command (`cliInstall`) and the
+ * host-owned `plugin_install` tool for the agent, so the two can never drift apart. The install
+ * target is the GLOBAL plugins directory `<configHome>/plugins` (default `~/.config/alisio/plugins`),
+ * installed with `npm install --prefix`; the package NAME is persisted in the global configuration
+ * `plugins` array (never the resolved filesystem path), keeping entries portable. Loading the plugin
+ * still follows the existing executable-plugin policy: it runs in-process wherever it is loaded and
+ * is disabled entirely under `--read-only`.
+ */
+import { chmod, mkdir, open, readdir, rename, unlink } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { textResult } from "@alisio/sdk";
+import { configHome } from "../config.js";
+import { readJson } from "../runtime/fs.js";
+import { PLUGIN_KEYWORD } from "../runtime/modules.js";
+import { runProcess } from "../runtime/process.js";
+/** npm package name: scope (optional) followed by the name; both start with an alphanumeric. */
+const PACKAGE_PART = "[A-Za-z0-9][A-Za-z0-9._-]*";
+const NAME_RE = new RegExp(`^(?:@${PACKAGE_PART}\\/)?${PACKAGE_PART}$`);
+/** Version specifier: npm's `@<version>` part, restricted to the same safe character set. */
+const VERSION_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * Validates an install spec without touching the network: `npm:<package>[@<version>]` (canonical),
+ * a bare package name (same resolution), and nothing else. Rejects shell metacharacters, `..` /
+ * absolute paths, and unknown prefixes (`registry:`, `git:`, `file:`, URLs) with a clear error.
+ */
+export function parsePluginSpec(spec) {
+    if (!spec || !spec.trim())
+        throw new Error("Plugin spec is empty: use npm:<package>[@<version>] or a bare package name, for example npm:plugin-openrouter");
+    const trimmed = spec.trim();
+    let rest = trimmed;
+    if (trimmed.startsWith("npm:"))
+        rest = trimmed.slice(4);
+    else {
+        const colon = trimmed.indexOf(":");
+        if (colon >= 0)
+            throw new Error(`Unsupported plugin spec prefix "${trimmed.slice(0, colon)}:": only npm:<package>[@<version>] ` +
+                `or a bare package name is supported (registry:/git:/file:/http: specs are not)` +
+                (trimmed.startsWith("registry:")
+                    ? "; pass the package name directly instead of a registry URL"
+                    : ""));
+    }
+    if (!rest)
+        throw new Error(`Plugin spec "${spec}" has no package name`);
+    const at = rest.lastIndexOf("@");
+    let name = rest;
+    let version;
+    if (at > 0) {
+        name = rest.slice(0, at);
+        version = rest.slice(at + 1);
+    }
+    if (name.length > 214)
+        throw new Error(`Invalid plugin spec "${spec}": package name is too long`);
+    if (!NAME_RE.test(name) || name.includes(".."))
+        throw new Error(`Invalid plugin package name "${name}" in spec "${spec}": allowed characters are letters, ` +
+            `digits, dot, underscore and dash, with "/" only for a scoped name and "@" only for a version; ` +
+            `names may not start with "." or "_" and may not contain ".."`);
+    if (version !== undefined && !VERSION_RE.test(version))
+        throw new Error(`Invalid plugin version "${version}" in spec "${spec}": versions may contain only letters, ` +
+            `digits, dot, underscore and dash (for example 1.2.3, 1.2.3-beta.1 or latest)`);
+    return { name, version };
+}
+/** The npm argument for a spec: `name`, `name@<version>` or `name@latest` for `--update`. */
+export function npmInstallTarget(name, version, update = false) {
+    return update ? `${name}@latest` : version ? `${name}@${version}` : name;
+}
+export const INSTALL_TIMEOUT_MS = 300_000;
+const defaultRunner = (command, args, options) => runProcess(command, args, { ...options, timeoutMs: INSTALL_TIMEOUT_MS, maxBytes: 64_000 });
+/**
+ * Redacts probable secrets from npm output (auth tokens, JWTs, bearer credentials, userinfo in
+ * URLs) and caps the size, so a failing install never echoes credentials to the user.
+ */
+export function sanitizeNpmError(text, maxLength = 4000) {
+    const MAX = Math.max(1, maxLength);
+    let cleaned = text.replace(/(eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]+|\bbearer\s+[A-Za-z0-9._~+/-]{12,}=*\b|\b(?:npm_?authToken|_authToken|NODE_AUTH_TOKEN|NPM_TOKEN|authToken|password|secret)\b\s*(?:=|:)\s*\S+|\b(?:npm_?authToken|_authToken|NODE_AUTH_TOKEN|NPM_TOKEN|authToken|password|secret)\b\s+\S+)/gi, "[redacted]");
+    cleaned = cleaned.replace(/([a-z][a-z0-9+.-]*):\/\/[^@\s/]+@/gi, "$1://[redacted]@");
+    if (cleaned.length > MAX)
+        cleaned = `${cleaned.slice(0, MAX)}\n…[npm output truncated]`;
+    return cleaned;
+}
+function npmInstallError(name, version, update, pluginsDir, result) {
+    const detail = sanitizeNpmError([result.stdout, result.stderr].filter(Boolean).join("\n"));
+    const retry = `npm install --prefix ${pluginsDir} ${npmInstallTarget(name, version, update)}`;
+    return new Error(`npm install failed for plugin "${name}" (exit ${result.exitCode}).\n${detail || "no output"}\n` +
+        `Retry with: ${retry}\n(or: alisio install npm:${npmInstallTarget(name, version)})`);
+}
+/** Atomically adds `packageName` to the global configuration `plugins` array, preserving all other fields. */
+async function persistGlobalPluginEntry(configHomeDir, packageName) {
+    const file = join(configHomeDir, "config.json");
+    const existing = await readJson(file);
+    let raw;
+    if (existing === undefined)
+        raw = {};
+    else if (typeof existing === "object" && !Array.isArray(existing))
+        raw = existing;
+    else
+        throw new Error(`Global Alisio configuration must be a JSON object: ${file}`);
+    const current = Array.isArray(raw.plugins) ? raw.plugins : [];
+    if (!current.includes(packageName))
+        raw.plugins = [...current, packageName];
+    raw.schemaVersion ??= 1;
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    const handle = await open(temporary, "wx", 0o600);
+    try {
+        await handle.writeFile(`${JSON.stringify(raw, null, 2)}\n`, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(temporary, file);
+        await chmod(file, 0o600);
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => { });
+        throw error;
+    }
+    return file;
+}
+/** The shared install routine used by both the CLI command and the `plugin_install` tool. */
+export async function installPlugin(input) {
+    const parsed = parsePluginSpec(input.spec);
+    if (input.readOnly)
+        throw new Error(`Installing npm plugin "${parsed.name}" is unavailable under --read-only: installation runs npm and writes your global configuration. Run without --read-only.`);
+    const home = resolve(input.configHome ?? configHome());
+    const pluginsDir = join(home, "plugins");
+    // npm creates the prefix directory itself, but the subprocess cwd must already exist for spawn.
+    await mkdir(pluginsDir, { recursive: true, mode: 0o700 });
+    const packageDir = join(pluginsDir, "node_modules", parsed.name);
+    const installedManifest = (await readJson(join(packageDir, "package.json")));
+    const alreadyInstalled = !!installedManifest?.version;
+    let updated = false;
+    if (!alreadyInstalled || input.update) {
+        const signal = input.signal ?? AbortSignal.timeout(INSTALL_TIMEOUT_MS);
+        const run = input.runner ?? defaultRunner;
+        const npmResult = await run("npm", [
+            "install",
+            "--prefix",
+            pluginsDir,
+            npmInstallTarget(parsed.name, parsed.version, input.update),
+        ], { cwd: pluginsDir, signal });
+        if (npmResult.exitCode !== 0)
+            throw npmInstallError(parsed.name, parsed.version, input.update, pluginsDir, npmResult);
+        updated = !!input.update && alreadyInstalled;
+    }
+    const manifest = (await readJson(join(packageDir, "package.json")));
+    const installedVersion = manifest?.version ?? "unknown";
+    const configFile = await persistGlobalPluginEntry(home, parsed.name);
+    return {
+        packageName: parsed.name,
+        installedVersion,
+        path: packageDir,
+        configEntry: parsed.name,
+        configFile,
+        pluginsDir,
+        alreadyInstalled,
+        updated,
+        trustRemark: pluginTrustRemark(parsed.name),
+    };
+}
+/** Final remark about loading and project trust, printed by the CLI and returned by the tool. */
+export function pluginTrustRemark(name) {
+    return (`The plugin "${name}" is installed globally for your user; it loads as trusted personal code ` +
+        `wherever global plugins load — use \`alisio --trust-project\` or accept the one-time trust prompt ` +
+        `in a project so its configuration and project plugins load too. \`--read-only\` keeps the plugin ` +
+        `from loading. Run \`alisio plugins list\` to inspect.`);
+}
+const PREINSTALL_WARNING = `Warning: "npm install" may run the package's lifecycle scripts (preinstall, install, postinstall) ` +
+    `with your user privileges. Alisio does not sandbox plugin installation or plugin code; the plugin ` +
+    `runs in-process if it is loaded. Only install packages you trust.`;
+export async function cliInstall(options) {
+    // Validate the spec before any network operation or prompt.
+    const parsed = parsePluginSpec(options.spec);
+    if (options.readOnly)
+        throw new Error(`Refusing to install npm plugin "${parsed.name}" under --read-only: installing runs npm and writes your global configuration. Run the command without --read-only.`);
+    if (options.yes) {
+        // Explicit opt-in: no warning, no prompt.
+    }
+    else if (options.interactive) {
+        process.stderr.write(`\n${PREINSTALL_WARNING}\n`);
+        const confirmed = await (options.confirm ?? defaultConfirm)();
+        if (!confirmed)
+            throw new Error(`Install of plugin "${parsed.name}" cancelled; nothing was installed or configured.`);
+    }
+    else {
+        // Headless (including --json): never prompt, fail with an actionable error.
+        throw new Error(`Refusing to install npm plugin "${parsed.name}" without confirmation: npm install may run ` +
+            `lifecycle scripts from the package. Re-run with --yes (or --trust-plugin) to confirm, for ` +
+            `example: alisio install npm:${npmInstallTarget(parsed.name, parsed.version)} --yes`);
+    }
+    const result = await installPlugin({
+        spec: options.spec,
+        configHome: options.configHome,
+        update: options.update,
+        signal: options.signal,
+        runner: options.runner,
+    });
+    printInstallResult(result, { json: !!options.json });
+    return result;
+}
+async function defaultConfirm() {
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = (await rl.question("Install this plugin package globally? [y/N] "))
+            .trim()
+            .toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+export function printInstallResult(result, options = {}) {
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify({
+            packageName: result.packageName,
+            installedVersion: result.installedVersion,
+            path: result.path,
+            configEntry: result.configEntry,
+            configFile: result.configFile,
+            alreadyInstalled: result.alreadyInstalled,
+            updated: result.updated,
+            trustRemark: result.trustRemark,
+        }, null, 2)}\n`);
+        return;
+    }
+    if (result.alreadyInstalled && !result.updated)
+        console.log(`Plugin "${result.packageName}" is already installed (v${result.installedVersion}). Use --update to refresh it to the latest version and keep its name.`);
+    else if (result.updated)
+        console.log(`Updated plugin "${result.packageName}" to v${result.installedVersion}.`);
+    else
+        console.log(`Installed plugin "${result.packageName}" v${result.installedVersion}.`);
+    console.log(`  path: ${result.path}`);
+    console.log(`  config: "plugins" entry "${result.configEntry}" in ${result.configFile}`);
+    console.log(result.trustRemark);
+}
+/**
+ * Registers the host-owned `plugin_install` tool (agent capability). It has process effect so it
+ * goes through the existing write/process/external permission gate (TUI approval or
+ * `--allow-process`; never available under `--read-only`, where it is not registered at all).
+ */
+export function registerPluginInstallTool(registry, options = {}) {
+    if (options.readOnly)
+        return;
+    const tool = {
+        name: "plugin_install",
+        effect: "process",
+        description: "Install an npm plugin package into Alisio's global plugins directory " +
+            "(<configHome>/plugins, for example ~/.config/alisio/plugins) and add its npm name to the " +
+            'global configuration "plugins" array so it can load across projects. Accepts "npm:<package>' +
+            "[@<version>]\" or a bare package name. npm may run the package's lifecycle scripts with your " +
+            "privileges, so this tool goes through the process permission gate like any subprocess; the " +
+            "installed plugin runs in-process wherever it is loaded and is disabled under --read-only.",
+        inputSchema: {
+            type: "object",
+            properties: { spec: { type: "string", minLength: 1 } },
+            required: ["spec"],
+            additionalProperties: false,
+        },
+        async execute(input, context) {
+            const result = await installPlugin({
+                spec: String(input.spec),
+                configHome: options.configHome,
+                runner: options.runner,
+                signal: context.signal,
+            });
+            return textResult(JSON.stringify({
+                packageName: result.packageName,
+                installedVersion: result.installedVersion,
+                path: result.path,
+                configEntry: result.configEntry,
+                configFile: result.configFile,
+                alreadyInstalled: result.alreadyInstalled,
+                updated: result.updated,
+                trustRemark: result.trustRemark,
+            }));
+        },
+    };
+    registry.register(tool);
+}
+/**
+ * Lists npm packages installed under `<root>/node_modules` that declare the `alisio-plugin`
+ * keyword — the same packages `plugins`-array entries resolve to. Used by `alisio plugins list`
+ * so an installed package shows up alongside file/directory plugins.
+ */
+export async function installedNpmPlugins(root) {
+    const packagesDir = join(root, "node_modules");
+    let entries;
+    try {
+        entries = await readdir(packagesDir, { withFileTypes: true });
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return [];
+        throw e;
+    }
+    const result = [];
+    const consider = async (dir) => {
+        const manifest = (await readJson(join(dir, "package.json")));
+        if (manifest && Array.isArray(manifest.keywords) && manifest.keywords.includes(PLUGIN_KEYWORD))
+            result.push(dir);
+    };
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        if (entry.name.startsWith("@")) {
+            const scoped = await readdir(join(packagesDir, entry.name), { withFileTypes: true }).catch(() => []);
+            for (const scope of scoped)
+                if (scope.isDirectory())
+                    await consider(join(packagesDir, entry.name, scope.name));
+        }
+        else {
+            await consider(join(packagesDir, entry.name));
+        }
+    }
+    return result.sort();
+}

package/dist/providers/openai-compatible.d.ts

@@ -0,0 +1,14 @@
+import type { ModelInfo, ModelProvider, ProviderEvent } from "@alisio/sdk";
+import OpenAI from "openai";
+import type { Config } from "../config.ts";
+export declare class OpenAICompatibleProvider implements ModelProvider {
+    private config;
+    readonly id: string;
+    readonly model: string;
+    private client;
+    constructor(config: Config["provider"], 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/providers/openai-compatible.js

@@ -0,0 +1,228 @@
+import OpenAI from "openai";
+const dataUrl = (a) => `data:${a.mimeType};base64,${a.data}`;
+export class OpenAICompatibleProvider {
+    config;
+    id;
+    model;
+    client;
+    constructor(config, client) {
+        this.config = config;
+        this.model = config.model;
+        if (!this.model)
+            throw new Error("Set ALISIO_MODEL, --model, or provider.model");
+        const key = config.auth === "none" ? "unused" : 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")
+            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");
+        yield { type: "completed", message: { role: "assistant", text, calls: completed }, 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 === "response.incomplete" ||
+                event.type === "error")
+                throw new Error(`Provider response failed: ${event.type}`);
+            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/providers/registry.d.ts

@@ -0,0 +1,35 @@
+import type { ModelInfo, ModelProvider, ProviderCreateRequest, ProviderRegistration } from "@alisio/sdk";
+export interface RegisteredProvider extends ProviderRegistration {
+    plugin: string;
+    builtin: boolean;
+}
+/** Additive provider catalog. Registrations are unique by provider id and independently removable. */
+export declare class ProviderRegistry {
+    private entries;
+    register(registration: ProviderRegistration, owner: {
+        plugin: string;
+        builtin: boolean;
+    }): () => void;
+    get(id: string): RegisteredProvider | undefined;
+    list(): RegisteredProvider[];
+    create(id: string, request: ProviderCreateRequest): Promise<ModelProvider>;
+}
+/** Mutable facade keeps runner/plugin completion references stable while the active provider changes. */
+export declare class ActiveProvider implements ModelProvider {
+    private current;
+    constructor(current: ModelProvider);
+    /** Core-only lifecycle access; credentials remain encapsulated by the provider instance. */
+    get currentProvider(): ModelProvider;
+    get id(): string;
+    get model(): string;
+    stream(request: Parameters<ModelProvider["stream"]>[0]): AsyncIterable<import("@alisio/sdk").ProviderEvent>;
+    listModels(signal: AbortSignal): Promise<ModelInfo[]>;
+    /** Swap only after the candidate exists; a failed candidate creation leaves the old provider live. */
+    replace(next: ModelProvider, disposePrevious?: boolean): Promise<void>;
+    dispose(): void | Promise<void> | undefined;
+}
+export declare class UnconfiguredProvider implements ModelProvider {
+    readonly id = "unconfigured";
+    readonly model = "";
+    stream(): AsyncIterable<never>;
+}

package/dist/providers/registry.js

@@ -0,0 +1,74 @@
+/** Additive provider catalog. Registrations are unique by provider id and independently removable. */
+export class ProviderRegistry {
+    entries = new Map();
+    register(registration, owner) {
+        if (!/^[a-z0-9][a-z0-9.-]{0,63}$/.test(registration.id))
+            throw new Error(`Invalid provider id: ${registration.id}`);
+        if (this.entries.has(registration.id))
+            throw new Error(`Duplicate provider: ${registration.id}`);
+        const entry = { ...registration, ...owner };
+        this.entries.set(entry.id, entry);
+        return () => {
+            if (this.entries.get(entry.id) === entry)
+                this.entries.delete(entry.id);
+        };
+    }
+    get(id) {
+        return this.entries.get(id);
+    }
+    list() {
+        return [...this.entries.values()].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async create(id, request) {
+        const registration = this.entries.get(id);
+        if (!registration)
+            throw new Error(`Unknown provider: ${id}`);
+        return registration.create(request);
+    }
+}
+/** Mutable facade keeps runner/plugin completion references stable while the active provider changes. */
+export class ActiveProvider {
+    current;
+    constructor(current) {
+        this.current = current;
+    }
+    /** Core-only lifecycle access; credentials remain encapsulated by the provider instance. */
+    get currentProvider() {
+        return this.current;
+    }
+    get id() {
+        return this.current.id;
+    }
+    get model() {
+        return this.current.model;
+    }
+    stream(request) {
+        return this.current.stream(request);
+    }
+    listModels(signal) {
+        return this.current.listModels?.(signal) ?? Promise.resolve([]);
+    }
+    /** Swap only after the candidate exists; a failed candidate creation leaves the old provider live. */
+    async replace(next, disposePrevious = true) {
+        const previous = this.current;
+        this.current = next;
+        if (!disposePrevious)
+            return;
+        try {
+            await previous.dispose?.();
+        }
+        catch {
+            // Activation already committed. A stale provider disposal failure must not roll it back.
+        }
+    }
+    dispose() {
+        return this.current.dispose?.();
+    }
+}
+export class UnconfiguredProvider {
+    id = "unconfigured";
+    model = "";
+    async *stream() {
+        throw new Error("No model provider is configured. Use /connect in the TUI or configure one before running headless.");
+    }
+}