happy2 0.0.12 → 0.0.14

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

@@ -1,58 +1,101 @@
-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 { realtimeTopics } from "../realtime/index.js";
+import { chatUpdateMetadata } from "../chat/chatUpdateMetadata.js";
+import { channelCreateWithMembers } from "../chat/channelCreateWithMembers.js";
+import { channelMembersUpdate } from "../chat/channelMembersUpdate.js";
+import { messageSend } from "../message/messageSend.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";
+import { pluginInstallationGetRequestUninstallContext } from "./pluginInstallationGetRequestUninstallContext.js";
+import { pluginInstallationUninstall } from "./pluginInstallationUninstall.js";
 import { pluginInstallationListIds } from "./pluginInstallationListIds.js";
 import { pluginInstallationListReadyMcpIds } from "./pluginInstallationListReadyMcpIds.js";
 import { pluginInstallationUpdateStatus } from "./pluginInstallationUpdateStatus.js";
+import { pluginInstallationPermissionsUpdate } from "./pluginInstallationPermissionsUpdate.js";
+import { pluginInstallationGetContainerName } from "./pluginInstallationGetContainerName.js";
+import { pluginAgentCallContextGet } from "./pluginAgentCallContextGet.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 { pluginApiPermissionSections } from "./impl/apiPermissions.js";
+import { effectiveContainer } from "./impl/effectiveContainer.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 { pluginManagementRequestBeginInstall } from "./pluginManagementRequestBeginInstall.js";
+import { pluginManagementRequestBeginUninstall } from "./pluginManagementRequestBeginUninstall.js";
+import { pluginManagementRequestCompleteInstall } from "./pluginManagementRequestCompleteInstall.js";
+import { pluginManagementRequestCompleteUninstall } from "./pluginManagementRequestCompleteUninstall.js";
+import { pluginManagementRequestCreateInstall } from "./pluginManagementRequestCreateInstall.js";
+import { pluginManagementRequestCreateUninstall } from "./pluginManagementRequestCreateUninstall.js";
+import { pluginManagementRequestDeny } from "./pluginManagementRequestDeny.js";
+import { pluginManagementRequestGetPackage } from "./pluginManagementRequestGetPackage.js";
+import { pluginManagementRequestList } from "./pluginManagementRequestList.js";
+import { pluginManagementRequestListTerminalIds } from "./pluginManagementRequestListTerminalIds.js";
+import { pluginManagementRequestRecoverProcessing } from "./pluginManagementRequestRecoverProcessing.js";
 import { RemotePluginMcpTransport } from "./utils/remoteMcpTransport.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 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";
+const PLUGIN_USERS_META_KEY = "happy2/users";
 /** Coordinates durable plugin installs with asynchronous container preparation, MCP health probes, restart recovery, and local connection creation. */
 export class PluginService {
     executor;
     pubsub;
     catalog;
     packages;
+    packageLinks;
     secrets;
     runtime;
     tokens;
     urlPolicy;
     remoteTransport;
     hostApiUrl;
+    archiveDownloader;
     onError;
     activations = new Map();
     commandHandles = new Map();
+    preparations = new Map();
     closed = false;
-    constructor(executor, pubsub, catalog, packages, secrets, runtime, tokens, urlPolicy, remoteTransport, hostApiUrl, onError) {
+    constructor(executor, pubsub, catalog, packages, packageLinks, secrets, runtime, tokens, urlPolicy, remoteTransport, hostApiUrl, archiveDownloader, onError) {
         this.executor = executor;
         this.pubsub = pubsub;
         this.catalog = catalog;
         this.packages = packages;
+        this.packageLinks = packageLinks;
         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();
+        for (const hint of await pluginManagementRequestRecoverProcessing(this.executor))
+            await this.publish(hint).catch(this.onError);
+        for (const requestId of await pluginManagementRequestListTerminalIds(this.executor))
+            await this.packages.removeRequest(requestId).catch(this.onError);
         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)),
@@ -64,24 +107,70 @@ export class PluginService {
             this.activate(installationId);
     }
     async install(input) {
-        await pluginAuthorizeManagement(this.executor, input.actorUserId);
+        if (input.actorUserId)
+            await pluginAuthorizeManagement(this.executor, input.actorUserId);
+        else if (!input.actorInstallationId)
+            throw new PluginError("forbidden", "Plugin installation authority is required");
         const plugin = this.catalog.get(input.shortName);
         if (!plugin)
             throw new PluginError("not_found", "Built-in plugin was not found");
-        const installationId = createId();
-        const existing = await pluginFindBySource(this.executor, plugin.source.kind, plugin.source.reference);
+        return this.installPackage({ ...input, plugin });
+    }
+    async installArchive(input) {
+        await pluginAuthorizeManagement(this.executor, input.actorUserId);
+        const prepared = await this.prepareRequestedArchive(input.archive, {
+            kind: "archive",
+            reference: "pending",
+        });
+        try {
+            return await this.installPackage({
+                ...input,
+                permissions: [],
+                plugin: prepared.plugin,
+            });
+        }
+        finally {
+            await prepared.cleanup();
+        }
+    }
+    async installLink(input) {
+        await pluginAuthorizeManagement(this.executor, input.actorUserId);
+        const downloaded = await this.downloadPackage(input.url);
+        const prepared = await this.prepareRequestedArchive(downloaded.body, {
+            kind: "link",
+            reference: downloaded.url,
+        });
+        try {
+            return await this.installPackage({
+                ...input,
+                permissions: [],
+                plugin: prepared.plugin,
+            });
+        }
+        finally {
+            await prepared.cleanup();
+        }
+    }
+    async installPackage(input) {
+        const installationId = input.installationId ?? createId();
+        const existing = await pluginFindBySource(this.executor, input.plugin.source.kind, input.plugin.source.reference);
         const candidateId = existing ? undefined : createId();
         const candidate = candidateId
-            ? { pluginId: candidateId, ...(await this.packages.install(plugin, candidateId)) }
+            ? {
+                pluginId: candidateId,
+                ...(await this.packages.install(input.plugin, candidateId)),
+            }
             : undefined;
         let result;
         try {
             result = await pluginInstall(this.executor, this.secrets, {
                 actorUserId: input.actorUserId,
+                actorInstallationId: input.actorInstallationId,
                 installationId,
-                plugin,
+                plugin: input.plugin,
                 candidate,
                 variables: input.variables,
+                permissions: input.permissions,
                 containerImageId: input.containerImageId,
             });
         }
@@ -92,11 +181,194 @@ 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,
+                    permissions: input.permissions,
+                    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 updatePermissions(input) {
+        const result = await pluginInstallationPermissionsUpdate(this.executor, input);
+        if (!result.changed)
+            return result.installation;
+        if (result.hint)
+            await this.publish(result.hint).catch(this.onError);
+        await this.stopActivation(input.installationId);
+        if (result.containerName)
+            await this.runtime.removeLocal(result.containerName).catch(this.onError);
+        this.activate(input.installationId);
+        return result.installation;
+    }
+    async uninstallInstallation(input) {
+        if (input.actorUserId)
+            await pluginAuthorizeManagement(this.executor, input.actorUserId);
+        else if (!input.actorInstallationId)
+            throw new PluginError("forbidden", "Plugin installation authority is required");
+        const containerName = await pluginInstallationGetContainerName(this.executor, input.installationId);
+        await this.stopActivation(input.installationId);
+        try {
+            if (containerName)
+                await this.runtime.removeLocal(containerName);
+            const result = await pluginInstallationUninstall(this.executor, input);
+            if (result.pluginRemoved)
+                await this.packages.remove(result.pluginId);
+            await this.publish(result.hint).catch(this.onError);
+        }
+        catch (error) {
+            this.activate(input.installationId);
+            throw error;
+        }
+    }
+    async downloadPackage(url) {
+        try {
+            return await this.packageLinks.download(url);
+        }
+        catch (error) {
+            if (error instanceof PluginError)
+                throw error;
+            throw new PluginError("broken_configuration", errorMessage(error));
+        }
+    }
+    async prepareRequestedArchive(archive, source) {
+        try {
+            return await this.packages.prepareArchive(archive, source);
+        }
+        catch (error) {
+            if (error instanceof PluginError)
+                throw error;
+            throw new PluginError("broken_configuration", errorMessage(error));
+        }
+    }
     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);
@@ -109,6 +381,165 @@ export class PluginService {
             checksumSha256: image.checksumSha256,
         };
     }
+    async requestInstallLink(input) {
+        const downloaded = await this.downloadPackage(input.url);
+        const prepared = await this.prepareRequestedArchive(downloaded.body, {
+            kind: "link",
+            reference: downloaded.url,
+        });
+        const requestId = createId();
+        try {
+            if (prepared.plugin.manifest.variables.length)
+                throw new PluginError("broken_configuration", "Plugins that require configuration must be installed directly by an administrator");
+            const container = effectiveContainer(prepared.plugin.manifest);
+            if (container && !container.dockerfile)
+                throw new PluginError("broken_configuration", "Plugins that require an administrator-selected image cannot be requested from chat");
+            const packageDirectory = await this.packages.stageRequest(prepared.plugin, requestId);
+            try {
+                const result = await pluginManagementRequestCreateInstall(this.executor, {
+                    id: requestId,
+                    actorUserId: input.agentCall.actorUserId,
+                    agentUserId: input.agentCall.agentUserId,
+                    callId: input.agentCall.callId,
+                    chatId: input.agentCall.chatId,
+                    requesterInstallationId: input.requesterInstallationId,
+                    displayName: prepared.plugin.manifest.displayName,
+                    shortName: prepared.plugin.manifest.shortName,
+                    description: prepared.plugin.manifest.description,
+                    reason: input.reason,
+                    sourceKind: "link",
+                    sourceReference: downloaded.url,
+                    packageDigest: prepared.plugin.packageDigest,
+                    packageDirectory,
+                    installationId: createId(),
+                });
+                if (!result.created)
+                    await this.packages.removeRequest(requestId);
+                if (result.hint)
+                    await this.publish(result.hint).catch(this.onError);
+                return result.request;
+            }
+            catch (error) {
+                await this.packages.removeRequest(requestId);
+                throw error;
+            }
+        }
+        finally {
+            await prepared.cleanup();
+        }
+    }
+    async requestUninstall(input) {
+        const target = await pluginInstallationGetRequestUninstallContext(this.executor, input.targetInstallationId);
+        const plugin = await this.packages.loadInstalled(target.pluginId, target.packageDirectory, target.shortName, target.packageDigest, target.source);
+        const requestId = createId();
+        const packageDirectory = await this.packages.stageRequest(plugin, requestId);
+        try {
+            const result = await pluginManagementRequestCreateUninstall(this.executor, {
+                id: requestId,
+                actorUserId: input.agentCall.actorUserId,
+                agentUserId: input.agentCall.agentUserId,
+                callId: input.agentCall.callId,
+                chatId: input.agentCall.chatId,
+                requesterInstallationId: input.requesterInstallationId,
+                targetInstallationId: input.targetInstallationId,
+                displayName: target.displayName,
+                shortName: target.shortName,
+                description: target.description,
+                reason: input.reason,
+                source: target.source,
+                packageDigest: target.packageDigest,
+                packageDirectory,
+            });
+            if (!result.created)
+                await this.packages.removeRequest(requestId);
+            if (result.hint)
+                await this.publish(result.hint).catch(this.onError);
+            return result.request;
+        }
+        catch (error) {
+            await this.packages.removeRequest(requestId);
+            throw error;
+        }
+    }
+    listManagementRequests(actorUserId, chatId) {
+        return pluginManagementRequestList(this.executor, actorUserId, chatId);
+    }
+    async managementRequestImage(input) {
+        const request = await pluginManagementRequestGetPackage(this.executor, input.actorUserId, input.chatId, input.requestId);
+        return this.packages.readRequestImage(request.id, request.packageDirectory, request.source, request.packageDigest);
+    }
+    async approveManagementRequest(input) {
+        const work = await pluginManagementRequestBeginInstall(this.executor, input);
+        await this.publish(work.hint).catch(this.onError);
+        try {
+            const plugin = await this.packages.loadRequest(work.id, work.packageDirectory, work.source, work.packageDigest);
+            await this.installPackage({
+                actorUserId: input.actorUserId,
+                installationId: work.installationId,
+                plugin,
+                variables: {},
+                permissions: [],
+            });
+        }
+        catch (error) {
+            const hint = await pluginManagementRequestCompleteInstall(this.executor, {
+                ...input,
+                installationId: work.installationId,
+                error: errorMessage(error),
+            });
+            await this.publish(hint).catch(this.onError);
+            await this.packages.removeRequest(input.requestId).catch(this.onError);
+            throw error;
+        }
+        const hint = await pluginManagementRequestCompleteInstall(this.executor, {
+            ...input,
+            installationId: work.installationId,
+        });
+        await this.publish(hint).catch(this.onError);
+        await this.packages.removeRequest(input.requestId).catch(this.onError);
+        const requests = await pluginManagementRequestList(this.executor, input.actorUserId, input.chatId);
+        const request = requests.find(({ id }) => id === input.requestId);
+        if (!request)
+            throw new Error("Completed plugin management request was not found");
+        return request;
+    }
+    async denyManagementRequest(input) {
+        const hint = await pluginManagementRequestDeny(this.executor, input);
+        await this.publish(hint).catch(this.onError);
+        await this.packages.removeRequest(input.requestId).catch(this.onError);
+        const requests = await pluginManagementRequestList(this.executor, input.actorUserId, input.chatId);
+        const request = requests.find(({ id }) => id === input.requestId);
+        if (!request)
+            throw new Error("Denied plugin management request was not found");
+        return request;
+    }
+    async approveUninstallManagementRequest(input) {
+        const work = await pluginManagementRequestBeginUninstall(this.executor, input);
+        await this.publish(work.hint).catch(this.onError);
+        try {
+            await this.uninstallInstallation({
+                actorUserId: input.actorUserId,
+                installationId: work.targetInstallationId,
+            });
+        }
+        catch (error) {
+            const hint = await pluginManagementRequestCompleteUninstall(this.executor, {
+                ...input,
+                error: errorMessage(error),
+            });
+            await this.publish(hint).catch(this.onError);
+            await this.packages.removeRequest(input.requestId).catch(this.onError);
+            throw error;
+        }
+        const hint = await pluginManagementRequestCompleteUninstall(this.executor, input);
+        await this.publish(hint).catch(this.onError);
+        await this.packages.removeRequest(input.requestId).catch(this.onError);
+        const requests = await pluginManagementRequestList(this.executor, input.actorUserId, input.chatId);
+        const request = requests.find(({ id }) => id === input.requestId);
+        if (!request)
+            throw new Error("Completed plugin uninstall request was not found");
+        return request;
+    }
     async openLocal(installationId) {
         const configuration = await pluginInstallationGetRuntimeConfiguration(this.executor, this.secrets, installationId);
         if (configuration.type !== "local" || !configuration.mcp)
@@ -133,9 +564,45 @@ export class PluginService {
             parameters: tool.inputSchema,
         }));
     }
-    async callFunction(functionName, args, signal) {
+    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),
+                },
+            };
+        }
+    }
+    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));
+            const agentCall = await pluginAgentCallContextGet(this.executor, context.sessionId, context.callId);
+            return await withOperationTimeout(FUNCTION_EXECUTION_TIMEOUT_MS, "Plugin MCP function execution", signal, (operationSignal) => this.callFunctionWithSignal(functionName, args, context, agentCall, operationSignal));
         }
         catch (error) {
             if (signal?.aborted)
@@ -149,7 +616,7 @@ export class PluginService {
             };
         }
     }
-    async callFunctionWithSignal(functionName, args, signal) {
+    async callFunctionWithSignal(functionName, args, context, agentCall, signal) {
         const installationId = pluginFunctionInstallationId(functionName);
         if (!installationId)
             throw new Error(`Unknown plugin function ${JSON.stringify(functionName)}`);
@@ -164,10 +631,31 @@ export class PluginService {
             pluginFunctionName(installationId, tool.name) === functionName);
         if (!cached)
             throw new Error("The plugin no longer exposes this cached function");
-        const result = await this.withClient(installationId, signal, async (client) => {
+        const chatToken = await this.tokens.issuePluginChatToken({
+            installationId,
+            chatId: context.chatId,
+            actorUserId: context.triggeredByUserId,
+            agentUserId: context.agentUserId,
+        });
+        const referencedUsers = await Promise.all(context.users.map(async (user) => ({
+            ...user,
+            token: await this.tokens.issuePluginUserToken({
+                installationId,
+                userId: user.id,
+            }),
+        })));
+        const result = await this.withClient(installationId, signal, agentCall, async (client) => {
             const result = await client.callTool({
                 name: cached.name,
                 arguments: jsonArguments(args),
+                _meta: {
+                    [PLUGIN_CHAT_META_KEY]: {
+                        id: context.chatId,
+                        token: chatToken,
+                        triggeredByUserId: context.triggeredByUserId,
+                    },
+                    [PLUGIN_USERS_META_KEY]: referencedUsers,
+                },
             });
             if (result.isError)
                 return {
@@ -184,6 +672,17 @@ 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 {
@@ -192,6 +691,14 @@ export class PluginService {
         catch {
             throw new PluginError("forbidden", "Plugin runtime token is invalid");
         }
+        if (claims.agentCall) {
+            const active = await pluginAgentCallContextGet(this.executor, claims.agentCall.sessionId, claims.agentCall.callId).catch(() => undefined);
+            if (!active ||
+                active.actorUserId !== claims.agentCall.actorUserId ||
+                active.agentUserId !== claims.agentCall.agentUserId ||
+                active.chatId !== claims.agentCall.chatId)
+                throw new PluginError("forbidden", "Plugin agent-call capability is no longer active");
+        }
         if (!claims.permissions.includes(permission))
             throw new PluginError("forbidden", `Plugin runtime lacks ${permission} permission`);
         const authorized = await pluginContainerInstanceAuthorize(this.executor, claims.installationId, claims.containerInstanceId);
@@ -208,7 +715,140 @@ export class PluginService {
                 await this.publish(hint).catch(this.onError);
             throw new PluginError("forbidden", "Plugin container incarnation is not running");
         }
-        return claims.installationId;
+        return claims;
+    }
+    async chatUpdate(runtimeToken, chatToken, input) {
+        const claims = await this.authorizeChat(runtimeToken, chatToken, "chats:update");
+        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 channelMembersUpdate(runtimeToken, chatToken, input) {
+        const claims = await this.authorizeChat(runtimeToken, chatToken, "channels:manage");
+        const [addUserIds, removeUserIds] = await Promise.all([
+            this.authorizeUsers(claims.installationId, input.add),
+            this.authorizeUsers(claims.installationId, input.remove),
+        ]);
+        const result = await channelMembersUpdate(this.executor, {
+            actorUserId: claims.actorUserId,
+            chatId: claims.chatId,
+            addUserIds,
+            removeUserIds,
+        });
+        await this.publishHints(result.hints, [...addUserIds, ...removeUserIds]);
+        return {
+            chatId: claims.chatId,
+            addedUserIds: addUserIds,
+            removedUserIds: removeUserIds,
+            sync: result.hints,
+        };
+    }
+    async channelCreate(runtimeToken, chatToken, input, agents) {
+        const claims = await this.authorizeChat(runtimeToken, chatToken, "channels:manage");
+        const memberUserIds = await this.authorizeUsers(claims.installationId, input.members);
+        const clientMutationId = input.idempotencyKey
+            ? `${claims.installationId}:${input.idempotencyKey}`
+            : undefined;
+        if (input.initialMessage?.audience === "agents" && !agents)
+            throw new PluginError("not_ready", "AI agents are not enabled on this server");
+        const created = await channelCreateWithMembers(this.executor, {
+            actorUserId: claims.actorUserId,
+            name: input.name,
+            slug: pluginChannelSlug(input.name),
+            topic: input.description,
+            memberUserIds,
+            clientMutationId,
+            ...(input.initialMessage?.audience === "agents"
+                ? { defaultAgentUserId: claims.agentUserId }
+                : {}),
+        });
+        const hints = [...created.hints];
+        let initialMessage;
+        if (input.initialMessage) {
+            const agentTurns = input.initialMessage.audience === "agents"
+                ? await agents.prepareTurns({
+                    actorUserId: claims.actorUserId,
+                    agentUserIds: [],
+                    chatId: created.chat.id,
+                })
+                : [];
+            const sent = await messageSend(this.executor, {
+                actorUserId: claims.actorUserId,
+                chatId: created.chat.id,
+                text: input.initialMessage.text,
+                audience: input.initialMessage.audience,
+                agentTurns,
+                clientMutationId,
+            });
+            initialMessage = sent.message;
+            hints.push(sent.hint);
+            if (agentTurns.length)
+                agents.startTurn(created.chat.id);
+        }
+        await this.publishHints(hints, [claims.actorUserId, ...memberUserIds]);
+        return {
+            chat: created.chat,
+            ...(initialMessage ? { initialMessage } : {}),
+            sync: hints,
+        };
+    }
+    async authorizeChat(runtimeToken, chatToken, permission) {
+        const { installationId } = await this.authorizeHost(runtimeToken, permission);
+        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");
+        return claims;
+    }
+    async authorizeUsers(installationId, capabilities) {
+        return Promise.all(capabilities.map(async (capability) => {
+            let claims;
+            try {
+                claims = await this.tokens.verifyPluginUserToken(capability.token);
+            }
+            catch {
+                throw new PluginError("forbidden", "Plugin user token is invalid");
+            }
+            if (claims.installationId !== installationId)
+                throw new PluginError("forbidden", "Plugin user token belongs to another installation");
+            if (claims.userId !== capability.id)
+                throw new PluginError("forbidden", "Plugin user token belongs to another user");
+            return claims.userId;
+        }));
+    }
+    async publishHints(hints, userIds) {
+        const publications = [];
+        for (const hint of hints) {
+            const event = { type: "sync", ...hint };
+            const topics = new Set([
+                realtimeTopics.server,
+                ...hint.chats.map(({ chatId }) => realtimeTopics.chat(chatId)),
+                ...userIds.map((userId) => realtimeTopics.user(userId)),
+            ]);
+            for (const topic of topics)
+                publications.push(this.pubsub.publish(topic, event));
+        }
+        await Promise.allSettled(publications).then((results) => {
+            for (const result of results)
+                if (result.status === "rejected")
+                    this.onError(result.reason);
+        });
     }
     async close() {
         this.closed = true;
@@ -218,6 +858,73 @@ export class PluginService {
         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))
@@ -228,7 +935,14 @@ export class PluginService {
             .finally(() => this.activations.delete(installationId));
         this.activations.set(installationId, { controller, promise });
     }
-    async withClient(installationId, signal, action) {
+    async stopActivation(installationId) {
+        const activation = this.activations.get(installationId);
+        activation?.controller.abort();
+        if (activation)
+            await activation.promise;
+        this.closeCommand(installationId);
+    }
+    async withClient(installationId, signal, agentCall, action) {
         signal?.throwIfAborted();
         const configuration = await pluginInstallationGetRuntimeConfiguration(this.executor, this.secrets, installationId);
         if (configuration.type === "skills_only")
@@ -236,7 +950,7 @@ export class PluginService {
         if (configuration.type === "local" && !configuration.mcp)
             return undefined;
         const localToken = configuration.type === "local"
-            ? await this.pluginRuntimeToken(configuration)
+            ? await this.pluginRuntimeToken(configuration, agentCall)
             : undefined;
         const transport = configuration.type === "local"
             ? await this.runtime.openLocal({
@@ -267,6 +981,7 @@ export class PluginService {
         let preparedContainerName;
         let preparedContainerInstanceId;
         let commandHandle;
+        let buildContextDirectory;
         this.closeCommand(installationId);
         try {
             signal.throwIfAborted();
@@ -288,16 +1003,19 @@ export class PluginService {
             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,
                         },
@@ -342,15 +1060,19 @@ export class PluginService {
                     this.commandHandles.delete(installationId);
                 commandHandle.close();
             }
-            if (signal.aborted && this.closed)
-                return;
             if (preparedContainerName)
                 await this.runtime.removeLocal(preparedContainerName).catch(this.onError);
+            if (signal.aborted)
+                return;
             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), undefined, preparedContainerInstanceId ? null : undefined).catch(this.onError);
         }
+        finally {
+            if (buildContextDirectory)
+                await this.packages.removeBuildContext(buildContextDirectory).catch(this.onError);
+        }
     }
     async probeLocal(configuration, environment, signal) {
         if (!configuration.mcp)
@@ -419,7 +1141,11 @@ export class PluginService {
         await this.publish(hint).catch(this.onError);
     }
     publish(hint) {
-        return this.pubsub.publish(realtimeTopics.server, { type: "sync", ...hint });
+        const event = { type: "sync", ...hint };
+        return Promise.all([
+            this.pubsub.publish(realtimeTopics.server, event),
+            ...hint.chats.map(({ chatId }) => this.pubsub.publish(realtimeTopics.chat(chatId), event)),
+        ]).then(() => undefined);
     }
     closeCommand(installationId) {
         const handle = this.commandHandles.get(installationId);
@@ -446,18 +1172,21 @@ export class PluginService {
             HAPPY2_PLUGIN_API_TOKEN: token,
         };
     }
-    pluginRuntimeToken(configuration) {
+    pluginRuntimeToken(configuration, agentCall) {
         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,
+            ...(agentCall ? { agentCall } : {}),
         });
     }
 }
 class PluginFunctionCatalogError extends Error {
 }
+class PluginSkillCatalogError extends Error {
+}
 function pluginFunctionName(installationId, toolName) {
     const normalized = toolName
         .normalize("NFKD")
@@ -467,6 +1196,17 @@ function pluginFunctionName(installationId, toolName) {
     const digest = createHash("sha256").update(toolName).digest("hex").slice(0, 16);
     return `plugin_${installationId}_${normalized || "tool"}_${digest}`;
 }
+function pluginChannelSlug(name) {
+    const suffix = createId();
+    const base = name
+        .normalize("NFKD")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 63 - suffix.length)
+        .replace(/-+$/g, "");
+    return `${base || "channel"}-${suffix}`;
+}
 function pluginFunctionInstallationId(functionName) {
     const match = /^plugin_([a-z0-9]+)_/u.exec(functionName);
     return match?.[1];
@@ -581,4 +1321,34 @@ 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,
+        apiPermissions: pluginApiPermissionSections(effectiveContainer(plugin.manifest)?.permissions ?? []),
+        ...(mcp
+            ? {
+                mcp: {
+                    type: mcp.type,
+                    container: mcp.type === "remote"
+                        ? "none"
+                        : mcp.container
+                            ? "bundled"
+                            : "selection_required",
+                },
+            }
+            : {}),
+        image: plugin.image,
+    };
+}
 //# sourceMappingURL=service.js.map