@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/server/plugins/index.js

@@ -0,0 +1,575 @@
+import path from "node:path";
+import { stat, rm } from "node:fs/promises";
+import { PluginIdSchema, } from "@camerontaylor/paseo-protocol/messages";
+import { parsePluginSourceReference } from "@camerontaylor/paseo-protocol/plugin-source-reference";
+import { assertPluginCompatibility } from "@camerontaylor/paseo-protocol/plugin-requirements";
+import { BUILTIN_PROVIDER_IDS } from "@camerontaylor/paseo-protocol/provider-manifest";
+import { readPluginManifest } from "./manifest.js";
+import { runPluginBuild } from "./preparation.js";
+import { PluginRuntime } from "./runtime.js";
+import { readPluginProviderIcon } from "./provider-icon.js";
+const BUILTIN_PROVIDER_ID_SET = new Set(BUILTIN_PROVIDER_IDS);
+function resolvePluginStatus(input) {
+    if (!input.enabled || !input.globallyEnabled)
+        return "disabled";
+    return input.running ? "running" : "failed";
+}
+export class PluginService {
+    constructor(logger, configStore, daemonVersion, dependencies = {}) {
+        this.configStore = configStore;
+        this.daemonVersion = daemonVersion;
+        this.dependencies = dependencies;
+        this.errors = new Map();
+        this.listeners = new Set();
+        this.providers = new Map();
+        this.providerIdsByPlugin = new Map();
+        this.providerListeners = new Set();
+        this.lifecycle = Promise.resolve();
+        this.globalStartsBlocked = true;
+        this.started = false;
+        this.settingsListeners = new Set();
+        this.emit = (name, event) => {
+            this.runtime.emit?.(name, event);
+        };
+        this.before = async (name, request) => {
+            if (this.runtime.before) {
+                return this.runtime.before(name, request);
+            }
+            return request;
+        };
+        this.logger = logger.child({ module: "plugin-service" });
+        this.runtime =
+            dependencies.runtime ??
+                new PluginRuntime(logger, daemonVersion, {
+                    settingsDirectory: dependencies.settingsDirectory,
+                    onSettingsChanged: (pluginId, settingsId) => {
+                        for (const listener of this.settingsListeners)
+                            listener(pluginId, settingsId);
+                    },
+                });
+        this.managedSources = dependencies.managedSources ?? null;
+        this.runtime.subscribe((pluginId, error) => {
+            this.removeProviderRegistrations(pluginId);
+            if (error)
+                this.errors.set(pluginId, error);
+            this.notify(pluginId);
+        });
+    }
+    subscribeSettings(listener) {
+        this.settingsListeners.add(listener);
+        return () => this.settingsListeners.delete(listener);
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    bindPaseoSessionHost(sessionHost) {
+        this.runtime.bindPaseoSessionHost(sessionHost);
+    }
+    getProviderRegistrations() {
+        return [...this.providers.values()].sort((left, right) => left.id.localeCompare(right.id));
+    }
+    subscribeProviderRegistrations(listener) {
+        this.providerListeners.add(listener);
+        return () => this.providerListeners.delete(listener);
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        const config = this.configStore.get();
+        this.globalStartsBlocked = config.pluginsEnabled !== true;
+        if (config.pluginsEnabled === true) {
+            for (const [pluginId, source] of Object.entries(config.plugins ?? {})) {
+                if (source.enabled === false)
+                    continue;
+                await this.startConfigured(pluginId);
+                this.notify(pluginId);
+            }
+        }
+        this.configStore.onFieldChange("pluginsEnabled", (value) => {
+            this.handleGlobalSwitch(value === true);
+        });
+    }
+    listPlugins() {
+        const config = this.configStore.get();
+        const running = new Set(this.runtime.catalog().map((plugin) => plugin.id));
+        return Object.entries(config.plugins ?? {})
+            .map(([id, source]) => {
+            const enabled = source.enabled !== false;
+            const item = {
+                id,
+                path: source.path,
+                enabled,
+                status: resolvePluginStatus({
+                    enabled,
+                    globallyEnabled: config.pluginsEnabled === true,
+                    running: running.has(id),
+                }),
+            };
+            const managed = this.managedSources?.get(id);
+            if (managed) {
+                item.source = "git";
+                const remote = this.managedSources?.displayRemote(id);
+                if (remote)
+                    item.remote = remote;
+                item.ref = managed.requestedRef ?? managed.trackingBranch ?? managed.commit;
+                item.commit = managed.commit;
+            }
+            const error = this.errors.get(id);
+            if (error && item.status === "failed")
+                item.error = error;
+            return item;
+        })
+            .sort((left, right) => left.id.localeCompare(right.id));
+    }
+    getLogs(pluginId) {
+        this.requireSource(pluginId);
+        return this.runtime.getLogs(pluginId);
+    }
+    catalog() {
+        return this.runtime.catalog();
+    }
+    async installDirectory(input) {
+        return this.enqueue(async () => {
+            const directory = path.resolve(input.path);
+            const manifest = await readPluginManifest(directory);
+            assertPluginCompatibility({ ...manifest, version: this.daemonVersion, runtime: "daemon" });
+            const pluginId = PluginIdSchema.parse(input.id ?? manifest.id);
+            if (this.configStore.get().plugins?.[pluginId]) {
+                throw new Error(`Plugin ID "${pluginId}" is already configured; choose another ID with --id`);
+            }
+            const sources = {
+                ...this.configStore.get().plugins,
+                [pluginId]: { source: "directory", path: directory, enabled: true },
+            };
+            this.configStore.patch({ plugins: sources });
+            if (this.canPublish(pluginId))
+                await this.startConfigured(pluginId);
+            this.notify(pluginId);
+            const installed = this.requireItem(pluginId);
+            if (installed.status === "failed") {
+                throw new Error(installed.error ?? `Plugin failed to start: ${pluginId}`);
+            }
+            return installed;
+        });
+    }
+    async inspectDirectory(configuredPath) {
+        return readPluginManifest(path.resolve(configuredPath));
+    }
+    async installSource(input) {
+        const directDirectory = path.resolve(input.source);
+        const directInfo = await stat(directDirectory).catch(() => null);
+        const reference = directInfo?.isDirectory()
+            ? { source: input.source, pluginPath: undefined }
+            : parsePluginSourceReference(input.source);
+        const directory = path.resolve(reference.source);
+        const info = directInfo?.isDirectory() ? directInfo : await stat(directory).catch(() => null);
+        if (info?.isDirectory()) {
+            if (input.ref)
+                throw new Error("Plugin --ref is only valid for Git sources");
+            const pluginDirectory = resolveLocalPluginPath(directory, reference.pluginPath);
+            return this.installDirectory({ path: pluginDirectory, id: input.id });
+        }
+        const managedSources = this.requireManagedSources();
+        return this.enqueue(async () => {
+            let candidate = await managedSources.prepareInstall({
+                ...input,
+                source: reference.source,
+                pluginPath: reference.pluginPath,
+            });
+            let pluginId;
+            try {
+                await this.checkRequirements(candidate.directory);
+                await runPluginBuild(candidate.directory, candidate.build, this.logger);
+                pluginId = PluginIdSchema.parse(input.id ?? candidate.defaultId);
+                if (this.configStore.get().plugins?.[pluginId]) {
+                    throw new Error(`Plugin ID "${pluginId}" is already configured; choose another ID with --id`);
+                }
+                candidate = await managedSources.place(pluginId, candidate);
+                await this.validateCandidate(candidate);
+            }
+            catch (error) {
+                await managedSources.discard(candidate);
+                throw error;
+            }
+            const sources = {
+                ...this.configStore.get().plugins,
+                [pluginId]: { source: "directory", path: candidate.directory, enabled: true },
+            };
+            managedSources.commit(pluginId, candidate.record);
+            this.configStore.patch({ plugins: sources });
+            if (this.canPublish(pluginId))
+                await this.startConfigured(pluginId);
+            this.notify(pluginId);
+            const installed = this.requireItem(pluginId);
+            if (installed.status === "failed") {
+                throw new Error(installed.error ?? `Plugin failed to start: ${pluginId}`);
+            }
+            return installed;
+        });
+    }
+    async statusSources(pluginId) {
+        return this.enqueue(async () => {
+            const sources = this.configStore.get().plugins ?? {};
+            const selected = pluginId
+                ? [[pluginId, this.requireSource(pluginId)]]
+                : Object.entries(sources);
+            const managedSources = this.requireManagedSources();
+            const statuses = [];
+            for (const [id, source] of selected) {
+                statuses.push(await managedSources.status(id, source.path));
+            }
+            return statuses.sort((left, right) => left.id.localeCompare(right.id));
+        });
+    }
+    async updateSources(pluginId) {
+        return this.enqueue(async () => {
+            const sources = this.configStore.get().plugins ?? {};
+            const ids = pluginId
+                ? [pluginId]
+                : Object.keys(sources).filter((id) => this.managedSources?.get(id));
+            const updates = [];
+            for (const id of ids.sort())
+                updates.push(await this.updateSource(id));
+            return updates;
+        });
+    }
+    async reloadPlugin(pluginId) {
+        return this.enqueue(async () => {
+            const source = this.requireEnabledSource(pluginId);
+            if (this.configStore.get().pluginsEnabled !== true) {
+                throw new Error("Plugins are globally disabled");
+            }
+            this.errors.delete(pluginId);
+            await this.stopPlugin(pluginId);
+            await this.startExplicit(pluginId, source.path);
+            this.notify(pluginId);
+            return this.requireItem(pluginId);
+        });
+    }
+    async enablePlugin(pluginId) {
+        const source = this.requireSource(pluginId);
+        this.patchSource(pluginId, { ...source, enabled: true });
+        this.errors.delete(pluginId);
+        return this.enqueue(async () => {
+            const current = this.requireSource(pluginId);
+            if (current.enabled !== false && this.configStore.get().pluginsEnabled === true) {
+                await this.startExplicit(pluginId, current.path);
+            }
+            this.notify(pluginId);
+            return this.requireItem(pluginId);
+        });
+    }
+    async disablePlugin(pluginId) {
+        const source = this.requireSource(pluginId);
+        this.patchSource(pluginId, { ...source, enabled: false });
+        const stopping = this.stopPlugin(pluginId);
+        return this.enqueue(async () => {
+            await stopping;
+            this.errors.delete(pluginId);
+            this.notify(pluginId);
+            return this.requireItem(pluginId);
+        });
+    }
+    async removePlugin(pluginId) {
+        this.requireSource(pluginId);
+        const stopping = this.stopPlugin(pluginId);
+        const sources = { ...this.configStore.get().plugins };
+        delete sources[pluginId];
+        this.configStore.patch({ plugins: sources });
+        await this.enqueue(async () => {
+            await stopping;
+            this.runtime.clearLogs(pluginId);
+            this.errors.delete(pluginId);
+            this.notify(pluginId);
+            await this.managedSources?.remove(pluginId);
+            if (this.dependencies.settingsDirectory)
+                await rm(path.join(this.dependencies.settingsDirectory, pluginId), {
+                    recursive: true,
+                    force: true,
+                });
+        });
+    }
+    invokePluginRpc(pluginId, method, input) {
+        return this.runtime.invoke(pluginId, method, input);
+    }
+    async stopAllPlugins() {
+        this.globalStartsBlocked = true;
+        const stopping = this.stopAll();
+        await this.enqueue(async () => {
+            await stopping;
+            await this.stopAll();
+        });
+    }
+    handleGlobalSwitch(enabled) {
+        if (!enabled) {
+            this.globalStartsBlocked = true;
+            const stopping = this.stopAll();
+            for (const id of Object.keys(this.configStore.get().plugins ?? {}))
+                this.notify(id);
+            void this.enqueue(async () => {
+                await stopping;
+            }).catch((error) => this.logger.error({ err: error }, "Failed to disable plugins"));
+            return;
+        }
+        void this.enqueue(async () => {
+            this.globalStartsBlocked = false;
+            for (const [pluginId, source] of Object.entries(this.configStore.get().plugins ?? {})) {
+                if (source.enabled !== false)
+                    await this.startConfigured(pluginId);
+                this.notify(pluginId);
+            }
+        }).catch((error) => this.logger.error({ err: error }, "Failed to enable plugins"));
+    }
+    async startConfigured(pluginId) {
+        const source = this.configStore.get().plugins?.[pluginId];
+        if (!source || source.enabled === false || !this.canPublish(pluginId))
+            return;
+        this.errors.delete(pluginId);
+        try {
+            await this.startPlugin(pluginId, source.path);
+        }
+        catch (error) {
+            if (this.canPublish(pluginId))
+                this.recordFailure(pluginId, error);
+        }
+    }
+    async startExplicit(pluginId, sourcePath) {
+        try {
+            await this.startPlugin(pluginId, sourcePath);
+        }
+        catch (error) {
+            if (this.canPublish(pluginId)) {
+                this.recordFailure(pluginId, error);
+                this.notify(pluginId);
+            }
+            throw error;
+        }
+    }
+    canPublish(pluginId) {
+        const config = this.configStore.get();
+        return (!this.globalStartsBlocked &&
+            config.pluginsEnabled === true &&
+            config.plugins?.[pluginId]?.enabled !== false &&
+            config.plugins?.[pluginId] !== undefined);
+    }
+    async startPlugin(pluginId, sourcePath) {
+        await this.runtime.startPlugin(pluginId, sourcePath, () => this.canPublish(pluginId));
+        try {
+            await this.publishProviderRegistrations(pluginId, sourcePath);
+        }
+        catch (error) {
+            try {
+                this.removeProviderRegistrations(pluginId);
+            }
+            finally {
+                await this.runtime.stopPluginById(pluginId);
+            }
+            throw error;
+        }
+    }
+    stopPlugin(pluginId) {
+        this.removeProviderRegistrations(pluginId);
+        return this.runtime.stopPluginById(pluginId);
+    }
+    async stopAll() {
+        for (const pluginId of this.providerIdsByPlugin.keys()) {
+            this.removeProviderRegistrations(pluginId);
+        }
+        await this.runtime.stopAll();
+    }
+    async publishProviderRegistrations(pluginId, pluginDirectory) {
+        const metadata = this.runtime.getProviderRegistrations?.(pluginId) ?? [];
+        const configuredIds = new Set(Object.keys(this.configStore.get().providers));
+        for (const provider of metadata) {
+            if (BUILTIN_PROVIDER_ID_SET.has(provider.id)) {
+                throw new Error(`Plugin ${pluginId} cannot register builtin provider ID "${provider.id}"`);
+            }
+            if (configuredIds.has(provider.id)) {
+                throw new Error(`Plugin ${pluginId} cannot register configured provider ID "${provider.id}"`);
+            }
+            if (this.providers.has(provider.id)) {
+                throw new Error(`Plugin ${pluginId} cannot register provider ID "${provider.id}" twice`);
+            }
+        }
+        const registrations = await Promise.all(metadata.map(async (provider) => ({
+            id: provider.id,
+            label: provider.label,
+            description: provider.description,
+            getCatalogCacheKey: provider.hasCatalogCacheKey
+                ? (options) => {
+                    if (!this.runtime.getProviderCatalogCacheKey)
+                        throw new Error("Plugin runtime cannot resolve catalogue keys");
+                    return this.runtime.getProviderCatalogCacheKey(pluginId, provider.id, options);
+                }
+                : undefined,
+            icon: provider.iconPath
+                ? await readPluginProviderIcon(pluginDirectory, provider.iconPath)
+                : undefined,
+            connect: (request) => this.runtime.connectProvider(pluginId, provider.id, request),
+        })));
+        const ids = registrations.map((provider) => provider.id);
+        for (const provider of registrations) {
+            this.providers.set(provider.id, {
+                ...provider,
+            });
+        }
+        if (ids.length > 0) {
+            this.providerIdsByPlugin.set(pluginId, ids);
+            this.notifyProviderRegistrations();
+        }
+    }
+    removeProviderRegistrations(pluginId) {
+        const ids = this.providerIdsByPlugin.get(pluginId);
+        if (!ids)
+            return;
+        this.providerIdsByPlugin.delete(pluginId);
+        for (const id of ids)
+            this.providers.delete(id);
+        this.notifyProviderRegistrations();
+    }
+    notifyProviderRegistrations() {
+        for (const listener of this.providerListeners)
+            listener();
+    }
+    enqueue(operation) {
+        const result = this.lifecycle.then(operation, operation);
+        this.lifecycle = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    recordFailure(pluginId, error) {
+        this.errors.set(pluginId, error instanceof Error ? error.message : String(error));
+    }
+    async checkRequirements(directory) {
+        const manifest = await readPluginManifest(directory);
+        assertPluginCompatibility({ ...manifest, version: this.daemonVersion, runtime: "daemon" });
+    }
+    async updateSource(pluginId) {
+        const managedSources = this.requireManagedSources();
+        const source = this.requireSource(pluginId);
+        const previous = managedSources.get(pluginId);
+        if (!previous)
+            throw new Error(`Plugin is not managed by Git: ${pluginId}`);
+        const prepared = await managedSources.prepareUpdate(pluginId, source.path);
+        if (!prepared.candidate) {
+            return {
+                id: pluginId,
+                previousCommit: previous.commit,
+                currentCommit: previous.commit,
+                commits: 0,
+                updated: false,
+            };
+        }
+        let candidate = prepared.candidate;
+        try {
+            await this.checkRequirements(candidate.directory);
+            await runPluginBuild(candidate.directory, candidate.build, this.logger);
+            candidate = await managedSources.place(pluginId, candidate);
+            await this.validateCandidate(candidate);
+        }
+        catch (error) {
+            await managedSources.discard(candidate);
+            throw error;
+        }
+        const current = this.configStore.get().plugins?.[pluginId];
+        if (!current) {
+            await managedSources.discard(candidate);
+            throw new Error(`Plugin is no longer configured: ${pluginId}`);
+        }
+        const isRunning = this.runtime.catalog().some((plugin) => plugin.id === pluginId);
+        const isEnabled = current.enabled !== false;
+        const isGloballyEnabled = this.configStore.get().pluginsEnabled === true;
+        const shouldActivate = isEnabled && isGloballyEnabled;
+        if (shouldActivate) {
+            if (isRunning)
+                await this.stopPlugin(pluginId);
+            try {
+                await this.startExplicit(pluginId, candidate.directory);
+            }
+            catch (error) {
+                this.errors.delete(pluginId);
+                const latest = this.configStore.get().plugins?.[pluginId];
+                const isStillConfigured = latest !== undefined;
+                const isStillEnabled = isStillConfigured && latest.enabled !== false;
+                const isStillGloballyEnabled = this.configStore.get().pluginsEnabled === true;
+                const canRestore = isRunning && isStillEnabled && isStillGloballyEnabled;
+                if (canRestore)
+                    await this.startExplicit(pluginId, source.path);
+                await managedSources.discard(candidate);
+                this.notify(pluginId);
+                throw error;
+            }
+        }
+        const activatedSource = this.configStore.get().plugins?.[pluginId];
+        if (!activatedSource) {
+            await this.stopPlugin(pluginId);
+            await managedSources.discard(candidate);
+            throw new Error(`Plugin is no longer configured: ${pluginId}`);
+        }
+        this.patchSource(pluginId, { ...activatedSource, path: candidate.directory });
+        managedSources.commit(pluginId, candidate.record);
+        await managedSources.removeVersion(previous);
+        this.errors.delete(pluginId);
+        this.notify(pluginId);
+        return {
+            id: pluginId,
+            previousCommit: previous.commit,
+            currentCommit: candidate.record.commit,
+            commits: prepared.commits,
+            updated: true,
+        };
+    }
+    validateCandidate(candidate) {
+        if (!this.runtime.validatePlugin) {
+            throw new Error("Plugin runtime cannot validate managed Git sources");
+        }
+        return this.runtime.validatePlugin(candidate.directory);
+    }
+    requireManagedSources() {
+        if (!this.managedSources)
+            throw new Error("Git plugin management is unavailable");
+        return this.managedSources;
+    }
+    requireSource(pluginId) {
+        PluginIdSchema.parse(pluginId);
+        const source = this.configStore.get().plugins?.[pluginId];
+        if (!source)
+            throw new Error(`Plugin is not configured: ${pluginId}`);
+        return source;
+    }
+    requireEnabledSource(pluginId) {
+        const source = this.requireSource(pluginId);
+        if (source.enabled === false)
+            throw new Error(`Plugin is disabled: ${pluginId}`);
+        return source;
+    }
+    patchSource(pluginId, source) {
+        this.configStore.patch({
+            plugins: { ...this.configStore.get().plugins, [pluginId]: source },
+        });
+    }
+    requireItem(pluginId) {
+        const item = this.listPlugins().find((plugin) => plugin.id === pluginId);
+        if (!item)
+            throw new Error(`Plugin is not configured: ${pluginId}`);
+        return item;
+    }
+    notify(pluginId) {
+        for (const listener of this.listeners)
+            listener(pluginId);
+    }
+}
+function resolveLocalPluginPath(directory, pluginPath) {
+    if (!pluginPath)
+        return directory;
+    if (path.isAbsolute(pluginPath))
+        throw new Error("Plugin path must be relative to the source");
+    const pluginDirectory = path.resolve(directory, pluginPath);
+    const relative = path.relative(directory, pluginDirectory);
+    const escapesSource = relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+    if (escapesSource)
+        throw new Error("Plugin path must stay inside the source directory");
+    return pluginDirectory;
+}
+//# sourceMappingURL=index.js.map

package/dist/server/server/plugins/lifecycle/index.d.ts

@@ -0,0 +1,40 @@
+import type { AgentStreamEvent, AgentTimelineItem } from "../../agent/agent-sdk-types.js";
+import type { PluginHookAgent, PluginHookContext, PluginLifecycleRegistration } from "@camerontaylor/paseo-plugin/server";
+import type { PluginBeforeRequests, PluginHookWorkspace, PluginLifecycleEvents } from "@camerontaylor/paseo-plugin/server";
+import type { PersistedWorkspaceRecord } from "../../workspace-registry.js";
+export declare const lifecycleEventNames: readonly ["agent.created", "agent.turn_started", "agent.turn_ended", "agent.permission_requested", "agent.permission_resolved", "agent.archived", "workspace.created", "workspace.archived"];
+export declare const beforeHookNames: readonly ["agent.create", "agent.session_open", "workspace.create"];
+export interface PluginLifecycle {
+    emit<Name extends keyof PluginLifecycleEvents>(name: Name, event: PluginLifecycleEvents[Name]): void;
+    before<Name extends keyof PluginBeforeRequests>(name: Name, request: PluginBeforeRequests[Name]): Promise<PluginBeforeRequests[Name]>;
+}
+export declare function validateBeforeRequest<Name extends keyof PluginBeforeRequests>(name: Name, value: unknown): PluginBeforeRequests[Name];
+export declare function describeHookWorkspace(workspace: PersistedWorkspaceRecord): PluginHookWorkspace;
+export declare function describeHookAgent(agent: {
+    id: string;
+    workspaceId?: string;
+    provider: string;
+    cwd: string;
+    title?: string | null;
+    labels: Record<string, string>;
+}): PluginHookAgent;
+export declare function publishAgentStream(lifecycle: PluginLifecycle, agent: PluginHookAgent, event: AgentStreamEvent, timeline: readonly AgentTimelineItem[]): void;
+export declare function validateBeforeResult<Name extends keyof PluginBeforeRequests>(name: Name, input: PluginBeforeRequests[Name], output: unknown): PluginBeforeRequests[Name];
+export declare class PluginHookHandlers implements PluginLifecycleRegistration {
+    private readonly events;
+    private readonly transforms;
+    private readonly active;
+    private readonly changed;
+    constructor(changed: () => void);
+    readonly on: PluginLifecycleRegistration["on"];
+    readonly before: PluginLifecycleRegistration["before"];
+    catalog(): {
+        events: string[];
+        before: string[];
+    };
+    invoke(id: string, kind: "event" | "before", name: string, input: unknown, paseo: PluginHookContext["paseo"]): Promise<unknown>;
+    cancel(id: string): void;
+    close(): void;
+    private register;
+}
+//# sourceMappingURL=index.d.ts.map