arcway 0.1.30 → 0.2.1

package/server/lib/vault/secrets.js

@@ -1,18 +1,11 @@
-import { createECDH, hkdfSync, randomBytes } from 'node:crypto';
+import { createECDH, createHash, hkdfSync, randomBytes } from 'node:crypto';
 
 const MASTER_VERSION = 'v1';
 const MASTER_BYTES = 32;
 const VAULT_KEY_BYTES = 32;
 const HKDF_SALT = 'arcway:infra-secrets:v1';
 
-const SECRET_NAMES = Object.freeze([
-  'session',
-  'plugin-vault',
-  'mcp-api',
-  'pty-api',
-  'pty-server-api',
-  'vapid',
-]);
+const SECRET_NAMES = Object.freeze(['session', 'plugin-vault', 'mcp-api', 'jwt']);
 
 function base64Url(buffer) {
   return Buffer.from(buffer).toString('base64url');
@@ -65,6 +58,13 @@ function deriveBytes(master, namespace, length = MASTER_BYTES) {
   return Buffer.from(hkdfSync('sha256', key, HKDF_SALT, `arcway:${namespace}`, length));
 }
 
+function deriveKey(master, label) {
+  if (!label || typeof label !== 'string') {
+    throw new Error('deriveKey label must be a non-empty string');
+  }
+  return base64Url(deriveBytes(master, `app:${label}`, MASTER_BYTES));
+}
+
 function formatVaultKey(bytes) {
   const key = Buffer.from(bytes);
   if (key.length !== VAULT_KEY_BYTES) {
@@ -77,11 +77,15 @@ function validateVaultKey(value, label = 'plugin-vault secret') {
   return formatVaultKey(decodeVersionedSecret(value, label));
 }
 
-function deriveVapidKeyPair(master) {
+function deriveKeyPair(master, label, { curve = 'prime256v1' } = {}) {
+  if (!label || typeof label !== 'string') {
+    throw new Error('deriveKeyPair label must be a non-empty string');
+  }
+
   for (let i = 0; i < 32; i += 1) {
-    const privateKey = deriveBytes(master, `vapid:private:${i}`, 32);
+    const privateKey = deriveBytes(master, `keypair:${curve}:${label}:private:${i}`, 32);
     try {
-      const ecdh = createECDH('prime256v1');
+      const ecdh = createECDH(curve);
       ecdh.setPrivateKey(privateKey);
       return {
         publicKey: base64Url(ecdh.getPublicKey(null, 'uncompressed')),
@@ -91,16 +95,14 @@ function deriveVapidKeyPair(master) {
       // Try the next deterministic candidate.
     }
   }
-  throw new Error('Unable to derive a valid deterministic VAPID keypair');
+  throw new Error(`Unable to derive a valid deterministic ${curve} keypair for label "${label}"`);
 }
 
 function deriveInfraSecret(master, name) {
   if (name === 'session') return base64Url(deriveBytes(master, name, 48));
   if (name === 'plugin-vault') return formatVaultKey(deriveBytes(master, name, VAULT_KEY_BYTES));
   if (name === 'mcp-api') return base64Url(deriveBytes(master, name, 48));
-  if (name === 'pty-api') return base64Url(deriveBytes(master, name, 48));
-  if (name === 'pty-server-api') return base64Url(deriveBytes(master, name, 48));
-  if (name === 'vapid') return deriveVapidKeyPair(master);
+  if (name === 'jwt') return base64Url(deriveBytes(master, name, 48));
   throw new Error(`Unknown Arcway infra secret namespace: ${name}`);
 }
 
@@ -112,6 +114,47 @@ function deriveInfraSecrets(master) {
   return values;
 }
 
+function normalizeMasterSecretRing(master) {
+  const masters = Array.isArray(master) ? master : [master];
+  const normalized = masters.filter(
+    (value) => value !== undefined && value !== null && value !== '',
+  );
+  if (normalized.length === 0) throw new Error('Arcway master secret keyring cannot be empty');
+  return normalized.map((value, index) =>
+    normalizeMasterSecret(value, `Arcway master secret keyring entry ${index + 1}`),
+  );
+}
+
+function stableSessionPasswordId(sessionSecret) {
+  const digest = createHash('sha256').update(`arcway:session-key-id:v1:${sessionSecret}`).digest();
+  const id = digest.readUIntBE(0, 6);
+  return String(id === 0 ? 1 : id);
+}
+
+function deriveInfraSecretRing(master) {
+  const masters = normalizeMasterSecretRing(master);
+  const entries = masters.map((value) => {
+    const secrets = deriveInfraSecrets(value);
+    return {
+      id: stableSessionPasswordId(secrets.session),
+      secrets,
+    };
+  });
+
+  const seenIds = new Set();
+  for (const entry of entries) {
+    if (seenIds.has(entry.id)) {
+      throw new Error('Derived session key ids collided; rotate with different master secrets');
+    }
+    seenIds.add(entry.id);
+  }
+
+  return {
+    entries,
+    active: entries.at(-1),
+  };
+}
+
 function decryptWithRotation(ciphertext, { current, previous, decrypt, encrypt, onRotate } = {}) {
   if (typeof decrypt !== 'function') throw new Error('decryptWithRotation requires decrypt');
   if (typeof encrypt !== 'function') throw new Error('decryptWithRotation requires encrypt');
@@ -138,12 +181,16 @@ function decryptWithRotation(ciphertext, { current, previous, decrypt, encrypt,
 export {
   SECRET_NAMES,
   decryptWithRotation,
+  deriveKey,
+  deriveKeyPair,
   deriveBytes,
   deriveInfraSecret,
+  deriveInfraSecretRing,
   deriveInfraSecrets,
-  deriveVapidKeyPair,
   encodeMasterSecret,
   formatVaultKey,
   normalizeMasterSecret,
+  normalizeMasterSecretRing,
+  stableSessionPasswordId,
   validateVaultKey,
 };

package/server/plugins/bundle.js

@@ -0,0 +1,122 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { build } from 'esbuild';
+import { discoverFiles } from '../discovery.js';
+import { loadModule } from '../module-loader.js';
+
+let bundleCounter = 0;
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+function importLine(name, filePath, namespace = true) {
+  const imported = namespace ? `* as ${name}` : name;
+  return `import ${imported} from ${JSON.stringify(filePath)};`;
+}
+
+function moduleEntry(name, entry) {
+  return `{ name: ${JSON.stringify(entry.name)}, filePath: ${JSON.stringify(entry.filePath)}, relativePath: ${JSON.stringify(entry.relativePath)}, module: ${name} }`;
+}
+
+async function loadPluginBundle(packageDir) {
+  const bundleDir = path.join(packageDir, '.arcway', 'plugin-bundles');
+  await fs.mkdir(bundleDir, { recursive: true });
+
+  const pluginJs = path.join(packageDir, 'plugin.js');
+  const exportsJs = path.join(packageDir, 'exports.js');
+  const routesDir = path.join(packageDir, 'routes');
+  const jobsDir = path.join(packageDir, 'jobs');
+  const capabilitiesDir = path.join(packageDir, 'capabilities');
+  const hooksDir = path.join(packageDir, 'hooks');
+
+  const hasPluginJs = await exists(pluginJs);
+  const hasExportsJs = await exists(exportsJs);
+  const routes = await discoverFiles(routesDir, { recursive: true });
+  const jobs = await discoverFiles(jobsDir, { recursive: true });
+  const capabilities = await discoverFiles(capabilitiesDir);
+  const hooks = await discoverFiles(hooksDir);
+
+  const lines = [];
+  if (hasPluginJs) lines.push(importLine('pluginModule', pluginJs));
+  if (hasExportsJs) lines.push(importLine('pluginExports', exportsJs, false));
+
+  for (const [index, entry] of routes.entries()) {
+    lines.push(importLine(`route${index}`, entry.filePath));
+  }
+  for (const [index, entry] of jobs.entries()) {
+    lines.push(importLine(`job${index}`, entry.filePath));
+  }
+  for (const [index, entry] of capabilities.entries()) {
+    lines.push(importLine(`capability${index}`, entry.filePath, false));
+  }
+  for (const [index, entry] of hooks.entries()) {
+    lines.push(importLine(`hook${index}`, entry.filePath, false));
+  }
+
+  lines.push(`export const module = ${hasPluginJs ? 'pluginModule' : '{}'};`);
+  lines.push(
+    `export const exportsModule = ${hasExportsJs ? '{ default: pluginExports }' : 'null'};`,
+  );
+  lines.push(
+    `export const routes = [${routes.map((entry, index) => moduleEntry(`route${index}`, entry)).join(',')}];`,
+  );
+  lines.push(
+    `export const jobs = [${jobs.map((entry, index) => moduleEntry(`job${index}`, entry)).join(',')}];`,
+  );
+  lines.push(
+    `export const capabilities = {${capabilities
+      .map((entry, index) => {
+        const name = path.basename(entry.name, path.extname(entry.name));
+        return `${JSON.stringify(name)}: capability${index}`;
+      })
+      .join(',')}};`,
+  );
+  lines.push(
+    `export const hooks = {${hooks
+      .map((entry, index) => {
+        const name = path.basename(entry.name, path.extname(entry.name));
+        return `${JSON.stringify(name)}: hook${index}`;
+      })
+      .join(',')}};`,
+  );
+
+  const counter = ++bundleCounter;
+  const entryPath = path.join(bundleDir, `entry-${counter}.mjs`);
+  const outFile = path.join(bundleDir, `bundle-${counter}.mjs`);
+  await fs.writeFile(entryPath, lines.join('\n'));
+
+  await build({
+    entryPoints: [entryPath],
+    outfile: outFile,
+    bundle: true,
+    format: 'esm',
+    platform: 'node',
+    target: 'node20',
+    logLevel: 'silent',
+  });
+
+  const bundled = await loadModule(outFile);
+  return {
+    module: bundled.module ?? {},
+    exportsModule: bundled.exportsModule ?? null,
+    routes: bundled.routes ?? [],
+    jobs: bundled.jobs ?? [],
+    capabilities: bundled.capabilities ?? {},
+    hooks: bundled.hooks ?? {},
+    artifact: outFile,
+  };
+}
+
+function fileUrl(filePath) {
+  return pathToFileURL(filePath).href;
+}
+
+export { fileUrl, loadPluginBundle };

package/server/plugins/discovery.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { discoverModules, discoverPackageDirectories } from '../discovery.js';
 import { loadModule } from '../module-loader.js';
 import { validateManifest } from './manifest.js';
+import { loadPluginBundle } from './bundle.js';
 
 async function exists(filePath) {
   try {
@@ -30,6 +31,23 @@ function getManifest(module, manifestPath) {
   return manifest;
 }
 
+function assertPlainObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${label} must export an object`);
+  }
+}
+
+function getExports(module, exportsPath) {
+  const exported = module.default;
+  assertPlainObject(exported, `Plugin exports at ${exportsPath}`);
+  for (const [name, value] of Object.entries(exported)) {
+    if (typeof value !== 'function') {
+      throw new Error(`Plugin export ${name} at ${exportsPath} must be a function`);
+    }
+  }
+  return { ...exported };
+}
+
 // Load every `<dir>/<name>.js` and key the default export by file basename.
 // Used for the capabilities/ and hooks/ folder conventions.
 async function loadConventionModules(dir, label) {
@@ -43,7 +61,7 @@ async function loadConventionModules(dir, label) {
   return map;
 }
 
-async function loadPluginPackage(packageDir) {
+async function loadPluginPackage(packageDir, { bundle = false } = {}) {
   const packageJsonPath = path.join(packageDir, 'package.json');
   if (!(await exists(packageJsonPath))) {
     throw new Error(`Plugin package at ${packageDir} must include package.json`);
@@ -52,13 +70,20 @@ async function loadPluginPackage(packageDir) {
 
   const pluginJs = path.join(packageDir, 'plugin.js');
   const pluginJson = path.join(packageDir, 'plugin.json');
+  const exportsJs = path.join(packageDir, 'exports.js');
   let manifestPath;
   let module = {};
+  let bundled = null;
   let rawManifest;
 
   if (await exists(pluginJs)) {
     manifestPath = pluginJs;
-    module = await loadModule(pluginJs, import.meta.url);
+    if (bundle) {
+      bundled = await loadPluginBundle(packageDir);
+      module = bundled.module;
+    } else {
+      module = await loadModule(pluginJs, import.meta.url);
+    }
     rawManifest = getManifest(module, pluginJs);
   } else if (await exists(pluginJson)) {
     manifestPath = pluginJson;
@@ -88,6 +113,12 @@ async function loadPluginPackage(packageDir) {
 
   const routesDir = path.join(packageDir, 'routes');
   const jobsDir = path.join(packageDir, 'jobs');
+  if (bundle && !bundled) bundled = await loadPluginBundle(packageDir);
+  const exportsModule = bundled
+    ? bundled.exportsModule
+    : (await exists(exportsJs))
+      ? await loadModule(exportsJs, import.meta.url)
+      : null;
 
   return {
     id: manifest.id,
@@ -95,15 +126,23 @@ async function loadPluginPackage(packageDir) {
     packageJson,
     manifest,
     module,
+    bundle: bundled ? { artifact: bundled.artifact } : null,
     manifestPath,
+    exports: exportsModule ? getExports(exportsModule, exportsJs) : {},
     routesDir: (await exists(routesDir)) ? routesDir : null,
     jobsDir: (await exists(jobsDir)) ? jobsDir : null,
-    capabilities: await loadConventionModules(path.join(packageDir, 'capabilities'), 'capability'),
-    hooks: await loadConventionModules(path.join(packageDir, 'hooks'), 'lifecycle hook'),
+    bundledRoutes: bundled?.routes ?? null,
+    bundledJobs: bundled?.jobs ?? null,
+    capabilities:
+      bundled?.capabilities ??
+      (await loadConventionModules(path.join(packageDir, 'capabilities'), 'capability')),
+    hooks:
+      bundled?.hooks ??
+      (await loadConventionModules(path.join(packageDir, 'hooks'), 'lifecycle hook')),
   };
 }
 
-async function discoverPlugins(dirs) {
+async function discoverPlugins(dirs, options = {}) {
   const plugins = [];
   const seen = new Map();
 
@@ -113,7 +152,7 @@ async function discoverPlugins(dirs) {
       label: 'plugin',
     });
     for (const entry of packages) {
-      const plugin = await loadPluginPackage(entry.dir);
+      const plugin = await loadPluginPackage(entry.dir, options);
       if (!plugin) continue;
       if (seen.has(plugin.id)) {
         throw new Error(

package/server/plugins/graph.js

@@ -18,29 +18,43 @@ function buildProviderMap(plugins) {
 function resolvePluginGraph(plugins, enabledIds) {
   const allProviders = buildProviderMap(plugins);
   const byId = new Map(plugins.map((plugin) => [plugin.id, plugin]));
-  const enabled = new Set(enabledIds);
+  const enabled = new Set([...enabledIds].map((id) => String(id)));
   const missing = [];
   const edges = new Map();
 
   for (const plugin of plugins) {
-    edges.set(plugin.id, new Set());
-    if (!enabled.has(plugin.id)) continue;
+    const pluginId = String(plugin.id);
+    edges.set(pluginId, new Set());
+  }
+
+  for (const plugin of plugins) {
+    const pluginId = String(plugin.id);
+    if (!enabled.has(pluginId)) continue;
     for (const capability of requiredCapabilities(plugin.manifest.requires)) {
       const provider = allProviders.get(capability);
       if (!provider) {
-        missing.push({ pluginId: plugin.id, capability, reason: 'missing provider' });
+        missing.push({ pluginId, capability, reason: 'missing provider' });
         continue;
       }
-      if (!enabled.has(provider.id)) {
+      const providerId = String(provider.id);
+      if (!enabled.has(providerId)) {
         missing.push({
-          pluginId: plugin.id,
+          pluginId,
           capability,
-          providerId: provider.id,
+          providerId,
           reason: 'provider disabled',
         });
         continue;
       }
-      if (provider.id !== plugin.id) edges.get(provider.id).add(plugin.id);
+      if (providerId !== pluginId) {
+        const providerEdges = edges.get(providerId);
+        if (!providerEdges) {
+          throw new Error(
+            `Plugin ${pluginId} requires capability ${capability} from unknown provider ${providerId}`,
+          );
+        }
+        providerEdges.add(pluginId);
+      }
     }
   }
 

package/server/plugins/manager.js

@@ -1,5 +1,6 @@
-import { discoverRoutes } from '../router/routes.js';
-import { discoverJobs } from '../jobs/runner.js';
+import path from 'node:path';
+import { buildRoutesFromModules, discoverRoutes } from '../router/routes.js';
+import { buildJobsFromModules, discoverJobs } from '../jobs/runner.js';
 import { CapabilityRegistry } from './capabilities.js';
 import { discoverPlugins } from './discovery.js';
 import { buildProviderMap, cascadeDisabled, resolvePluginGraph } from './graph.js';
@@ -14,7 +15,7 @@ function pluginEnabledByDefault(plugin, enablements) {
   if (Object.prototype.hasOwnProperty.call(enablements, plugin.id)) {
     return enablements[plugin.id] === true;
   }
-  return plugin.manifest.defaultEnabled === true;
+  return plugin.manifest.enabled !== false;
 }
 
 function capabilityFactory(plugin, capability) {
@@ -26,11 +27,64 @@ function capabilityFactory(plugin, capability) {
   );
 }
 
+function collectDependentIds(plugins, ids) {
+  const affected = new Set(ids);
+  const providers = buildProviderMap(plugins);
+  let changed = true;
+
+  while (changed) {
+    changed = false;
+    for (const plugin of plugins) {
+      if (affected.has(plugin.id)) continue;
+      for (const capability of requiredCapabilities(plugin.manifest.requires)) {
+        const provider = providers.get(capability);
+        if (provider && affected.has(provider.id)) {
+          affected.add(plugin.id);
+          changed = true;
+          break;
+        }
+      }
+    }
+  }
+
+  return affected;
+}
+
+function bindPluginExports(plugin, ctx) {
+  return new Proxy(
+    {},
+    {
+      get(_target, prop) {
+        if (typeof prop === 'symbol') return undefined;
+        if (prop === 'then') return undefined;
+
+        const fn = plugin.exports?.[prop];
+        if (!fn) {
+          throw new Error(`Plugin ${plugin.id} does not export function ${prop}`);
+        }
+        return (...args) => fn(ctx, ...args);
+      },
+      has(_target, prop) {
+        return typeof prop === 'string' && Object.hasOwn(plugin.exports ?? {}, prop);
+      },
+      ownKeys() {
+        return Object.keys(plugin.exports ?? {});
+      },
+      getOwnPropertyDescriptor(_target, prop) {
+        if (typeof prop !== 'string' || !Object.hasOwn(plugin.exports ?? {}, prop))
+          return undefined;
+        return { enumerable: true, configurable: true };
+      },
+    },
+  );
+}
+
 class PluginManager {
-  constructor(config, { log, runLifecycle = true } = {}) {
+  constructor(config, { log, runLifecycle = true, bundle = false } = {}) {
     this.config = config ?? { enabled: false, dirs: [] };
     this.log = log;
     this.runLifecycle = runLifecycle;
+    this.bundle = bundle;
     this.plugins = [];
     this.enabled = new Set();
     this.status = new Map();
@@ -41,7 +95,7 @@ class PluginManager {
   async init() {
     if (this.config.enabled !== true) return this;
 
-    this.plugins = await discoverPlugins(this.config.dirs);
+    this.plugins = await discoverPlugins(this.config.dirs, { bundle: this.bundle });
     const enablements = configuredEnablements(this.config);
     this.enabled = new Set(
       this.plugins
@@ -97,17 +151,36 @@ class PluginManager {
     return this.capabilities.inject(ctx, requires);
   }
 
+  exportsFor(id, ctx) {
+    const plugin = this.getPlugin(id);
+    if (!plugin) throw new Error(`Unknown plugin: ${id}`);
+    if (this.status.get(plugin.id) !== 'enabled') {
+      throw new Error(`Plugin ${plugin.id} is not enabled`);
+    }
+    return bindPluginExports(plugin, ctx);
+  }
+
+  buildContextProxy(ctx) {
+    return {
+      get: (id) => this.exportsFor(id, ctx),
+    };
+  }
+
   async discoverRoutes() {
     const routes = [];
     for (const plugin of this.enabledPlugins) {
-      if (!plugin.routesDir) continue;
-      const discovered = await discoverRoutes(plugin.routesDir, {
-        prefix: `/plugins/${plugin.id}`,
+      const routeOptions = {
+        prefix: `/_plugins/${plugin.id}`,
         plugin: {
           id: plugin.id,
           requires: plugin.manifest.requires,
         },
-      });
+      };
+      const discovered = plugin.bundledRoutes
+        ? buildRoutesFromModules(plugin.bundledRoutes, routeOptions)
+        : plugin.routesDir
+          ? await discoverRoutes(plugin.routesDir, routeOptions)
+          : [];
       routes.push(...discovered);
     }
     return routes;
@@ -116,8 +189,11 @@ class PluginManager {
   async discoverJobs() {
     const jobs = [];
     for (const plugin of this.enabledPlugins) {
-      if (!plugin.jobsDir) continue;
-      const discovered = await discoverJobs(plugin.jobsDir);
+      const discovered = plugin.bundledJobs
+        ? buildJobsFromModules(plugin.bundledJobs)
+        : plugin.jobsDir
+          ? await discoverJobs(plugin.jobsDir)
+          : [];
       for (const job of discovered) {
         const definition = {
           ...job.definition,
@@ -133,6 +209,115 @@ class PluginManager {
     return jobs;
   }
 
+  async reload(ids) {
+    if (this.config.enabled !== true) return { reloaded: [] };
+
+    const requested = ids ? new Set(Array.isArray(ids) ? ids : [ids]) : null;
+    const oldPlugins = this.plugins;
+    const oldEnabledIds = new Set(
+      oldPlugins
+        .filter((plugin) => this.status.get(plugin.id) === 'enabled')
+        .map((plugin) => plugin.id),
+    );
+    let affected = requested ? collectDependentIds(oldPlugins, requested) : new Set();
+
+    const discovered = await discoverPlugins(this.config.dirs, { bundle: this.bundle });
+    const discoveredIds = new Set(discovered.map((plugin) => plugin.id));
+    const enablements = configuredEnablements(this.config);
+    const nextEnabled = new Set();
+    for (const plugin of discovered) {
+      if (
+        this.enabled.has(plugin.id) ||
+        (!oldPlugins.some((old) => old.id === plugin.id) &&
+          pluginEnabledByDefault(plugin, enablements))
+      ) {
+        nextEnabled.add(plugin.id);
+      }
+    }
+
+    if (!requested) {
+      affected = new Set([...oldPlugins.map((plugin) => plugin.id), ...discoveredIds]);
+    } else {
+      for (const id of requested) {
+        if (!discoveredIds.has(id) && !oldPlugins.some((plugin) => plugin.id === id)) {
+          affected = new Set([...oldPlugins.map((plugin) => plugin.id), ...discoveredIds]);
+          break;
+        }
+      }
+      affected = collectDependentIds(discovered, affected);
+    }
+
+    const oldAffectedEnabled = [...this.loadOrder]
+      .filter((plugin) => affected.has(plugin.id) && oldEnabledIds.has(plugin.id))
+      .reverse();
+    for (const plugin of oldAffectedEnabled) {
+      if (this.runLifecycle) await this.#runLifecycle(plugin, 'onDisable');
+    }
+
+    this.plugins = discovered;
+    this.enabled = nextEnabled;
+    this.#rebuildGraph();
+
+    for (const plugin of this.loadOrder) {
+      if (!affected.has(plugin.id)) continue;
+      if (this.runLifecycle) {
+        await this.#runLifecycle(plugin, 'onLoad');
+        await this.#runLifecycle(plugin, 'onEnable');
+      }
+      this.log?.info?.(`Plugin reloaded: ${plugin.id}`);
+    }
+
+    return {
+      reloaded: [...affected].filter((id) => discoveredIds.has(id)),
+      removed: [...affected].filter((id) => !discoveredIds.has(id)),
+    };
+  }
+
+  pluginIdsForChangedFiles(events) {
+    const ids = new Set();
+    for (const event of events) {
+      const filePath = event.path;
+      const existing = this.plugins.find(
+        (plugin) => filePath === plugin.dir || filePath.startsWith(plugin.dir + path.sep),
+      );
+      if (existing) {
+        ids.add(existing.id);
+        continue;
+      }
+
+      const rootDir = (this.config.dirs ?? []).find((dir) => {
+        const relative = path.relative(dir, filePath);
+        return relative && !relative.startsWith('..') && !path.isAbsolute(relative);
+      });
+      if (!rootDir) continue;
+      const [packageDirName] = path.relative(rootDir, filePath).split(path.sep);
+      if (!packageDirName) continue;
+      if (!this.plugins.some((plugin) => plugin.id === packageDirName)) return null;
+      ids.add(packageDirName);
+    }
+    return ids;
+  }
+
+  watch(fileWatcher, { apiRouter, jobRunner } = {}) {
+    if (this.config.enabled !== true || !fileWatcher) return;
+    fileWatcher.subscribe('plugins', {
+      dirs: this.config.dirs,
+      extensions: ['.js', '.json'],
+      debounceMs: 200,
+      onChange: async (events) => {
+        const changedIds = this.pluginIdsForChangedFiles(events);
+        await this.reload(changedIds);
+        await apiRouter?.reload?.();
+        await jobRunner?.reload?.();
+      },
+    });
+    this.log?.info?.('Plugins: watching for changes');
+  }
+
+  unwatch(fileWatcher) {
+    fileWatcher?.unsubscribe?.('plugins');
+  }
+
   #rebuildGraph() {
     const providers = buildProviderMap(this.plugins);
     for (const plugin of this.plugins) {