@elizaos/agent 2.0.0-beta.2 → 2.0.3-beta.3

package/services/remote-plugin-bridge.js

@@ -0,0 +1,669 @@
+/**
+ * RemotePluginBridge — host-side wiring for a remote-mode plugin.
+ *
+ * Sits between a `RemotePluginHost`-managed worker (or any
+ * `BridgeChannel`-shaped transport) and an `IAgentRuntime`. On
+ * `worker-announce-plugin` it walks the descriptor, synthesises proxy
+ * Plugin contributions (actions, providers, events, models) whose
+ * handlers proxy back to the worker over `worker-rpc`, and registers
+ * the resulting Plugin with `runtime.registerPlugin(...)`.
+ *
+ * Inbound `host-rpc` messages from the worker are dispatched to the
+ * real runtime (`getService`, `useModel`, `getMemory`, `emitEvent`,
+ * `composeState`, etc.) and the result is shipped back as
+ * `host-rpc-result`.
+ *
+ * Wired: actions, providers, events, models, evaluators, action callbacks,
+ * services, routes, and views. Streaming model token forwarding remains a
+ * separate bridge capability.
+ */
+// ./error subpath, not the barrel: the barrel eagerly loads ./bootstrap's heavy
+// runtime chain, which crashed agent boot in the cloud image.
+import { fromWireError, toWireError, } from "@elizaos/plugin-worker-runtime/error";
+import * as z from "zod";
+/**
+ * Schema for the announce/dynamic descriptor the worker emits via
+ * {@link buildAnnounceDescriptor} (packages/plugin-worker-runtime/src/descriptor.ts).
+ *
+ * The descriptor is untrusted JSON crossing the host↔worker RPC boundary, so
+ * it is parsed once at ingress instead of being blind-cast field by field.
+ *
+ * Object schemas are intentionally passthrough (extra keys pass through): the
+ * producer only writes a field when it is present, the metadata surfaces
+ * (`views`/`widgets`/`componentTypes`) are author-defined JSON, and the
+ * service entries carry dynamic `rpc:<method>` keys. The schema validates the
+ * *container shape* (array vs record vs object) and the fields the bridge
+ * actually reads; everything else is preserved verbatim. Functions are
+ * replaced on the wire by {@link RemoteFunctionRef} (`{ rpc: true, id }`).
+ */
+const RemoteFunctionRefSchema = z
+    .object({
+    rpc: z.literal(true),
+    id: z.string(),
+})
+    .passthrough();
+const ActionDescriptorSchema = z
+    .object({
+    name: z.string(),
+    handler: RemoteFunctionRefSchema,
+    similes: z.array(z.string()).optional(),
+    description: z.string().optional(),
+    examples: z.unknown().optional(),
+    validate: RemoteFunctionRefSchema.optional(),
+})
+    .passthrough();
+const ProviderDescriptorSchema = z
+    .object({
+    name: z.string(),
+    get: RemoteFunctionRefSchema,
+    description: z.string().optional(),
+    dynamic: z.boolean().optional(),
+    position: z.number().optional(),
+    private: z.boolean().optional(),
+})
+    .passthrough();
+const ServiceDescriptorSchema = z
+    .object({
+    serviceType: z.string(),
+    rpcMethods: z.array(z.string()),
+    capabilityDescription: z.string().optional(),
+})
+    .passthrough();
+const RouteDescriptorSchema = z
+    .object({
+    path: z.string(),
+    routeHandler: RemoteFunctionRefSchema.optional(),
+    type: z.unknown().optional(),
+    name: z.unknown().optional(),
+    public: z.unknown().optional(),
+    isMultipart: z.unknown().optional(),
+})
+    .passthrough();
+const RemotePluginDescriptorSchema = z
+    .object({
+    name: z.string().optional(),
+    description: z.unknown().optional(),
+    priority: z.unknown().optional(),
+    dependencies: z.array(z.string()).optional(),
+    actions: z.array(ActionDescriptorSchema).optional(),
+    providers: z.array(ProviderDescriptorSchema).optional(),
+    events: z.record(z.string(), z.array(RemoteFunctionRefSchema)).optional(),
+    models: z.record(z.string(), RemoteFunctionRefSchema).optional(),
+    services: z.array(ServiceDescriptorSchema).optional(),
+    routes: z.array(RouteDescriptorSchema).optional(),
+    views: z.array(z.unknown()).optional(),
+    widgets: z.array(z.unknown()).optional(),
+    componentTypes: z.array(z.unknown()).optional(),
+})
+    .passthrough();
+function isWorkerActionCallbackEnvelope(message) {
+    const candidate = message;
+    return candidate.type === "worker-action-callback";
+}
+export class RemotePluginBridge {
+    channel;
+    runtime;
+    rpcTimeoutMs;
+    state;
+    constructor(options) {
+        this.channel = options.channel;
+        this.runtime = options.runtime;
+        this.rpcTimeoutMs = options.rpcTimeoutMs ?? 60_000;
+        this.state = {
+            pluginName: null,
+            plugin: null,
+            pending: new Map(),
+            actionCallbacks: new Map(),
+            nextRequestId: (() => {
+                let n = 0;
+                return () => {
+                    n = (n + 1) >>> 0;
+                    return n;
+                };
+            })(),
+            unsubscribe: undefined,
+        };
+    }
+    /** Begin listening for announce + host-rpc messages from the worker. */
+    attach() {
+        if (this.state.unsubscribe)
+            return;
+        this.state.unsubscribe = this.channel.onMessage((message) => {
+            void this.onMessage(message);
+        });
+    }
+    /** Tear down. Unloads the plugin from the runtime if registered. */
+    async detach() {
+        this.state.unsubscribe?.();
+        this.state.unsubscribe = undefined;
+        const rejection = new Error("RemotePluginBridge detached.");
+        for (const [, slot] of this.state.pending) {
+            if (slot.timer)
+                clearTimeout(slot.timer);
+            slot.reject(rejection);
+        }
+        this.state.pending.clear();
+        this.state.actionCallbacks.clear();
+        if (this.state.pluginName) {
+            await this.runtime.unloadPlugin(this.state.pluginName).catch(() => {
+                // ignore unload failures during tear-down
+            });
+            this.state.pluginName = null;
+        }
+    }
+    async onMessage(message) {
+        // Keep this staged callback envelope source-typed here so the bridge does
+        // not depend on ignored plugin-remote-manifest dist declarations being
+        // regenerated before every workspace typecheck.
+        if (isWorkerActionCallbackEnvelope(message)) {
+            await this.handleActionCallback(message);
+            return;
+        }
+        switch (message.type) {
+            case "worker-announce-plugin":
+                await this.handleAnnounce(message);
+                return;
+            case "worker-announce-dynamic":
+                await this.handleDynamicAnnounce(message);
+                return;
+            case "worker-rpc-result":
+                this.handleRpcResult(message);
+                return;
+            case "host-rpc":
+                await this.handleHostRpc(message);
+                return;
+            default:
+                // init-complete, stream-chunk, stream-end, ready, event, etc.
+                // not handled in P1; the broader RemotePluginHost owns these.
+                return;
+        }
+    }
+    async handleAnnounce(message) {
+        const plugin = this.materialisePlugin(message.descriptor);
+        this.state.pluginName = plugin.name;
+        this.state.plugin = plugin;
+        await this.runtime.registerPlugin(plugin);
+    }
+    async handleDynamicAnnounce(message) {
+        const registeredPlugin = this.state.plugin;
+        if (!registeredPlugin || !this.state.pluginName) {
+            throw new Error("worker-announce-dynamic received before plugin announce");
+        }
+        const dynamicPlugin = this.materialisePlugin(message.descriptor);
+        if (dynamicPlugin.name !== this.state.pluginName) {
+            throw new Error(`worker-announce-dynamic plugin mismatch: expected ${this.state.pluginName}, got ${dynamicPlugin.name}`);
+        }
+        await this.applyDynamicContributions(registeredPlugin, dynamicPlugin);
+    }
+    materialisePlugin(rawDescriptor) {
+        const descriptor = RemotePluginDescriptorSchema.parse(rawDescriptor);
+        const name = String(descriptor.name ?? "");
+        if (!name)
+            throw new Error("worker-announce-plugin descriptor missing name");
+        const plugin = {
+            name,
+            description: String(descriptor.description ?? ""),
+            mode: "remote",
+        };
+        if (descriptor.priority !== undefined) {
+            plugin.priority = Number(descriptor.priority);
+        }
+        if (descriptor.dependencies) {
+            plugin.dependencies = descriptor.dependencies;
+        }
+        this.attachFunctionContributions(plugin, descriptor);
+        this.attachServiceContributions(plugin, descriptor);
+        this.attachRouteContributions(plugin, descriptor);
+        this.attachViewContributions(plugin, descriptor);
+        return plugin;
+    }
+    async applyDynamicContributions(registeredPlugin, dynamicPlugin) {
+        if (dynamicPlugin.actions?.length) {
+            registeredPlugin.actions = [
+                ...(registeredPlugin.actions ?? []),
+                ...dynamicPlugin.actions,
+            ];
+            for (const action of dynamicPlugin.actions) {
+                this.runtime.registerAction(action);
+            }
+        }
+        if (dynamicPlugin.providers?.length) {
+            registeredPlugin.providers = [
+                ...(registeredPlugin.providers ?? []),
+                ...dynamicPlugin.providers,
+            ];
+            for (const provider of dynamicPlugin.providers) {
+                this.runtime.registerProvider(provider);
+            }
+        }
+        if (dynamicPlugin.evaluators?.length) {
+            registeredPlugin.evaluators = [
+                ...(registeredPlugin.evaluators ?? []),
+                ...dynamicPlugin.evaluators,
+            ];
+            for (const evaluator of dynamicPlugin.evaluators) {
+                this.runtime.registerEvaluator(evaluator);
+            }
+        }
+        if (dynamicPlugin.models) {
+            registeredPlugin.models = {
+                ...(registeredPlugin.models ?? {}),
+                ...dynamicPlugin.models,
+            };
+            for (const [modelType, handler] of Object.entries(dynamicPlugin.models)) {
+                this.runtime.registerModel(modelType, handler, registeredPlugin.name, registeredPlugin.priority);
+            }
+        }
+        if (dynamicPlugin.events) {
+            registeredPlugin.events = {
+                ...(registeredPlugin.events ?? {}),
+            };
+            for (const [eventName, handlers] of Object.entries(dynamicPlugin.events)) {
+                const existingHandlers = registeredPlugin.events[eventName] ??
+                    [];
+                registeredPlugin.events[eventName] = [
+                    ...existingHandlers,
+                    ...handlers,
+                ];
+                const registerEvent = this.runtime.registerEvent;
+                for (const handler of handlers) {
+                    registerEvent(eventName, handler);
+                }
+            }
+        }
+        if (dynamicPlugin.services?.length) {
+            registeredPlugin.services = [
+                ...(registeredPlugin.services ?? []),
+                ...dynamicPlugin.services,
+            ];
+            for (const service of dynamicPlugin.services) {
+                await this.runtime.registerService(service);
+            }
+        }
+        if (dynamicPlugin.routes?.length) {
+            registeredPlugin.routes = [
+                ...(registeredPlugin.routes ?? []),
+                ...dynamicPlugin.routes,
+            ];
+            const runtimeRoutes = this.runtime.routes;
+            if (Array.isArray(runtimeRoutes)) {
+                for (const route of dynamicPlugin.routes) {
+                    const rawPath = route.rawPath === true;
+                    const routePath = route.path.startsWith("/")
+                        ? route.path
+                        : `/${route.path}`;
+                    runtimeRoutes.push({
+                        ...route,
+                        path: rawPath ? routePath : `/${registeredPlugin.name}${routePath}`,
+                    });
+                }
+            }
+        }
+        if (dynamicPlugin.views?.length) {
+            registeredPlugin.views = [
+                ...(registeredPlugin.views ?? []),
+                ...dynamicPlugin.views,
+            ];
+        }
+        if (dynamicPlugin.widgets?.length) {
+            registeredPlugin.widgets = [
+                ...(registeredPlugin.widgets ?? []),
+                ...dynamicPlugin.widgets,
+            ];
+        }
+        if (dynamicPlugin.componentTypes?.length) {
+            registeredPlugin.componentTypes = [
+                ...(registeredPlugin.componentTypes ?? []),
+                ...dynamicPlugin.componentTypes,
+            ];
+        }
+    }
+    attachFunctionContributions(plugin, descriptor) {
+        if (descriptor.actions?.length) {
+            plugin.actions = descriptor.actions.map((action) => this.makeActionProxy(action));
+        }
+        if (descriptor.providers?.length) {
+            plugin.providers = descriptor.providers.map((provider) => this.makeProviderProxy(provider));
+        }
+        if (descriptor.events) {
+            const eventMap = {};
+            for (const [eventName, refs] of Object.entries(descriptor.events)) {
+                const handlers = refs.map((ref) => this.makeEventHandlerProxy(ref));
+                eventMap[eventName] = handlers;
+            }
+            plugin.events = eventMap;
+        }
+        if (descriptor.models) {
+            const modelMap = {};
+            for (const [modelType, ref] of Object.entries(descriptor.models)) {
+                modelMap[modelType] =
+                    this.makeModelHandlerProxy(ref);
+            }
+            plugin.models = modelMap;
+        }
+    }
+    attachServiceContributions(plugin, descriptor) {
+        // Services: opt-in via `static rpcMethods`. The descriptor carries
+        // one entry per service with the methods list and per-method rpc
+        // ids; we synthesise a ServiceClass with dynamic methods.
+        if (descriptor.services?.length) {
+            plugin.services = descriptor.services.map((svc) => this.makeServiceClassProxy(svc));
+        }
+    }
+    attachRouteContributions(plugin, descriptor) {
+        // Routes: the agent's existing plugin-route lifecycle will pick
+        // these up. Each routeHandler is wrapped to forward
+        // RouteHandlerContext via worker-rpc and return RouteHandlerResult.
+        if (descriptor.routes?.length) {
+            plugin.routes = descriptor.routes
+                .map((r) => this.makeRouteProxy(r))
+                .filter((r) => r !== null);
+        }
+    }
+    attachViewContributions(plugin, descriptor) {
+        // Views/widgets/componentTypes are pure JSON metadata; pass them
+        // through unchanged so the existing view registry serves the
+        // remote plugin's bundle the same way it does direct plugins'.
+        if (descriptor.views)
+            plugin.views = descriptor.views;
+        if (descriptor.widgets)
+            plugin.widgets = descriptor.widgets;
+        if (descriptor.componentTypes) {
+            plugin.componentTypes =
+                descriptor.componentTypes;
+        }
+    }
+    makeActionProxy(descriptor) {
+        const name = descriptor.name;
+        const similes = descriptor.similes ?? [];
+        const description = String(descriptor.description ?? "");
+        const examples = descriptor.examples ?? [];
+        const validateRef = descriptor.validate;
+        const handler = async (_runtime, message, state, options, callback, responses) => {
+            let callbackId;
+            if (callback) {
+                callbackId = `action-callback:${this.state.nextRequestId()}`;
+                this.state.actionCallbacks.set(callbackId, callback);
+            }
+            try {
+                const result = await this.workerRpc("action", descriptor.handler.id, {
+                    message: this.normalize(message),
+                    state: this.normalize(state),
+                    options: this.normalize(options ?? null),
+                    responses: this.normalize(responses ?? null),
+                    ...(callbackId ? { callbackId } : {}),
+                });
+                return result;
+            }
+            finally {
+                if (callbackId) {
+                    this.state.actionCallbacks.delete(callbackId);
+                }
+            }
+        };
+        const validate = validateRef
+            ? async (_runtime, message, state) => {
+                const result = await this.workerRpc("action", validateRef.id, {
+                    message: this.normalize(message),
+                    state: this.normalize(state ?? null),
+                });
+                return Boolean(result);
+            }
+            : async () => true;
+        const action = {
+            name,
+            similes,
+            description,
+            examples,
+            handler,
+            validate,
+        };
+        return action;
+    }
+    makeProviderProxy(descriptor) {
+        const name = descriptor.name;
+        const description = String(descriptor.description ?? "");
+        const dynamic = descriptor.dynamic === true;
+        const priv = descriptor.private === true;
+        const position = descriptor.position;
+        const get = async (_runtime, message, state) => {
+            const result = await this.workerRpc("provider", descriptor.get.id, {
+                message: this.normalize(message),
+                state: this.normalize(state),
+            });
+            if (result && typeof result === "object" && !Array.isArray(result)) {
+                return result;
+            }
+            return { values: {}, data: {}, text: "" };
+        };
+        const provider = {
+            name,
+            description,
+            get,
+        };
+        if (dynamic)
+            provider.dynamic = true;
+        if (priv)
+            provider.private = true;
+        if (position !== undefined)
+            provider.position = position;
+        return provider;
+    }
+    /**
+     * Build a {@link ServiceClass} proxy from a service descriptor. The
+     * returned class has the announced serviceType and a static `start`
+     * factory that constructs an instance whose declared rpcMethods
+     * worker-rpc into the worker's service trampoline.
+     *
+     * Methods not in rpcMethods are absent — there is no way to reach
+     * private worker methods from the host, which is the whole point of
+     * the opt-in.
+     */
+    makeServiceClassProxy(descriptor) {
+        const bridge = this;
+        const serviceType = descriptor.serviceType;
+        const description = descriptor.capabilityDescription ?? "";
+        const methodIdMap = new Map();
+        for (const method of descriptor.rpcMethods) {
+            const ref = RemoteFunctionRefSchema.safeParse(descriptor[`rpc:${method}`]);
+            if (ref.success)
+                methodIdMap.set(method, ref.data.id);
+        }
+        // Build the proxy class on the fly. The Service base class isn't
+        // imported here to avoid pulling all of @elizaos/core into this
+        // module; the runtime only needs the static fields it checks.
+        class RemoteServiceProxy {
+            static serviceType = serviceType;
+            static capabilityDescription = description;
+            capabilityDescription = description;
+            static async start() {
+                const instance = new RemoteServiceProxy();
+                return instance;
+            }
+            constructor() {
+                for (const method of descriptor.rpcMethods) {
+                    const id = methodIdMap.get(method);
+                    if (!id)
+                        continue;
+                    this[method] = async (...callArgs) => bridge.workerRpc("service", id, {
+                        args: callArgs.map((a) => bridge.normalize(a)),
+                    });
+                }
+            }
+            async stop() {
+                // Stopping the proxy doesn't tear down the worker; the
+                // RemotePluginHost owns the worker lifecycle.
+            }
+        }
+        return RemoteServiceProxy;
+    }
+    /**
+     * Build a route proxy. The agent's plugin-route registration code
+     * picks up `plugin.routes[i]` exactly as for direct plugins; the
+     * `routeHandler` here forwards via worker-rpc.
+     */
+    makeRouteProxy(descriptor) {
+        if (!descriptor.routeHandler)
+            return null;
+        const ref = descriptor.routeHandler;
+        const routeHandler = async (ctx) => this.workerRpc("route", ref.id, { ctx: this.normalize(ctx) });
+        const route = {
+            path: descriptor.path,
+            ...(descriptor.type ? { type: descriptor.type } : {}),
+            ...(descriptor.name ? { name: descriptor.name } : {}),
+            ...(descriptor.public !== undefined
+                ? { public: Boolean(descriptor.public) }
+                : {}),
+            ...(descriptor.isMultipart !== undefined
+                ? { isMultipart: Boolean(descriptor.isMultipart) }
+                : {}),
+            routeHandler,
+        };
+        return route;
+    }
+    makeEventHandlerProxy(ref) {
+        return async (payload) => {
+            await this.workerRpc("event", ref.id, this.normalize(payload));
+        };
+    }
+    makeModelHandlerProxy(ref) {
+        return async (_runtime, params) => {
+            return this.workerRpc("model", ref.id, {
+                params: this.normalize(params),
+            });
+        };
+    }
+    workerRpc(surface, target, args) {
+        const requestId = this.state.nextRequestId();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                if (this.state.pending.delete(requestId)) {
+                    reject(new Error(`worker-rpc ${surface}:${target} timed out after ${this.rpcTimeoutMs}ms`));
+                }
+            }, this.rpcTimeoutMs);
+            this.state.pending.set(requestId, {
+                resolve: (v) => resolve(v),
+                reject,
+                timer,
+            });
+            const envelope = {
+                type: "worker-rpc",
+                requestId,
+                surface,
+                target,
+                args,
+            };
+            this.channel.send(envelope);
+        });
+    }
+    handleRpcResult(message) {
+        const slot = this.state.pending.get(message.requestId);
+        if (!slot)
+            return;
+        this.state.pending.delete(message.requestId);
+        if (slot.timer)
+            clearTimeout(slot.timer);
+        if (message.ok) {
+            slot.resolve((message.payload ?? null));
+        }
+        else {
+            slot.reject(fromWireError(message.error ?? {
+                name: "Error",
+                message: "Unknown worker-rpc failure",
+            }, "remote worker"));
+        }
+    }
+    async handleActionCallback(message) {
+        const callback = this.state.actionCallbacks.get(message.callbackId);
+        if (!callback)
+            return;
+        await callback(message.payload);
+    }
+    async handleHostRpc(message) {
+        const reply = (result) => {
+            this.channel.send(result);
+        };
+        try {
+            const payload = await this.dispatchRuntimeMethod(message);
+            reply({
+                type: "host-rpc-result",
+                requestId: message.requestId,
+                ok: true,
+                payload,
+            });
+        }
+        catch (error) {
+            reply({
+                type: "host-rpc-result",
+                requestId: message.requestId,
+                ok: false,
+                error: toWireError(error),
+            });
+        }
+    }
+    async dispatchRuntimeMethod(message) {
+        const args = (message.args ?? {});
+        switch (message.method) {
+            case "getService": {
+                const serviceType = String(args.serviceType);
+                const service = this.runtime.getService(serviceType);
+                return service ? { available: true } : null;
+            }
+            case "useModel": {
+                const modelType = String(args.modelType);
+                const params = args.params;
+                const result = await this.runtime.useModel(modelType, params);
+                return (result ?? null);
+            }
+            case "getMemory": {
+                const memoryId = String(args.memoryId);
+                const memory = await this.runtime.getMemoryById(memoryId);
+                return JSON.parse(JSON.stringify(memory ?? null));
+            }
+            case "createMemory": {
+                const memory = args.memory;
+                const tableName = typeof args.tableName === "string" ? args.tableName : undefined;
+                const created = await this.runtime.createMemory(memory, tableName ?? "messages");
+                return String(created);
+            }
+            case "updateMemory": {
+                await this.runtime.updateMemory(args.memory);
+                return null;
+            }
+            case "emitEvent": {
+                const eventName = String(args.name);
+                const payload = args.payload;
+                await this.runtime.emitEvent(eventName, payload);
+                return null;
+            }
+            case "getSetting": {
+                const key = String(args.key);
+                const value = this.runtime.getSetting(key);
+                return (value ?? null);
+            }
+            case "setSetting": {
+                const key = String(args.key);
+                const value = args.value;
+                this.runtime.setSetting(key, value);
+                return null;
+            }
+            case "composeState": {
+                const memory = args.message;
+                const result = await this.runtime.composeState(memory);
+                return JSON.parse(JSON.stringify(result ?? null));
+            }
+            default:
+                throw new Error(`Unsupported host-rpc method: ${message.method}. P1 supports getService, useModel, getMemory, createMemory, updateMemory, emitEvent, getSetting, setSetting, composeState.`);
+        }
+    }
+    normalize(value) {
+        if (value === undefined)
+            return null;
+        try {
+            return JSON.parse(JSON.stringify(value));
+        }
+        catch {
+            return null;
+        }
+    }
+}