@vellumai/assistant 0.7.3 → 0.8.1

package/src/plugins/external-plugin-loader.ts

@@ -0,0 +1,294 @@
+/**
+ * External plugin loader — builds a {@link Plugin} from a directory and
+ * registers it with the runtime.
+ *
+ * The convention this loader walks is currently **experimental**: surface
+ * set, manifest fields, and discovery shape may all change before the
+ * framework stabilizes. We keep this module's identifiers harness-neutral
+ * ("external") so the stable call path through the harness —
+ * `loadUserPlugins → loadExternalPlugin → registerPlugin` — does not
+ * need to be renamed when the convention shifts.
+ *
+ *     <pluginDir>/
+ *       package.json              ← manifest.name comes from `name`
+ *                                   (npm scope stripped); manifest.requires
+ *                                   comes from `vellum.requires` if present
+ *       hooks/
+ *         <name>.ts               ← default export → plugin.hooks[<name>]
+ *                                   (today the runtime invokes "init" at
+ *                                    bootstrap and "shutdown" at teardown;
+ *                                    other filenames sit in the map for
+ *                                    forward compatibility)
+ *       tools/
+ *         *.ts                    ← each file's default export → plugin.tools[]
+ *       src/                      ← internal helpers, ignored by the loader
+ *
+ * Per-surface, `.js` is preferred over `.ts` (compiled-binary semantics).
+ * Missing surface files are silently omitted (the harness treats absent
+ * fields as "this plugin contributes nothing here"). Surface files
+ * present without a usable default export are a hard failure: the
+ * loader logs with attribution and skips the plugin.
+ *
+ * This function owns the per-plugin isolation contract: it never throws,
+ * times out after `importTimeoutMs`, catches any error from the build or
+ * `registerPlugin` call, and logs an attributed entry. Callers can
+ * `await loadExternalPlugin(...)` in a loop with no per-iteration guard.
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { z } from "zod";
+
+import { getLogger } from "../util/logger.js";
+import { registerPlugin } from "./registry.js";
+import type {
+  Plugin,
+  PluginHookFn,
+  PluginHooks,
+  PluginManifest,
+  PluginToolRegistration,
+} from "./types.js";
+
+const log = getLogger("external-plugin-loader");
+
+/** Default upper bound on how long a single plugin load may take. */
+const DEFAULT_IMPORT_TIMEOUT_MS = 10_000;
+
+/**
+ * Zod schema for the subset of `package.json` the external loader reads.
+ *
+ * - `name` is the only required field; everything else is best-effort.
+ * - `vellum.requires` is forwarded to {@link PluginManifest.requires}
+ *   verbatim (no merge with defaults) — empty objects propagate so the
+ *   registry can reject under-specified plugins.
+ * - Unknown fields pass through (`passthrough`) so the loader does not
+ *   destructively reshape the file when the rest of the npm ecosystem
+ *   writes to it.
+ */
+const PluginPackageJsonSchema = z
+  .object({
+    name: z.string().min(1, "package.json `name` must be a non-empty string"),
+    version: z.string().optional(),
+    vellum: z
+      .object({
+        requires: z.record(z.string(), z.string()).optional(),
+      })
+      .passthrough()
+      .optional(),
+  })
+  .passthrough();
+
+type PluginPackageJson = z.infer<typeof PluginPackageJsonSchema>;
+
+export interface LoadExternalPluginOptions {
+  /**
+   * Maximum time to spend building the `Plugin` from disk before bailing.
+   * The build runs to completion in the background if it eventually
+   * resolves, but the loader has already moved on. Defaults to
+   * {@link DEFAULT_IMPORT_TIMEOUT_MS}.
+   */
+  readonly importTimeoutMs?: number;
+}
+
+/**
+ * Strip the npm scope from a package name. `@vellumai/simple-memory` →
+ * `simple-memory`; an unscoped name passes through unchanged.
+ */
+function stripScope(name: string): string {
+  const match = /^@[^/]+\/(.+)$/.exec(name);
+  return match ? match[1]! : name;
+}
+
+/**
+ * Dynamic-import `absolutePath` and return its default export. Throws when
+ * the module has no default export — callers attribute the error.
+ */
+async function importDefault<T>(absolutePath: string): Promise<T> {
+  const url = pathToFileURL(absolutePath).href;
+  const mod = (await import(url)) as { default?: T };
+  if (mod.default === undefined) {
+    throw new Error(
+      `module ${absolutePath} has no default export — external plugins must default-export their interface surfaces`,
+    );
+  }
+  return mod.default;
+}
+
+interface SurfaceFile {
+  /** Basename without `.js`/`.ts` extension. */
+  readonly name: string;
+  /** Absolute path on disk. */
+  readonly path: string;
+}
+
+/**
+ * List every `.js`/`.ts` file directly under `dir`, deduplicating `.js`
+ * over `.ts` when both are present for the same basename. Returns entries
+ * sorted by basename so plugin authors get a deterministic per-plugin
+ * registration sequence; cross-plugin order remains the registry's job.
+ *
+ * Used to walk both `hooks/` and `tools/` — neither surface needs
+ * subdirectory recursion today, so this stays flat on purpose.
+ */
+function listSurfaceDir(dir: string): SurfaceFile[] {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  const entries = readdirSync(dir);
+  const byBase = new Map<string, string>();
+  for (const entry of entries) {
+    // `.d.ts` declaration files are TypeScript type-only artifacts shipped
+    // alongside compiled `.js`. They have no default-exported runtime
+    // function and would crash `importDefault`, so the walker filters
+    // them out before the `.js`/`.ts` extension check.
+    if (entry.endsWith(".d.ts")) continue;
+    const base =
+      entry.endsWith(".js") || entry.endsWith(".ts")
+        ? entry.slice(0, -3)
+        : null;
+    if (base === null) continue;
+    const existing = byBase.get(base);
+    if (
+      existing === undefined ||
+      (existing.endsWith(".ts") && entry.endsWith(".js"))
+    ) {
+      byBase.set(base, entry);
+    }
+  }
+  return [...byBase.keys()]
+    .sort()
+    .map((name) => ({ name, path: join(dir, byBase.get(name)!) }));
+}
+
+/**
+ * Walk every file under `<pluginDir>/hooks/` and import each as a
+ * lifecycle hook keyed by filename basename. The runtime today invokes
+ * `init` at bootstrap and `shutdown` at teardown; other filenames are
+ * loaded into the map for forward compatibility with future lifecycle
+ * events but stay inert.
+ */
+async function loadHooks(
+  pluginDir: string,
+  pluginName: string,
+): Promise<PluginHooks | undefined> {
+  const files = listSurfaceDir(join(pluginDir, "hooks"));
+  if (files.length === 0) return undefined;
+  const hooks: PluginHooks = {};
+  for (const { name, path } of files) {
+    const fn = await importDefault<PluginHookFn>(path);
+    if (typeof fn !== "function") {
+      throw new Error(
+        `external plugin ${pluginName}: hooks/${name} default export must be a function (got ${typeof fn})`,
+      );
+    }
+    hooks[name] = fn;
+  }
+  return hooks;
+}
+
+/**
+ * Build a `Plugin` object from the directory layout. Internal — the
+ * public entry point ({@link loadExternalPlugin}) wraps this in the
+ * timeout/try-catch/register triple.
+ */
+async function buildPluginFromDir(pluginDir: string): Promise<Plugin> {
+  const pkgPath = join(pluginDir, "package.json");
+  let rawPkg: unknown;
+  try {
+    rawPkg = JSON.parse(await readFile(pkgPath, "utf8"));
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `package.json at ${pluginDir} could not be read or parsed: ${reason}`,
+    );
+  }
+  const parsed = PluginPackageJsonSchema.safeParse(rawPkg);
+  if (!parsed.success) {
+    throw new Error(
+      `package.json at ${pluginDir} failed schema validation: ${parsed.error.message}`,
+    );
+  }
+  const pkg: PluginPackageJson = parsed.data;
+  const name = stripScope(pkg.name);
+  const version = pkg.version && pkg.version.length > 0 ? pkg.version : "0.0.0";
+
+  // Default `requires` keeps the existing v1 negotiation working for
+  // plugins that have not yet opted into `vellum.requires`. Plugins that
+  // set `vellum.requires` get exactly what they declared — no merge.
+  const requires = pkg.vellum?.requires ?? { pluginRuntime: "v1" };
+
+  const manifest: PluginManifest = { name, version, requires };
+  const plugin: Plugin = { manifest };
+
+  const hooks = await loadHooks(pluginDir, name);
+  if (hooks !== undefined) plugin.hooks = hooks;
+
+  const tools: PluginToolRegistration[] = [];
+  for (const { path: toolPath } of listSurfaceDir(join(pluginDir, "tools"))) {
+    const tool = await importDefault<PluginToolRegistration>(toolPath);
+    if (
+      tool === null ||
+      typeof tool !== "object" ||
+      typeof (tool as { name?: unknown }).name !== "string"
+    ) {
+      throw new Error(
+        `external plugin ${name}: ${toolPath} default export must be a Tool object with a string "name"`,
+      );
+    }
+    tools.push(tool);
+  }
+  if (tools.length > 0) plugin.tools = tools;
+
+  return plugin;
+}
+
+/**
+ * Load the external plugin at `pluginDir` and register it.
+ */
+export async function loadExternalPlugin(
+  pluginDir: string,
+  opts: LoadExternalPluginOptions = {},
+): Promise<void> {
+  const timeoutMs = opts.importTimeoutMs ?? DEFAULT_IMPORT_TIMEOUT_MS;
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timeoutSentinel = Symbol("external-plugin-load-timeout");
+    const buildPromise = buildPluginFromDir(pluginDir);
+    const timeoutPromise = new Promise<typeof timeoutSentinel>((resolve) => {
+      timeoutHandle = setTimeout(() => resolve(timeoutSentinel), timeoutMs);
+    });
+    const result = await Promise.race([buildPromise, timeoutPromise]);
+    if (result === timeoutSentinel) {
+      // Abandoned build — surface imports may still be running. Attach a
+      // terminal `.catch` so a late rejection does not surface as an
+      // unhandled-rejection crash. The closed-registration latch in
+      // `registry.ts` rejects any late `registerPlugin()` call from a
+      // surface module that finishes evaluating after this loader has
+      // moved on.
+      buildPromise.catch(() => {
+        /* swallow — see comment above */
+      });
+      log.warn(
+        { pluginDir, timeoutMs },
+        `Timed out loading external plugin ${pluginDir} after ${timeoutMs}ms — skipping`,
+      );
+      return;
+    }
+    registerPlugin(result);
+    log.info(
+      { pluginDir, name: result.manifest.name },
+      "loaded external plugin",
+    );
+  } catch (err) {
+    // Per-plugin isolation: one bad external plugin must not crash the
+    // daemon. Surface the failure with attribution and move on.
+    const message = err instanceof Error ? err.message : String(err);
+    log.error(
+      { err, pluginDir },
+      `Failed to load external plugin ${pluginDir}: ${message}`,
+    );
+  } finally {
+    if (timeoutHandle !== undefined) clearTimeout(timeoutHandle);
+  }
+}

package/src/plugins/types.ts

@@ -93,30 +93,14 @@ export interface PluginManifest {
   config?: unknown;
 }
 
-// ─── Init context ────────────────────────────────────────────────────────────
-
-/**
- * Context passed to `Plugin.init()` during bootstrap. Carries resolved
- * config/credentials, a pino-compatible logger scoped to the plugin, a
- * per-plugin writable data directory, and the assistant's version metadata.
- */
-export interface PluginInitContext {
-  /** Parsed config for this plugin (may be `unknown` until the manifest validates). */
-  config: unknown;
-  /** Resolved credential values keyed by the entries of `manifest.requiresCredential`. */
-  credentials: Record<string, string>;
-  /**
-   * Pino-compatible child logger bound to `{ plugin: <name> }`. Untyped here
-   * to avoid pulling pino into the types module.
-   */
-  logger: unknown;
-  /** Absolute path to `<workspaceDir>/plugins-data/<plugin>/` (created by bootstrap). */
-  pluginStorageDir: string;
-  /** Assistant semver for compatibility checks inside the plugin. */
-  assistantVersion: string;
-  /** Capability → version-list map (`ASSISTANT_API_VERSIONS`) for defensive runtime checks. */
-  apiVersions: Record<string, string[]>;
-}
+// ─── Init / Shutdown context ─────────────────────────────────────────────────
+// Public types — defined in `assistant/src/plugin-api/types.ts` and re-exported
+// here so existing internal call sites keep working. Plugin authors will
+// import these from `@vellumai/plugin-api` once that package is published.
+export type {
+  PluginInitContext,
+  PluginShutdownContext,
+} from "../plugin-api/types.js";
 
 // ─── Middleware ──────────────────────────────────────────────────────────────
 
@@ -1077,19 +1061,51 @@ export interface PluginSkillRegistration {
 
 // ─── Plugin ──────────────────────────────────────────────────────────────────
 
+/**
+ * A plugin lifecycle hook. Receives a per-lifecycle context shape and
+ * may return either a transformed context or `void`. Today's runtime
+ * consumes only the resolved-or-rejected nature of the promise; the
+ * `TCtx` return is reserved for future hooks that fan a transformed
+ * context out to downstream plugins.
+ *
+ * Each known hook key has a documented context shape:
+ *   - `init` — {@link PluginInitContext}
+ *   - `shutdown` — {@link PluginShutdownContext}
+ *
+ * Unknown keys are populated by the loader for forward compatibility
+ * but are not invoked by today's runtime.
+ */
+export type PluginHookFn<TCtx = unknown> = (
+  ctx: TCtx,
+) => Promise<TCtx | void>;
+
+/**
+ * Map of lifecycle hooks contributed by a plugin. Keys match file
+ * basenames under `<plugin>/hooks/` — the external loader populates one
+ * entry per `hooks/<name>.{ts,js}` it finds. The runtime invokes
+ * known keys (`init`, `shutdown`) at the matching lifecycle event;
+ * unknown keys are forward-compat scaffolding.
+ *
+ * See `assistant/src/daemon/external-plugins-bootstrap.ts` for the
+ * full lifecycle, and {@link PluginHookFn} for the per-entry signature.
+ */
+// The map stores hooks for arbitrary keys with arbitrary context shapes.
+// `any` (rather than `unknown`) is required so concrete plugin signatures
+// like `(ctx: PluginInitContext) => Promise<void>` and `() => Promise<void>`
+// both assign in/out of slot entries under strict-function-types contravariance.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type PluginHooks = Record<string, PluginHookFn<any>>;
+
 /**
  * A registered plugin. Every field besides `manifest` is optional — a plugin
  * may contribute any combination of middleware, injectors, and model-visible
- * capabilities. Lifecycle hooks (`init`, `onShutdown`) run sequentially
- * during daemon startup/shutdown.
+ * capabilities. Lifecycle hooks live under `hooks`.
  */
 export interface Plugin {
   /** Static manifest validated by the registry. */
   manifest: PluginManifest;
-  /** Optional async initializer. Runs once during bootstrap, before traffic. */
-  init?(ctx: PluginInitContext): Promise<void>;
-  /** Optional shutdown hook. Runs during daemon shutdown in reverse-registration order. */
-  onShutdown?(): Promise<void>;
+  /** Lifecycle hooks (init, shutdown). See {@link PluginHooks}. */
+  hooks?: PluginHooks;
   /** Tool registrations visible to the model. */
   tools?: PluginToolRegistration[];
   /** HTTP route registrations served by the assistant. */

package/src/plugins/user-loader.ts

@@ -1,28 +1,39 @@
 /**
- * User plugin loader — discovers plugins under `<workspaceDir>/plugins/*` and
- * invokes each plugin's registration side effect via a dynamic import.
+ * User plugin loader — discovers plugins under `<workspaceDir>/plugins/*` via
+ * one of two paths, gated by the contents of each candidate directory.
  *
- * A user plugin is a directory under `getWorkspaceDir()/plugins/` that contains a
- * `register.ts` (or `register.js` after compilation). The file is expected to
- * call {@link registerPlugin} at import time so the plugin ends up in the
- * registry before {@link bootstrapPlugins} runs during daemon startup.
+ * **External plugin framework path** (`package.json` present **and** no
+ * `register.{ts,js}`): the harness delegates to {@link loadExternalPlugin},
+ * which builds a `Plugin` from the directory's interface dirs (`hooks/`,
+ * `tools/`) and registers it directly. This path is opt-in by the plugin
+ * author and currently experimental — see
+ * `assistant/src/plugins/external-plugin-loader.ts` for the full
+ * convention.
+ *
+ * **Legacy path** (`register.{ts,js}` present): the file is dynamic-imported
+ * and expected to call {@link registerPlugin} at import time as a side
+ * effect, populating the registry before {@link bootstrapPlugins} runs.
+ *
+ * The legacy path takes precedence when a directory contains both
+ * `package.json` and `register.{ts,js}` — a migration-friendly default
+ * that keeps existing plugins (including the in-repo `examples/plugins/echo`
+ * reference) working unchanged while we iterate the external-plugin
+ * convention. A directory matching neither path is skipped silently.
  *
  * The loader deliberately:
  *
  * - Uses `getWorkspaceDir()` so each instance loads its own plugin set
  *   when `VELLUM_WORKSPACE_DIR` is set.
- * - Prefers `register.js` over `register.ts` when both exist (compiled plugins
- *   always win; this matches how `bun`/Node consumers resolve modules at
- *   runtime in the compiled binary).
- * - Treats any error from the dynamic import as a per-plugin isolation
- *   boundary: the offending directory is logged with `"Failed to load user
- *   plugin <dir>: <err>"` and the loader moves on to the next candidate.
- *   One bad user plugin must not crash the daemon.
- * - Bounds each dynamic import with a timeout
- *   ({@link USER_PLUGIN_IMPORT_TIMEOUT_MS}) so a plugin whose top-level
- *   `await` hangs or whose module evaluation never resolves cannot stall
- *   daemon startup. Timed-out plugins are logged and skipped just like
- *   thrown-error plugins.
+ * - Prefers `.js` over `.ts` per surface file (compiled-binary semantics).
+ *   The external loader applies the same rule per surface file; the
+ *   legacy path picks between `register.js` and `register.ts`.
+ * - Treats any error from a plugin load as a per-plugin isolation
+ *   boundary. {@link loadExternalPlugin} owns its own try/catch/timeout;
+ *   the legacy path is wrapped here. One bad user plugin must not crash
+ *   the daemon.
+ * - Bounds each plugin load with {@link USER_PLUGIN_IMPORT_TIMEOUT_MS}
+ *   so a plugin whose top-level `await` hangs or whose module evaluation
+ *   never resolves cannot stall daemon startup.
  *
  * Call order relative to the rest of the plugin system:
  *
@@ -39,6 +50,7 @@ import { pathToFileURL } from "node:url";
 
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceDir } from "../util/platform.js";
+import { loadExternalPlugin } from "./external-plugin-loader.js";
 import { closeRegistration } from "./registry.js";
 
 const log = getLogger("user-plugin-loader");
@@ -55,9 +67,10 @@ const log = getLogger("user-plugin-loader");
 const USER_PLUGIN_IMPORT_TIMEOUT_MS = 10_000;
 
 /**
- * Scan `getWorkspaceDir()/plugins/` for subdirectories containing a
- * `register.{ts,js}` file, and dynamic-import each one so the module's
- * side-effecting {@link registerPlugin} calls populate the registry.
+ * Scan `getWorkspaceDir()/plugins/` for subdirectories, then dispatch each
+ * one to the external loader (if `package.json` is present and there is no
+ * `register.{ts,js}`) or the legacy side-effect importer (if
+ * `register.{ts,js}` is present).
  *
  * Invariants:
  *
@@ -68,24 +81,24 @@ const USER_PLUGIN_IMPORT_TIMEOUT_MS = 10_000;
  * - Does not return plugin instances. The registry is the single source of
  *   truth for who got registered, and the caller inspects it directly.
  *
- * Must be called after first-party plugin side-effect imports have run and
- * before {@link bootstrapPlugins} — see the module docstring for the ordering
- * contract.
+ * Caller responsibilities:
+ *
+ * - Must be invoked exactly once during daemon startup, before
+ *   `bootstrapPlugins()` walks the registry.
+ * - Holds no locks during the import — bun's dynamic `import()` resolution
+ *   is concurrency-safe.
  */
 export async function loadUserPlugins(
   options: { importTimeoutMs?: number } = {},
 ): Promise<void> {
-  const importTimeoutMs =
-    options.importTimeoutMs ?? USER_PLUGIN_IMPORT_TIMEOUT_MS;
+  const importTimeoutMs = options.importTimeoutMs ?? USER_PLUGIN_IMPORT_TIMEOUT_MS;
+
   const pluginsDir = join(getWorkspaceDir(), "plugins");
+
   if (!existsSync(pluginsDir)) {
-    log.debug(
-      { pluginsDir },
-      "loadUserPlugins: no plugins directory — skipping",
-    );
-    // Close the registration window even on the fast path so a late arrival
-    // from an unrelated source (e.g. a mis-ordered static import) still can't
-    // slip in after bootstrap walks the registry.
+    // The clean-install case. Closing the registration window keeps the
+    // post-loader invariant uniform: `bootstrapPlugins()` may rely on the
+    // registry being final by the time `loadUserPlugins()` resolves.
     closeRegistration();
     return;
   }
@@ -118,10 +131,12 @@ export async function loadUserPlugins(
     }
     if (!stats.isDirectory()) continue;
 
-    // Prefer the compiled `register.js` over the TypeScript source. In the
-    // bun-compiled daemon binary only the compiled file can be imported;
-    // in development both may exist, in which case resolving the compiled
-    // artifact matches how the runtime would behave in production.
+    // Path selection: the legacy side-effect path takes precedence when
+    // both a `register.{ts,js}` and a `package.json` are present.
+    // Migration-friendly: any plugin in the wild today that happens to
+    // ship a `package.json` keeps loading via its existing register entry.
+    // The external-plugin path only fires when the directory is
+    // unambiguously the new convention.
     const jsPath = join(pluginDir, "register.js");
     const tsPath = join(pluginDir, "register.ts");
     let registerPath: string | undefined;
@@ -130,16 +145,24 @@ export async function loadUserPlugins(
     } else if (existsSync(tsPath)) {
       registerPath = tsPath;
     }
-    if (!registerPath) {
+
+    if (registerPath === undefined) {
+      // External plugin framework path. `loadExternalPlugin` owns its own
+      // try/catch + timeout, so a `continue` is the entire branch here.
+      if (existsSync(join(pluginDir, "package.json"))) {
+        await loadExternalPlugin(pluginDir, { importTimeoutMs });
+        continue;
+      }
       log.debug(
         { pluginDir },
-        "loadUserPlugins: no register.{ts,js} — skipping",
+        "loadUserPlugins: no register.{ts,js} or package.json — skipping",
       );
       continue;
     }
 
-    // `import()` with a `file://` URL works identically under Node and bun
-    // and sidesteps platform-specific absolute-path quirks on Windows.
+    // Legacy side-effect import path. `import()` with a `file://` URL
+    // works identically under Node and bun and sidesteps platform-specific
+    // absolute-path quirks on Windows.
     const moduleUrl = pathToFileURL(registerPath).href;
     let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
     try {