@rynx-ai/daemon 0.1.0 → 0.1.9

package/dist/plugin-supervisor.js

@@ -0,0 +1,1143 @@
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { resolveAllowedRoots, rynxHome, } from "@rynx-ai/core";
+import { PLUGIN_RUNNER_API_VERSION, spawnPluginRunner, } from "@rynx-ai/plugin-runner";
+import { normalizePluginConfig, } from "@rynx-ai/plugin-sdk";
+import { MAX_PLUGIN_HOST_EVENT_BYTES, PluginHostRpc, } from "./plugin-host-rpc.js";
+const DEFAULT_RESTART_BASE_MS = 1_000;
+const MAX_RESTART_DELAY_MS = 30_000;
+const DEFAULT_STABLE_RESET_MS = 60_000;
+const MAX_HOST_EVENT_QUEUE_ITEMS = 64;
+const MAX_HOST_EVENT_QUEUE_BYTES = 8 * 1024 * 1024;
+const MAX_STDERR_LINE_BYTES = 64 * 1024;
+const MAX_STATUS_ERROR_BYTES = 16 * 1024;
+const DEFAULT_READY_TIMEOUT_MS = 15_000;
+const MAX_READY_TIMEOUT_MS = 60_000;
+const RUNTIME_STATUS_POLL_MS = 50;
+const TARGET_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+/**
+ * Owns isolated plugin child processes and projects their static chat-channel
+ * declarations onto trusted host-side ChannelManager handles.
+ *
+ * There is at most one resident child per enabled plugin. Chat-channel
+ * instances are independent desired-state entries inside that child, so
+ * stopping the final channel does not tear down the plugin runtime itself.
+ */
+export class PluginSupervisor {
+    states = new Map();
+    services;
+    spawnRunner;
+    logger;
+    restartBaseMs;
+    restartMaxMs;
+    stableResetMs;
+    daemonInstanceId;
+    runtimeOperations = new Map();
+    disposed = false;
+    constructor(plugins, options) {
+        this.services = options.services;
+        this.spawnRunner = options.spawnRunner ?? spawnPluginRunner;
+        this.logger = options.log;
+        this.restartBaseMs = Math.min(positiveDelay(options.restartBaseMs, DEFAULT_RESTART_BASE_MS), MAX_RESTART_DELAY_MS);
+        this.restartMaxMs = Math.max(this.restartBaseMs, Math.min(positiveDelay(options.restartMaxMs, MAX_RESTART_DELAY_MS), MAX_RESTART_DELAY_MS));
+        this.stableResetMs = positiveDelay(options.stableResetMs, DEFAULT_STABLE_RESET_MS);
+        this.daemonInstanceId = options.daemonInstanceId?.trim() || randomUUID();
+        for (const record of plugins) {
+            validateRecord(record);
+            if (this.states.has(record.manifest.id)) {
+                throw new Error(`duplicate runnable plugin id: ${record.manifest.id}`);
+            }
+            this.states.set(record.manifest.id, createPluginState(record));
+        }
+    }
+    /** Static channel catalog. Calling this never loads or executes plugin code. */
+    createChannelTypeDescriptors() {
+        const descriptors = [];
+        for (const state of this.states.values()) {
+            for (const contribution of state.record.manifest.contributions?.chatChannels ?? []) {
+                descriptors.push(this.channelDescriptor(state, contribution));
+            }
+        }
+        return descriptors;
+    }
+    /** Bind the trusted host once, after the server composition root constructs it. */
+    bindHostServices(services) {
+        this.assertOpen();
+        if (this.services)
+            throw new Error("plugin host services are already bound");
+        this.services = services;
+        return this;
+    }
+    /** Cached, non-blocking runner/contribution health for the generic control API. */
+    statusSnapshot() {
+        const plugins = [];
+        for (const state of this.states.values()) {
+            if (state.runner)
+                void this.refreshRuntimeStatus(state).catch(() => undefined);
+            for (const desired of state.desired.values()) {
+                if (state.runner && desired.startedGeneration === state.generation) {
+                    void this.refreshContributionStatus(state, desired).catch(() => undefined);
+                }
+            }
+            const contributions = [...state.desired.values()].map((desired) => ({
+                key: desired.key,
+                target: { ...desired.target },
+                desired: true,
+                ...(desired.startedGeneration === undefined
+                    ? {}
+                    : { generation: desired.startedGeneration }),
+                failureCount: desired.failureCount,
+                status: { ...desired.status },
+            }));
+            plugins.push({
+                pluginId: state.record.manifest.id,
+                runner: {
+                    state: runnerSnapshotState(state, this.disposed),
+                    generation: state.generation,
+                    failureCount: state.failureCount,
+                    ...(state.lastRunnerError ? { lastError: state.lastRunnerError } : {}),
+                },
+                runtimeStatus: { ...state.runtimeStatus },
+                contributions,
+            });
+        }
+        return { capturedAt: new Date().toISOString(), plugins };
+    }
+    /** Start one resident runner for every enabled runtime plugin. */
+    async startPluginRuntimes() {
+        this.assertReady();
+        await Promise.all([...this.states.values()].map(async (state) => {
+            try {
+                await this.ensureRunner(state);
+                await this.refreshRuntimeStatus(state);
+            }
+            catch (error) {
+                this.writeLog({
+                    level: "error",
+                    event: "plugin.runner.start_failed",
+                    pluginId: state.record.manifest.id,
+                    message: messageOf(error),
+                });
+            }
+        }));
+    }
+    /**
+     * Atomically replace or add one plugin runtime, preserving its live chat
+     * desired state. Concurrent reloads of the same plugin are applied in call
+     * order; other plugins continue running independently.
+     */
+    reloadPluginRuntime(record, { readyTimeoutMs } = {}) {
+        this.assertReady();
+        validateRecord(record);
+        const pluginId = record.manifest.id;
+        return this.enqueueRuntimeOperation(pluginId, () => this.performPluginRuntimeReload(record, createRuntimeReadyDeadline(boundedReadyTimeout(readyTimeoutMs))));
+    }
+    /**
+     * Make one enabled plugin runtime ready without replacing an already healthy
+     * runner. This is the idempotent operation plugin CLIs use when their durable
+     * configuration has not changed.
+     */
+    ensurePluginRuntime(record, { readyTimeoutMs } = {}) {
+        this.assertReady();
+        validateRecord(record);
+        const pluginId = record.manifest.id;
+        return this.enqueueRuntimeOperation(pluginId, () => this.performPluginRuntimeEnsure(record, createRuntimeReadyDeadline(boundedReadyTimeout(readyTimeoutMs))));
+    }
+    enqueueRuntimeOperation(pluginId, execute) {
+        const preceding = this.runtimeOperations.get(pluginId);
+        const operation = (preceding ? preceding.catch(() => undefined) : Promise.resolve())
+            .then(execute);
+        this.runtimeOperations.set(pluginId, operation);
+        void operation.finally(() => {
+            if (this.runtimeOperations.get(pluginId) === operation) {
+                this.runtimeOperations.delete(pluginId);
+            }
+        }).catch(() => undefined);
+        return operation;
+    }
+    async performPluginRuntimeEnsure(record, deadline) {
+        this.assertReady();
+        const state = this.states.get(record.manifest.id);
+        if (!state || !sameRuntimeRecord(state.record, record)) {
+            return this.performPluginRuntimeReload(record, deadline);
+        }
+        if (!state.runner) {
+            return this.performPluginRuntimeReload(record, deadline);
+        }
+        const status = await this.refreshRuntimeStatus(state, deadline);
+        if (status.state === "unconfigured" ||
+            status.state === "failed" ||
+            status.state === "stopped") {
+            return this.performPluginRuntimeReload(record, deadline);
+        }
+        // A starting or degraded runtime may be recovering its own transport. Do
+        // not destroy it (and any active task leases) merely because the user ran
+        // the same connect command twice; wait for its bounded readiness result.
+        return this.waitForRuntimeReady(state, deadline);
+    }
+    async performPluginRuntimeReload(record, deadline) {
+        this.assertReady();
+        const pluginId = record.manifest.id;
+        let state = this.states.get(pluginId);
+        if (!state) {
+            state = createPluginState(record);
+            this.states.set(pluginId, state);
+        }
+        else {
+            await this.joinExitTransition(state);
+            const spawning = state.spawnPromise;
+            this.cancelRestart(state);
+            await this.closeRunner(state);
+            await spawning?.catch(() => undefined);
+            // A runner that was already spawning may have bound after the first
+            // close. Close once more before switching the immutable package record.
+            await this.closeRunner(state);
+            this.cancelRestart(state);
+            state.record = record;
+            state.failureCount = 0;
+            state.lastRunnerError = undefined;
+            state.runtimeStatusRefresh = undefined;
+            for (const desired of state.desired.values()) {
+                desired.startedGeneration = undefined;
+                desired.status = { state: "starting", connected: false, lastError: null };
+                state.channelStatus.set(desired.key, {
+                    ...(state.channelStatus.get(desired.key) ?? {}),
+                    connected: false,
+                    lastError: null,
+                });
+            }
+        }
+        state.runtimeStatus = { state: "starting", connected: false, lastError: null };
+        try {
+            const runner = await this.ensureRunner(state);
+            await this.restoreDesiredContributions(state, runner);
+        }
+        catch {
+            // ensureRunner already cached the failure and scheduled resident backoff.
+            // The bounded readiness loop remains authoritative and can observe a
+            // successful retry before the caller's timeout expires.
+        }
+        return this.waitForRuntimeReady(state, deadline);
+    }
+    /** Permanently stop all children and cancel every pending automatic restart. */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        const closes = [];
+        for (const state of this.states.values()) {
+            state.desired.clear();
+            for (const [key, status] of state.channelStatus) {
+                state.channelStatus.set(key, { ...status, connected: false });
+            }
+            this.cancelRestart(state);
+            clearTimer(state.stableTimer);
+            state.stableTimer = undefined;
+            state.runtimeStatus = { state: "stopping", connected: false };
+            closes.push(this.disposeState(state));
+        }
+        await Promise.all(closes);
+        for (const state of this.states.values()) {
+            state.runtimeStatus = { state: "stopped", connected: false };
+        }
+    }
+    channelDescriptor(state, contribution) {
+        return {
+            type: contribution.type,
+            factory: (context) => this.createRemoteChannel(state, contribution, context),
+            ...(contribution.configSchema ? { configSchema: contribution.configSchema } : {}),
+            ...(contribution.authorize
+                ? {
+                    authorize: (emit, signal, context) => this.authorize(state, contribution, emit, signal, context),
+                }
+                : {}),
+        };
+    }
+    createRemoteChannel(state, contribution, context) {
+        const instanceId = context.instanceId ?? contribution.type;
+        if (!TARGET_ID_PATTERN.test(instanceId)) {
+            throw new Error(`invalid plugin channel instance id: ${instanceId}`);
+        }
+        const key = channelKey(contribution.type, instanceId);
+        const target = {
+            kind: "chat-channel",
+            contributionId: contribution.type,
+            instanceId,
+        };
+        const request = {
+            ...target,
+            config: normalizeChatChannelConfig(contribution, context.options),
+            ...(context.defaultAgent ? { defaultAgent: context.defaultAgent } : {}),
+            executionDefaults: {
+                runtime: context.config.AGENT_RUNTIME,
+                ...(context.config.RYNX_DEFAULT_AGENT
+                    ? { defaultAgent: context.config.RYNX_DEFAULT_AGENT }
+                    : {}),
+                allowedRoots: resolveAllowedRoots(context.config),
+            },
+        };
+        return {
+            id: contribution.type,
+            start: async () => {
+                this.assertReady();
+                const existing = state.desired.get(key);
+                const desired = existing ?? this.rememberDesired(state, { key, request, target });
+                if (existing && !sameStartRequest(existing.request, request)) {
+                    throw new Error(`plugin channel instance is already started with different config: ${instanceId}`);
+                }
+                await this.ensureDesiredStarted(state, desired);
+            },
+            stop: async () => {
+                const desired = state.desired.get(key);
+                if (!desired) {
+                    state.channelStatus.set(key, { connected: false, lastError: null });
+                    return;
+                }
+                await this.stopDesired(state, desired);
+            },
+            getStatus: () => {
+                const cached = state.channelStatus.get(key) ?? {
+                    connected: false,
+                    lastError: null,
+                    lastEventAt: null,
+                };
+                const desired = state.desired.get(key);
+                if (desired)
+                    void this.refreshContributionStatus(state, desired).catch(() => undefined);
+                return { ...cached };
+            },
+        };
+    }
+    async authorize(state, contribution, emit, signal, context) {
+        this.assertReady();
+        const runner = await this.ensureRunner(state);
+        return runner.client.authorize({
+            kind: "chat-channel",
+            contributionId: contribution.type,
+            ...(context?.instanceId ? { instanceId: context.instanceId } : {}),
+            config: clonePluginConfig(context?.config),
+        }, (material) => emit(material), { signal });
+    }
+    rememberDesired(state, input) {
+        const desired = {
+            ...input,
+            status: { state: "stopped" },
+            failureCount: 0,
+        };
+        state.desired.set(desired.key, desired);
+        if (desired.target.kind === "chat-channel") {
+            state.channelStatus.set(desired.key, { connected: false, lastError: null });
+        }
+        return desired;
+    }
+    async ensureDesiredStarted(state, desired) {
+        const runner = await this.ensureRunner(state);
+        if (state.desired.get(desired.key) !== desired) {
+            return;
+        }
+        await this.startDesiredOnRunner(state, desired, runner);
+        await this.refreshContributionStatus(state, desired);
+    }
+    async startDesiredOnRunner(state, desired, runner) {
+        const generation = state.generation;
+        if (desired.startedGeneration === generation)
+            return;
+        if (desired.starting && desired.startingGeneration === generation) {
+            await desired.starting;
+            return;
+        }
+        desired.status = { state: "starting" };
+        const operation = runner.client.startContribution(desired.request).then(() => {
+            if (state.runner === runner && state.desired.get(desired.key) === desired) {
+                desired.startedGeneration = generation;
+                desired.failureCount = 0;
+                desired.status = {
+                    state: "running",
+                    connected: false,
+                    lastError: null,
+                };
+                state.channelStatus.set(desired.key, {
+                    ...(state.channelStatus.get(desired.key) ?? {}),
+                    connected: state.channelStatus.get(desired.key)?.connected ?? false,
+                    lastError: null,
+                });
+            }
+        }, (error) => {
+            if (state.runner === runner && state.desired.get(desired.key) === desired) {
+                this.markContributionFailed(state, desired, error);
+            }
+            throw error;
+        });
+        desired.starting = operation;
+        desired.startingGeneration = generation;
+        try {
+            await operation;
+        }
+        finally {
+            if (desired.starting === operation) {
+                desired.starting = undefined;
+                desired.startingGeneration = undefined;
+            }
+        }
+    }
+    async stopDesired(state, desired) {
+        if (state.desired.get(desired.key) !== desired)
+            return;
+        state.desired.delete(desired.key);
+        state.channelStatus.set(desired.key, {
+            connected: false,
+            lastError: null,
+            lastEventAt: state.channelStatus.get(desired.key)?.lastEventAt ?? null,
+        });
+        let stopError;
+        const runner = state.runner;
+        if (runner) {
+            try {
+                await runner.client.stopContribution(desired.target);
+            }
+            catch (error) {
+                stopError = error;
+            }
+        }
+        if (stopError)
+            throw stopError;
+    }
+    async refreshContributionStatus(state, desired) {
+        if (desired.statusRefresh)
+            return desired.statusRefresh;
+        const runner = state.runner;
+        if (!runner || desired.startedGeneration !== state.generation)
+            return;
+        const refresh = runner.client.status(desired.target).then((status) => {
+            if (state.runner !== runner || state.desired.get(desired.key) !== desired)
+                return;
+            desired.status = boundedContributionStatus(status);
+            state.channelStatus.set(desired.key, statusToChannelStatus(desired.status));
+        }, (error) => {
+            if (state.runner !== runner || state.desired.get(desired.key) !== desired)
+                return;
+            desired.status = {
+                state: "degraded",
+                connected: false,
+                lastError: messageOf(error),
+            };
+            state.channelStatus.set(desired.key, {
+                ...(state.channelStatus.get(desired.key) ?? {}),
+                connected: false,
+                lastError: messageOf(error),
+            });
+        });
+        desired.statusRefresh = refresh;
+        try {
+            await refresh;
+        }
+        finally {
+            if (desired.statusRefresh === refresh)
+                desired.statusRefresh = undefined;
+        }
+    }
+    async refreshRuntimeStatus(state, deadline) {
+        if (deadline && deadline.expiresAt - Date.now() <= 0) {
+            throw this.runtimeReadyTimeoutError(state, deadline.timeoutMs);
+        }
+        const runner = state.runner;
+        if (!runner)
+            return state.runtimeStatus;
+        let refresh = state.runtimeStatusRefresh;
+        if (!refresh) {
+            refresh = runner.client.runtimeStatus().then((status) => {
+                if (state.runner !== runner)
+                    return state.runtimeStatus;
+                state.runtimeStatus = boundedRuntimeStatus(status);
+                return state.runtimeStatus;
+            }, (error) => {
+                if (state.runner !== runner)
+                    return state.runtimeStatus;
+                state.runtimeStatus = {
+                    state: "degraded",
+                    connected: false,
+                    lastError: messageOf(error),
+                };
+                return state.runtimeStatus;
+            });
+            state.runtimeStatusRefresh = refresh;
+            void refresh.finally(() => {
+                if (state.runtimeStatusRefresh === refresh)
+                    state.runtimeStatusRefresh = undefined;
+            }).catch(() => undefined);
+        }
+        return deadline
+            ? await settleBeforeDeadline(refresh, deadline.expiresAt, () => this.runtimeReadyTimeoutError(state, deadline.timeoutMs))
+            : await refresh;
+    }
+    async waitForRuntimeReady(state, deadline) {
+        while (true) {
+            this.assertOpen();
+            const remainingBeforeRefresh = deadline.expiresAt - Date.now();
+            if (remainingBeforeRefresh <= 0) {
+                throw this.runtimeReadyTimeoutError(state, deadline.timeoutMs);
+            }
+            const status = state.runner
+                ? await this.refreshRuntimeStatus(state, deadline)
+                : state.runtimeStatus;
+            if (status.state === "running" && status.connected !== false)
+                return { ...status };
+            const remaining = deadline.expiresAt - Date.now();
+            if (remaining <= 0) {
+                throw this.runtimeReadyTimeoutError(state, deadline.timeoutMs);
+            }
+            await delay(Math.min(RUNTIME_STATUS_POLL_MS, remaining));
+        }
+    }
+    runtimeReadyTimeoutError(state, timeoutMs) {
+        const status = state.runtimeStatus;
+        const detail = status.lastError ? `: ${status.lastError}` : ` (state=${status.state})`;
+        return new Error(`plugin runtime "${state.record.manifest.id}" did not become ready within ${timeoutMs}ms${detail}`);
+    }
+    ensureRunner(state) {
+        this.assertReady();
+        if (state.exitTransition) {
+            return this.joinExitTransition(state).then(() => this.ensureRunner(state));
+        }
+        if (state.runner)
+            return Promise.resolve(state.runner);
+        if (state.spawnPromise)
+            return state.spawnPromise;
+        state.runtimeStatus = { state: "starting", connected: false, lastError: null };
+        const spawn = this.spawnAndBind(state).catch((error) => {
+            if (!this.disposed) {
+                state.failureCount += 1;
+                this.markRunnerUnavailable(state, `plugin runner failed to start: ${messageOf(error)}`);
+                this.scheduleRestart(state);
+            }
+            throw error;
+        });
+        state.spawnPromise = spawn;
+        void spawn.finally(() => {
+            if (state.spawnPromise === spawn)
+                state.spawnPromise = undefined;
+        }).catch(() => undefined);
+        return spawn;
+    }
+    async spawnAndBind(state) {
+        const pluginId = state.record.manifest.id;
+        const eventQueue = new BoundedHostEventQueue();
+        const host = new PluginHostRpc({
+            pluginId,
+            daemonInstanceId: this.daemonInstanceId,
+            grants: state.record.grants,
+            services: this.requireHostServices(),
+            emit: (event) => eventQueue.enqueue(event),
+        });
+        const stderr = this.stderrSink(pluginId);
+        let runner;
+        try {
+            runner = await this.spawnRunner({
+                pluginId,
+                packageRoot: state.record.installPath,
+                runtimeEntry: path.resolve(state.record.installPath, state.record.manifest.runtimeEntry),
+                dataDir: path.join(rynxHome(), "plugin-data", pluginId),
+                config: {},
+                grantedCapabilities: [...state.record.grants],
+                handleHostCall: (method, params) => host.call(method, params),
+                onStderr: stderr.write,
+            });
+            assertHandshake(pluginId, state.record.grants, runner.handshake);
+        }
+        catch (error) {
+            eventQueue.close(error);
+            stderr.flush();
+            await runner?.close().catch(() => undefined);
+            await host.dispose();
+            throw error;
+        }
+        if (this.disposed) {
+            eventQueue.close(new Error("plugin supervisor is disposed"));
+            stderr.flush();
+            await runner.close().catch(() => undefined);
+            await host.dispose();
+            throw new Error("plugin supervisor is disposed");
+        }
+        eventQueue.bind(runner.client);
+        state.runner = runner;
+        state.host = host;
+        state.eventQueue = eventQueue;
+        state.lastRunnerError = undefined;
+        state.generation += 1;
+        const generation = state.generation;
+        clearTimer(state.stableTimer);
+        state.stableTimer = setTimeout(() => {
+            if (state.runner === runner)
+                state.failureCount = 0;
+        }, this.stableResetMs);
+        state.stableTimer.unref?.();
+        void runner.completion.then((outcome) => {
+            eventQueue.close(new Error("plugin runner exited"));
+            stderr.flush();
+            this.trackRunnerExit(state, runner, host, generation, outcome);
+        }, (error) => {
+            eventQueue.close(error);
+            stderr.flush();
+            this.trackRunnerExit(state, runner, host, generation, undefined, error);
+        }).catch((error) => {
+            this.writeLog({
+                level: "error",
+                event: "plugin.runner.exit_handler_failed",
+                pluginId,
+                message: messageOf(error),
+            });
+        });
+        return runner;
+    }
+    trackRunnerExit(state, runner, host, generation, outcome, error) {
+        const preceding = state.exitTransition;
+        const transition = (preceding
+            ? preceding.catch(() => undefined)
+            : Promise.resolve()).then(() => this.runnerExited(state, runner, host, generation, outcome, error));
+        state.exitTransition = transition;
+        void transition.then(() => {
+            if (state.exitTransition === transition)
+                state.exitTransition = undefined;
+        }, (transitionError) => {
+            if (state.exitTransition === transition)
+                state.exitTransition = undefined;
+            this.writeLog({
+                level: "error",
+                event: "plugin.runner.exit_handler_failed",
+                pluginId: state.record.manifest.id,
+                message: messageOf(transitionError),
+            });
+        }).catch(() => undefined);
+    }
+    async runnerExited(state, runner, host, generation, outcome, error) {
+        if (state.runner !== runner || state.generation !== generation)
+            return;
+        state.runner = undefined;
+        if (state.host === host)
+            state.host = undefined;
+        state.eventQueue?.close(error ?? new Error("plugin runner exited"));
+        state.eventQueue = undefined;
+        state.runtimeStatusRefresh = undefined;
+        clearTimer(state.stableTimer);
+        state.stableTimer = undefined;
+        await host.dispose();
+        // Reload, explicit start, and dispose all join this transition. Keep the
+        // generation guard as a final defence against any future call path that
+        // can bind a successor without waiting for the old host cleanup.
+        if (this.disposed || state.runner || state.generation !== generation)
+            return;
+        const message = error
+            ? messageOf(error)
+            : `plugin runner exited (code=${String(outcome?.code)}, signal=${String(outcome?.signal)})`;
+        this.markRunnerUnavailable(state, message);
+        this.writeLog({
+            level: outcome?.code === 0 && !error ? "warn" : "error",
+            event: "plugin.runner.exited",
+            pluginId: state.record.manifest.id,
+            message,
+            code: outcome?.code,
+            signal: outcome?.signal,
+        });
+        state.failureCount += 1;
+        this.scheduleRestart(state);
+    }
+    async joinExitTransition(state) {
+        while (state.exitTransition) {
+            const transition = state.exitTransition;
+            await transition.catch(() => undefined);
+            if (state.exitTransition === transition)
+                state.exitTransition = undefined;
+        }
+    }
+    scheduleRestart(state) {
+        if (this.disposed || state.restartTimer)
+            return;
+        const exponent = Math.min(Math.max(state.failureCount - 1, 0), 30);
+        const delayMs = Math.min(this.restartMaxMs, this.restartBaseMs * 2 ** exponent);
+        this.writeLog({
+            level: "warn",
+            event: "plugin.runner.restart_scheduled",
+            pluginId: state.record.manifest.id,
+            delayMs,
+        });
+        state.restartTimer = setTimeout(() => {
+            state.restartTimer = undefined;
+            void this.restart(state);
+        }, delayMs);
+        state.restartTimer.unref?.();
+    }
+    async restart(state) {
+        if (this.disposed)
+            return;
+        let runner;
+        try {
+            runner = await this.ensureRunner(state);
+        }
+        catch (error) {
+            this.writeLog({
+                level: "error",
+                event: "plugin.runner.restart_failed",
+                pluginId: state.record.manifest.id,
+                message: messageOf(error),
+            });
+            return;
+        }
+        await this.refreshRuntimeStatus(state);
+        await this.restoreDesiredContributions(state, runner);
+    }
+    async restoreDesiredContributions(state, runner) {
+        for (const desired of [...state.desired.values()]) {
+            try {
+                await this.startDesiredOnRunner(state, desired, runner);
+                await this.refreshContributionStatus(state, desired);
+            }
+            catch (error) {
+                this.writeLog({
+                    level: "error",
+                    event: "plugin.contribution.restore_failed",
+                    pluginId: state.record.manifest.id,
+                    message: messageOf(error),
+                });
+            }
+        }
+    }
+    async closeRunner(state) {
+        const runner = state.runner;
+        const host = state.host;
+        const eventQueue = state.eventQueue;
+        state.runner = undefined;
+        state.host = undefined;
+        state.eventQueue = undefined;
+        state.runtimeStatusRefresh = undefined;
+        eventQueue?.close(new Error("plugin runner is closing"));
+        clearTimer(state.stableTimer);
+        state.stableTimer = undefined;
+        if (runner) {
+            try {
+                await runner.close();
+            }
+            catch (error) {
+                this.writeLog({
+                    level: "warn",
+                    event: "plugin.runner.close_failed",
+                    pluginId: state.record.manifest.id,
+                    message: messageOf(error),
+                });
+            }
+        }
+        await host?.dispose();
+    }
+    async disposeState(state) {
+        await this.joinExitTransition(state);
+        const spawning = state.spawnPromise;
+        await this.closeRunner(state);
+        await spawning?.catch(() => undefined);
+        // A spawn can bind between the first close and the disposed check inside
+        // spawnAndBind. A final idempotent close makes dispose a true join point.
+        await this.closeRunner(state);
+        await this.joinExitTransition(state);
+    }
+    cancelRestart(state) {
+        clearTimer(state.restartTimer);
+        state.restartTimer = undefined;
+    }
+    markRunnerUnavailable(state, message) {
+        state.lastRunnerError = message;
+        state.runtimeStatus = {
+            state: "failed",
+            connected: false,
+            lastError: message,
+        };
+        for (const desired of state.desired.values()) {
+            desired.startedGeneration = undefined;
+            desired.status = {
+                state: "failed",
+                connected: false,
+                lastError: message,
+            };
+            state.channelStatus.set(desired.key, {
+                ...(state.channelStatus.get(desired.key) ?? {}),
+                connected: false,
+                lastError: message,
+            });
+        }
+    }
+    markContributionFailed(state, desired, error) {
+        desired.startedGeneration = undefined;
+        desired.failureCount += 1;
+        desired.status = {
+            state: "failed",
+            connected: false,
+            lastError: messageOf(error),
+        };
+        state.channelStatus.set(desired.key, {
+            ...(state.channelStatus.get(desired.key) ?? {}),
+            connected: false,
+            lastError: messageOf(error),
+        });
+    }
+    stderrSink(pluginId) {
+        let buffered = "";
+        const continuation = " …[continued]";
+        const contentLimit = MAX_STDERR_LINE_BYTES - Buffer.byteLength(continuation, "utf8");
+        const emitLine = (line) => {
+            const message = line.trimEnd();
+            if (!message)
+                return;
+            this.writeLog({
+                level: "warn",
+                event: "plugin.runner.stderr",
+                pluginId,
+                message,
+            });
+        };
+        const appendSegment = (segment) => {
+            let remaining = segment;
+            while (remaining.length > 0) {
+                const bufferedBytes = Buffer.byteLength(buffered, "utf8");
+                const budget = Math.max(1, contentLimit - bufferedBytes);
+                const [prefix, rest] = splitUtf8AtMost(remaining, budget);
+                if (!prefix && rest) {
+                    if (buffered) {
+                        emitLine(`${buffered}${continuation}`);
+                        buffered = "";
+                        continue;
+                    }
+                    // `contentLimit` is much larger than a single UTF-8 code point, so
+                    // this branch is defensive only.
+                    const first = String.fromCodePoint(remaining.codePointAt(0));
+                    buffered = first;
+                    remaining = remaining.slice(first.length);
+                    continue;
+                }
+                buffered += prefix;
+                remaining = rest;
+                if (remaining.length > 0 || Buffer.byteLength(buffered, "utf8") >= contentLimit) {
+                    emitLine(`${buffered}${continuation}`);
+                    buffered = "";
+                }
+            }
+        };
+        return {
+            write: (chunk) => {
+                let offset = 0;
+                while (offset < chunk.length) {
+                    const newline = chunk.indexOf("\n", offset);
+                    if (newline < 0) {
+                        appendSegment(chunk.slice(offset));
+                        return;
+                    }
+                    appendSegment(chunk.slice(offset, newline));
+                    emitLine(buffered);
+                    buffered = "";
+                    offset = newline + 1;
+                }
+            },
+            flush: () => {
+                if (buffered)
+                    emitLine(buffered);
+                buffered = "";
+            },
+        };
+    }
+    writeLog(entry) {
+        if (this.logger) {
+            this.logger(entry);
+            return;
+        }
+        console.error(JSON.stringify({ timestamp: new Date().toISOString(), ...entry }));
+    }
+    assertOpen() {
+        if (this.disposed)
+            throw new Error("plugin supervisor is disposed");
+    }
+    assertReady() {
+        this.assertOpen();
+        this.requireHostServices();
+    }
+    requireHostServices() {
+        if (!this.services)
+            throw new Error("plugin host services are not bound");
+        return this.services;
+    }
+}
+/** A single-writer queue: bounded buffering plus an awaitable delivery ack. */
+class BoundedHostEventQueue {
+    items = [];
+    client;
+    queuedBytes = 0;
+    draining = false;
+    closed = false;
+    closeError;
+    bind(client) {
+        if (this.client)
+            throw new Error("plugin host event queue is already bound");
+        if (this.closed)
+            throw this.closeError ?? new Error("plugin host event queue is closed");
+        this.client = client;
+        void this.drain();
+    }
+    enqueue(event) {
+        if (this.closed) {
+            return Promise.reject(this.closeError ?? new Error("plugin host event queue is closed"));
+        }
+        let bytes;
+        try {
+            bytes = Buffer.byteLength(JSON.stringify(event), "utf8");
+        }
+        catch {
+            return Promise.reject(new Error("plugin host event must be JSON serializable"));
+        }
+        if (bytes > MAX_PLUGIN_HOST_EVENT_BYTES) {
+            return Promise.reject(new Error("plugin host event exceeds the bounded event budget"));
+        }
+        if (this.items.length + (this.draining ? 1 : 0) >= MAX_HOST_EVENT_QUEUE_ITEMS ||
+            this.queuedBytes + bytes > MAX_HOST_EVENT_QUEUE_BYTES) {
+            return Promise.reject(new Error("plugin host event queue is full"));
+        }
+        const promise = new Promise((resolve, reject) => {
+            this.items.push({ event, bytes, resolve, reject });
+            this.queuedBytes += bytes;
+        });
+        void this.drain();
+        return promise;
+    }
+    close(error) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.closeError = error instanceof Error
+            ? error
+            : new Error(error === undefined ? "plugin host event queue is closed" : String(error));
+        for (const item of this.items.splice(0)) {
+            this.queuedBytes -= item.bytes;
+            item.reject(this.closeError);
+        }
+    }
+    async drain() {
+        if (this.draining || this.closed || !this.client)
+            return;
+        this.draining = true;
+        try {
+            while (!this.closed && this.client && this.items.length > 0) {
+                const item = this.items.shift();
+                try {
+                    await this.client.emitHostEvent(item.event.event, item.event.payload);
+                    item.resolve();
+                }
+                catch (error) {
+                    const failure = error instanceof Error ? error : new Error(String(error));
+                    item.reject(failure);
+                    this.queuedBytes -= item.bytes;
+                    this.close(failure);
+                    return;
+                }
+                this.queuedBytes -= item.bytes;
+            }
+        }
+        finally {
+            this.draining = false;
+            if (!this.closed && this.client && this.items.length > 0)
+                void this.drain();
+        }
+    }
+}
+/** Convenience export for composition roots that only need the static catalog. */
+export function createChannelTypeDescriptors(supervisor) {
+    return supervisor.createChannelTypeDescriptors();
+}
+function createPluginState(record) {
+    return {
+        record,
+        desired: new Map(),
+        channelStatus: new Map(),
+        generation: 0,
+        failureCount: 0,
+        runtimeStatus: { state: "stopped", connected: false },
+    };
+}
+function validateRecord(record) {
+    if (record.name !== record.manifest.id) {
+        throw new Error(`runnable plugin id mismatch: ${record.name} != ${record.manifest.id}`);
+    }
+    if (!record.enabled) {
+        throw new Error(`plugin ${record.manifest.id} is disabled`);
+    }
+    const requested = new Set(record.manifest.requestedCapabilities);
+    for (const grant of record.grants) {
+        if (!requested.has(grant)) {
+            throw new Error(`plugin ${record.manifest.id} was granted an unrequested capability: ${grant}`);
+        }
+    }
+}
+function sameRuntimeRecord(left, right) {
+    return left.installPath === right.installPath &&
+        left.integrity === right.integrity &&
+        JSON.stringify(left.manifest) === JSON.stringify(right.manifest) &&
+        JSON.stringify(left.grants) === JSON.stringify(right.grants);
+}
+function assertHandshake(pluginId, grants, handshake) {
+    if (handshake.pluginId !== pluginId) {
+        throw new Error(`plugin runner identity mismatch: ${handshake.pluginId} != ${pluginId}`);
+    }
+    if (handshake.apiVersion !== PLUGIN_RUNNER_API_VERSION) {
+        throw new Error(`plugin runner API mismatch: ${handshake.apiVersion} != ${PLUGIN_RUNNER_API_VERSION}`);
+    }
+    if (handshake.grantedCapabilities.length !== grants.length ||
+        handshake.grantedCapabilities.some((capability, index) => capability !== grants[index])) {
+        throw new Error(`plugin runner capability handshake mismatch: ${pluginId}`);
+    }
+}
+function statusToChannelStatus(status) {
+    return {
+        connected: status.connected ?? status.state === "running",
+        lastError: status.lastError ?? null,
+        lastEventAt: status.lastEventAt ?? null,
+    };
+}
+function boundedContributionStatus(status) {
+    return {
+        ...status,
+        ...(typeof status.lastError === "string"
+            ? { lastError: boundedText(status.lastError, MAX_STATUS_ERROR_BYTES) }
+            : {}),
+        ...(typeof status.lastEventAt === "string"
+            ? { lastEventAt: boundedText(status.lastEventAt, 256) }
+            : {}),
+    };
+}
+function boundedRuntimeStatus(status) {
+    return {
+        ...status,
+        ...(typeof status.lastError === "string"
+            ? { lastError: boundedText(status.lastError, MAX_STATUS_ERROR_BYTES) }
+            : {}),
+        ...(typeof status.lastEventAt === "string"
+            ? { lastEventAt: boundedText(status.lastEventAt, 256) }
+            : {}),
+    };
+}
+function channelKey(contributionId, instanceId) {
+    return `channel:${contributionId}:${instanceId}`;
+}
+function positiveDelay(value, fallback) {
+    return value !== undefined && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function boundedReadyTimeout(value) {
+    if (value === undefined)
+        return DEFAULT_READY_TIMEOUT_MS;
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error("plugin runtime ready timeout must be a non-negative finite number");
+    }
+    return Math.min(value, MAX_READY_TIMEOUT_MS);
+}
+function createRuntimeReadyDeadline(timeoutMs) {
+    return { timeoutMs, expiresAt: Date.now() + timeoutMs };
+}
+function settleBeforeDeadline(promise, expiresAt, timeoutError) {
+    const remaining = expiresAt - Date.now();
+    if (remaining <= 0)
+        return Promise.reject(timeoutError());
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(timeoutError()), remaining);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function clearTimer(timer) {
+    if (timer)
+        clearTimeout(timer);
+}
+function runnerSnapshotState(state, disposed) {
+    if (state.runner)
+        return "running";
+    if (state.spawnPromise)
+        return "starting";
+    if (state.restartTimer)
+        return "backoff";
+    if (state.lastRunnerError && !disposed)
+        return "failed";
+    return "stopped";
+}
+function splitUtf8AtMost(value, maxBytes) {
+    if (Buffer.byteLength(value, "utf8") <= maxBytes)
+        return [value, ""];
+    let low = 0;
+    let high = value.length;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (Buffer.byteLength(value.slice(0, middle), "utf8") <= maxBytes)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    if (low > 0 && low < value.length && isHighSurrogate(value.charCodeAt(low - 1)))
+        low -= 1;
+    return [value.slice(0, low), value.slice(low)];
+}
+function isHighSurrogate(value) {
+    return value >= 0xd800 && value <= 0xdbff;
+}
+function messageOf(error) {
+    return boundedText(error instanceof Error ? error.message : String(error), MAX_STATUS_ERROR_BYTES);
+}
+function boundedText(value, maxBytes) {
+    if (Buffer.byteLength(value, "utf8") <= maxBytes)
+        return value;
+    const marker = "…[truncated]";
+    const budget = maxBytes - Buffer.byteLength(marker, "utf8");
+    const [prefix] = splitUtf8AtMost(value, Math.max(1, budget));
+    return `${prefix}${marker}`;
+}
+function sameStartRequest(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function clonePluginConfig(value) {
+    if (!value)
+        return {};
+    return cloneJsonValue(value, "options", new WeakSet());
+}
+function normalizeChatChannelConfig(contribution, value) {
+    const config = clonePluginConfig(value);
+    const schema = contribution.configSchema ?? [];
+    return schema.length > 0 ? normalizePluginConfig(schema, config) : config;
+}
+function cloneJsonValue(value, pathLabel, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error(`${pathLabel} must contain finite numbers`);
+        return value;
+    }
+    if (typeof value !== "object") {
+        throw new Error(`${pathLabel} must contain only JSON values`);
+    }
+    if (ancestors.has(value))
+        throw new Error(`${pathLabel} must not be cyclic`);
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.map((item, index) => cloneJsonValue(item, `${pathLabel}[${index}]`, ancestors));
+        }
+        if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+            throw new Error(`${pathLabel} must contain only plain objects`);
+        }
+        const output = {};
+        for (const [key, item] of Object.entries(value)) {
+            output[key] = cloneJsonValue(item, `${pathLabel}.${key}`, ancestors);
+        }
+        return output;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}