@chainingintention/pi-web-cn 1.202610.1 → 1.202610.3

package/dist/server/plugins/serverPluginRuntime.js

@@ -1,32 +1,56 @@
+import { mkdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { isPiWebPluginId } from "../../shared/pluginIds.js";
 import { pathToFileURL } from "node:url";
+import { parseServerNoticeScope, SERVER_PLUGIN_NOTICE_CONTEXT_MAX_BYTES, SERVER_PLUGIN_NOTICE_CONTEXT_MAX_DEPTH, SERVER_PLUGIN_NOTICE_MESSAGE_MAX_BYTES, SERVER_PLUGIN_NOTICE_SOURCE_PREFIX, serverNoticeStringExceedsUtf8ByteLimit, } from "../../shared/serverNoticeContract.js";
+import { REQUIRED_TERMINAL_PLUGIN_ID, REQUIRED_TERMINAL_RECOVERY_GUIDANCE, } from "../../shared/requiredTerminalPlugin.js";
+import { REQUIRED_TERMINAL_SERVICE_CAPABILITY } from "../terminals/requiredTerminalService.js";
 import { createServerPluginExecFile } from "./serverPluginExec.js";
 const DEFAULT_LIFECYCLE_TIMEOUT_MS = 10_000;
 /**
  * Resolves exactly one desired catalog snapshot and activates its server
  * entries. The resulting runtime is immutable except for explicit shutdown;
- * v1 intentionally has no hot reload or unload path.
+ * this lifecycle intentionally has no hot reload or unload path.
  */
 export async function createServerPluginRuntime(options) {
     if (options.safeStart === "none") {
         return await ServerPluginRuntime.activate({ plugins: [], diagnostics: [] }, options);
     }
     const snapshot = await options.catalog.snapshot(options.safeStart === "bundled-only" ? { scope: "bundled" } : undefined);
+    if (options.enforceRequiredTerminal !== false)
+        requireTerminalCatalogEntry(snapshot);
     return await ServerPluginRuntime.activate(snapshot, options);
 }
 export class ServerPluginRuntime {
-    constructor(safeStart, diagnostics, logger, importer, execFile, lifecycleTimeoutMs) {
+    constructor(dataDir, safeStart, diagnostics, logger, importer, execFile, lifecycleTimeoutMs, noticeSink, hostCapabilities, hostCapabilityFactories, lateHostCapabilities, enforceRequiredTerminal) {
+        this.dataDir = dataDir;
         this.safeStart = safeStart;
         this.diagnostics = diagnostics;
         this.logger = logger;
         this.importer = importer;
         this.execFile = execFile;
         this.lifecycleTimeoutMs = lifecycleTimeoutMs;
+        this.noticeSink = noticeSink;
+        this.enforceRequiredTerminal = enforceRequiredTerminal;
         this.recordsById = new Map();
+        this.declaredCapabilitiesByKey = new Map();
+        this.activeCapabilitiesByKey = new Map();
         this.activePlugins = [];
+        this.stagedPlugins = [];
+        this.lifetimesAborted = false;
+        this.lateHostCapabilitiesResumed = false;
         this.stopped = false;
+        for (const provision of hostCapabilities) {
+            this.registerHostCapability(provision);
+            this.activeCapabilitiesByKey.set(provision.key, provision);
+        }
+        for (const factory of hostCapabilityFactories)
+            this.registerHostCapability(factory);
+        for (const capability of lateHostCapabilities)
+            this.registerHostCapability(capability);
     }
     static async activate(snapshot, options) {
-        const runtime = new ServerPluginRuntime(options.safeStart, Object.freeze(snapshot.diagnostics.map((diagnostic) => Object.freeze({ ...diagnostic }))), options.logger, options.importer ?? importServerPluginModule, options.execFile ?? createServerPluginExecFile(), positiveInteger(options.lifecycleTimeoutMs, DEFAULT_LIFECYCLE_TIMEOUT_MS, "lifecycleTimeoutMs"));
+        const runtime = new ServerPluginRuntime(resolve(options.dataDir), options.safeStart, Object.freeze(snapshot.diagnostics.map((diagnostic) => Object.freeze({ ...diagnostic }))), options.logger, options.importer ?? importServerPluginModule, options.execFile ?? createServerPluginExecFile(), positiveInteger(options.lifecycleTimeoutMs, DEFAULT_LIFECYCLE_TIMEOUT_MS, "lifecycleTimeoutMs"), options.noticeSink, snapshotHostCapabilities(options.hostCapabilities), snapshotHostCapabilityFactories(options.hostCapabilityFactories), snapshotLateHostCapabilities(options.lateHostCapabilities), options.enforceRequiredTerminal !== false && options.safeStart !== "none");
         try {
             await runtime.start(snapshot.plugins);
             return runtime;
@@ -36,6 +60,12 @@ export class ServerPluginRuntime {
             throw error;
         }
     }
+    registerHostCapability(declaration) {
+        if (this.declaredCapabilitiesByKey.has(declaration.key)) {
+            throw new Error(`Host capability ${formatCapability(declaration.capability)} is configured more than once`);
+        }
+        this.declaredCapabilitiesByKey.set(declaration.key, declaration);
+    }
     safeStartLevel() {
         return this.safeStart;
     }
@@ -48,11 +78,67 @@ export class ServerPluginRuntime {
             .map((record) => Object.freeze({ ...record })));
     }
     providerContributions() {
-        return Object.freeze(this.activePlugins.flatMap((active) => active.contribution === undefined ? [] : [active.contribution]));
+        return Object.freeze(this.activePlugins.flatMap((active) => active.providerContribution === undefined ? [] : [active.providerContribution]));
+    }
+    pairedBackendContributions() {
+        return Object.freeze(this.activePlugins.flatMap((active) => active.pairedBackendContribution === undefined ? [] : [active.pairedBackendContribution]));
     }
-    async inspectHealth() {
+    /** Resolves one exact active capability for a core host consumer. */
+    resolve(capability) {
+        const parsed = snapshotTypedCapability(capability, "Host capability request");
+        const provision = this.activeCapabilitiesByKey.get(capabilityKey(parsed));
+        if (provision === undefined) {
+            throw new Error(`Server capability ${formatCapability(parsed)} is not active`);
+        }
+        return parseCapabilityValue(parsed, provision.value, `Server capability ${formatCapability(parsed)}`);
+    }
+    /**
+     * Registers every declared late host factory atomically, then resumes the
+     * plugins staged on those capabilities. This boundary is intentionally one-shot.
+     */
+    async resumeWithHostCapabilityFactories(factories) {
+        if (this.stopped || this.lifetimesAborted) {
+            throw new Error("Server plugin runtime cannot resume after shutdown begins");
+        }
+        if (this.lateHostCapabilitiesResumed) {
+            throw new Error("Server plugin late host capabilities have already resumed");
+        }
+        const snapshottedFactories = snapshotHostCapabilityFactories(factories);
+        const lateDeclarations = [...this.declaredCapabilitiesByKey.values()]
+            .filter((declaration) => declaration.source === "late-host");
+        const factoriesByKey = new Map(snapshottedFactories.map((factory) => [factory.key, factory]));
+        for (const factory of snapshottedFactories) {
+            if (!lateDeclarations.some(({ key }) => key === factory.key)) {
+                throw new Error(`Host capability ${formatCapability(factory.capability)} was not declared for late registration`);
+            }
+        }
+        for (const declaration of lateDeclarations) {
+            if (!factoriesByKey.has(declaration.key)) {
+                throw new Error(`Late host capability ${formatCapability(declaration.capability)} was not registered`);
+            }
+        }
+        this.lateHostCapabilitiesResumed = true;
+        for (const factory of snapshottedFactories)
+            this.declaredCapabilitiesByKey.set(factory.key, factory);
+        await this.startStagedPlugins(false);
+    }
+    /** Cancels plugin lifetimes while retaining publications for consumer cleanup. */
+    beginShutdown() {
+        if (this.lifetimesAborted)
+            return;
+        this.lifetimesAborted = true;
+        const reason = new DOMException("Server plugin host is shutting down", "AbortError");
+        for (const plugin of [...this.activePlugins, ...this.stagedPlugins]) {
+            if (!plugin.lifetimeController.signal.aborted)
+                plugin.lifetimeController.abort(reason);
+        }
+    }
+    async inspectHealth(pluginIds) {
+        const selectedPluginIds = pluginIds === undefined ? undefined : new Set(pluginIds);
         const inspections = [];
         for (const active of this.activePlugins) {
+            if (selectedPluginIds !== undefined && !selectedPluginIds.has(active.entry.id))
+                continue;
             const callback = active.activation.health?.bind(active.activation);
             if (callback === undefined) {
                 inspections.push(Object.freeze({ pluginId: active.entry.id, health: Object.freeze({ status: "healthy" }) }));
@@ -75,39 +161,43 @@ export class ServerPluginRuntime {
         }
         return Object.freeze(inspections);
     }
-    /** Stops every successfully published plugin in reverse activation order. */
+    /** Disposes published plugins in reverse dependency/start order. */
     async stop() {
         if (this.stopped)
             return;
+        this.beginShutdown();
         this.stopped = true;
+        // During failed construction, activated entries may not have reached start.
+        // Dispose those first while any started providers remain published.
+        const stagedPlugins = [...this.stagedPlugins].reverse();
+        this.stagedPlugins = [];
+        for (const staged of stagedPlugins) {
+            await this.disposeForShutdown(staged);
+        }
         const activePlugins = [...this.activePlugins].reverse();
         this.activePlugins = [];
+        this.activeCapabilitiesByKey.clear();
         for (const active of activePlugins) {
-            const stop = active.activation.stop?.bind(active.activation);
-            if (stop === undefined)
-                continue;
-            try {
-                await runBounded(active.entry.id, "stop", this.lifecycleTimeoutMs, (signal) => stop(signal));
-            }
-            catch (error) {
-                this.recordsById.set(active.entry.id, recordFor(active.entry, {
-                    state: "failed",
-                    name: active.plugin.name,
-                    phase: "stop",
-                    message: errorMessage(error),
-                }));
-                this.logger.error({ err: error, pluginId: active.entry.id, phase: "stop" }, "server plugin stop failed");
-            }
+            await this.disposeForShutdown(active);
         }
     }
     async start(entries) {
         const serverEntries = entries
             .filter((entry) => entry.serverModule !== undefined)
-            .sort((left, right) => left.id.localeCompare(right.id));
+            .sort(requiredTerminalFirst);
         for (const entry of serverEntries)
-            await this.activateEntry(entry);
+            await this.stageEntry(entry);
+        await this.startStagedPlugins(true);
+        if (this.enforceRequiredTerminal) {
+            try {
+                this.resolve(REQUIRED_TERMINAL_SERVICE_CAPABILITY);
+            }
+            catch (error) {
+                throw requiredTerminalError("Required Terminal service capability is not active", error);
+            }
+        }
     }
-    async activateEntry(entry) {
+    async stageEntry(entry) {
         const disabledMessage = disabledReason(entry, this.safeStart);
         if (disabledMessage !== undefined) {
             this.recordsById.set(entry.id, recordFor(entry, { state: "disabled", message: disabledMessage }));
@@ -116,7 +206,9 @@ export class ServerPluginRuntime {
         }
         let phase = "validate";
         let plugin;
-        let activation;
+        let rollbackDispose;
+        let noticeReporter;
+        const lifetimeController = new AbortController();
         try {
             const settings = cloneJsonObject(entry.settings, `settings for server plugin ${entry.id}`);
             phase = "import";
@@ -126,51 +218,56 @@ export class ServerPluginRuntime {
             const loadedPlugin = parsePluginExport(imported);
             plugin = loadedPlugin;
             phase = "activate";
+            if (!isPiWebPluginId(entry.id))
+                throw new Error(`Invalid PI WEB plugin id: ${entry.id}`);
+            const dataDirectory = resolve(this.dataDir, "plugin-data", entry.id);
+            await mkdir(dataDirectory, { recursive: true });
             const scopedLogger = createScopedLogger(entry.id, this.logger);
+            noticeReporter = createScopedNoticeReporter(entry.id, this.noticeSink);
             const activationValue = await runBounded(entry.id, phase, this.lifecycleTimeoutMs, (signal) => loadedPlugin.activate(Object.freeze({
-                apiVersion: 1,
+                apiVersion: 3,
                 pluginId: entry.id,
                 packageRoot: entry.packageRoot,
+                dataDirectory,
                 logger: scopedLogger,
                 settings,
+                ...(noticeReporter === undefined ? {} : { notices: noticeReporter.reporter }),
                 execFile: this.execFile,
                 signal,
+                lifetimeSignal: lifetimeController.signal,
             })));
+            rollbackDispose = activationDisposeForRollback(activationValue);
             phase = "validate";
-            const loadedActivation = parseActivation(activationValue);
-            activation = loadedActivation;
-            phase = "start";
-            const start = loadedActivation.start?.bind(loadedActivation);
-            if (start !== undefined) {
-                await runBounded(entry.id, phase, this.lifecycleTimeoutMs, (signal) => start(signal));
+            const loadedActivation = parseActivation(activationValue, entry.id);
+            if (this.enforceRequiredTerminal && entry.id === REQUIRED_TERMINAL_PLUGIN_ID) {
+                requireTerminalActivation(loadedActivation);
             }
-            const contribution = loadedActivation.workspaceProvider === undefined
-                ? undefined
-                : Object.freeze({
-                    pluginId: entry.id,
-                    pluginName: loadedPlugin.name,
-                    packageRoot: entry.packageRoot,
-                    source: entry.source,
-                    scope: entry.scope,
-                    moduleRevision: requireServerModule(entry).revision,
-                    provider: loadedActivation.workspaceProvider,
-                });
-            this.activePlugins.push(Object.freeze({
+            const provisions = internalProvisions(loadedActivation, "plugin");
+            for (const provision of provisions) {
+                if (this.declaredCapabilitiesByKey.has(provision.key)) {
+                    throw new IncompatibleServerPluginError(`Server capability ${formatCapability(provision.capability)} is provided more than once`);
+                }
+            }
+            const staged = Object.freeze({
                 entry,
                 plugin: loadedPlugin,
                 activation: loadedActivation,
-                ...(contribution === undefined ? {} : { contribution }),
-            }));
-            this.recordsById.set(entry.id, recordFor(entry, { state: "active", name: loadedPlugin.name }));
-            this.logger.info({ pluginId: entry.id, pluginName: loadedPlugin.name }, "server plugin activated");
+                lifetimeController,
+                ...(noticeReporter === undefined ? {} : { noticeReporter }),
+                provisions,
+                hostCapabilityInstances: [],
+            });
+            this.stagedPlugins.push(staged);
+            for (const provision of provisions)
+                this.declaredCapabilitiesByKey.set(provision.key, provision);
         }
         catch (error) {
-            const rollbackError = phase === "start" && activation?.stop !== undefined
-                ? await this.rollbackStart(entry.id, activation)
-                : undefined;
-            const message = rollbackError === undefined
-                ? errorMessage(error)
-                : `${errorMessage(error)}; startup rollback failed: ${errorMessage(rollbackError)}`;
+            abortPluginLifetime(lifetimeController, entry.id, "activation failed");
+            noticeReporter?.revoke();
+            const rollbackError = rollbackDispose === undefined
+                ? undefined
+                : await this.runDispose(entry.id, rollbackDispose);
+            const message = withRollbackError(errorMessage(error), rollbackError);
             const state = error instanceof IncompatibleServerPluginError ? "incompatible" : "failed";
             this.recordsById.set(entry.id, recordFor(entry, {
                 state,
@@ -179,20 +276,311 @@ export class ServerPluginRuntime {
                 message,
             }));
             const details = { err: error, pluginId: entry.id, phase, ...(rollbackError === undefined ? {} : { rollbackError }) };
-            if (state === "incompatible") {
+            if (state === "incompatible")
                 this.logger.warn(details, "server plugin is incompatible");
+            else
+                this.logger.error(details, "server plugin activation failed");
+            if (this.enforceRequiredTerminal && entry.id === REQUIRED_TERMINAL_PLUGIN_ID) {
+                throw requiredTerminalError(`Required Terminal server entry failed during ${phase}: ${message}`, error);
+            }
+        }
+    }
+    async startStagedPlugins(allowLateHostWait) {
+        const pending = new Map(this.stagedPlugins.map((plugin) => [plugin.entry.id, plugin]));
+        while (pending.size > 0) {
+            let progressed = false;
+            const candidates = [...pending.values()].sort((left, right) => requiredTerminalFirst(left.entry, right.entry));
+            for (const staged of candidates) {
+                const dependencyFailure = this.dependencyFailure(staged, pending);
+                if (dependencyFailure !== undefined) {
+                    pending.delete(staged.entry.id);
+                    const message = await this.failBeforeStart(staged, dependencyFailure);
+                    progressed = true;
+                    if (this.enforceRequiredTerminal && staged.entry.id === REQUIRED_TERMINAL_PLUGIN_ID) {
+                        throw requiredTerminalError(`Required Terminal server entry failed during start: ${message}`, dependencyFailure);
+                    }
+                    continue;
+                }
+                if (this.waitingForDependencies(staged))
+                    continue;
+                pending.delete(staged.entry.id);
+                const startError = await this.startStagedPlugin(staged);
+                progressed = true;
+                if (startError !== undefined && this.enforceRequiredTerminal && staged.entry.id === REQUIRED_TERMINAL_PLUGIN_ID) {
+                    const record = this.recordsById.get(staged.entry.id);
+                    throw requiredTerminalError(`Required Terminal server entry failed during start: ${record?.message ?? errorMessage(startError)}`, startError);
+                }
+            }
+            if (progressed)
+                continue;
+            const cycleIds = findCapabilityCycle(pending, this.declaredCapabilitiesByKey);
+            if (cycleIds.length > 0) {
+                for (const pluginId of cycleIds) {
+                    const staged = pending.get(pluginId);
+                    if (staged === undefined)
+                        continue;
+                    pending.delete(pluginId);
+                    const cyclicRequirement = (staged.plugin.requires ?? []).find((requirement) => cycleIds.includes(requirement.pluginId));
+                    const error = new Error(cyclicRequirement === undefined
+                        ? `Server plugin ${pluginId} has an unresolved capability dependency cycle`
+                        : `Server plugin ${pluginId} requires ${formatCapability(cyclicRequirement)} in a capability dependency cycle`);
+                    const message = await this.failBeforeStart(staged, error);
+                    if (this.enforceRequiredTerminal && pluginId === REQUIRED_TERMINAL_PLUGIN_ID) {
+                        throw requiredTerminalError(`Required Terminal server entry failed during start: ${message}`, error);
+                    }
+                }
+                continue;
+            }
+            if (allowLateHostWait) {
+                const providerCycles = candidates.flatMap((staged) => {
+                    if (staged.activation.workspaceProvider === undefined)
+                        return [];
+                    const lateCapability = findLateHostDependency(staged, pending, this.declaredCapabilitiesByKey);
+                    return lateCapability === undefined ? [] : [{ staged, lateCapability }];
+                });
+                if (providerCycles.length > 0) {
+                    for (const { staged, lateCapability } of providerCycles) {
+                        pending.delete(staged.entry.id);
+                        const error = new Error(`Server plugin ${staged.entry.id} contributes a workspace provider that depends on late host capability ${formatCapability(lateCapability)} in a capability dependency cycle`);
+                        const message = await this.failBeforeStart(staged, error);
+                        if (this.enforceRequiredTerminal && staged.entry.id === REQUIRED_TERMINAL_PLUGIN_ID) {
+                            throw requiredTerminalError(`Required Terminal server entry failed during start: ${message}`, error);
+                        }
+                    }
+                    continue;
+                }
+                if (candidates.every((staged) => (findLateHostDependency(staged, pending, this.declaredCapabilitiesByKey) !== undefined)))
+                    return;
+            }
+            const unresolved = candidates[0];
+            if (unresolved === undefined)
+                return;
+            pending.delete(unresolved.entry.id);
+            const error = new Error(`Server plugin ${unresolved.entry.id} has an unresolved capability dependency cycle`);
+            const message = await this.failBeforeStart(unresolved, error);
+            if (this.enforceRequiredTerminal && unresolved.entry.id === REQUIRED_TERMINAL_PLUGIN_ID) {
+                throw requiredTerminalError(`Required Terminal server entry failed during start: ${message}`, error);
+            }
+        }
+    }
+    dependencyFailure(staged, pending) {
+        for (const requirement of staged.plugin.requires ?? []) {
+            const key = capabilityKey(requirement);
+            const provision = this.declaredCapabilitiesByKey.get(key);
+            if (provision === undefined) {
+                return new Error(`Server plugin ${staged.entry.id} requires unavailable capability ${formatCapability(requirement)}`);
+            }
+            if (this.activeCapabilitiesByKey.has(key)
+                || provision.source === "host"
+                || provision.source === "host-factory"
+                || provision.source === "late-host")
+                continue;
+            if (!pending.has(requirement.pluginId)) {
+                return new Error(`Server plugin ${staged.entry.id} requires ${formatCapability(requirement)}, but provider plugin ${requirement.pluginId} did not start`);
+            }
+        }
+        return undefined;
+    }
+    waitingForDependencies(staged) {
+        return (staged.plugin.requires ?? []).some((requirement) => {
+            const key = capabilityKey(requirement);
+            return this.declaredCapabilitiesByKey.get(key)?.source !== "host-factory"
+                && !this.activeCapabilitiesByKey.has(key);
+        });
+    }
+    async startStagedPlugin(staged) {
+        try {
+            const capabilities = this.capabilityResolver(staged);
+            const start = staged.activation.start?.bind(staged.activation);
+            if (start !== undefined) {
+                await runBounded(staged.entry.id, "start", this.lifecycleTimeoutMs, (signal) => start(Object.freeze({
+                    capabilities,
+                    signal,
+                })));
+            }
+            if (this.enforceRequiredTerminal && staged.entry.id === REQUIRED_TERMINAL_PLUGIN_ID) {
+                await this.requireHealthyTerminal(staged);
+            }
+            this.publish(staged);
+            return undefined;
+        }
+        catch (error) {
+            await this.failBeforeStart(staged, error);
+            return error;
+        }
+    }
+    capabilityResolver(staged) {
+        const resolved = new Map();
+        for (const requirement of staged.plugin.requires ?? []) {
+            const key = capabilityKey(requirement);
+            const activeProvision = this.activeCapabilitiesByKey.get(key);
+            const declaration = this.declaredCapabilitiesByKey.get(key);
+            let provisionValue;
+            if (activeProvision !== undefined) {
+                provisionValue = activeProvision.value;
+            }
+            else if (declaration?.source === "host-factory") {
+                provisionValue = this.createHostCapabilityValue(staged, declaration);
             }
             else {
-                this.logger.error(details, "server plugin activation failed");
+                throw new Error(`Server plugin ${staged.entry.id} requires inactive capability ${formatCapability(requirement)}`);
             }
+            // Validate the declared requirement before start, but retain the provider value:
+            // resolve() may supply a different parser for this same capability key.
+            parseCapabilityValue(requirement, provisionValue, `Required capability ${formatCapability(requirement)} for server plugin ${staged.entry.id}`);
+            resolved.set(key, { provisionValue });
         }
+        return createCapabilityResolver(staged.entry.id, resolved);
+    }
+    createHostCapabilityValue(staged, factory) {
+        const context = Object.freeze({
+            pluginId: staged.entry.id,
+            packageRoot: staged.entry.packageRoot,
+            lifetimeSignal: staged.lifetimeController.signal,
+        });
+        const instance = factory.create(context);
+        staged.hostCapabilityInstances.push(instance);
+        return parseCapabilityValue(factory.capability, instance.value, `Host capability ${formatCapability(factory.capability)} for server plugin ${staged.entry.id}`);
+    }
+    async requireHealthyTerminal(staged) {
+        const health = staged.activation.health?.bind(staged.activation);
+        if (health === undefined)
+            return;
+        const result = await runBounded(staged.entry.id, "health", this.lifecycleTimeoutMs, (signal) => health(signal));
+        const parsed = parseHealth(result);
+        if (parsed.status === "unhealthy") {
+            throw new Error(`Required Terminal server entry is unhealthy: ${parsed.message ?? "health check failed"}`);
+        }
+    }
+    publish(staged) {
+        const providerContribution = staged.activation.workspaceProvider === undefined
+            ? undefined
+            : Object.freeze({
+                pluginId: staged.entry.id,
+                pluginName: staged.plugin.name,
+                packageRoot: staged.entry.packageRoot,
+                source: staged.entry.source,
+                scope: staged.entry.scope,
+                moduleRevision: requireServerModule(staged.entry).revision,
+                provider: staged.activation.workspaceProvider,
+            });
+        const pairedBackendContribution = staged.activation.peer === undefined
+            ? undefined
+            : Object.freeze({
+                pluginId: staged.entry.id,
+                pluginName: staged.plugin.name,
+                packageRoot: staged.entry.packageRoot,
+                source: staged.entry.source,
+                scope: staged.entry.scope,
+                moduleRevision: requireServerModule(staged.entry).revision,
+                backend: staged.activation.peer,
+                requires: this.resolvedCapabilityRequirements(staged),
+            });
+        const active = Object.freeze({
+            ...staged,
+            ...(providerContribution === undefined ? {} : { providerContribution }),
+            ...(pairedBackendContribution === undefined ? {} : { pairedBackendContribution }),
+        });
+        this.removeStaged(staged.entry.id);
+        this.activePlugins.push(active);
+        for (const provision of staged.provisions)
+            this.activeCapabilitiesByKey.set(provision.key, provision);
+        this.recordsById.set(staged.entry.id, recordFor(staged.entry, {
+            state: "active",
+            name: staged.plugin.name,
+            ...(pairedBackendContribution?.backend.request === undefined ? {} : { pairedRequestVersion: 1 }),
+            ...(pairedBackendContribution?.backend.openChannel === undefined ? {} : { pairedChannelVersion: 1 }),
+        }));
+        this.logger.info({ pluginId: staged.entry.id, pluginName: staged.plugin.name }, "server plugin activated");
+    }
+    resolvedCapabilityRequirements(staged) {
+        const requirements = new Map();
+        const visited = new Set();
+        const visit = (plugin) => {
+            if (visited.has(plugin.entry.id))
+                return;
+            visited.add(plugin.entry.id);
+            for (const requirement of plugin.plugin.requires ?? []) {
+                const key = capabilityKey(requirement);
+                requirements.set(key, requirement);
+                if (this.declaredCapabilitiesByKey.get(key)?.source !== "plugin")
+                    continue;
+                const provider = this.activePlugins.find(({ entry }) => entry.id === requirement.pluginId);
+                if (provider !== undefined)
+                    visit(provider);
+            }
+        };
+        visit(staged);
+        return Object.freeze([...requirements.values()]);
     }
-    async rollbackStart(pluginId, activation) {
-        const stop = activation.stop?.bind(activation);
-        if (stop === undefined)
+    async failBeforeStart(staged, error) {
+        abortPluginLifetime(staged.lifetimeController, staged.entry.id, "startup failed");
+        staged.noticeReporter?.revoke();
+        this.removeStaged(staged.entry.id);
+        const dispose = staged.activation.dispose?.bind(staged.activation);
+        const rollbackError = dispose === undefined ? undefined : await this.runDispose(staged.entry.id, dispose);
+        const hostCleanupError = await this.disposeHostCapabilityInstances(staged);
+        const message = withHostCleanupError(withRollbackError(errorMessage(error), rollbackError), hostCleanupError);
+        this.recordsById.set(staged.entry.id, recordFor(staged.entry, {
+            state: "failed",
+            name: staged.plugin.name,
+            phase: "start",
+            message,
+        }));
+        this.logger.error({
+            err: error,
+            pluginId: staged.entry.id,
+            phase: "start",
+            ...(rollbackError === undefined ? {} : { rollbackError }),
+            ...(hostCleanupError === undefined ? {} : { hostCleanupError }),
+        }, "server plugin start failed");
+        return message;
+    }
+    removeStaged(pluginId) {
+        this.stagedPlugins = this.stagedPlugins.filter(({ entry }) => entry.id !== pluginId);
+    }
+    async disposeForShutdown(plugin) {
+        plugin.noticeReporter?.revoke();
+        const dispose = plugin.activation.dispose?.bind(plugin.activation);
+        const pluginDisposeError = dispose === undefined ? undefined : await this.runDispose(plugin.entry.id, dispose);
+        const hostCleanupError = await this.disposeHostCapabilityInstances(plugin);
+        const error = combinedDisposalError(pluginDisposeError, hostCleanupError);
+        if (error === undefined)
+            return;
+        this.recordsById.set(plugin.entry.id, recordFor(plugin.entry, {
+            state: "failed",
+            name: plugin.plugin.name,
+            phase: "dispose",
+            message: errorMessage(error),
+            ...(plugin.activation.peer?.request === undefined ? {} : { pairedRequestVersion: 1 }),
+            ...(plugin.activation.peer?.openChannel === undefined ? {} : { pairedChannelVersion: 1 }),
+        }));
+        this.logger.error({
+            err: error,
+            pluginId: plugin.entry.id,
+            phase: "dispose",
+            ...(hostCleanupError === undefined ? {} : { hostCleanupError }),
+        }, "server plugin disposal failed");
+    }
+    async disposeHostCapabilityInstances(plugin) {
+        const instances = plugin.hostCapabilityInstances.splice(0).reverse();
+        const errors = [];
+        for (const instance of instances) {
+            if (instance.dispose === undefined)
+                continue;
+            const error = await this.runDispose(plugin.entry.id, instance.dispose);
+            if (error !== undefined)
+                errors.push(error);
+        }
+        if (errors.length === 0)
             return undefined;
+        if (errors.length === 1)
+            return errors[0];
+        return new AggregateError(errors, "Multiple host capability cleanup operations failed");
+    }
+    async runDispose(pluginId, dispose) {
         try {
-            await runBounded(pluginId, "stop", this.lifecycleTimeoutMs, (signal) => stop(signal));
+            await runBounded(pluginId, "dispose", this.lifecycleTimeoutMs, (signal) => dispose(signal));
             return undefined;
         }
         catch (error) {
@@ -200,6 +588,46 @@ export class ServerPluginRuntime {
         }
     }
 }
+function requireTerminalCatalogEntry(snapshot) {
+    const entry = snapshot.plugins.find(({ id }) => id === REQUIRED_TERMINAL_PLUGIN_ID);
+    if (entry === undefined)
+        throw requiredTerminalError("Required bundled Terminal package is missing");
+    if (entry.scope !== "bundled" || entry.source !== "bundled") {
+        throw requiredTerminalError("Required Terminal package must come from the bundled plugin scope");
+    }
+    if (entry.browserModule === undefined || entry.serverModule === undefined || !entry.machineSpecific) {
+        throw requiredTerminalError("Required Terminal package must provide machine-specific browser and server entries");
+    }
+    if (!entry.enabled)
+        throw requiredTerminalError("Required Terminal package cannot be disabled in normal startup");
+    return entry;
+}
+function requireTerminalActivation(activation) {
+    if (activation.peer?.request === undefined || activation.peer.openChannel === undefined) {
+        throw new IncompatibleServerPluginError("Required Terminal server entry must expose peer request and channel capabilities");
+    }
+    const requiredKey = capabilityKey(REQUIRED_TERMINAL_SERVICE_CAPABILITY);
+    const provision = activation.provides?.find(({ capability }) => capabilityKey(capability) === requiredKey);
+    if (provision === undefined) {
+        throw new IncompatibleServerPluginError(`Required Terminal server entry must provide ${formatCapability(REQUIRED_TERMINAL_SERVICE_CAPABILITY)}`);
+    }
+    try {
+        REQUIRED_TERMINAL_SERVICE_CAPABILITY.parse(provision.value);
+    }
+    catch (error) {
+        throw new IncompatibleServerPluginError(errorMessage(error), { cause: error });
+    }
+}
+function requiredTerminalFirst(left, right) {
+    if (left.id === REQUIRED_TERMINAL_PLUGIN_ID)
+        return right.id === REQUIRED_TERMINAL_PLUGIN_ID ? 0 : -1;
+    if (right.id === REQUIRED_TERMINAL_PLUGIN_ID)
+        return 1;
+    return left.id.localeCompare(right.id);
+}
+function requiredTerminalError(message, cause) {
+    return new RequiredTerminalPluginError(`${message}. ${REQUIRED_TERMINAL_RECOVERY_GUIDANCE}`, cause === undefined ? {} : { cause });
+}
 function disabledReason(entry, safeStart) {
     if (!entry.enabled)
         return "disabled in PI WEB config";
@@ -218,6 +646,8 @@ function recordFor(entry, status) {
         ...(entry.browserModule === undefined ? {} : { browserRevision: entry.browserModule.revision }),
         settingsRevision: entry.settingsRevision,
         machineSpecific: entry.machineSpecific,
+        ...(status.pairedRequestVersion === undefined ? {} : { pairedRequestVersion: status.pairedRequestVersion }),
+        ...(status.pairedChannelVersion === undefined ? {} : { pairedChannelVersion: status.pairedChannelVersion }),
         state: status.state,
         ...(status.name === undefined ? {} : { name: status.name }),
         ...(status.phase === undefined ? {} : { phase: status.phase }),
@@ -246,44 +676,62 @@ function parsePluginExport(imported) {
     const plugin = imported["default"];
     if (!isRecord(plugin))
         throw new IncompatibleServerPluginError("Server plugin module must export a default plugin object");
-    const candidate = {
-        apiVersion: plugin["apiVersion"],
-        name: plugin["name"],
-        activate: plugin["activate"],
-    };
-    if (candidate.apiVersion !== 1) {
-        throw new IncompatibleServerPluginError(`Unsupported server plugin API version: ${formatUnknown(candidate.apiVersion)}`);
+    const apiVersion = plugin["apiVersion"];
+    const name = plugin["name"];
+    const activateValue = plugin["activate"];
+    if (apiVersion !== 3) {
+        throw new IncompatibleServerPluginError(`Unsupported server plugin API version: ${formatUnknown(apiVersion)}`);
     }
-    if (typeof candidate.name !== "string" || candidate.name === "") {
+    if (typeof name !== "string" || name === "") {
         throw new IncompatibleServerPluginError("Server plugin name must be a non-empty string");
     }
-    if (typeof candidate.activate !== "function" || !isPiWebServerPlugin(candidate)) {
+    if (typeof activateValue !== "function") {
         throw new IncompatibleServerPluginError("Server plugin activate must be a function");
     }
-    const activate = candidate.activate.bind(plugin);
-    return Object.freeze({ apiVersion: 1, name: candidate.name, activate: (context) => activate(context) });
+    const requires = snapshotCapabilityRequirements(plugin["requires"], `Server plugin ${name} requirements`);
+    return Object.freeze({
+        name,
+        ...(requires.length === 0 ? {} : { requires }),
+        activate(context) {
+            const result = Reflect.apply(activateValue, plugin, [context]);
+            return result;
+        },
+    });
 }
-function isPiWebServerPlugin(value) {
-    return isRecord(value)
-        && value["apiVersion"] === 1
-        && typeof value["name"] === "string"
-        && value["name"] !== ""
-        && typeof value["activate"] === "function";
+function activationDisposeForRollback(value) {
+    if (!isRecord(value))
+        return undefined;
+    const dispose = value["dispose"];
+    if (typeof dispose !== "function")
+        return undefined;
+    return async (signal) => {
+        await Reflect.apply(dispose, value, [signal]);
+    };
 }
-function parseActivation(value) {
+function parseActivation(value, pluginId) {
     if (!isRecord(value))
         throw new IncompatibleServerPluginError("Server plugin activation must be an object");
     if (value["workspaceProviders"] !== undefined) {
         throw new IncompatibleServerPluginError("Server plugins may contribute only one workspaceProvider");
     }
+    if (value["requiredTerminalService"] !== undefined) {
+        throw new IncompatibleServerPluginError("requiredTerminalService was removed in server plugin API v3; use a typed capability provision");
+    }
+    if (value["stop"] !== undefined) {
+        throw new IncompatibleServerPluginError("Server plugin stop was removed in API v3; use dispose");
+    }
     const workspaceProviderValue = value["workspaceProvider"];
+    const peerValue = value["peer"];
+    const provides = snapshotCapabilityProvisions(value["provides"], pluginId, `Server plugin ${pluginId} provisions`);
     const candidate = {
         workspaceProvider: workspaceProviderValue === undefined ? undefined : snapshotWorkspaceProvider(workspaceProviderValue),
+        peer: peerValue === undefined ? undefined : snapshotPluginPeer(peerValue),
+        provides,
         start: value["start"],
-        stop: value["stop"],
+        dispose: value["dispose"],
         health: value["health"],
     };
-    for (const callback of ["start", "stop", "health"]) {
+    for (const callback of ["start", "dispose", "health"]) {
         const callbackValue = candidate[callback];
         if (callbackValue !== undefined && typeof callbackValue !== "function") {
             throw new IncompatibleServerPluginError(`Server plugin ${callback} must be a function`);
@@ -292,12 +740,14 @@ function parseActivation(value) {
     if (!isServerPluginActivation(candidate))
         throw new IncompatibleServerPluginError("Server plugin activation is invalid");
     const start = candidate.start?.bind(value);
-    const stop = candidate.stop?.bind(value);
+    const dispose = candidate.dispose?.bind(value);
     const health = candidate.health?.bind(value);
     return Object.freeze({
         ...(candidate.workspaceProvider === undefined ? {} : { workspaceProvider: candidate.workspaceProvider }),
-        ...(start === undefined ? {} : { start: (signal) => start(signal) }),
-        ...(stop === undefined ? {} : { stop: (signal) => stop(signal) }),
+        ...(candidate.peer === undefined ? {} : { peer: candidate.peer }),
+        ...(provides.length === 0 ? {} : { provides }),
+        ...(start === undefined ? {} : { start: (context) => start(context) }),
+        ...(dispose === undefined ? {} : { dispose: (signal) => dispose(signal) }),
         ...(health === undefined ? {} : { health: (signal) => health(signal) }),
     });
 }
@@ -305,14 +755,342 @@ function isServerPluginActivation(value) {
     if (!isRecord(value))
         return false;
     const workspaceProvider = value["workspaceProvider"];
+    const peer = value["peer"];
+    const provides = value["provides"];
     const start = value["start"];
-    const stop = value["stop"];
+    const dispose = value["dispose"];
     const health = value["health"];
     return (workspaceProvider === undefined || isWorkspaceProvider(workspaceProvider))
+        && (peer === undefined || isPluginPeer(peer))
+        && (provides === undefined || Array.isArray(provides))
         && (start === undefined || typeof start === "function")
-        && (stop === undefined || typeof stop === "function")
+        && (dispose === undefined || typeof dispose === "function")
         && (health === undefined || typeof health === "function");
 }
+function snapshotCapabilityRequirements(value, label) {
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value))
+        throw new IncompatibleServerPluginError(`${label} must be an array`);
+    const seen = new Set();
+    const requirements = [];
+    for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index))
+            throw new IncompatibleServerPluginError(`${label} must not be sparse`);
+        const capability = snapshotUnknownCapability(value[index], `${label}[${String(index)}]`);
+        const key = capabilityKey(capability);
+        if (seen.has(key))
+            throw new IncompatibleServerPluginError(`${label} declares ${formatCapability(capability)} more than once`);
+        seen.add(key);
+        requirements.push(capability);
+    }
+    return Object.freeze(requirements);
+}
+function snapshotCapabilityProvisions(value, ownerPluginId, label) {
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value))
+        throw new IncompatibleServerPluginError(`${label} must be an array`);
+    const seen = new Set();
+    const provisions = [];
+    for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index))
+            throw new IncompatibleServerPluginError(`${label} must not be sparse`);
+        const candidate = value[index];
+        if (!isRecord(candidate))
+            throw new IncompatibleServerPluginError(`${label}[${String(index)}] must be an object`);
+        const capability = snapshotUnknownCapability(candidate["capability"], `${label}[${String(index)}].capability`);
+        if (ownerPluginId !== undefined && capability.pluginId !== ownerPluginId) {
+            throw new IncompatibleServerPluginError(`Server plugin ${ownerPluginId} cannot provide capability owned by ${capability.pluginId}`);
+        }
+        const key = capabilityKey(capability);
+        if (seen.has(key))
+            throw new IncompatibleServerPluginError(`${label} publishes ${formatCapability(capability)} more than once`);
+        seen.add(key);
+        const parsedValue = parseCapabilityValue(capability, candidate["value"], `Provided capability ${formatCapability(capability)}`);
+        provisions.push(Object.freeze({ capability, value: parsedValue }));
+    }
+    return Object.freeze(provisions);
+}
+function snapshotHostCapabilities(value) {
+    const provisions = snapshotCapabilityProvisions(value, undefined, "Host capability provisions");
+    return internalProvisions({ provides: provisions }, "host");
+}
+function snapshotLateHostCapabilities(value) {
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value))
+        throw new Error("Late host capabilities must be an array");
+    const seen = new Set();
+    const capabilities = [];
+    for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index))
+            throw new Error("Late host capabilities must not be sparse");
+        const capability = snapshotUnknownCapability(value[index], `Late host capabilities[${String(index)}]`);
+        const key = capabilityKey(capability);
+        if (seen.has(key))
+            throw new Error(`Late host capability ${formatCapability(capability)} is configured more than once`);
+        seen.add(key);
+        capabilities.push(Object.freeze({ capability, key, source: "late-host" }));
+    }
+    return Object.freeze(capabilities);
+}
+function snapshotHostCapabilityFactories(value) {
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value))
+        throw new Error("Host capability factories must be an array");
+    const seen = new Set();
+    const factories = [];
+    for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index))
+            throw new Error("Host capability factories must not be sparse");
+        const candidate = value[index];
+        if (!isRecord(candidate))
+            throw new Error(`Host capability factories[${String(index)}] must be an object`);
+        const capability = snapshotUnknownCapability(candidate["capability"], `Host capability factories[${String(index)}].capability`);
+        const key = capabilityKey(capability);
+        if (seen.has(key))
+            throw new Error(`Host capability factory for ${formatCapability(capability)} is configured more than once`);
+        const create = candidate["create"];
+        if (typeof create !== "function")
+            throw new Error(`Host capability factory for ${formatCapability(capability)} must expose create`);
+        seen.add(key);
+        factories.push(Object.freeze({
+            capability,
+            key,
+            source: "host-factory",
+            create(context) {
+                const result = Reflect.apply(create, candidate, [context]);
+                return snapshotHostCapabilityInstance(result, `Host capability ${formatCapability(capability)}`);
+            },
+        }));
+    }
+    return Object.freeze(factories);
+}
+function snapshotHostCapabilityInstance(value, label) {
+    if (!isRecord(value) || !Object.hasOwn(value, "value")) {
+        throw new Error(`${label} factory must return an object containing value`);
+    }
+    const dispose = value["dispose"];
+    if (dispose !== undefined && typeof dispose !== "function") {
+        throw new Error(`${label} factory dispose must be a function`);
+    }
+    return Object.freeze({
+        value: value["value"],
+        ...(dispose === undefined
+            ? {}
+            : { dispose: async (signal) => { await Reflect.apply(dispose, value, [signal]); } }),
+    });
+}
+function internalProvisions(activation, source) {
+    return Object.freeze((activation.provides ?? []).map((provision) => Object.freeze({
+        capability: provision.capability,
+        key: capabilityKey(provision.capability),
+        value: provision.value,
+        source,
+    })));
+}
+function snapshotUnknownCapability(value, label) {
+    if (!isRecord(value))
+        throw new IncompatibleServerPluginError(`${label} must be an object`);
+    const pluginId = value["pluginId"];
+    const id = value["id"];
+    const version = value["version"];
+    const parse = value["parse"];
+    const validated = validateCapabilityFields(pluginId, id, version, parse, label);
+    return Object.freeze({
+        pluginId: validated.pluginId,
+        id: validated.id,
+        version: validated.version,
+        parse(input) {
+            const result = Reflect.apply(validated.parse, value, [input]);
+            return result;
+        },
+    });
+}
+function snapshotTypedCapability(value, label) {
+    const validated = validateCapabilityFields(value.pluginId, value.id, value.version, value.parse, label);
+    const parse = value.parse.bind(value);
+    return Object.freeze({
+        pluginId: validated.pluginId,
+        id: validated.id,
+        version: validated.version,
+        parse: (input) => parse(input),
+    });
+}
+function validateCapabilityFields(pluginId, id, version, parse, label) {
+    if (typeof pluginId !== "string" || pluginId.trim() === "") {
+        throw new IncompatibleServerPluginError(`${label} pluginId must be a non-empty string`);
+    }
+    if (typeof id !== "string" || id.trim() === "") {
+        throw new IncompatibleServerPluginError(`${label} id must be a non-empty string`);
+    }
+    if (typeof version !== "number" || !Number.isInteger(version) || version <= 0) {
+        throw new IncompatibleServerPluginError(`${label} version must be a positive integer`);
+    }
+    if (!isCapabilityParser(parse))
+        throw new IncompatibleServerPluginError(`${label} parse must be a function`);
+    return { pluginId, id, version, parse };
+}
+function isCapabilityParser(value) {
+    return typeof value === "function";
+}
+function parseCapabilityValue(capability, value, label) {
+    try {
+        return capability.parse(value);
+    }
+    catch (error) {
+        throw new IncompatibleServerPluginError(`${label} is invalid: ${errorMessage(error)}`, { cause: error });
+    }
+}
+function capabilityKey(capability) {
+    return JSON.stringify([capability.pluginId, capability.id, capability.version]);
+}
+function formatCapability(capability) {
+    return `${capability.pluginId}/${capability.id} v${String(capability.version)}`;
+}
+function createCapabilityResolver(pluginId, resolved) {
+    return Object.freeze({
+        resolve(value) {
+            const capability = snapshotTypedCapability(value, `Capability request from server plugin ${pluginId}`);
+            const requirement = resolved.get(capabilityKey(capability));
+            if (requirement === undefined) {
+                throw new Error(`Server plugin ${pluginId} did not declare required capability ${formatCapability(capability)}`);
+            }
+            return parseCapabilityValue(capability, requirement.provisionValue, `Required capability ${formatCapability(capability)} for server plugin ${pluginId}`);
+        },
+    });
+}
+function findLateHostDependency(staged, pending, declared, visiting = new Set()) {
+    if (visiting.has(staged.entry.id))
+        return undefined;
+    const nextVisiting = new Set(visiting);
+    nextVisiting.add(staged.entry.id);
+    for (const requirement of staged.plugin.requires ?? []) {
+        const declaration = declared.get(capabilityKey(requirement));
+        if (declaration?.source === "late-host")
+            return declaration.capability;
+        if (declaration?.source !== "plugin")
+            continue;
+        const provider = pending.get(requirement.pluginId);
+        if (provider === undefined)
+            continue;
+        const lateCapability = findLateHostDependency(provider, pending, declared, nextVisiting);
+        if (lateCapability !== undefined)
+            return lateCapability;
+    }
+    return undefined;
+}
+function findCapabilityCycle(pending, declared) {
+    const state = new Map();
+    const stack = [];
+    const visit = (pluginId) => {
+        state.set(pluginId, "visiting");
+        stack.push(pluginId);
+        const plugin = pending.get(pluginId);
+        const providers = (plugin?.plugin.requires ?? [])
+            .filter((requirement) => declared.get(capabilityKey(requirement))?.source === "plugin" && pending.has(requirement.pluginId))
+            .map((requirement) => requirement.pluginId)
+            .sort((left, right) => left.localeCompare(right));
+        for (const providerId of providers) {
+            if (state.get(providerId) === "visiting") {
+                const start = stack.indexOf(providerId);
+                return stack.slice(start);
+            }
+            if (state.get(providerId) !== "visited") {
+                const cycle = visit(providerId);
+                if (cycle !== undefined)
+                    return cycle;
+            }
+        }
+        stack.pop();
+        state.set(pluginId, "visited");
+        return undefined;
+    };
+    for (const pluginId of [...pending.keys()].sort((left, right) => left.localeCompare(right))) {
+        if (state.has(pluginId))
+            continue;
+        const cycle = visit(pluginId);
+        if (cycle !== undefined)
+            return cycle;
+    }
+    return [];
+}
+function abortPluginLifetime(controller, pluginId, outcome) {
+    if (!controller.signal.aborted) {
+        controller.abort(new DOMException(`Server plugin ${pluginId} ${outcome}`, "AbortError"));
+    }
+}
+function withRollbackError(message, rollbackError) {
+    return rollbackError === undefined
+        ? message
+        : `${message}; startup rollback failed: ${errorMessage(rollbackError)}`;
+}
+function withHostCleanupError(message, cleanupError) {
+    return cleanupError === undefined
+        ? message
+        : `${message}; host capability cleanup failed: ${errorMessage(cleanupError)}`;
+}
+function combinedDisposalError(pluginError, hostCleanupError) {
+    if (pluginError === undefined)
+        return hostCleanupError;
+    if (hostCleanupError === undefined)
+        return pluginError;
+    return new AggregateError([pluginError, hostCleanupError], `${errorMessage(pluginError)}; host capability cleanup failed: ${errorMessage(hostCleanupError)}`);
+}
+function snapshotPluginPeer(value) {
+    if (!isPluginPeer(value)) {
+        throw new IncompatibleServerPluginError("Server plugin peer must include a request or channel handler");
+    }
+    const request = value.request?.bind(value);
+    const openChannel = value.openChannel?.bind(value);
+    const snapshotRequest = request === undefined
+        ? undefined
+        : (context) => request(context);
+    const snapshotOpenChannel = openChannel === undefined
+        ? undefined
+        : async (context) => (snapshotPluginPeerChannel(await openChannel(context)));
+    if (snapshotRequest !== undefined && snapshotOpenChannel !== undefined) {
+        return Object.freeze({ request: snapshotRequest, openChannel: snapshotOpenChannel });
+    }
+    if (snapshotRequest !== undefined)
+        return Object.freeze({ request: snapshotRequest });
+    if (snapshotOpenChannel !== undefined)
+        return Object.freeze({ openChannel: snapshotOpenChannel });
+    throw new IncompatibleServerPluginError("Server plugin peer must include a request or channel handler");
+}
+function isPluginPeer(value) {
+    if (!isRecord(value))
+        return false;
+    const request = value["request"];
+    const openChannel = value["openChannel"];
+    return (typeof request === "function" || typeof openChannel === "function")
+        && (request === undefined || typeof request === "function")
+        && (openChannel === undefined || typeof openChannel === "function");
+}
+function snapshotPluginPeerChannel(value) {
+    if (!isPluginPeerChannel(value)) {
+        throw new Error("Server plugin openChannel must return a channel with receive, optional completion, and optional close callbacks");
+    }
+    const receive = value.receive.bind(value);
+    const closed = value.closed === undefined ? undefined : Promise.resolve(value.closed);
+    const close = value.close?.bind(value);
+    return Object.freeze({
+        receive: (data, signal) => receive(data, signal),
+        ...(closed === undefined ? {} : { closed }),
+        ...(close === undefined ? {} : { close: (context) => close(context) }),
+    });
+}
+function isPluginPeerChannel(value) {
+    return isRecord(value)
+        && typeof value["receive"] === "function"
+        && (value["closed"] === undefined || isPromiseLike(value["closed"]))
+        && (value["close"] === undefined || typeof value["close"] === "function");
+}
+function isPromiseLike(value) {
+    return isRecord(value) && typeof value["then"] === "function";
+}
 function snapshotWorkspaceProvider(value) {
     if (!isRecord(value))
         throw new IncompatibleServerPluginError("Server plugin workspaceProvider is invalid");
@@ -320,20 +1098,17 @@ function snapshotWorkspaceProvider(value) {
         fallback: value["fallback"],
         probe: value["probe"],
         list: value["list"],
-        request: value["request"],
         prepareRemove: value["prepareRemove"],
     };
     if (!isWorkspaceProvider(candidate))
         throw new IncompatibleServerPluginError("Server plugin workspaceProvider is invalid");
     const probe = candidate.probe.bind(value);
     const list = candidate.list.bind(value);
-    const request = candidate.request?.bind(value);
     const prepareRemove = candidate.prepareRemove?.bind(value);
     return Object.freeze({
         ...(candidate.fallback === undefined ? {} : { fallback: candidate.fallback }),
         probe: (project, signal) => probe(project, signal),
         list: (project, signal) => list(project, signal),
-        ...(request === undefined ? {} : { request: (context) => request(context) }),
         ...(prepareRemove === undefined ? {} : { prepareRemove: (context) => prepareRemove(context) }),
     });
 }
@@ -343,12 +1118,10 @@ function isWorkspaceProvider(value) {
     const fallback = value["fallback"];
     const probe = value["probe"];
     const list = value["list"];
-    const request = value["request"];
     const prepareRemove = value["prepareRemove"];
     return (fallback === undefined || typeof fallback === "boolean")
         && typeof probe === "function"
         && typeof list === "function"
-        && (request === undefined || typeof request === "function")
         && (prepareRemove === undefined || typeof prepareRemove === "function");
 }
 function parseHealth(value) {
@@ -370,6 +1143,67 @@ function parseHealth(value) {
         ...(clonedDetails === undefined ? {} : { details: clonedDetails }),
     });
 }
+function createScopedNoticeReporter(pluginId, sink) {
+    if (sink === undefined)
+        return undefined;
+    const source = `${SERVER_PLUGIN_NOTICE_SOURCE_PREFIX}${pluginId}`;
+    let active = true;
+    const reporter = Object.freeze({
+        version: 1,
+        record(input) {
+            if (!active)
+                throw new Error(`Server plugin notice reporter for ${pluginId} is no longer active`);
+            sink(source, parseServerPluginNoticeInput(input));
+        },
+    });
+    return Object.freeze({
+        reporter,
+        revoke() { active = false; },
+    });
+}
+function parseServerPluginNoticeInput(value) {
+    if (!isPlainRecord(value))
+        throw new Error("Server plugin notice input must be an object");
+    if ("source" in value)
+        throw new Error("Server plugin notices cannot set their source");
+    for (const key in value) {
+        if (!Object.hasOwn(value, key))
+            continue;
+        if (key !== "severity" && key !== "message" && key !== "scope" && key !== "context") {
+            throw new Error(`Unsupported server plugin notice field: ${key}`);
+        }
+    }
+    const severity = value["severity"];
+    if (severity !== "info" && severity !== "warning" && severity !== "error") {
+        throw new Error("Server plugin notice severity must be info, warning, or error");
+    }
+    const message = value["message"];
+    if (typeof message !== "string") {
+        throw new Error("Server plugin notice message must be a non-empty string");
+    }
+    if (serverNoticeStringExceedsUtf8ByteLimit(message, SERVER_PLUGIN_NOTICE_MESSAGE_MAX_BYTES)) {
+        throw new Error(`Server plugin notice message exceeds the ${String(SERVER_PLUGIN_NOTICE_MESSAGE_MAX_BYTES)} byte limit`);
+    }
+    // This scan and allocation are bounded because the UTF-8 limit passed first.
+    if (message.trim() === "") {
+        throw new Error("Server plugin notice message must be a non-empty string");
+    }
+    const scope = value["scope"] === undefined
+        ? undefined
+        : parseServerNoticeScope(value["scope"], "Server plugin notice scope");
+    const context = value["context"] === undefined
+        ? undefined
+        : cloneJsonObject(value["context"], "server plugin notice context", {
+            maxDepth: SERVER_PLUGIN_NOTICE_CONTEXT_MAX_DEPTH,
+            maxBytes: SERVER_PLUGIN_NOTICE_CONTEXT_MAX_BYTES,
+        });
+    return Object.freeze({
+        severity,
+        message,
+        ...(scope === undefined ? {} : { scope }),
+        ...(context === undefined ? {} : { context }),
+    });
+}
 function createScopedLogger(pluginId, logger) {
     return Object.freeze({
         debug(message, details) {
@@ -404,40 +1238,136 @@ async function runBounded(pluginId, phase, timeoutMs, operation) {
             controller.abort(new DOMException("Server plugin operation completed", "AbortError"));
     }
 }
-function cloneJsonObject(value, label) {
-    if (!isRecord(value))
+function cloneJsonObject(value, label, limits = {}) {
+    if (!isPlainRecord(value))
         throw new IncompatibleServerPluginError(`${label} must be a JSON object`);
-    return cloneJsonRecord(value, new Set(), label);
+    const byteBudget = limits.maxBytes === undefined
+        ? undefined
+        : { label, maxBytes: limits.maxBytes, remaining: limits.maxBytes };
+    return cloneJsonRecord(value, new Set(), label, 0, limits.maxDepth, byteBudget);
 }
-function cloneJsonRecord(value, ancestors, label) {
+function cloneJsonRecord(value, ancestors, label, depth, maxDepth, byteBudget) {
+    requireJsonDepth(depth, maxDepth, label);
     if (ancestors.has(value))
         throw new IncompatibleServerPluginError(`${label} must not contain cycles`);
+    consumeJsonBytes(byteBudget, 2); // Opening and closing braces.
     ancestors.add(value);
     const output = {};
-    for (const [key, child] of Object.entries(value))
-        output[key] = cloneJsonValue(child, ancestors, label);
+    let propertyCount = 0;
+    for (const key in value) {
+        if (!Object.hasOwn(value, key))
+            continue;
+        if (propertyCount > 0)
+            consumeJsonBytes(byteBudget, 1); // Comma.
+        consumeJsonStringBytes(byteBudget, key);
+        consumeJsonBytes(byteBudget, 1); // Colon.
+        defineJsonProperty(output, key, cloneJsonValue(value[key], ancestors, label, depth + 1, maxDepth, byteBudget));
+        propertyCount += 1;
+    }
     ancestors.delete(value);
     return Object.freeze(output);
 }
-function cloneJsonValue(value, ancestors, label) {
-    if (value === null || typeof value === "string" || typeof value === "boolean")
+function cloneJsonValue(value, ancestors, label, depth, maxDepth, byteBudget) {
+    requireJsonDepth(depth, maxDepth, label);
+    if (value === null) {
+        consumeJsonBytes(byteBudget, 4);
+        return value;
+    }
+    if (typeof value === "string") {
+        consumeJsonStringBytes(byteBudget, value);
+        return value;
+    }
+    if (typeof value === "boolean") {
+        consumeJsonBytes(byteBudget, value ? 4 : 5);
         return value;
+    }
     if (typeof value === "number") {
         if (!Number.isFinite(value))
             throw new IncompatibleServerPluginError(`${label} must contain only finite JSON numbers`);
+        consumeJsonBytes(byteBudget, String(value).length);
         return value;
     }
-    if (Array.isArray(value)) {
-        if (ancestors.has(value))
-            throw new IncompatibleServerPluginError(`${label} must not contain cycles`);
-        ancestors.add(value);
-        const output = value.map((child) => cloneJsonValue(child, ancestors, label));
-        ancestors.delete(value);
+    if (Array.isArray(value))
+        return cloneJsonArray(value, ancestors, label, depth, maxDepth, byteBudget);
+    if (isPlainRecord(value))
+        return cloneJsonRecord(value, ancestors, label, depth, maxDepth, byteBudget);
+    throw new IncompatibleServerPluginError(`${label} must contain only JSON values`);
+}
+function cloneJsonArray(value, ancestors, label, depth, maxDepth, byteBudget) {
+    requireJsonDepth(depth, maxDepth, label);
+    if (ancestors.has(value))
+        throw new IncompatibleServerPluginError(`${label} must not contain cycles`);
+    consumeJsonBytes(byteBudget, 2); // Opening and closing brackets.
+    ancestors.add(value);
+    try {
+        const output = [];
+        const length = value.length;
+        // Plugin-owned arrays may override iteration helpers; inspect each dense element directly.
+        for (let index = 0; index < length; index += 1) {
+            if (!Object.hasOwn(value, index)) {
+                throw new IncompatibleServerPluginError(`${label} must not contain sparse arrays`);
+            }
+            if (index > 0)
+                consumeJsonBytes(byteBudget, 1); // Comma.
+            output[index] = cloneJsonValue(value[index], ancestors, label, depth + 1, maxDepth, byteBudget);
+        }
         return Object.freeze(output);
     }
-    if (isRecord(value))
-        return cloneJsonRecord(value, ancestors, label);
-    throw new IncompatibleServerPluginError(`${label} must contain only JSON values`);
+    finally {
+        ancestors.delete(value);
+    }
+}
+function consumeJsonStringBytes(byteBudget, value) {
+    if (byteBudget === undefined)
+        return;
+    consumeJsonBytes(byteBudget, 2); // Opening and closing quotes.
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit === 0x22 || codeUnit === 0x5c
+            || codeUnit === 0x08 || codeUnit === 0x09 || codeUnit === 0x0a
+            || codeUnit === 0x0c || codeUnit === 0x0d) {
+            consumeJsonBytes(byteBudget, 2);
+        }
+        else if (codeUnit <= 0x1f) {
+            consumeJsonBytes(byteBudget, 6);
+        }
+        else if (codeUnit <= 0x7f) {
+            consumeJsonBytes(byteBudget, 1);
+        }
+        else if (codeUnit <= 0x7ff) {
+            consumeJsonBytes(byteBudget, 2);
+        }
+        else if (codeUnit >= 0xd800 && codeUnit <= 0xdbff
+            && index + 1 < value.length
+            && value.charCodeAt(index + 1) >= 0xdc00
+            && value.charCodeAt(index + 1) <= 0xdfff) {
+            consumeJsonBytes(byteBudget, 4);
+            index += 1;
+        }
+        else if (codeUnit >= 0xd800 && codeUnit <= 0xdfff) {
+            // Well-formed JSON.stringify escapes isolated UTF-16 surrogates as \uXXXX.
+            consumeJsonBytes(byteBudget, 6);
+        }
+        else {
+            consumeJsonBytes(byteBudget, 3);
+        }
+    }
+}
+function consumeJsonBytes(byteBudget, count) {
+    if (byteBudget === undefined)
+        return;
+    byteBudget.remaining -= count;
+    if (byteBudget.remaining < 0) {
+        throw new Error(`${byteBudget.label} exceeds the ${String(byteBudget.maxBytes)} byte limit`);
+    }
+}
+function requireJsonDepth(depth, maxDepth, label) {
+    if (maxDepth !== undefined && depth > maxDepth) {
+        throw new IncompatibleServerPluginError(`${label} exceeds the maximum JSON depth of ${String(maxDepth)}`);
+    }
+}
+function defineJsonProperty(record, key, value) {
+    Object.defineProperty(record, key, { value, enumerable: true, configurable: true, writable: true });
 }
 function abortError(signal) {
     const reason = signal.reason;
@@ -449,6 +1379,12 @@ class IncompatibleServerPluginError extends Error {
         this.name = "IncompatibleServerPluginError";
     }
 }
+export class RequiredTerminalPluginError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = "RequiredTerminalPluginError";
+    }
+}
 class ServerPluginTimeoutError extends Error {
     constructor() {
         super(...arguments);
@@ -477,4 +1413,10 @@ function formatUnknown(value) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isPlainRecord(value) {
+    if (!isRecord(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
 //# sourceMappingURL=serverPluginRuntime.js.map