@vellumai/assistant 0.10.2-dev.202606250318.5e7cfb0 → 0.10.2

package/src/plugins/mtime-cache.ts

@@ -1,42 +1,32 @@
 /**
- * Per-surface mtime cache for user plugins (discovery + tools).
+ * Per-surface mtime cache for user plugins.
  *
- * Instead of caching whole `Plugin` objects, the user-plugin system caches
- * individual surfaces keyed by their source file's mtime. This module owns
- * plugin **discovery** (which plugin directories exist, in what order) and the
- * **tool** cache; the **hook** cache and every hook operation live in
- * `../hooks/hook-loader.ts`. This module is the boot orchestrator: it scans the
- * plugins directory, registers tools, and drives hook pre-import / init /
- * shutdown by handing the discovered directories to the hook loader.
+ * Instead of caching whole `Plugin` objects, this module caches individual
+ * hooks and tools keyed by their source file's mtime. This means:
  *
- * - A changed tool file triggers a re-import of just that tool, not a full
- *   plugin rebuild. Added and removed surface files are picked up live, since
- *   discovery is by directory listing.
- * - Plugins are never "registered" as a unit — we register their tools into
- *   the global tool registry and cache-bust them using mtime on reads.
+ * - A changed hook file triggers a re-import of just that hook, not a full
+ *   plugin rebuild.
+ * - The same machinery extends to workspace-driven hooks and tools in the
+ *   future (PR B), since each surface is cached independently.
+ * - Plugins are never "registered" as a unit — we just register their tools
+ *   and hooks into the global registries, then cache-bust them using mtime
+ *   on reads.
  *
  * The cache is populated at boot by `loadUserPlugins()` and read on every
- * `getHooksFor` / `getAllTools` call.
+ * `getHooksFor` / `getAllTools` call. When a surface file's mtime changes,
+ * the next read detects the mismatch, re-imports the file, and swaps the
+ * cached entry.
  */
 
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 
+import { getConfig } from "../config/loader.js";
 import { registerShutdownHook } from "../daemon/shutdown-registry.js";
-import {
-  clearPluginHooks,
-  collectUserHooks,
-  evictHooksForOwner,
-  hasWorkspaceHooks,
-  preImportHooksDir,
-  preImportWorkspaceHooks,
-  resetHookCacheForTests,
-  runInitHook,
-  runShutdownHook,
-  WORKSPACE_HOOKS_OWNER,
-} from "../hooks/hook-loader.js";
+import { HOOKS } from "../plugin-api/constants.js";
 import type {
   PluginHookFn,
+  PluginInitContext,
   PluginShutdownContext,
 } from "../plugin-api/types.js";
 import {
@@ -46,19 +36,14 @@ import {
 import { finalizeTool } from "../tools/tool-defaults.js";
 import type { Tool, ToolDefinition } from "../tools/types.js";
 import { getLogger } from "../util/logger.js";
-import { getWorkspacePluginsDir } from "../util/platform.js";
+import { getWorkspaceDir, getWorkspacePluginsDir } from "../util/platform.js";
 import { APP_VERSION } from "../version.js";
 import {
   deriveToolName,
+  importDefault,
   listSurfaceDir,
   parsePluginManifest,
 } from "./external-plugin-loader.js";
-import {
-  clearSurfaceImportInflight,
-  getMtime,
-  importWithTimeout,
-  setSurfaceImportTimeout,
-} from "./surface-import.js";
 
 // Re-export for type compat — consumers that import PluginHookFn from
 // the mtime cache module still resolve.
@@ -66,6 +51,13 @@ export type { PluginHookFn } from "./types.js";
 
 const log = getLogger("plugin-mtime-cache");
 
+/**
+ * Import timeout for surface file imports. Set by `populateCacheAtBoot` from
+ * the value passed by `loadUserPlugins`, and used by `getUserHooksFor` and
+ * `reconcilePluginTools` for runtime re-imports. Defaults to 10s.
+ */
+let importTimeoutMs = 10_000;
+
 /**
  * Cached install-date timestamps per plugin directory, so `scanPlugins`
  * doesn't re-read `install-meta.json` on every turn. Populated on first
@@ -138,6 +130,16 @@ function getInstallDate(pluginDir: string): number {
 
 // ─── Cache entries ───────────────────────────────────────────────────────────
 
+/**
+ * A cached hook function plus the mtime of its source file. When the on-disk
+ * mtime changes, the hook is re-imported and the entry is replaced.
+ */
+interface CachedHook {
+  readonly hook: PluginHookFn;
+  /** mtimeMs of the source file this hook was imported from. */
+  readonly sourceMtime: number;
+}
+
 /**
  * A cached tool plus the mtime of its source file. When the on-disk mtime
  * changes, the tool is re-imported, the old tool is unregistered from the
@@ -153,12 +155,25 @@ interface CachedTool {
 
 // ─── Internal state ──────────────────────────────────────────────────────────
 
+/**
+ * Cached hooks keyed by `${pluginName}/${hookName}`. The key includes the
+ * plugin name so hooks from different plugins don't collide.
+ */
+const hookCache = new Map<string, CachedHook>();
+
 /**
  * Cached tools keyed by `${pluginName}/${toolName}`. The key includes the
  * plugin name so tools from different plugins don't collide.
  */
 const toolCache = new Map<string, CachedTool>();
 
+/**
+ * In-flight import promises, keyed by file path. Prevents duplicate
+ * `import()` calls when multiple readers request the same surface
+ * concurrently.
+ */
+const inflight = new Map<string, Promise<unknown>>();
+
 /**
  * Plugin directories discovered at boot, in discovery order. Maps directory
  * path to the plugin's scope-stripped manifest name so eviction can find
@@ -174,19 +189,94 @@ const discoveredPluginDirs = new Map<string, string>();
  */
 const disabledPluginDirs = new Set<string>();
 
-// ─── Hook reads ──────────────────────────────────────────────────────────────
+// ─── Mtime helpers ───────────────────────────────────────────────────────────
 
 /**
- * Get all hooks for a given event name from user plugins and standalone
- * workspace hooks. Refreshes plugin discovery first, then delegates the actual
- * hook resolution to the hook loader. Plugin hooks run in install-date order,
- * the workspace hook runs last.
+ * Get the mtimeMs of a file, or 0 if the file doesn't exist or can't be
+ * stat'd.
+ */
+function getMtime(filePath: string): number {
+  try {
+    return statSync(filePath).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+// ─── Hook cache ──────────────────────────────────────────────────────────────
+
+/**
+ * Cache key for a hook: `${pluginName}/${hookName}`.
+ */
+function hookKey(pluginName: string, hookName: string): string {
+  return `${pluginName}/${hookName}`;
+}
+
+/**
+ * Get all hooks for a given event name from user plugins, re-importing
+ * any whose source files have changed since the cache was populated.
+ *
+ * Also scans for newly added plugins and hooks (via directory listing).
+ * Deleted plugins/hooks are skipped naturally (their directories/files
+ * no longer appear in the listing).
  */
 export async function getUserHooksFor<TCtx = unknown>(
   hookName: string,
 ): Promise<PluginHookFn<TCtx>[]> {
   await scanPlugins();
-  return collectUserHooks<TCtx>(hookName, discoveredPluginDirs);
+
+  const out: PluginHookFn<TCtx>[] = [];
+
+  for (const [pluginDir, pluginName] of discoveredPluginDirs) {
+    const hooksDir = join(pluginDir, "hooks");
+    const surfaceFiles = listSurfaceDir(hooksDir);
+    const hookFile = surfaceFiles.find((f) => f.name === hookName);
+    if (hookFile === undefined) continue;
+
+    const key = hookKey(pluginName, hookName);
+    const currentMtime = getMtime(hookFile.path);
+
+    // Cache hit — same mtime.
+    const cached = hookCache.get(key);
+    if (
+      cached !== undefined &&
+      cached.sourceMtime === currentMtime &&
+      currentMtime > 0
+    ) {
+      out.push(cached.hook as PluginHookFn<TCtx>);
+      continue;
+    }
+
+    // Cache miss — re-import.
+    if (currentMtime === 0) {
+      // File was deleted — evict cache entry.
+      hookCache.delete(key);
+      continue;
+    }
+
+    try {
+      const hook = await importWithTimeout<PluginHookFn>(
+        hookFile.path,
+        importTimeoutMs,
+      );
+      if (hook === undefined || typeof hook !== "function") {
+        log.error(
+          { plugin: pluginName, hook: hookName, path: hookFile.path },
+          `hook ${hookName} default export must be a function (got ${typeof hook}) — skipping`,
+        );
+        continue;
+      }
+      hookCache.set(key, { hook, sourceMtime: currentMtime });
+      out.push(hook as PluginHookFn<TCtx>);
+    } catch (err) {
+      log.error(
+        { err, plugin: pluginName, hook: hookName, path: hookFile.path },
+        `Failed to import hook ${hookName} from ${hookFile.path}`,
+      );
+    }
+  }
+
+  return out;
 }
 
 // ─── Tool cache ──────────────────────────────────────────────────────────────
@@ -236,7 +326,10 @@ async function reconcilePluginTools(
     }
 
     try {
-      const toolSpec = await importWithTimeout<ToolDefinition>(file.path);
+      const toolSpec = await importWithTimeout<ToolDefinition>(
+        file.path,
+        importTimeoutMs,
+      );
       if (
         toolSpec === undefined ||
         toolSpec === null ||
@@ -377,13 +470,17 @@ async function evictPlugin(
   pluginDir: string,
   pluginName: string,
 ): Promise<void> {
-  // Evict hooks (owned by the hook loader).
-  evictHooksForOwner(pluginName);
+  // Evict hooks.
+  const hookPrefix = `${pluginName}/`;
+  for (const key of hookCache.keys()) {
+    if (key.startsWith(hookPrefix)) {
+      hookCache.delete(key);
+    }
+  }
 
   // Evict tools.
-  const toolPrefix = `${pluginName}/`;
   for (const key of toolCache.keys()) {
-    if (key.startsWith(toolPrefix)) {
+    if (key.startsWith(hookPrefix)) {
       toolCache.delete(key);
     }
   }
@@ -397,30 +494,83 @@ async function evictPlugin(
 }
 
 /**
- * Evict all plugin-owned cache entries (when the plugins directory is gone
- * entirely). Standalone workspace hooks are preserved by the hook loader:
- * they live outside the plugins directory, so the absence of any plugin must
- * not evict them.
+ * Evict all cache entries (when the plugins directory is gone entirely).
  */
 async function evictAll(): Promise<void> {
-  clearPluginHooks();
+  hookCache.clear();
   toolCache.clear();
   discoveredPluginDirs.clear();
   installDateCache.clear();
   disabledPluginDirs.clear();
 }
 
+// ─── Import dedup ────────────────────────────────────────────────────────────
+
+/**
+ * Import a module's default export with a timeout. If the import doesn't
+ * resolve within `timeoutMs`, logs a warning and returns `undefined` so
+ * a hanging plugin module doesn't block daemon startup indefinitely.
+ */
+async function importWithTimeout<T>(
+  filePath: string,
+  timeoutMs: number,
+): Promise<T | undefined> {
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timeoutSentinel = Symbol("import-timeout");
+    const importPromise = importWithDedup<T>(filePath);
+    const timeoutPromise = new Promise<typeof timeoutSentinel>((resolve) => {
+      timeoutHandle = setTimeout(() => resolve(timeoutSentinel), timeoutMs);
+    });
+    const result = await Promise.race([importPromise, timeoutPromise]);
+    if (result === timeoutSentinel) {
+      importPromise.catch(() => {
+        /* swallow — late rejection from abandoned import */
+      });
+      log.warn(
+        { filePath, timeoutMs },
+        `Import timed out after ${timeoutMs}ms — skipping surface`,
+      );
+      return undefined;
+    }
+    return result as T;
+  } finally {
+    if (timeoutHandle !== undefined) clearTimeout(timeoutHandle);
+  }
+}
+
+/**
+ * Import a module's default export, deduplicating concurrent imports for
+ * the same file path. This prevents two readers from triggering duplicate
+ * `import()` calls when they request the same surface simultaneously.
+ *
+ * Note: Bun caches `import()` by URL within a process, so the dedup is
+ * primarily about avoiding redundant async work, not about cache-busting.
+ */
+async function importWithDedup<T>(filePath: string): Promise<T> {
+  let promise = inflight.get(filePath);
+  if (promise === undefined) {
+    promise = importDefault<T>(filePath);
+    inflight.set(filePath, promise);
+  }
+  try {
+    return (await promise) as T;
+  } finally {
+    inflight.delete(filePath);
+  }
+}
+
 // ─── Boot population ─────────────────────────────────────────────────────────
 
 /**
- * Plugins (and the workspace-hooks pseudo-owner) that were fully activated at
- * boot (tools registered + init hook run). Used by the shutdown hook to tear
- * down only what was actually brought up.
+ * Plugins that were fully activated at boot (tools registered + init hook
+ * run). Used by the shutdown hook to tear down only what was actually
+ * brought up.
  */
 const activatedPlugins: Array<{ name: string }> = [];
 
 /**
- * Populate the caches at boot by scanning the plugins directory once,
+ * Populate the cache at boot by scanning the plugins directory once,
  * importing all surfaces, registering tools into the tool registry,
  * running `init` hooks, and installing a shutdown hook.
  *
@@ -437,7 +587,7 @@ export async function populateCacheAtBoot(
   opts: { importTimeoutMs?: number } = {},
 ): Promise<void> {
   if (opts.importTimeoutMs !== undefined) {
-    setSurfaceImportTimeout(opts.importTimeoutMs);
+    importTimeoutMs = opts.importTimeoutMs;
   }
 
   await scanPlugins();
@@ -448,7 +598,28 @@ export async function populateCacheAtBoot(
 
   for (const [pluginDir, pluginName] of discoveredPluginDirs) {
     // Pre-import all hooks so the first turn doesn't pay the import cost.
-    await preImportHooksDir(join(pluginDir, "hooks"), pluginName);
+    const hooksDir = join(pluginDir, "hooks");
+    const hookFiles = listSurfaceDir(hooksDir);
+    for (const file of hookFiles) {
+      const key = hookKey(pluginName, file.name);
+      const currentMtime = getMtime(file.path);
+      if (currentMtime === 0) continue;
+
+      try {
+        const hook = await importWithTimeout<PluginHookFn>(
+          file.path,
+          importTimeoutMs,
+        );
+        if (hook !== undefined && typeof hook === "function") {
+          hookCache.set(key, { hook, sourceMtime: currentMtime });
+        }
+      } catch (err) {
+        log.error(
+          { err, plugin: pluginName, hook: file.name, path: file.path },
+          `Failed to pre-import hook ${file.name}`,
+        );
+      }
+    }
 
     // Register user plugin tools into the global tool registry so
     // `getAllTools()` and `getTool()` can find them. Tools were already
@@ -472,33 +643,38 @@ export async function populateCacheAtBoot(
     }
 
     // Run the `init` hook if present.
-    await runInitHook(pluginName);
+    const initHookEntry = hookCache.get(hookKey(pluginName, HOOKS.INIT));
+    if (initHookEntry !== undefined) {
+      try {
+        const initContext: PluginInitContext = {
+          config: getConfig().plugins?.[pluginName],
+          credentials: {},
+          logger: log.child({ plugin: pluginName }),
+          pluginStorageDir: ensurePluginStorageDir(pluginName),
+          assistantVersion: APP_VERSION,
+        };
+        await initHookEntry.hook(initContext);
+        log.info({ plugin: pluginName }, "user plugin initialized");
+      } catch (err) {
+        log.error(
+          { err, plugin: pluginName },
+          `User plugin ${pluginName} init() failed — continuing`,
+        );
+      }
+    }
 
     activatedPlugins.push({ name: pluginName });
   }
 
-  // Activate standalone workspace hooks under `<workspace>/hooks/`. These
-  // carry no package.json, no tools, and no install-date ordering — just hook
-  // files. Pre-import them and run their `init` hook so a workspace-wide
-  // `init`/`shutdown` lifecycle works the same way a plugin's does. Only
-  // register for teardown when at least one hook file is actually present, so
-  // an empty/absent directory adds no shutdown work.
-  if (hasWorkspaceHooks()) {
-    await preImportWorkspaceHooks();
-    await runInitHook(WORKSPACE_HOOKS_OWNER);
-    activatedPlugins.push({ name: WORKSPACE_HOOKS_OWNER });
-  }
-
-  // Register a single shutdown hook that walks all activated owners in reverse
-  // order, unregistering tools and running shutdown hooks.
+  // Register a single shutdown hook that walks all activated user plugins
+  // in reverse order, unregistering tools and running shutdown hooks.
   const shutdownSnapshot = [...activatedPlugins];
   registerShutdownHook("user-plugins", async (reason) => {
     for (let i = shutdownSnapshot.length - 1; i >= 0; i--) {
       const { name } = shutdownSnapshot[i]!;
 
       // Unregister tools before running shutdown so onShutdown sees a
-      // clean model-visible surface. (No-op for the workspace-hooks owner,
-      // which registers no tools.)
+      // clean model-visible surface.
       try {
         unregisterPluginTools(name);
       } catch (err) {
@@ -509,11 +685,30 @@ export async function populateCacheAtBoot(
       }
 
       // Run the `shutdown` hook if present.
-      await runShutdownHook(name, shutdownContext, reason);
+      const shutdownHookEntry = hookCache.get(hookKey(name, HOOKS.SHUTDOWN));
+      if (shutdownHookEntry !== undefined) {
+        try {
+          await shutdownHookEntry.hook(shutdownContext);
+        } catch (err) {
+          log.warn(
+            { err, plugin: name, reason },
+            "user plugin shutdown hook failed (continuing)",
+          );
+        }
+      }
     }
   });
 }
 
+/**
+ * Ensure `<workspaceDir>/plugins-data/<name>/` exists and return its path.
+ */
+function ensurePluginStorageDir(pluginName: string): string {
+  const dir = join(getWorkspaceDir(), "plugins-data", pluginName);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
 // ─── Test hooks ──────────────────────────────────────────────────────────────
 
 /**
@@ -527,15 +722,35 @@ export function resetPluginCacheForTests(): void {
       "resetPluginCacheForTests may only be called in test environments",
     );
   }
-  resetHookCacheForTests();
-  clearSurfaceImportInflight();
+  hookCache.clear();
   toolCache.clear();
+  inflight.clear();
   discoveredPluginDirs.clear();
   installDateCache.clear();
   activatedPlugins.length = 0;
   disabledPluginDirs.clear();
 }
 
+/**
+ * Test-only: inspect the hook cache.
+ */
+export function _inspectHookCacheForTests(): Array<{
+  key: string;
+  sourceMtime: number;
+}> {
+  const isTest =
+    process.env.BUN_TEST === "1" || process.env.NODE_ENV === "test";
+  if (!isTest) {
+    throw new Error(
+      "_inspectHookCacheForTests may only be called in test environments",
+    );
+  }
+  return Array.from(hookCache.entries()).map(([key, c]) => ({
+    key,
+    sourceMtime: c.sourceMtime,
+  }));
+}
+
 /**
  * Test-only: inspect the tool cache.
  */

package/src/plugins/pipeline.ts

@@ -4,10 +4,9 @@
  * A "hook" is a named lifecycle event (`user-prompt-submit`, `post-tool-use`,
  * ...) that every registered plugin may handle. The runner walks each plugin's
  * hook for a given event in registration order, threading a context value
- * through the chain so hooks can observe and transform it. Each hook receives
- * an isolated draft of the current context. A hook either mutates the draft in
- * place (returning `void`) or returns a partial context whose fields are merged
- * onto the draft. Failed hook drafts are discarded.
+ * through the chain so hooks can observe and transform it. A hook either
+ * mutates the context in place (returning `void`) or returns a partial
+ * context whose fields are merged onto the threaded value.
  *
  * `getHooksFor` is now async — it pulls user-land hooks from the mtime
  * cache (filesystem-as-truth) and default plugin hooks from the registry
@@ -17,131 +16,34 @@
  */
 
 import type { HookName } from "../plugin-api/constants.js";
-import { getLogger } from "../util/logger.js";
 import { getHooksFor } from "./registry.js";
-import type { PluginHookFn } from "./types.js";
 
 // ─── Hook runner ────────────────────────────────────────────────────────────
 
-const log = getLogger("plugin-pipeline");
-
-function isPluginLogger(value: unknown): value is {
-  info: unknown;
-  warn: unknown;
-  error: unknown;
-  debug: unknown;
-} {
-  return (
-    value !== null &&
-    typeof value === "object" &&
-    typeof (value as { info?: unknown }).info === "function" &&
-    typeof (value as { warn?: unknown }).warn === "function" &&
-    typeof (value as { error?: unknown }).error === "function" &&
-    typeof (value as { debug?: unknown }).debug === "function"
-  );
-}
-
-function isPlainObject(value: object): boolean {
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}
-
-function cloneHookValue<T>(value: T, seen = new WeakMap<object, unknown>()): T {
-  if (value === null || typeof value !== "object") return value;
-  if (value instanceof Error || isPluginLogger(value)) return value;
-
-  const existing = seen.get(value);
-  if (existing !== undefined) return existing as T;
-
-  if (Array.isArray(value)) {
-    const copy: unknown[] = [];
-    seen.set(value, copy);
-    for (const item of value) {
-      copy.push(cloneHookValue(item, seen));
-    }
-    return copy as T;
-  }
-
-  if (value instanceof Date) {
-    return new Date(value.getTime()) as T;
-  }
-
-  if (value instanceof Map) {
-    const copy = new Map();
-    seen.set(value, copy);
-    for (const [key, mapValue] of value) {
-      copy.set(cloneHookValue(key, seen), cloneHookValue(mapValue, seen));
-    }
-    return copy as T;
-  }
-
-  if (value instanceof Set) {
-    const copy = new Set();
-    seen.set(value, copy);
-    for (const item of value) {
-      copy.add(cloneHookValue(item, seen));
-    }
-    return copy as T;
-  }
-
-  if (!isPlainObject(value)) return value;
-
-  const copy: Record<PropertyKey, unknown> = {};
-  seen.set(value, copy);
-  for (const key of Reflect.ownKeys(value)) {
-    copy[key] = cloneHookValue(
-      (value as Record<PropertyKey, unknown>)[key],
-      seen,
-    );
-  }
-  return copy as T;
-}
-
 /**
  * Execute a hook chain: walk every registered plugin's hook for `name` in
  * registration order, threading `initialCtx` through each. Hooks may either
- * mutate their draft context in place (returning `void`) or return a partial
- * context whose fields are merged onto the draft — keys the hook returns
- * overwrite the running context, every other field is preserved. If a hook
- * throws, its draft is discarded and the next hook receives the last
- * successfully committed context. The final context after the chain settles is
- * returned.
+ * mutate the context in place (returning `void`) or return a partial context
+ * whose fields are merged onto the threaded value — keys the hook returns
+ * overwrite the running context, every other field is preserved. The final
+ * context after the chain settles is returned.
  *
  * @param name        The hook identifier — pick one from {@link HOOKS}.
  * @param initialCtx  Context the first hook receives.
  * @returns The final context after the chain settles. Same reference as
- *          `initialCtx` when no plugin registers `name`.
+ *          `initialCtx` when no plugin registers `name`, and when every
+ *          chained hook returns `void` (mutation-in-place style).
  */
 export async function runHook<TCtx>(
   name: HookName,
   initialCtx: TCtx,
 ): Promise<TCtx> {
-  let hooks: PluginHookFn<TCtx>[];
-  try {
-    hooks = await getHooksFor<TCtx>(name);
-  } catch (err) {
-    log.error(
-      { err, hookName: name },
-      "plugin hook discovery failed — proceeding without hooks",
-    );
-    return initialCtx;
-  }
-
+  const hooks = await getHooksFor<TCtx>(name);
   let active = initialCtx;
   for (const hook of hooks) {
-    const draft = cloneHookValue(active);
-    try {
-      const result = await hook(draft);
-      if (result !== undefined) {
-        active = { ...draft, ...result };
-      } else {
-        active = draft;
-      }
-    } catch (err) {
-      log.error(
-        { err, hookName: name },
-        "plugin hook failed — proceeding with current context",
-      );
+    const result = await hook(active);
+    if (result !== undefined) {
+      active = { ...active, ...result };
     }
   }
   return active;

package/src/plugins/types.ts

@@ -47,6 +47,8 @@ export interface PluginManifest {
    * own version at load time.
    */
   version: string;
+  /** Credential keys the plugin needs resolved before `init()` runs. */
+  requiresCredential?: string[];
   /**
    * Assistant feature-flag keys that must all be enabled for this plugin to
    * activate. Checked by `bootstrapPlugins` via `isAssistantFeatureFlagEnabled`