Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
/**
* In-process plugin runtime: loads the plugin's bundled ES module into the
* daemon and hands it a PluginContext.
*
* Containment, since the code shares our process:
* - loading, activate() and deactivate() each have a timeout;
* - tools/commands can only be registered under names the manifest
* declared, so the install prompt always tells the truth;
* - timers go through ctx.timers, which catches their errors and clears
* them on stop; fetches go through ctx.fetch (declared hosts, SSRF guard,
* aborted on stop);
* - stop() tears down everything registered, however activate() ended.
* What try/catch cannot contain (a busy loop, process.exit) is why
* untrusted code belongs in an out-of-process plugin.
*/
import { pathToFileURL } from 'node:url';
import { resolve } from 'node:path';
import { assertFetchableTarget, MAX_REDIRECTS } from '../../utils/ssrf.js';
import { logger } from '../../utils/logger.js';
import { PLUGIN_API_VERSION, providerSecretNames, type PluginManifest, type PluginProviderId } from '../types.js';
import type { Disposable, PluginCommandDefinition, PluginContext, PluginModule, PluginToolDefinition } from '../sdk.js';
import { publishCommand, publishTool,
screenshotContract, unpublishPlugin } from '../tool-bridge.js';
import type { PluginRuntime, RuntimeDeps } from './types.js';
export const IN_PROCESS_TIMEOUTS = { load: 10_000, activate: 15_000, deactivate: 5_000, dispose: 3_000 };
function withTimeout<T>(p: Promise<T>, ms: number, what: string): Promise<T> {
let timer: ReturnType<typeof setTimeout> | undefined;
return Promise.race([
p.finally(() => timer && clearTimeout(timer)),
new Promise<never>((_, reject) => {
timer = setTimeout(() => reject(new Error(`${what} timed out after ${Math.round(ms / 1000)}s`)), ms);
}),
]);
}
/** Host may match exactly, or a "*.example.com" entry matches subdomains (not the apex). */
export function hostAllowed(host: string, allowed: readonly string[]): boolean {
const h = host.toLowerCase().replace(/\.$/, '');
return allowed.some((rule) => {
const r = rule.toLowerCase();
if (r.startsWith('*.')) return h.endsWith(r.slice(1)) && h.length > r.length - 1;
return h === r;
});
}
let loadCounter = 0;
export class InProcessRuntime implements PluginRuntime {
readonly kind = 'in-process' as const;
private ac = new AbortController();
private disposables: Array<() => void | Promise<void>> = [];
private module: PluginModule | null = null;
private running = false;
private registered = new Set<string>();
constructor(private readonly manifest: PluginManifest, private readonly dir: string, private readonly deps: RuntimeDeps) {}
isRunning(): boolean {
return this.running;
}
async start(): Promise<void> {
this.ac = new AbortController();
const entry = resolve(this.dir, this.manifest.entry!);
const href = pathToFileURL(entry).href;
loadCounter += 1;
let mod: unknown;
try {
// A query string gives a fresh module instance after disable → enable.
mod = await withTimeout(import(`${href}?instance=${loadCounter}`), IN_PROCESS_TIMEOUTS.load, 'Loading the plugin');
} catch (err) {
const msg = (err as Error).message ?? '';
if (!/Cannot find (module|package)|ERR_MODULE_NOT_FOUND|not found/i.test(msg) || /Cannot find package/i.test(msg)) throw this.explainLoadError(err);
mod = await withTimeout(import(href), IN_PROCESS_TIMEOUTS.load, 'Loading the plugin').catch((e) => { throw this.explainLoadError(e); });
}
const m = mod as Partial<PluginModule> & { default?: Partial<PluginModule> };
const plugin = (typeof m.activate === 'function' ? m : m.default) as PluginModule | undefined;
if (!plugin || typeof plugin.activate !== 'function') throw new Error('The plugin module does not export an activate(ctx) function.');
this.module = plugin;
this.running = true;
try {
await withTimeout(Promise.resolve().then(() => plugin.activate(this.context())), IN_PROCESS_TIMEOUTS.activate, 'activate()');
} catch (err) {
await this.stop();
throw err;
}
const declared = this.manifest.contributes.tools.map((t) => t.name);
const missing = declared.filter((n) => !this.registered.has(`tool:${n}`));
if (missing.length > 0) this.deps.log.warn(`declared tools not registered by activate(): ${missing.join(', ')}`);
}
private explainLoadError(err: unknown): Error {
const msg = (err as Error)?.message ?? String(err);
if (/Cannot find package/i.test(msg)) {
return new Error(`${msg.split('\n')[0]}. In-process plugins must be bundled into a single file; Mercury can't resolve packages for them.`);
}
return err instanceof Error ? err : new Error(msg);
}
async stop(): Promise<void> {
const wasRunning = this.running;
this.running = false;
this.ac.abort(new Error('plugin stopped'));
if (wasRunning && this.module?.deactivate) {
try {
await withTimeout(Promise.resolve().then(() => this.module!.deactivate!()), IN_PROCESS_TIMEOUTS.deactivate, 'deactivate()');
} catch (err) {
this.deps.log.warn(`deactivate() failed: ${(err as Error).message}`);
}
}
const pending = this.disposables.splice(0).reverse();
for (const d of pending) {
try {
await withTimeout(Promise.resolve().then(d), IN_PROCESS_TIMEOUTS.dispose, 'cleanup');
} catch (err) {
this.deps.log.warn(`cleanup failed: ${(err as Error).message}`);
}
}
unpublishPlugin(this.manifest.id);
this.registered.clear();
this.module = null;
}
private track(fn: () => void | Promise<void>): Disposable {
let done = false;
const d = () => {
if (done) return;
done = true;
return fn();
};
this.disposables.push(d);
return { dispose: () => void d() };
}
/** Run plugin code from a timer or callback; failures count against the plugin instead of crashing us. */
private guard(fn: () => void | Promise<void>, where: string): void {
if (!this.running) return;
Promise.resolve()
.then(fn)
.catch((err) => this.deps.onError(`${where}: ${(err as Error)?.message ?? String(err)}`));
}
private context(): PluginContext {
const m = this.manifest;
const declaredTools = new Map(m.contributes.tools.map((t) => [t.name, t]));
const declaredCommands = new Map(m.contributes.commands.map((c) => [c.name, c]));
const declaredSecrets = new Set([
...m.permissions.secrets,
...(Object.keys(m.permissions.providers ?? {}) as PluginProviderId[]).flatMap((p) => Object.values(providerSecretNames(p))),
]);
const signal = this.ac.signal;
const register = (def: PluginToolDefinition): Disposable => {
if (!this.running) throw new Error('Plugin is not running.');
const decl = declaredTools.get(def?.name);
if (!decl) throw new Error(`Tool "${def?.name}" is not declared in mercury-plugin.json (contributes.tools).`);
if (typeof def.execute !== 'function') throw new Error(`Tool "${def.name}" has no execute function.`);
const schema = def.inputSchema ?? { type: 'object', properties: {} };
if (typeof schema !== 'object' || (schema as { type?: unknown }).type !== 'object') {
throw new Error(`Tool "${def.name}" needs an inputSchema with type "object".`);
}
const unpublish = publishTool({
pluginId: m.id,
pluginName: m.name,
name: decl.name,
description: decl.description,
...screenshotContract(schema, decl.screenshots),
readOnly: decl.readOnly,
timeoutMs: decl.timeoutMs,
invoke: async (args, toolSignal) => {
if (!this.running) throw new Error('the plugin is not running');
const combined = AbortSignal.any([toolSignal, signal]);
return def.execute(args, { signal: combined });
},
});
this.registered.add(`tool:${decl.name}`);
return this.track(() => {
unpublish();
this.registered.delete(`tool:${decl.name}`);
});
};
const registerCommand = (def: PluginCommandDefinition): Disposable => {
if (!this.running) throw new Error('Plugin is not running.');
const decl = declaredCommands.get(def?.name);
if (!decl) throw new Error(`Command "${def?.name}" is not declared in mercury-plugin.json (contributes.commands).`);
if (typeof def.run !== 'function') throw new Error(`Command "${def.name}" has no run function.`);
const unpublish = publishCommand({
pluginId: m.id,
pluginName: m.name,
name: decl.name,
description: decl.description,
run: async (args, io) => {
if (!this.running) throw new Error('the plugin is not running');
await def.run(args, { reply: io.reply, signal: AbortSignal.any([io.signal, signal]) });
},
});
this.registered.add(`command:${decl.name}`);
return this.track(() => {
unpublish();
this.registered.delete(`command:${decl.name}`);
});
};
const pluginFetch = async (url: string, init: RequestInit = {}): Promise<Response> => {
if (!this.running) throw new Error('Plugin is not running.');
let target = url;
const reqSignal = init.signal ? AbortSignal.any([init.signal, signal]) : signal;
for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
const parsed = new URL(target);
if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') throw new Error(`Only http(s) requests are allowed (got ${parsed.protocol}).`);
if (!hostAllowed(parsed.hostname, m.permissions.network)) {
throw new Error(`Network access to ${parsed.hostname} is not declared in this plugin's permissions.network.`);
}
await assertFetchableTarget(parsed.href);
const res = await fetch(parsed.href, { ...init, signal: reqSignal, redirect: 'manual' });
if (res.status >= 300 && res.status < 400 && res.headers.get('location')) {
try { void res.body?.cancel(); } catch { /* ignore */ }
target = new URL(res.headers.get('location')!, parsed).href;
continue;
}
return res;
}
throw new Error(`Too many redirects (more than ${MAX_REDIRECTS}).`);
};
const scoped = this.deps.log;
return Object.freeze({
apiVersion: PLUGIN_API_VERSION,
mercuryVersion: this.deps.mercuryVersion,
plugin: Object.freeze({ id: m.id, version: m.version, dataDir: this.deps.dataDir }),
log: Object.freeze({
debug: (msg: string, data?: Record<string, unknown>) => scoped.debug(msg, data),
info: (msg: string, data?: Record<string, unknown>) => scoped.info(msg, data),
warn: (msg: string, data?: Record<string, unknown>) => scoped.warn(msg, data),
error: (msg: string, data?: Record<string, unknown>) => scoped.error(msg, data),
}),
settings: Object.freeze({
get: <T,>(key: string) => this.deps.settings[key] as T | undefined,
all: () => ({ ...this.deps.settings }),
}),
secrets: Object.freeze({
get: (name: string) => (declaredSecrets.has(name) ? this.deps.secrets[name] : undefined),
}),
tools: Object.freeze({ register }),
commands: Object.freeze({ register: registerCommand }),
timers: Object.freeze({
setTimeout: (fn: () => void | Promise<void>, ms: number): Disposable => {
const h = setTimeout(() => this.guard(fn, 'timer'), Math.max(0, ms));
return this.track(() => clearTimeout(h));
},
setInterval: (fn: () => void | Promise<void>, ms: number): Disposable => {
const h = setInterval(() => this.guard(fn, 'interval'), Math.max(1000, ms));
return this.track(() => clearInterval(h));
},
}),
fetch: pluginFetch,
signal,
onDispose: (fn: () => void | Promise<void>) => {
this.track(fn);
},
}) as PluginContext;
}
}
export function inProcessLogger(pluginId: string): RuntimeDeps['log'] {
const child = logger.child({ plugin: pluginId });
return {
debug: (msg, data) => child.debug(data ?? {}, msg),
info: (msg, data) => child.info(data ?? {}, msg),
warn: (msg, data) => child.warn(data ?? {}, msg),
error: (msg, data) => child.error(data ?? {}, msg),
};
}