@alisio/core 0.1.0-alpha.10

package/dist/mcp/connector.js

@@ -0,0 +1,423 @@
+import { createHash } from "node:crypto";
+import { textResult } from "@alisio/sdk";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { objectSchema } from "../tools/standard.js";
+import { loadVersion } from "../version.js";
+const TOOL_NAME_LIMIT = 64;
+/**
+ * Per-server client close cap used ONLY by the terminal `close()`: the MCP SDK's stdio close can
+ * take ~4s worst case (stdin end → 2s → SIGTERM → 2s → SIGKILL) when a server ignores
+ * termination, and exit must never wait for that ladder. Runtime `disconnect()` keeps its
+ * unbounded semantics so interactive reconnect flows stay unchanged.
+ */
+const CLOSE_SERVER_TIMEOUT_MS = 800;
+/** Overall cap for `close()` (every connected server in parallel plus bridge unregistration). */
+const CLOSE_TOTAL_TIMEOUT_MS = 1_500;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const semanticSegment = (value, fallback) => value
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "") || fallback;
+const shortHash = (server, tool) => createHash("sha256").update(`${server}\0${tool}`).digest("hex").slice(0, 8);
+const withHash = (base, server, tool) => {
+    const suffix = `_${shortHash(server, tool)}`;
+    const stem = base.slice(0, TOOL_NAME_LIMIT - suffix.length).replace(/_+$/g, "");
+    return `${stem || "mcp_tool"}${suffix}`;
+};
+/** Deterministic provider-safe names while retaining the exact source mapping in the connector. */
+export function semanticMcpToolNames(server, tools, configuredServers, unavailable = new Set()) {
+    if (new Set(tools).size !== tools.length)
+        throw new Error(`MCP server "${server}" returned duplicate tool names`);
+    const serverPart = semanticSegment(server, "server");
+    const serverCollision = configuredServers.filter((candidate) => semanticSegment(candidate, "server") === serverPart)
+        .length > 1;
+    const toolParts = tools.map((tool) => semanticSegment(tool, "tool"));
+    const collisions = new Set(toolParts.filter((part, index) => toolParts.indexOf(part) !== index));
+    return tools.map((tool, index) => {
+        const base = `mcp_${serverPart}_${toolParts[index]}`;
+        const needsHash = base.length > TOOL_NAME_LIMIT ||
+            serverCollision ||
+            collisions.has(toolParts[index]) ||
+            unavailable.has(base);
+        const result = needsHash ? withHash(base, server, tool) : base;
+        if (unavailable.has(result))
+            throw new Error(`MCP tool name collision could not be resolved for ${server}/${tool}`);
+        return result;
+    });
+}
+const readable = (value, limit = 160) => value
+    .replace(/[\u0000-\u001f\u007f]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, limit);
+const safeFailure = (error) => {
+    const message = error instanceof Error ? error.message.toLowerCase() : "";
+    if (message.includes("timeout") || message.includes("timed out"))
+        return "Connection timed out";
+    if (message.includes("abort"))
+        return "Connection cancelled";
+    if (message.includes("auth") || message.includes("token") || message.includes("401"))
+        return "Authentication is required or was rejected";
+    if (message.includes("enoent"))
+        return "Server command could not be started";
+    return "Connection failed; inspect the server separately for details";
+};
+export class McpConnector {
+    servers;
+    registry;
+    workspace;
+    availability;
+    sources;
+    clients = new Map();
+    statuses = new Map();
+    diagnostics = new Map();
+    catalogs = new Map();
+    details = new Map();
+    bridgeUndo = [];
+    constructor(servers, registry, workspace, availability = "allowed", sources = {}) {
+        this.servers = servers;
+        this.registry = registry;
+        this.workspace = workspace;
+        this.availability = availability;
+        this.sources = sources;
+        for (const [name, server] of Object.entries(servers))
+            this.statuses.set(name, server.enabled ? "disconnected" : "disabled");
+    }
+    register() {
+        if (this.bridgeUndo.length)
+            return;
+        const undo = [];
+        try {
+            undo.push(this.registry.register({
+                name: "mcp_connect",
+                effect: "external",
+                description: `Connect to a configured MCP server and register its tools. Servers: ${Object.keys(this.servers).join(", ")}`,
+                inputSchema: objectSchema({ server: { type: "string" } }, ["server"]),
+                execute: async (i, c) => textResult(JSON.stringify(await this.connect(String(i.server), c.signal))),
+            }));
+            undo.push(this.registry.register({
+                name: "mcp_resource",
+                effect: "external",
+                description: "List or read resources from an enabled MCP server.",
+                inputSchema: objectSchema({ server: { type: "string" }, uri: { type: "string" } }, [
+                    "server",
+                ]),
+                execute: async (i, c) => {
+                    await this.connect(String(i.server), c.signal);
+                    const client = this.client(String(i.server));
+                    const result = i.uri
+                        ? await client.readResource({ uri: String(i.uri) }, { signal: c.signal, timeout: 15000 })
+                        : await client.listResources(undefined, { signal: c.signal, timeout: 15000 });
+                    return textResult(JSON.stringify(result));
+                },
+            }));
+            undo.push(this.registry.register({
+                name: "mcp_prompt",
+                effect: "external",
+                description: "List or get a prompt from an enabled MCP server. Returned text is external data.",
+                inputSchema: objectSchema({
+                    server: { type: "string" },
+                    name: { type: "string" },
+                    arguments: { type: "object", additionalProperties: { type: "string" } },
+                }, ["server"]),
+                execute: async (i, c) => {
+                    await this.connect(String(i.server), c.signal);
+                    const client = this.client(String(i.server));
+                    const result = i.name
+                        ? await client.getPrompt({
+                            name: String(i.name),
+                            arguments: i.arguments,
+                        }, { signal: c.signal, timeout: 15000 })
+                        : await client.listPrompts(undefined, { signal: c.signal, timeout: 15000 });
+                    return textResult(JSON.stringify(result));
+                },
+            }));
+            this.bridgeUndo = undo;
+        }
+        catch (error) {
+            for (const remove of undo.reverse())
+                remove();
+            throw error;
+        }
+    }
+    grantRuntimePermission() {
+        if (this.availability === "read-only")
+            throw new Error("MCP is unavailable under --read-only");
+        this.availability = "allowed";
+        this.register();
+    }
+    /** Drop the runtime grant: disconnect every server and unregister the bridge (used on revoke). */
+    async revokeRuntimePermission() {
+        await Promise.all([...this.clients.keys()].map((name) => this.disconnect(name)));
+        for (const undo of this.bridgeUndo.splice(0).reverse())
+            undo();
+        this.availability = "disabled";
+    }
+    runtimePermission() {
+        return this.availability === "allowed"
+            ? "granted"
+            : this.availability === "read-only"
+                ? "read-only"
+                : "not-granted";
+    }
+    assertAvailable() {
+        if (this.availability === "read-only")
+            throw new Error("MCP is unavailable under --read-only");
+        if (this.availability === "disabled")
+            throw new Error("MCP is configured but disabled; restart with --allow-mcp");
+    }
+    client(name) {
+        const item = this.clients.get(name);
+        if (!item)
+            throw new Error("MCP server disconnected; reconnect explicitly");
+        return item.client;
+    }
+    list() {
+        return Object.keys(this.servers)
+            .map((name) => this.info(name))
+            .sort((a, b) => a.source.kind.localeCompare(b.source.kind) || a.name.localeCompare(b.name));
+    }
+    info(name) {
+        const config = this.servers[name];
+        if (!config)
+            throw new Error(`Unknown MCP server: ${name}`);
+        const detail = this.details.get(name);
+        return {
+            name,
+            displayName: detail?.displayName ?? name,
+            source: this.sources[name] ?? { kind: "builtin", form: "canonical" },
+            status: this.statuses.get(name) ?? (config.enabled ? "disconnected" : "disabled"),
+            enabled: config.enabled,
+            runtimePermission: this.runtimePermission(),
+            transport: config.transport,
+            ...(config.transport === "stdio"
+                ? { command: config.command, args: [...config.args] }
+                : { url: config.url }),
+            capabilities: [...(detail?.capabilities ?? [])],
+            counts: {
+                tools: this.catalogs.get(name)?.length ?? 0,
+                resources: detail?.resources ?? 0,
+                prompts: detail?.prompts ?? 0,
+            },
+            ...(this.diagnostics.has(name) ? { diagnostic: this.diagnostics.get(name) } : {}),
+        };
+    }
+    tools(name) {
+        this.info(name);
+        return (this.catalogs.get(name) ?? []).map((tool) => ({
+            ...tool,
+            ...(tool.annotations ? { annotations: { ...tool.annotations } } : {}),
+        }));
+    }
+    async connect(name, signal) {
+        this.assertAvailable();
+        const config = this.servers[name];
+        if (!config)
+            throw new Error(`Unknown MCP server: ${name}`);
+        if (!config.enabled)
+            throw new Error(`MCP server "${name}" is disabled; enable it in /mcp`);
+        if (this.clients.has(name))
+            return this.registeredNames(name);
+        if (config.transport === "http" &&
+            config.bearerTokenEnv &&
+            !process.env[config.bearerTokenEnv]) {
+            this.statuses.set(name, "needs-authentication");
+            this.diagnostics.set(name, `Set the ${config.bearerTokenEnv} environment variable, then reconnect`);
+            throw new Error(`MCP server "${name}" needs authentication; set ${config.bearerTokenEnv}`);
+        }
+        this.statuses.set(name, "connecting");
+        this.diagnostics.delete(name);
+        const client = new Client({ name: "alisio", version: loadVersion(import.meta.url) }, { capabilities: {} });
+        const undo = [];
+        const generation = Symbol(name);
+        const transport = config.transport === "stdio"
+            ? new StdioClientTransport((() => {
+                const env = Object.fromEntries(["PATH", "HOME", "SystemRoot", ...config.envAllow].flatMap((key) => process.env[key] ? [[key, process.env[key]]] : []));
+                Object.assign(env, config.env);
+                return {
+                    command: config.command,
+                    args: config.args,
+                    cwd: this.workspace,
+                    env,
+                    stderr: "pipe",
+                    maxBufferSize: 1_048_576,
+                };
+            })())
+            : new StreamableHTTPClientTransport(new URL(config.url), {
+                reconnectionOptions: {
+                    maxRetries: 0,
+                    maxReconnectionDelay: 1000,
+                    initialReconnectionDelay: 100,
+                    reconnectionDelayGrowFactor: 1,
+                },
+                ...(config.bearerTokenEnv
+                    ? {
+                        authProvider: {
+                            token: async () => process.env[config.bearerTokenEnv],
+                        },
+                    }
+                    : {}),
+            });
+        try {
+            await client.connect(transport, { signal, timeout: 15000 });
+            if (transport instanceof StdioClientTransport)
+                transport.stderr?.on("data", () => { });
+            const serverCapabilities = client.getServerCapabilities() ?? {};
+            const capabilities = Object.keys(serverCapabilities).sort();
+            const tools = serverCapabilities.tools
+                ? (await client.listTools(undefined, { signal, timeout: 15000 })).tools
+                : [];
+            if (tools.length > 100)
+                throw new Error("MCP server exposes more than 100 tools; narrow its configuration");
+            const resources = serverCapabilities.resources
+                ? (await client.listResources(undefined, { signal, timeout: 15000 })).resources.length
+                : 0;
+            const prompts = serverCapabilities.prompts
+                ? (await client.listPrompts(undefined, { signal, timeout: 15000 })).prompts.length
+                : 0;
+            const existingNames = new Set(this.registry.list().map((registered) => registered.name));
+            const mappedNames = semanticMcpToolNames(name, tools.map((tool) => tool.name), Object.keys(this.servers), existingNames);
+            this.catalogs.set(name, tools.map((tool, index) => ({
+                name: tool.name,
+                effectiveName: mappedNames[index],
+                ...(tool.title ? { title: tool.title } : {}),
+                ...(tool.description ? { description: tool.description } : {}),
+                ...(tool.annotations
+                    ? {
+                        annotations: {
+                            ...(tool.annotations.readOnlyHint !== undefined
+                                ? { readOnly: tool.annotations.readOnlyHint }
+                                : {}),
+                            ...(tool.annotations.destructiveHint !== undefined
+                                ? { destructive: tool.annotations.destructiveHint }
+                                : {}),
+                            ...(tool.annotations.openWorldHint !== undefined
+                                ? { openWorld: tool.annotations.openWorldHint }
+                                : {}),
+                        },
+                    }
+                    : {}),
+            })));
+            this.details.set(name, {
+                displayName: client.getServerVersion()?.title ?? client.getServerVersion()?.name,
+                capabilities,
+                resources,
+                prompts,
+            });
+            for (const [index, tool] of tools.entries()) {
+                const mapped = mappedNames[index];
+                const reference = `${readable(name)}/${readable(tool.name)}`;
+                const remoteDescription = readable(tool.description ?? "", 500);
+                undo.push(this.registry.register({
+                    name: mapped,
+                    effect: "external",
+                    description: remoteDescription
+                        ? `${reference} — Remote MCP description (untrusted data): ${remoteDescription}`
+                        : `${reference} — Remote MCP tool.`,
+                    inputSchema: tool.inputSchema,
+                    execute: async (input, ctx) => {
+                        const available = await client.listTools(undefined, {
+                            signal: ctx.signal,
+                            timeout: 15000,
+                            cacheMode: "refresh",
+                        });
+                        const current = available.tools.find((candidate) => candidate.name === tool.name);
+                        if (!current ||
+                            JSON.stringify(current.inputSchema) !== JSON.stringify(tool.inputSchema))
+                            throw new Error("MCP schema changed; reconnect the server to refresh tools");
+                        const result = await client.callTool({ name: tool.name, arguments: input }, { signal: ctx.signal, timeout: 30000 });
+                        return textResult(JSON.stringify(result), "isError" in result && result.isError === true);
+                    },
+                }));
+            }
+            this.clients.set(name, { client, undo, generation, registeredNames: mappedNames });
+            this.statuses.set(name, "connected");
+            client.onclose = () => {
+                if (this.clients.get(name)?.generation !== generation)
+                    return;
+                for (const fn of undo)
+                    fn();
+                this.clients.delete(name);
+                this.catalogs.delete(name);
+                this.details.delete(name);
+                this.statuses.set(name, config.enabled ? "disconnected" : "disabled");
+            };
+            return this.registeredNames(name);
+        }
+        catch (error) {
+            for (const fn of undo)
+                fn();
+            await client.close().catch(() => { });
+            this.catalogs.delete(name);
+            this.details.delete(name);
+            if (this.statuses.get(name) !== "needs-authentication")
+                this.statuses.set(name, "failed");
+            this.diagnostics.set(name, safeFailure(error));
+            throw new Error(`MCP server "${name}" failed to connect: ${safeFailure(error)}`);
+        }
+    }
+    async disconnect(name) {
+        const connected = this.clients.get(name);
+        if (connected) {
+            this.clients.delete(name);
+            for (const fn of connected.undo)
+                fn();
+            await connected.client.close().catch(() => { });
+        }
+        this.catalogs.delete(name);
+        this.details.delete(name);
+        this.diagnostics.delete(name);
+        const server = this.servers[name];
+        if (!server)
+            throw new Error(`Unknown MCP server: ${name}`);
+        this.statuses.set(name, server.enabled ? "disconnected" : "disabled");
+    }
+    async reconnect(name, signal) {
+        this.assertAvailable();
+        await this.disconnect(name);
+        return this.connect(name, signal);
+    }
+    async setEnabled(name, enabled, signal) {
+        const server = this.servers[name];
+        if (!server)
+            throw new Error(`Unknown MCP server: ${name}`);
+        server.enabled = enabled;
+        if (!enabled)
+            return this.disconnect(name);
+        this.statuses.set(name, "disconnected");
+        if (signal)
+            await this.connect(name, signal);
+    }
+    registeredNames(name) {
+        return [...(this.clients.get(name)?.registeredNames ?? [])];
+    }
+    async close() {
+        const servers = [...this.clients.keys()];
+        // Exit latency is user-facing: every server is disconnected in parallel, each client close
+        // raced against a short cap, and the whole phase against an overall cap. An abandoned close
+        // keeps running in the background and the SDK still SIGKILLs an unresponsive server; the
+        // registry cleanup runs synchronously inside `disconnect`, so tools are always unregistered.
+        await Promise.race([
+            (async () => {
+                await Promise.all(servers.map((name) => Promise.race([this.disconnect(name), delay(CLOSE_SERVER_TIMEOUT_MS)])));
+                for (const undo of this.bridgeUndo.splice(0).reverse())
+                    undo();
+            })(),
+            delay(CLOSE_TOTAL_TIMEOUT_MS),
+        ]);
+        // A raced `disconnect` may have been abandoned before its final status cleanup (it flips
+        // the status only after `client.close()` resolves): the client entry is already gone, so
+        // settle the status here for exit without touching runtime disconnect semantics.
+        for (const name of servers) {
+            if (this.clients.has(name) || this.statuses.get(name) !== "connected")
+                continue;
+            const server = this.servers[name];
+            if (!server)
+                continue;
+            this.statuses.set(name, server.enabled ? "disconnected" : "disabled");
+        }
+    }
+}

package/dist/plugins/host.d.ts

@@ -0,0 +1,169 @@
+import type { AskQuestionsRequest, AskQuestionsResult, CommandContext, CommandOptions, CompletionRequest, Message, PanelProvider, Plugin, PluginAPI, PluginMetadata, RunEvent, SelectRequest } from "@alisio/sdk";
+import type { HookFailure, RunnerExtensions } from "../core/contracts.ts";
+import type { ToolRegistry } from "../core/registry.ts";
+import { ExtensionRegistry } from "../extensions/registry.ts";
+import type { ProviderRegistry } from "../providers/registry.ts";
+export declare const pluginPrefix: (id: string) => string;
+export interface PluginHostOptions {
+    /** Timeout for compaction and session-start hooks. */
+    hookTimeoutMs?: number;
+    /** Timeout for session-end hooks (for example an automatic summary). */
+    sessionEndTimeoutMs?: number;
+}
+export declare class PluginHost implements RunnerExtensions {
+    private registry;
+    private state;
+    private options;
+    private providers?;
+    commands: Map<string, (args: string, context?: CommandContext) => Promise<string>>;
+    commandInfo: Map<string, CommandOptions & {
+        plugin: string;
+        builtin: boolean;
+    }>;
+    /** Ids of active built-in plugins. */
+    builtins: Set<string>;
+    /** Status entries contributed through `ui.status`, keyed `plugin:key`. */
+    status: Map<string, {
+        plugin: string;
+        text: string;
+        detail?: string;
+    }>;
+    onStatusChange?: () => void;
+    /** Providers for typed extension points (mascot, startup-screen, ...). */
+    readonly extensions: ExtensionRegistry;
+    /** Loaded plugins that did not come from the built-in registry. */
+    externalCount: number;
+    private compactionHooks;
+    private startHandlers;
+    private endHandlers;
+    private fieldOwners;
+    private completer?;
+    private modelsImpl?;
+    observers: Set<(event: Readonly<RunEvent>) => void>;
+    contexts: Array<() => Promise<string>>;
+    /** Skill directories registered by plugins, retaining trusted registration ownership. */
+    skillSources: Array<{
+        plugin: string;
+        name: string;
+        dir: string;
+    }>;
+    /** Prompt template directories registered by plugins, with their plugin id. */
+    promptSources: Array<{
+        plugin: string;
+        dir: string;
+    }>;
+    /** Agent definition directories registered by plugins, with their plugin id. */
+    agentSources: Array<{
+        plugin: string;
+        dir: string;
+    }>;
+    /** Tree panels contributed by plugins, keyed `plugin:id`. */
+    panels: Map<string, {
+        plugin: string;
+        provider: PanelProvider;
+    }>;
+    private sessionsImpl?;
+    private uiImpl?;
+    /** Binds the child session service once the runner exists. */
+    setSessions(sessions: PluginAPI["sessions"]): void;
+    /** Binds interactive UI services (the TUI); without them select/askQuestions resolve undefined. */
+    setInteractiveUI(ui: {
+        select(request: SelectRequest): Promise<string | undefined>;
+        askQuestions(request: AskQuestionsRequest): Promise<AskQuestionsResult>;
+        open(sessionId: string): boolean;
+    }): void;
+    get sessions(): PluginAPI["sessions"];
+    /**
+     * Live accessor for core standard tools (e.g. `ask_user_question`), which are not "a plugin"
+     * with an id and so cannot use the per-plugin `ui` wrapper built in `activate()`. Bound lazily
+     * (reads `this.uiImpl` at call time) since `registerStandard` runs before the TUI calls
+     * `setInteractiveUI`. `interactive()` reflects whether ANY interactive UI is bound at all,
+     * never which session is asking, so child sessions under an interactive root TUI pass too.
+     */
+    get ui(): {
+        interactive(): boolean;
+        askQuestions(request: AskQuestionsRequest): Promise<AskQuestionsResult>;
+    };
+    get promptRoots(): string[];
+    get skillRoots(): string[];
+    private loaded;
+    constructor(registry: ToolRegistry, state: {
+        getState(plugin: string, key: string): unknown;
+        setState(plugin: string, key: string, value: unknown): void;
+    }, options?: PluginHostOptions, providers?: ProviderRegistry | undefined);
+    /**
+     * Live-update host-enforced hook timeouts so the NEXT hook call honors them without restarting.
+     * Keeps the same options object reference the constructors of new hooks read at call time.
+     */
+    applyTimeoutSettings(patch: Partial<PluginHostOptions>): void;
+    /** Binds the provider-agnostic completion service once a provider exists. */
+    setCompleter(fn: (request: CompletionRequest & {
+        signal: AbortSignal;
+    }) => Promise<string>): void;
+    /** Binds credential-free model discovery/resolution after provider startup is complete. */
+    setModels(models: PluginAPI["models"]): void;
+    /**
+     * Loads an explicitly trusted plugin: a file/directory path, or an npm package name resolved
+     * from `from` (project) upwards and then global roots. Never called for untrusted input.
+     */
+    load(spec: string, options?: {
+        from?: string;
+        globalRoots?: string[];
+    }): Promise<void>;
+    /** Imports and validates a trusted plugin without running setup, for cataloging disabled entries. */
+    inspect(spec: string, options?: {
+        from?: string;
+        globalRoots?: string[];
+    }): Promise<{
+        plugin: Plugin;
+        base: string;
+    }>;
+    private validate;
+    /**
+     * `builtin` is reserved for first-party plugins from the built-in registry: their tools and
+     * commands keep unprefixed names and may declare the `internal` effect.
+     */
+    activate(plugin: Plugin, base: string, options?: {
+        builtin?: boolean;
+    }): Promise<void>;
+    /** Runs one hook with a host-enforced timeout; the hook receives an abort signal. */
+    private guarded;
+    beforeCompact(input: Parameters<RunnerExtensions["beforeCompact"]>[0]): Promise<{
+        instructions: string[];
+        fields: Record<string, {
+            source: string;
+            description: string;
+        }>;
+        failures: HookFailure[];
+    }>;
+    afterCompact(input: Parameters<RunnerExtensions["afterCompact"]>[0]): Promise<{
+        inject: string[];
+        reports: Record<string, Record<string, unknown>>;
+        failures: HookFailure[];
+    }>;
+    sessionStart(input: Parameters<RunnerExtensions["sessionStart"]>[0]): Promise<{
+        inject: {
+            source: string;
+            text: string;
+        }[];
+        failures: HookFailure[];
+    }>;
+    /** Session end hooks run concurrently and are bounded by one host timeout. */
+    sessionEnd(input: {
+        sessionId: string;
+        model: string;
+        workspace: string;
+        reason: "clear" | "exit";
+        messages: readonly Message[];
+    }): Promise<{
+        failures: HookFailure[];
+    }>;
+    /** Loaded plugins (id, version, built-in flag), ordered by id. */
+    metadata(): PluginMetadata[];
+    get hasSessionEndHooks(): boolean;
+    /** Conservative ownership check used to protect a live session from plugin removal. */
+    ownsSessionResources(plugin: string): boolean;
+    emit(event: RunEvent): void;
+    close(): Promise<void>;
+}
+export declare function discoverPlugins(root: string): Promise<string[]>;