happy2 0.0.11 → 0.0.13

package/packages/happy2-server/dist/modules/plugin/service.js

@@ -1,12 +1,13 @@
-import { createHash } from "node:crypto";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { createId } from "@paralleldrive/cuid2";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types.js";
 import { realtimeTopics } from "../realtime/index.js";
+import { chatUpdateMetadata } from "../chat/chatUpdateMetadata.js";
 import { pluginInstall } from "./pluginInstall.js";
 import { pluginFindBySource } from "./pluginFindBySource.js";
+import { pluginGetSource } from "./pluginGetSource.js";
 import { pluginGetImage } from "./pluginGetImage.js";
 import { pluginAuthorizeManagement } from "./pluginAuthorizeManagement.js";
 import { pluginInstallationGetRuntimeConfiguration } from "./pluginInstallationGetRuntimeConfiguration.js";
@@ -14,12 +15,25 @@ import { pluginInstallationListIds } from "./pluginInstallationListIds.js";
 import { pluginInstallationListReadyMcpIds } from "./pluginInstallationListReadyMcpIds.js";
 import { pluginInstallationUpdateStatus } from "./pluginInstallationUpdateStatus.js";
 import { pluginRemoveMissingBuiltins } from "./pluginRemoveMissingBuiltins.js";
+import { pluginMcpToolsReplace } from "./pluginMcpToolsReplace.js";
+import { pluginMcpToolsListReady } from "./pluginMcpToolsListReady.js";
+import { pluginSkillsListReady } from "./pluginSkillsListReady.js";
+import { pluginSkillsListInstalled } from "./pluginSkillsListInstalled.js";
+import { pluginContainerInstanceAuthorize } from "./pluginContainerInstanceAuthorize.js";
+import { pluginContainerInstanceInvalidate } from "./pluginContainerInstanceInvalidate.js";
+import { pluginUninstall } from "./pluginUninstall.js";
+import { pluginArchiveExtract } from "./archive.js";
+import { pluginPackageLoadSource } from "./catalog.js";
 import { RemotePluginMcpTransport } from "./utils/remoteMcpTransport.js";
-import { PluginError, } from "./types.js";
+import { downloadedPluginSource, remotePluginSource, remotePluginSourceFromInstalled, uploadedPluginSource, } from "./source.js";
+import { PluginError, MAX_PLUGIN_MCP_TOOLS, } from "./types.js";
 const HEALTH_TIMEOUT_MS = 15_000;
-const FUNCTION_DISCOVERY_TIMEOUT_MS = 15_000;
+const COMMAND_STARTUP_GRACE_MS = 250;
 const FUNCTION_EXECUTION_TIMEOUT_MS = 30_000;
 const MAX_RIG_PLUGIN_FUNCTIONS = 128;
+const MAX_RIG_PLUGIN_SKILLS = 128;
+const PREPARATION_TTL_MS = 15 * 60_000;
+const PLUGIN_CHAT_META_KEY = "happy2/chat";
 /** Coordinates durable plugin installs with asynchronous container preparation, MCP health probes, restart recovery, and local connection creation. */
 export class PluginService {
     executor;
@@ -28,24 +42,32 @@ export class PluginService {
     packages;
     secrets;
     runtime;
+    tokens;
     urlPolicy;
     remoteTransport;
+    hostApiUrl;
+    archiveDownloader;
     onError;
     activations = new Map();
-    localContainers = new Set();
+    commandHandles = new Map();
+    preparations = new Map();
     closed = false;
-    constructor(executor, pubsub, catalog, packages, secrets, runtime, urlPolicy, remoteTransport, onError) {
+    constructor(executor, pubsub, catalog, packages, secrets, runtime, tokens, urlPolicy, remoteTransport, hostApiUrl, archiveDownloader, onError) {
         this.executor = executor;
         this.pubsub = pubsub;
         this.catalog = catalog;
         this.packages = packages;
         this.secrets = secrets;
         this.runtime = runtime;
+        this.tokens = tokens;
         this.urlPolicy = urlPolicy;
         this.remoteTransport = remoteTransport;
+        this.hostApiUrl = hostApiUrl;
+        this.archiveDownloader = archiveDownloader;
         this.onError = onError;
     }
     async start() {
+        await this.packages.cleanupTemporary();
         const removed = await pluginRemoveMissingBuiltins(this.executor, this.catalog.list().map(({ source }) => source.reference));
         await Promise.all([
             ...removed.plugins.map(({ pluginId }) => this.packages.remove(pluginId).catch(this.onError)),
@@ -85,11 +107,141 @@ export class PluginService {
         }
         if (candidateId && !result.pluginCreated)
             await this.packages.remove(candidateId);
+        await this.packages.workspaceDirectory(result.pluginId, installationId);
         await this.publish(result.hint).catch(this.onError);
         if (result.installation.status === "preparing")
             this.activate(installationId);
         return result.installation;
     }
+    async prepareUpload(actorUserId, archive, onProgress) {
+        await pluginAuthorizeManagement(this.executor, actorUserId);
+        onProgress("verifying", "Inspecting uploaded ZIP package.");
+        const prepared = await this.prepareArchive(actorUserId, archive, "zip", undefined, onProgress);
+        return { selectionRequired: false, candidates: prepared };
+    }
+    async prepareRemote(actorUserId, input, onProgress, signal) {
+        await pluginAuthorizeManagement(this.executor, actorUserId);
+        const remote = remotePluginSource(input.kind, input.url);
+        onProgress("downloading", "Downloading plugin ZIP from its remote source.");
+        const downloaded = await this.archiveDownloader.download(remote.archiveUrl, {
+            signal,
+            onProgress: (bytes) => onProgress("downloading", "Downloading plugin ZIP.", bytes),
+        });
+        onProgress("verifying", "Verifying archive structure and plugin metadata.");
+        const candidates = await this.prepareArchive(actorUserId, downloaded.body, input.kind === "github" ? "github" : "zip", remote, onProgress);
+        return { selectionRequired: candidates.length > 1, candidates };
+    }
+    async installPrepared(input) {
+        await pluginAuthorizeManagement(this.executor, input.actorUserId);
+        const prepared = await this.preparationTake(input.actorUserId, input.preparedToken);
+        try {
+            const existing = await pluginFindBySource(this.executor, prepared.plugin.source.kind, prepared.plugin.source.reference);
+            if (existing && existing.packageDigest !== prepared.plugin.packageDigest)
+                throw new PluginError("conflict", "This remote plugin has changed since its installed snapshot; update it before adding another installation");
+            const installationId = createId();
+            const candidateId = existing ? undefined : createId();
+            const candidate = candidateId
+                ? {
+                    pluginId: candidateId,
+                    ...(await this.packages.install(prepared.plugin, candidateId)),
+                }
+                : undefined;
+            let result;
+            try {
+                result = await pluginInstall(this.executor, this.secrets, {
+                    actorUserId: input.actorUserId,
+                    installationId,
+                    plugin: prepared.plugin,
+                    candidate,
+                    variables: input.variables,
+                    containerImageId: input.containerImageId,
+                });
+            }
+            catch (error) {
+                if (candidateId)
+                    await this.packages.remove(candidateId);
+                throw error;
+            }
+            if (candidateId && !result.pluginCreated)
+                await this.packages.remove(candidateId);
+            await this.packages.workspaceDirectory(result.pluginId, installationId);
+            await this.publish(result.hint).catch(this.onError);
+            if (result.installation.status === "preparing")
+                this.activate(installationId);
+            return result.installation;
+        }
+        finally {
+            await this.packages.removePreparation(prepared.id).catch(this.onError);
+        }
+    }
+    async uninstall(actorUserId, pluginId) {
+        const result = await pluginUninstall(this.executor, actorUserId, pluginId);
+        for (const installationId of result.installationIds) {
+            const activation = this.activations.get(installationId);
+            activation?.controller.abort();
+            this.closeCommand(installationId);
+        }
+        await Promise.allSettled(result.installationIds.flatMap((installationId) => {
+            const activation = this.activations.get(installationId);
+            return activation ? [activation.promise] : [];
+        }));
+        await this.publish(result.hint).catch(this.onError);
+        await Promise.allSettled([
+            ...result.containerNames.map((containerName) => {
+                return this.runtime.removeLocal(containerName);
+            }),
+            this.packages.remove(pluginId),
+        ]).then((settled) => {
+            for (const item of settled)
+                if (item.status === "rejected")
+                    this.onError(item.reason);
+        });
+        return { installationIds: result.installationIds, pluginId };
+    }
+    async checkForUpdate(actorUserId, pluginId, onProgress, signal) {
+        const installed = await pluginGetSource(this.executor, actorUserId, pluginId);
+        let remotePackage;
+        if (installed.source.kind === "builtin") {
+            const catalogPackage = this.catalog.get(installed.source.reference);
+            if (!catalogPackage)
+                throw new PluginError("not_found", "Built-in plugin is no longer in the catalog");
+            remotePackage = catalogPackage;
+        }
+        else {
+            const remote = remotePluginSourceFromInstalled(installed.source);
+            onProgress("downloading", "Downloading the current remote plugin package.");
+            const downloaded = await this.archiveDownloader.download(remote.archiveUrl, {
+                signal,
+                onProgress: (bytes) => onProgress("downloading", "Downloading remote package.", bytes),
+            });
+            const directory = await this.packages.createDownloadDirectory();
+            try {
+                onProgress("verifying", "Verifying the current remote plugin package.");
+                const candidates = await pluginArchiveExtract(downloaded.body, directory, remote.kind === "github" ? "github" : "zip");
+                const candidate = remote.packagePath === undefined
+                    ? candidates[0]
+                    : candidates.find(({ packagePath }) => packagePath === remote.packagePath);
+                if (!candidate)
+                    throw new PluginError("invalid_package", "The installed plugin path no longer exists remotely");
+                remotePackage = await pluginPackageLoadSource(candidate.directory, installed.source);
+            }
+            finally {
+                await this.packages.removeDownloadDirectory(directory);
+            }
+        }
+        if (remotePackage.manifest.shortName !== installed.shortName)
+            throw new PluginError("invalid_package", "Remote plugin shortName changed");
+        return {
+            pluginId,
+            checkedAt: new Date().toISOString(),
+            updateAvailable: remotePackage.packageDigest !== installed.packageDigest,
+            installed: { version: installed.sourceVersion, packageDigest: installed.packageDigest },
+            remote: {
+                version: remotePackage.manifest.version,
+                packageDigest: remotePackage.packageDigest,
+            },
+        };
+    }
     async image(actorUserId, pluginId) {
         const image = await pluginGetImage(this.executor, actorUserId, pluginId);
         const body = await this.packages.readImage(image.pluginId, image.packageDirectory, image.storageKey, image.shortName, image.packageDigest);
@@ -104,71 +256,66 @@ export class PluginService {
     }
     async openLocal(installationId) {
         const configuration = await pluginInstallationGetRuntimeConfiguration(this.executor, this.secrets, installationId);
-        if (configuration.type !== "stdio")
+        if (configuration.type !== "local" || !configuration.mcp)
             throw new PluginError("not_found", "Plugin does not expose a local stdio MCP server");
+        const environment = this.runtimeEnvironment(configuration, await this.pluginRuntimeToken(configuration));
         return this.runtime.openLocal({
             containerName: configuration.containerName,
-            command: configuration.command,
-            args: configuration.args,
-            environment: configuration.environment,
+            command: configuration.mcp.command,
+            args: configuration.mcp.args,
+            environment,
         });
     }
     async listFunctions(signal) {
-        return withOperationTimeout(FUNCTION_DISCOVERY_TIMEOUT_MS, "Plugin MCP function discovery", signal, (operationSignal) => this.listFunctionsWithSignal(operationSignal));
+        signal?.throwIfAborted();
+        const tools = await pluginMcpToolsListReady(this.executor);
+        if (tools.length > MAX_RIG_PLUGIN_FUNCTIONS)
+            throw new PluginFunctionCatalogError(`Installed plugins expose ${tools.length} MCP tools, exceeding Rig's ${MAX_RIG_PLUGIN_FUNCTIONS}-function limit`);
+        return tools.map((tool) => ({
+            description: tool.description ?? `Runs ${tool.name} from the ${tool.shortName} plugin.`,
+            label: `${tool.shortName}: ${tool.title ?? tool.name}`,
+            name: pluginFunctionName(tool.installationId, tool.name),
+            parameters: tool.inputSchema,
+        }));
     }
-    async listFunctionsWithSignal(signal) {
-        const installationIds = await pluginInstallationListReadyMcpIds(this.executor);
-        const functions = [];
-        for (const installationId of installationIds) {
-            try {
-                const discovered = await this.withClient(installationId, signal, async (client, configuration) => {
-                    const definitions = [];
-                    const seenCursors = new Set();
-                    const remaining = MAX_RIG_PLUGIN_FUNCTIONS - functions.length;
-                    let pages = 0;
-                    let cursor;
-                    do {
-                        pages += 1;
-                        if (pages > MAX_RIG_PLUGIN_FUNCTIONS)
-                            throw new PluginFunctionCatalogError("Plugin MCP tool pagination exceeded the page limit");
-                        const page = await client.listTools(cursor === undefined ? undefined : { cursor });
-                        for (const tool of page.tools) {
-                            if (definitions.length >= remaining)
-                                throw new PluginFunctionCatalogError(`Installed plugins expose more than Rig's ${MAX_RIG_PLUGIN_FUNCTIONS}-function limit`);
-                            definitions.push({
-                                description: tool.description ??
-                                    `Runs ${tool.name} from the ${configuration.shortName} plugin.`,
-                                label: `${configuration.shortName}: ${tool.title ?? tool.name}`,
-                                name: pluginFunctionName(installationId, tool.name),
-                                parameters: tool.inputSchema,
-                            });
-                        }
-                        if (page.nextCursor && seenCursors.has(page.nextCursor))
-                            throw new Error("Plugin MCP tool pagination repeated a cursor");
-                        if (page.nextCursor)
-                            seenCursors.add(page.nextCursor);
-                        cursor = page.nextCursor;
-                    } while (cursor !== undefined);
-                    return definitions;
-                });
-                if (discovered)
-                    functions.push(...discovered);
-            }
-            catch (error) {
-                if (signal.aborted)
-                    throw error;
-                if (error instanceof PluginFunctionCatalogError)
-                    throw error;
-                this.onError(error);
-            }
+    async listSkills(signal) {
+        const skills = this.skillSources(await pluginSkillsListReady(this.executor), signal);
+        if (skills.length > MAX_RIG_PLUGIN_SKILLS)
+            throw new PluginSkillCatalogError(`Installed plugins expose ${skills.length} skills, exceeding Rig's ${MAX_RIG_PLUGIN_SKILLS}-skill limit`);
+        return skills.map(({ name, description }) => ({
+            name,
+            description,
+            location: "durable",
+        }));
+    }
+    async readSkill(skill, signal) {
+        try {
+            return await withOperationTimeout(FUNCTION_EXECUTION_TIMEOUT_MS, "Plugin skill read", signal, async (operationSignal) => {
+                const sources = this.skillSources(await pluginSkillsListInstalled(this.executor), operationSignal);
+                const source = sources.find(({ name }) => name === skill.name);
+                if (!source || source.description !== skill.description)
+                    throw new Error("The plugin no longer provides this durable skill");
+                const loaded = await this.packages.readSkill(source.pluginId, source.packageDirectory, source.shortName, source.packageDigest, source.name, source.directory, operationSignal);
+                if (loaded.description !== skill.description)
+                    throw new Error("Installed plugin skill metadata no longer matches");
+                return { status: "completed", output: loaded.source };
+            });
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            return {
+                status: "failed",
+                error: {
+                    code: "plugin_skill_failed",
+                    message: errorMessage(error),
+                },
+            };
         }
-        if (functions.length > MAX_RIG_PLUGIN_FUNCTIONS)
-            throw new Error(`Installed plugins expose ${functions.length} MCP tools, exceeding Rig's ${MAX_RIG_PLUGIN_FUNCTIONS}-function limit`);
-        return functions;
     }
-    async callFunction(functionName, args, signal) {
+    async callFunction(functionName, args, context, signal) {
         try {
-            return await withOperationTimeout(FUNCTION_EXECUTION_TIMEOUT_MS, "Plugin MCP function execution", signal, (operationSignal) => this.callFunctionWithSignal(functionName, args, operationSignal));
+            return await withOperationTimeout(FUNCTION_EXECUTION_TIMEOUT_MS, "Plugin MCP function execution", signal, (operationSignal) => this.callFunctionWithSignal(functionName, args, context, operationSignal));
         }
         catch (error) {
             if (signal?.aborted)
@@ -182,7 +329,7 @@ export class PluginService {
             };
         }
     }
-    async callFunctionWithSignal(functionName, args, signal) {
+    async callFunctionWithSignal(functionName, args, context, signal) {
         const installationId = pluginFunctionInstallationId(functionName);
         if (!installationId)
             throw new Error(`Unknown plugin function ${JSON.stringify(functionName)}`);
@@ -193,28 +340,24 @@ export class PluginService {
         const ready = await pluginInstallationListReadyMcpIds(this.executor);
         if (!ready.includes(installationId))
             throw new Error("The plugin installation is not ready");
-        const result = await this.withClient(installationId, signal, async (client, configuration) => {
-            const seenCursors = new Set();
-            let pages = 0;
-            let cursor;
-            let toolName;
-            do {
-                pages += 1;
-                if (pages > MAX_RIG_PLUGIN_FUNCTIONS)
-                    throw new Error("Plugin MCP tool pagination exceeded the page limit");
-                const page = await client.listTools(cursor === undefined ? undefined : { cursor });
-                toolName = page.tools.find((tool) => pluginFunctionName(installationId, tool.name) === functionName)?.name;
-                if (page.nextCursor && seenCursors.has(page.nextCursor))
-                    throw new Error("Plugin MCP tool pagination repeated a cursor");
-                if (page.nextCursor)
-                    seenCursors.add(page.nextCursor);
-                cursor = page.nextCursor;
-            } while (!toolName && cursor !== undefined);
-            if (!toolName)
-                throw new Error(`The ${configuration.shortName} plugin no longer exposes this function`);
+        const cached = (await pluginMcpToolsListReady(this.executor)).find((tool) => tool.installationId === installationId &&
+            pluginFunctionName(installationId, tool.name) === functionName);
+        if (!cached)
+            throw new Error("The plugin no longer exposes this cached function");
+        const chatToken = await this.tokens.issuePluginChatToken({
+            installationId,
+            chatId: context.chatId,
+        });
+        const result = await this.withClient(installationId, signal, async (client) => {
             const result = await client.callTool({
-                name: toolName,
+                name: cached.name,
                 arguments: jsonArguments(args),
+                _meta: {
+                    [PLUGIN_CHAT_META_KEY]: {
+                        id: context.chatId,
+                        token: chatToken,
+                    },
+                },
             });
             if (result.isError)
                 return {
@@ -231,13 +374,144 @@ export class PluginService {
             throw new Error("The plugin does not expose MCP tools");
         return result;
     }
+    skillSources(records, signal) {
+        const names = new Map();
+        for (const record of records) {
+            signal?.throwIfAborted();
+            const existing = names.get(record.name);
+            if (existing)
+                throw new PluginSkillCatalogError(`Installed plugins ${existing} and ${record.shortName} both provide skill ${record.name}`);
+            names.set(record.name, record.shortName);
+        }
+        return [...records];
+    }
+    async authorizeHost(token, permission) {
+        let claims;
+        try {
+            claims = await this.tokens.verifyPluginRuntimeToken(token);
+        }
+        catch {
+            throw new PluginError("forbidden", "Plugin runtime token is invalid");
+        }
+        if (!claims.permissions.includes(permission))
+            throw new PluginError("forbidden", `Plugin runtime lacks ${permission} permission`);
+        const authorized = await pluginContainerInstanceAuthorize(this.executor, claims.installationId, claims.containerInstanceId);
+        if (!authorized)
+            throw new PluginError("forbidden", "Plugin container incarnation is not authorized");
+        if (!this.runtime.isLocalRunning ||
+            !(await this.runtime.isLocalRunning(authorized.containerName, claims.installationId, claims.containerInstanceId))) {
+            const hint = await pluginContainerInstanceInvalidate(this.executor, {
+                installationId: claims.installationId,
+                containerInstanceId: claims.containerInstanceId,
+                detail: "Plugin container is missing or stopped.",
+            });
+            if (hint)
+                await this.publish(hint).catch(this.onError);
+            throw new PluginError("forbidden", "Plugin container incarnation is not running");
+        }
+        return claims.installationId;
+    }
+    async chatUpdate(runtimeToken, chatToken, input) {
+        const installationId = await this.authorizeHost(runtimeToken, "chats:update");
+        let claims;
+        try {
+            claims = await this.tokens.verifyPluginChatToken(chatToken);
+        }
+        catch {
+            throw new PluginError("forbidden", "Plugin chat token is invalid");
+        }
+        if (claims.installationId !== installationId)
+            throw new PluginError("forbidden", "Plugin chat token belongs to another installation");
+        const result = await chatUpdateMetadata(this.executor, {
+            chatId: claims.chatId,
+            ...input,
+        });
+        const event = { type: "sync", ...result.hint };
+        await Promise.allSettled([
+            this.pubsub.publish(realtimeTopics.chat(claims.chatId), event),
+            this.pubsub.publish(realtimeTopics.server, event),
+        ]).then((publications) => {
+            for (const publication of publications)
+                if (publication.status === "rejected")
+                    this.onError(publication.reason);
+        });
+        return { chat: result.chat, sync: result.hint };
+    }
     async close() {
         this.closed = true;
         for (const { controller } of this.activations.values())
             controller.abort();
         await Promise.allSettled([...this.activations.values()].map(({ promise }) => promise));
-        await Promise.allSettled([...this.localContainers].map((containerName) => this.runtime.removeLocal(containerName)));
-        this.localContainers.clear();
+        for (const handle of this.commandHandles.values())
+            handle.close();
+        this.commandHandles.clear();
+        await Promise.allSettled([...this.preparations.values()].map(({ id }) => this.packages.removePreparation(id)));
+        this.preparations.clear();
+    }
+    async prepareArchive(actorUserId, archive, kind, remote, onProgress) {
+        this.preparationsExpire();
+        const directory = await this.packages.createDownloadDirectory();
+        try {
+            const candidates = await pluginArchiveExtract(archive, directory, kind);
+            const prepared = [];
+            for (const candidate of candidates) {
+                const provisionalSource = remote
+                    ? downloadedPluginSource(remote, candidate.packagePath)
+                    : { kind: "upload", reference: "upload:pending" };
+                let plugin = await pluginPackageLoadSource(candidate.directory, provisionalSource);
+                if (/^plugins\/[^/]+$/.test(candidate.packagePath)) {
+                    const folder = candidate.packagePath.split("/").at(-1);
+                    if (plugin.manifest.shortName !== folder)
+                        throw new PluginError("invalid_package", `${candidate.packagePath}: shortName must match its plugin folder`);
+                }
+                if (!remote)
+                    plugin = { ...plugin, source: uploadedPluginSource(plugin.packageDigest) };
+                const id = createId();
+                plugin = await this.packages.prepare(plugin, id);
+                const secret = randomBytes(32).toString("base64url");
+                const token = `${id}.${secret}`;
+                const expiresAt = Date.now() + PREPARATION_TTL_MS;
+                this.preparations.set(id, {
+                    actorUserId,
+                    expiresAt,
+                    id,
+                    plugin,
+                    secretHash: createHash("sha256").update(secret).digest(),
+                });
+                prepared.push(preparedSummary(plugin, token, expiresAt));
+            }
+            onProgress("prepared", "Plugin package is verified and ready to install.");
+            return prepared;
+        }
+        catch (error) {
+            if (error instanceof PluginError)
+                throw error;
+            throw new PluginError("invalid_package", errorMessage(error));
+        }
+        finally {
+            await this.packages.removeDownloadDirectory(directory);
+        }
+    }
+    async preparationTake(actorUserId, token) {
+        this.preparationsExpire();
+        const match = /^([a-z0-9]+)\.([A-Za-z0-9_-]{43})$/.exec(token);
+        const prepared = match ? this.preparations.get(match[1]) : undefined;
+        const suppliedHash = match ? createHash("sha256").update(match[2]).digest() : undefined;
+        if (!prepared ||
+            !suppliedHash ||
+            prepared.actorUserId !== actorUserId ||
+            !timingSafeEqual(prepared.secretHash, suppliedHash))
+            throw new PluginError("not_found", "Prepared plugin token was not found or expired");
+        this.preparations.delete(prepared.id);
+        return prepared;
+    }
+    preparationsExpire() {
+        const now = Date.now();
+        for (const [id, prepared] of this.preparations)
+            if (prepared.expiresAt <= now) {
+                this.preparations.delete(id);
+                void this.packages.removePreparation(id).catch(this.onError);
+            }
     }
     activate(installationId) {
         if (this.closed || this.activations.has(installationId))
@@ -253,12 +527,17 @@ export class PluginService {
         const configuration = await pluginInstallationGetRuntimeConfiguration(this.executor, this.secrets, installationId);
         if (configuration.type === "skills_only")
             return undefined;
-        const transport = configuration.type === "stdio"
+        if (configuration.type === "local" && !configuration.mcp)
+            return undefined;
+        const localToken = configuration.type === "local"
+            ? await this.pluginRuntimeToken(configuration)
+            : undefined;
+        const transport = configuration.type === "local"
             ? await this.runtime.openLocal({
                 containerName: configuration.containerName,
-                command: configuration.command,
-                args: configuration.args,
-                environment: configuration.environment,
+                command: configuration.mcp.command,
+                args: configuration.mcp.args,
+                environment: this.runtimeEnvironment(configuration, localToken),
             }, signal)
             : new RemotePluginMcpTransport({
                 headers: configuration.headers,
@@ -280,6 +559,10 @@ export class PluginService {
     }
     async runActivation(installationId, signal) {
         let preparedContainerName;
+        let preparedContainerInstanceId;
+        let commandHandle;
+        let buildContextDirectory;
+        this.closeCommand(installationId);
         try {
             signal.throwIfAborted();
             await this.status(installationId, "preparing", "Preparing the installed plugin runtime.");
@@ -291,21 +574,28 @@ export class PluginService {
             }
             if (configuration.type === "remote") {
                 await this.status(installationId, "starting", "Checking the remote MCP server.");
-                await this.probeRemote(configuration, signal);
-                await this.status(installationId, "ready", "Remote MCP server is healthy.");
+                const tools = await this.probeRemote(configuration, signal);
+                const hint = await pluginMcpToolsReplace(this.executor, installationId, tools);
+                await this.publish(hint).catch(this.onError);
+                await this.status(installationId, "ready", "Remote MCP server and cached tools are ready.");
                 return;
             }
             const dockerfile = configuration.bundledDockerfile
                 ? await readFile(join(configuration.packageDirectory, configuration.bundledDockerfile), "utf8")
                 : undefined;
+            if (dockerfile)
+                buildContextDirectory = await this.packages.createBuildContext(configuration.pluginId, configuration.packageDirectory, configuration.shortName, configuration.packageDigest);
             const prepared = await this.runtime.prepareLocal({
                 installationId,
                 containerName: configuration.containerName,
+                containerInstanceId: createId(),
+                existingContainerInstanceId: configuration.containerInstanceId,
                 imageTag: configuration.imageTag,
+                workspaceDirectory: await this.packages.workspaceDirectory(configuration.pluginId, installationId),
                 ...(dockerfile
                     ? {
                         build: {
-                            contextDirectory: configuration.packageDirectory,
+                            contextDirectory: buildContextDirectory,
                             dockerfile,
                             tag: configuration.imageTag,
                         },
@@ -313,98 +603,165 @@ export class PluginService {
                     : {}),
             }, signal);
             preparedContainerName = configuration.containerName;
-            this.localContainers.add(configuration.containerName);
-            await this.status(installationId, "starting", "Starting and checking the containerized MCP server.", undefined, prepared.imageTag);
-            await this.probeLocal(configuration, signal);
-            await this.status(installationId, "ready", "Containerized MCP server is healthy.", undefined, prepared.imageTag);
+            preparedContainerInstanceId = prepared.containerInstanceId;
+            const token = await this.tokens.issuePluginRuntimeToken({
+                installationId,
+                containerInstanceId: prepared.containerInstanceId,
+                permissions: configuration.permissions,
+            });
+            const environment = this.runtimeEnvironment(configuration, token);
+            await this.status(installationId, "starting", "Starting and checking the containerized plugin runtime.", undefined, prepared.imageTag, prepared.containerInstanceId);
+            if (configuration.command) {
+                commandHandle = prepared.reused
+                    ? await this.runtime.monitorLocalCommand(configuration.containerName, signal)
+                    : await this.runtime.startLocalCommand({
+                        containerName: configuration.containerName,
+                        command: configuration.command.command,
+                        args: configuration.command.args,
+                        environment,
+                    }, signal);
+                this.commandHandles.set(installationId, commandHandle);
+                await commandSurviveStartup(commandHandle.wait, signal);
+            }
+            if (configuration.mcp) {
+                const tools = await this.probeLocal(configuration, environment, signal);
+                const hint = await pluginMcpToolsReplace(this.executor, installationId, tools);
+                await this.publish(hint).catch(this.onError);
+            }
+            await this.status(installationId, "ready", configuration.mcp
+                ? "Containerized plugin runtime and MCP tools are ready."
+                : "Containerized plugin command is running.", undefined, prepared.imageTag, prepared.containerInstanceId);
+            if (commandHandle)
+                this.monitorCommand(installationId, configuration.containerName, commandHandle);
         }
         catch (error) {
-            if (preparedContainerName) {
-                this.localContainers.delete(preparedContainerName);
-                await this.runtime.removeLocal(preparedContainerName).catch(this.onError);
+            if (commandHandle) {
+                if (this.commandHandles.get(installationId) === commandHandle)
+                    this.commandHandles.delete(installationId);
+                commandHandle.close();
             }
             if (signal.aborted && this.closed)
                 return;
+            if (preparedContainerName)
+                await this.runtime.removeLocal(preparedContainerName).catch(this.onError);
             const broken = error instanceof PluginError && error.code === "broken_configuration";
             await this.status(installationId, broken ? "broken_configuration" : "failed", broken
                 ? "Plugin configuration must be corrected before it can start."
-                : "Plugin runtime failed to prepare or start.", errorMessage(error)).catch(this.onError);
+                : "Plugin runtime failed to prepare or start.", errorMessage(error), undefined, preparedContainerInstanceId ? null : undefined).catch(this.onError);
+        }
+        finally {
+            if (buildContextDirectory)
+                await this.packages.removeBuildContext(buildContextDirectory).catch(this.onError);
         }
     }
-    async probeLocal(configuration, signal) {
+    async probeLocal(configuration, environment, signal) {
+        if (!configuration.mcp)
+            return [];
         const transport = await this.runtime.openLocal({
             containerName: configuration.containerName,
-            command: configuration.command,
-            args: configuration.args,
-            environment: configuration.environment,
+            command: configuration.mcp.command,
+            args: configuration.mcp.args,
+            environment,
         }, signal);
+        return this.discoverTools(transport, signal);
+    }
+    async discoverTools(transport, signal) {
         const client = new Client({ name: "happy2-plugin-health", version: "1.0.0" });
         try {
             await withTimeout(client.connect(transport), HEALTH_TIMEOUT_MS, "MCP initialization", signal);
             await withTimeout(client.ping(), HEALTH_TIMEOUT_MS, "MCP ping", signal);
+            const tools = [];
+            const cursors = new Set();
+            let cursor;
+            do {
+                const listed = await withTimeout(client.listTools(cursor ? { cursor } : undefined), HEALTH_TIMEOUT_MS, "MCP tool discovery", signal);
+                tools.push(...listed.tools.map((tool) => ({
+                    name: tool.name,
+                    ...(tool.title ? { title: tool.title } : {}),
+                    ...(tool.description ? { description: tool.description } : {}),
+                    inputSchema: tool.inputSchema,
+                    ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
+                    ...(tool.annotations ? { annotations: tool.annotations } : {}),
+                })));
+                if (tools.length > MAX_PLUGIN_MCP_TOOLS)
+                    throw new PluginError("broken_configuration", "Plugin MCP exposes too many tools");
+                cursor = listed.nextCursor;
+                if (cursor && cursors.has(cursor))
+                    throw new PluginError("broken_configuration", "Plugin MCP tool pagination repeated a cursor");
+                if (cursor)
+                    cursors.add(cursor);
+                if (cursors.size > MAX_PLUGIN_MCP_TOOLS)
+                    throw new PluginError("broken_configuration", "Plugin MCP tool pagination has too many pages");
+            } while (cursor);
+            return tools;
         }
         finally {
             await client.close().catch(() => transport.close());
         }
     }
     async probeRemote(configuration, signal) {
-        const destination = await withTimeout(this.urlPolicy.resolveForDelivery(configuration.url), HEALTH_TIMEOUT_MS, "Remote MCP DNS resolution", signal);
-        const id = createId();
-        const response = await withTimeout(this.remoteTransport.deliver({
-            deliveryId: `plugin-health:${configuration.installationId}`,
-            eventId: id,
-            eventType: "plugin.mcp.initialize",
-            url: destination.url,
-            allowedAddresses: destination.addresses,
-            headers: {
-                ...configuration.headers,
-                accept: "application/json, text/event-stream",
-                "content-type": "application/json",
-                "mcp-protocol-version": LATEST_PROTOCOL_VERSION,
-            },
-            body: JSON.stringify({
-                jsonrpc: "2.0",
-                id,
-                method: "initialize",
-                params: {
-                    protocolVersion: LATEST_PROTOCOL_VERSION,
-                    capabilities: {},
-                    clientInfo: { name: "happy2-plugin-health", version: "1.0.0" },
-                },
-            }),
-        }), HEALTH_TIMEOUT_MS, "Remote MCP initialization", signal);
-        if (response.statusCode < 200 || response.statusCode >= 300)
-            throw new Error(`Remote MCP initialization returned HTTP ${response.statusCode}`);
-        const payload = remoteJson(response.body ?? "");
-        if (!payload ||
-            payload.jsonrpc !== "2.0" ||
-            payload.id !== id ||
-            (!payload.result && !payload.error))
-            throw new Error("Remote MCP initialization returned an invalid JSON-RPC response");
-        if (payload.error) {
-            const error = payload.error && typeof payload.error === "object" && !Array.isArray(payload.error)
-                ? payload.error
-                : undefined;
-            const code = typeof error?.code === "number" ? ` with code ${error.code}` : "";
-            throw new Error(`Remote MCP initialization returned a JSON-RPC error${code}`);
-        }
+        return this.discoverTools(new RemotePluginMcpTransport({
+            headers: configuration.headers,
+            installationId: configuration.installationId,
+            remoteTransport: this.remoteTransport,
+            signal,
+            url: configuration.url,
+            urlPolicy: this.urlPolicy,
+        }), signal);
     }
-    async status(installationId, status, detail, error, runtimeImageTag) {
+    async status(installationId, status, detail, error, runtimeImageTag, containerInstanceId) {
         const hint = await pluginInstallationUpdateStatus(this.executor, {
             installationId,
             status,
             detail,
             error,
             runtimeImageTag,
+            containerInstanceId,
         });
         await this.publish(hint).catch(this.onError);
     }
     publish(hint) {
         return this.pubsub.publish(realtimeTopics.server, { type: "sync", ...hint });
     }
+    closeCommand(installationId) {
+        const handle = this.commandHandles.get(installationId);
+        if (!handle)
+            return;
+        this.commandHandles.delete(installationId);
+        handle.close();
+    }
+    monitorCommand(installationId, containerName, handle) {
+        void handle.wait
+            .then(async (result) => {
+            if (this.closed || this.commandHandles.get(installationId) !== handle)
+                return;
+            this.commandHandles.delete(installationId);
+            await this.runtime.removeLocal(containerName).catch(this.onError);
+            await this.status(installationId, "failed", "Plugin runtime command exited.", commandExitMessage(result), undefined, null);
+        })
+            .catch(this.onError);
+    }
+    runtimeEnvironment(configuration, token) {
+        return {
+            ...configuration.environment,
+            HAPPY2_PLUGIN_API_URL: this.hostApiUrl,
+            HAPPY2_PLUGIN_API_TOKEN: token,
+        };
+    }
+    pluginRuntimeToken(configuration) {
+        if (!configuration.containerInstanceId)
+            throw new PluginError("not_ready", "Plugin container incarnation is unavailable");
+        return this.tokens.issuePluginRuntimeToken({
+            installationId: configuration.installationId,
+            containerInstanceId: configuration.containerInstanceId,
+            permissions: configuration.permissions,
+        });
+    }
 }
 class PluginFunctionCatalogError extends Error {
 }
+class PluginSkillCatalogError extends Error {
+}
 function pluginFunctionName(installationId, toolName) {
     const normalized = toolName
         .normalize("NFKD")
@@ -438,36 +795,29 @@ function mcpErrorMessage(content) {
     }
     return "The plugin MCP tool returned an error";
 }
-function remoteJson(body) {
-    const direct = jsonRecord(body.trim());
-    if (direct)
-        return direct;
-    let data = [];
-    for (const line of body.split(/\r?\n/)) {
-        if (!line) {
-            const event = jsonRecord(data.join("\n"));
-            if (event)
-                return event;
-            data = [];
-        }
-        else if (line.startsWith("data:")) {
-            data.push(line.slice(5).trimStart());
-        }
-    }
-    return jsonRecord(data.join("\n"));
+function commandSurviveStartup(wait, signal) {
+    if (signal.aborted)
+        return Promise.reject(abortReason(signal));
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (action) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal.removeEventListener("abort", aborted);
+            action();
+        };
+        const aborted = () => finish(() => reject(abortReason(signal)));
+        const timer = setTimeout(() => finish(resolve), COMMAND_STARTUP_GRACE_MS);
+        signal.addEventListener("abort", aborted, { once: true });
+        wait.then((result) => finish(() => reject(new Error(`Plugin command exited during startup: ${commandExitMessage(result)}`))), (error) => finish(() => reject(error)));
+    });
 }
-function jsonRecord(source) {
-    if (!source)
-        return undefined;
-    try {
-        const value = JSON.parse(source);
-        return value && typeof value === "object" && !Array.isArray(value)
-            ? value
-            : undefined;
-    }
-    catch {
-        return undefined;
-    }
+function commandExitMessage(result) {
+    return result.signal
+        ? `Plugin command exited after signal ${result.signal}`
+        : `Plugin command exited with code ${result.exitCode ?? "unknown"}`;
 }
 function withTimeout(promise, timeoutMs, operation, signal) {
     if (signal?.aborted)
@@ -535,4 +885,33 @@ function errorMessage(error) {
     const message = error instanceof Error ? error.message : String(error);
     return message.slice(0, 4_000);
 }
+function preparedSummary(plugin, preparedToken, expiresAt) {
+    const mcp = plugin.manifest.mcp;
+    return {
+        preparedToken,
+        expiresAt: new Date(expiresAt).toISOString(),
+        sourceKind: plugin.source.kind,
+        sourceReference: plugin.source.reference,
+        packageDigest: plugin.packageDigest,
+        version: plugin.manifest.version,
+        displayName: plugin.manifest.displayName,
+        shortName: plugin.manifest.shortName,
+        description: plugin.manifest.description,
+        skills: plugin.skills.map(({ name, description }) => ({ name, description })),
+        variables: plugin.manifest.variables,
+        ...(mcp
+            ? {
+                mcp: {
+                    type: mcp.type,
+                    container: mcp.type === "remote"
+                        ? "none"
+                        : mcp.container
+                            ? "bundled"
+                            : "selection_required",
+                },
+            }
+            : {}),
+        image: plugin.image,
+    };
+}
 //# sourceMappingURL=service.js.map