@vellumai/assistant 0.8.1 → 0.8.3

package/src/plugins/external-api.ts

@@ -0,0 +1,104 @@
+/**
+ * External plugin runtime — `globalThis.__vellumPluginRuntime` bridge.
+ *
+ * Workspace-local plugins (`<workspaceDir>/plugins/*`) get dynamic-imported by
+ * {@link loadUserPlugins}. They need to call `registerPlugin()` from their
+ * module body and they typically also want to read secrets, subscribe to
+ * runtime events, etc.
+ *
+ * Importing those symbols by absolute path
+ * (`/abs/path/to/assistant/src/plugins/registry.js`) works when the daemon is
+ * running from source — both the daemon and the dynamic-imported plugin
+ * resolve the same on-disk file and share module identity. It DOES NOT work
+ * when the daemon is a `bun --compile` binary: the daemon's modules are baked
+ * into the executable, and any absolute-path import re-loads a fresh disk
+ * copy. `registerPlugin()` then writes into a disjoint registry instance and
+ * the daemon never sees the plugin.
+ *
+ * The fix is to expose a single, stable handle on `globalThis` that plugins
+ * read at module-load time. The daemon's bundled modules attach themselves
+ * here once at startup; plugins consume the same instance regardless of how
+ * the daemon was built.
+ *
+ * Plugins use the bridge like this:
+ *
+ *   const runtime = (globalThis as { __vellumPluginRuntime?: ... })
+ *     .__vellumPluginRuntime;
+ *   if (!runtime || runtime.version !== 1) throw new Error("...");
+ *   const { registerPlugin, assistantEventHub, getSecureKeyAsync } = runtime;
+ *
+ * Type-only imports (`import type { Plugin } from "..."`) remain free to use
+ * absolute paths or workspace-local copies — the TypeScript compiler erases
+ * them and they have no module-identity effect at runtime.
+ *
+ * See `assistant/docs/plugins.md` for the full authoring contract and
+ * `assistant/examples/plugins/echo/register.ts` for a worked example.
+ */
+
+import { assistantEventHub } from "../runtime/assistant-event-hub.js";
+import { getSecureKeyAsync } from "../security/secure-keys.js";
+import { registerPlugin } from "./registry.js";
+
+/**
+ * The handle plugins read from `globalThis.__vellumPluginRuntime`.
+ *
+ * `version` is the contract version. Plugins should assert against the
+ * version they were authored against and refuse to register if they see a
+ * different one — bumping it is a breaking change to the plugin surface.
+ *
+ * The field set is intentionally small: the most-commonly-needed symbols
+ * across both static (module-load-time) and dynamic (init-time) plugin
+ * lifecycle. Plugins that need richer runtime state can still receive it
+ * through {@link PluginInitContext} during `init()`.
+ */
+export interface VellumPluginRuntime {
+  readonly version: 1;
+  readonly registerPlugin: typeof registerPlugin;
+  readonly assistantEventHub: typeof assistantEventHub;
+  readonly getSecureKeyAsync: typeof getSecureKeyAsync;
+}
+
+/** Stable globalThis key. Don't rename — plugins reference it by string. */
+const RUNTIME_GLOBAL_KEY = "__vellumPluginRuntime" as const;
+
+interface GlobalWithRuntime {
+  [RUNTIME_GLOBAL_KEY]?: VellumPluginRuntime;
+}
+
+/**
+ * Install the plugin runtime bridge on `globalThis`. Idempotent — repeat
+ * calls are no-ops, so it's safe to invoke from tests that also touch the
+ * lifecycle path.
+ *
+ * Must be called BEFORE {@link loadUserPlugins} runs, otherwise plugins that
+ * touch `globalThis.__vellumPluginRuntime` in their module body will throw.
+ */
+export function installPluginRuntime(): void {
+  const g = globalThis as GlobalWithRuntime;
+  if (g[RUNTIME_GLOBAL_KEY]) return;
+  g[RUNTIME_GLOBAL_KEY] = {
+    version: 1,
+    registerPlugin,
+    assistantEventHub,
+    getSecureKeyAsync,
+  };
+}
+
+/**
+ * Read the installed runtime. Returns `undefined` if {@link installPluginRuntime}
+ * hasn't been called yet — plugins should treat this as a fatal error.
+ *
+ * Exposed mainly for tests and for the rare in-process consumer that wants
+ * to read the bridge from the same module graph that installed it.
+ */
+export function getPluginRuntime(): VellumPluginRuntime | undefined {
+  return (globalThis as GlobalWithRuntime)[RUNTIME_GLOBAL_KEY];
+}
+
+/**
+ * Tear down the runtime handle. Test-only — production code never uninstalls
+ * because the runtime lifetime is the daemon lifetime.
+ */
+export function uninstallPluginRuntimeForTests(): void {
+  delete (globalThis as GlobalWithRuntime)[RUNTIME_GLOBAL_KEY];
+}

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

@@ -11,8 +11,11 @@
  *
  *     <pluginDir>/
  *       package.json              ← manifest.name comes from `name`
- *                                   (npm scope stripped); manifest.requires
- *                                   comes from `vellum.requires` if present
+ *                                   (npm scope stripped);
+ *                                   peerDependencies["@vellumai/plugin-api"]
+ *                                   semver range is checked against the
+ *                                   running assistant version and rejects
+ *                                   the plugin if unsatisfied
  *       hooks/
  *         <name>.ts               ← default export → plugin.hooks[<name>]
  *                                   (today the runtime invokes "init" at
@@ -20,7 +23,9 @@
  *                                    other filenames sit in the map for
  *                                    forward compatibility)
  *       tools/
- *         *.ts                    ← each file's default export → plugin.tools[]
+ *         *.ts                    ← each default export → plugin.tools[];
+ *                                   runtime name derives from the filename
+ *                                   basename
  *       src/                      ← internal helpers, ignored by the loader
  *
  * Per-surface, `.js` is preferred over `.ts` (compiled-binary semantics).
@@ -40,8 +45,16 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 
+import semver from "semver";
 import { z } from "zod";
 
+import assistantPkg from "../../package.json" with { type: "json" };
+import type {
+  LoadedPluginTool,
+  PluginTool,
+  RiskLevel,
+  ToolExecutionResult,
+} from "../tools/types.js";
 import { getLogger } from "../util/logger.js";
 import { registerPlugin } from "./registry.js";
 import type {
@@ -52,6 +65,8 @@ import type {
   PluginToolRegistration,
 } from "./types.js";
 
+const PLUGIN_API_PEER_DEP = "@vellumai/plugin-api";
+
 const log = getLogger("external-plugin-loader");
 
 /** Default upper bound on how long a single plugin load may take. */
@@ -61,9 +76,11 @@ 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.
+ * - `peerDependencies["@vellumai/plugin-api"]` is the canonical host-compat
+ *   declaration. If present, the loader checks `semver.satisfies(host, range)`
+ *   against the running assistant version and rejects the plugin on
+ *   mismatch. If absent, the plugin loads without a host-compat claim
+ *   (with a warning).
  * - Unknown fields pass through (`passthrough`) so the loader does not
  *   destructively reshape the file when the rest of the npm ecosystem
  *   writes to it.
@@ -72,12 +89,7 @@ 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(),
+    peerDependencies: z.record(z.string(), z.string()).optional(),
   })
   .passthrough();
 
@@ -102,6 +114,72 @@ function stripScope(name: string): string {
   return match ? match[1]! : name;
 }
 
+function toToolNameSegment(value: string): string {
+  return value.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "tool";
+}
+
+function deriveToolName(toolFileBaseName: string): string {
+  return toToolNameSegment(toolFileBaseName);
+}
+
+/**
+ * Defaults applied by {@link applyPluginToolDefaults} when a plugin tool
+ * omits one of the normally-required fields. Exported as a constant so
+ * tests and callers can reference the same source of truth.
+ *
+ * The default `execute` returns an error result so the model sees a clear
+ * "this tool isn't wired up" signal at call time. The plugin still loads
+ * cleanly — broken individual tools must never block daemon boot.
+ */
+export const PLUGIN_TOOL_DEFAULTS = Object.freeze({
+  description: "",
+  defaultRiskLevel: "medium" as RiskLevel,
+  input_schema: Object.freeze({
+    type: "object",
+    properties: {},
+    additionalProperties: false,
+  }) as object,
+});
+
+/**
+ * Fill the four normally-required {@link PluginTool} fields with documented
+ * defaults when the author omitted them. Returns a {@link LoadedPluginTool}
+ * that is safe to register.
+ */
+function applyPluginToolDefaults(
+  tool: PluginTool,
+  name: string,
+): LoadedPluginTool {
+  const description =
+    typeof tool.description === "string"
+      ? tool.description
+      : PLUGIN_TOOL_DEFAULTS.description;
+  const defaultRiskLevel =
+    typeof tool.defaultRiskLevel === "string"
+      ? tool.defaultRiskLevel
+      : PLUGIN_TOOL_DEFAULTS.defaultRiskLevel;
+  const input_schema =
+    tool.input_schema !== null &&
+    typeof tool.input_schema === "object"
+      ? tool.input_schema
+      : PLUGIN_TOOL_DEFAULTS.input_schema;
+  const execute =
+    typeof tool.execute === "function"
+      ? tool.execute
+      : async (): Promise<ToolExecutionResult> => ({
+          content: `plugin tool ${name} has no execute implementation`,
+          isError: true,
+        });
+  return {
+    ...tool,
+    name,
+    description,
+    defaultRiskLevel,
+    input_schema,
+    execute,
+  };
+}
+
 /**
  * Dynamic-import `absolutePath` and return its default export. Throws when
  * the module has no default export — callers attribute the error.
@@ -213,30 +291,65 @@ async function buildPluginFromDir(pluginDir: string): Promise<Plugin> {
   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" };
+  // Host-compat negotiation: plugins declare their plugin-api version
+  // range via standard `peerDependencies["@vellumai/plugin-api"]`. We
+  // inspect the range and report unparseable / unsatisfied cases via
+  // `log.error` but still load the plugin — the plugin-installation
+  // flow is in flux and a strict gate here would block experimentation
+  // for the customers driving the install UX. Once the install path
+  // settles, the two `log.error` branches below should harden into
+  // throws so a stale plugin can't silently run against a mismatched
+  // host.
+  //
+  // If the peerDep is absent, the plugin loads without a host-compat
+  // claim; we log a warning so the omission is visible at boot.
+  const range = pkg.peerDependencies?.[PLUGIN_API_PEER_DEP];
+  if (range !== undefined) {
+    if (!semver.validRange(range)) {
+      log.error(
+        { pluginDir, plugin: name, peerDep: PLUGIN_API_PEER_DEP, range },
+        `external plugin ${name}: peerDependencies["${PLUGIN_API_PEER_DEP}"] is not a valid semver range — loading anyway`,
+      );
+    } else if (
+      !semver.satisfies(assistantPkg.version, range, {
+        includePrerelease: true,
+      })
+    ) {
+      log.error(
+        {
+          pluginDir,
+          plugin: name,
+          peerDep: PLUGIN_API_PEER_DEP,
+          range,
+          assistantVersion: assistantPkg.version,
+        },
+        `external plugin ${name}: peerDependencies["${PLUGIN_API_PEER_DEP}"] requires "${range}" but assistant is ${assistantPkg.version} — loading anyway`,
+      );
+    }
+  } else {
+    log.warn(
+      { pluginDir, plugin: name, peerDep: PLUGIN_API_PEER_DEP },
+      "external plugin missing plugin-api peerDependency — loading without host-compat claim",
+    );
+  }
 
-  const manifest: PluginManifest = { name, version, requires };
+  const manifest: PluginManifest = { name, version };
   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"
-    ) {
+  for (const { name: toolName, path: toolPath } of listSurfaceDir(
+    join(pluginDir, "tools"),
+  )) {
+    const tool = await importDefault<PluginTool>(toolPath);
+    if (tool === null || typeof tool !== "object") {
       throw new Error(
-        `external plugin ${name}: ${toolPath} default export must be a Tool object with a string "name"`,
+        `external plugin ${name}: ${toolPath} default export must be an object`,
       );
     }
-    tools.push(tool);
+    tools.push(applyPluginToolDefaults(tool, deriveToolName(toolName)));
   }
   if (tools.length > 0) plugin.tools = tools;
 
@@ -244,16 +357,23 @@ async function buildPluginFromDir(pluginDir: string): Promise<Plugin> {
 }
 
 /**
- * Load the external plugin at `pluginDir` and register it.
+ * Build a {@link Plugin} from `pluginDir` with the same timeout +
+ * per-plugin isolation contract as {@link loadExternalPlugin}, but
+ * without registering it. The plugin-source watcher consumes this so it
+ * can decide between first-time registration (init once, then publish) and
+ * hot-reload (replace + skip init) based on what's already in the registry.
+ *
+ * Returns `undefined` on timeout, build failure, or abandoned surface
+ * import. Never throws — failures are logged with directory attribution.
  */
-export async function loadExternalPlugin(
+export async function buildExternalPlugin(
   pluginDir: string,
   opts: LoadExternalPluginOptions = {},
-): Promise<void> {
+): Promise<Plugin | undefined> {
   const timeoutMs = opts.importTimeoutMs ?? DEFAULT_IMPORT_TIMEOUT_MS;
   let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
   try {
-    const timeoutSentinel = Symbol("external-plugin-load-timeout");
+    const timeoutSentinel = Symbol("external-plugin-build-timeout");
     const buildPromise = buildPluginFromDir(pluginDir);
     const timeoutPromise = new Promise<typeof timeoutSentinel>((resolve) => {
       timeoutHandle = setTimeout(() => resolve(timeoutSentinel), timeoutMs);
@@ -262,33 +382,58 @@ export async function loadExternalPlugin(
     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.
+      // unhandled-rejection crash. Callers who feed the returned plugin
+      // into `registerPlugin` rely on the closed-registration latch
+      // (registry.ts) to reject any stale late-arriving registration.
       buildPromise.catch(() => {
         /* swallow — see comment above */
       });
       log.warn(
         { pluginDir, timeoutMs },
-        `Timed out loading external plugin ${pluginDir} after ${timeoutMs}ms — skipping`,
+        `Timed out building external plugin ${pluginDir} after ${timeoutMs}ms — skipping`,
       );
-      return;
+      return undefined;
     }
-    registerPlugin(result);
-    log.info(
-      { pluginDir, name: result.manifest.name },
-      "loaded external plugin",
-    );
+    return result;
   } 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}`,
+      `Failed to build external plugin ${pluginDir}: ${message}`,
     );
+    return undefined;
   } finally {
     if (timeoutHandle !== undefined) clearTimeout(timeoutHandle);
   }
 }
+
+/**
+ * Load the external plugin at `pluginDir` and register it. Thin wrapper
+ * over {@link buildExternalPlugin} that calls `registerPlugin` on the
+ * built plugin, preserving the existing `loadUserPlugins` call shape.
+ */
+export async function loadExternalPlugin(
+  pluginDir: string,
+  opts: LoadExternalPluginOptions = {},
+): Promise<void> {
+  const plugin = await buildExternalPlugin(pluginDir, opts);
+  if (plugin === undefined) {
+    // buildExternalPlugin already logged the failure with attribution.
+    return;
+  }
+  try {
+    registerPlugin(plugin);
+    log.info(
+      { pluginDir, name: plugin.manifest.name },
+      "loaded external plugin",
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error(
+      { err, pluginDir, plugin: plugin.manifest.name },
+      `Failed to register external plugin ${pluginDir}: ${message}`,
+    );
+  }
+}

package/src/plugins/feature-gate.ts

@@ -0,0 +1,22 @@
+/**
+ * External-plugin feature gate.
+ *
+ * Single source of truth for whether the experimental external-plugin
+ * surface is enabled. The flag gates both the `assistant plugins` CLI
+ * command tree and (in future) the declarative external-plugin loader
+ * pathway in the daemon.
+ *
+ * The flag key uses the simple kebab-case format and is declared in
+ * `meta/feature-flags/feature-flag-registry.json`.
+ */
+
+import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
+import type { AssistantConfig } from "../config/schema.js";
+
+/** Gate key for the external-plugin surface. */
+const EXTERNAL_PLUGINS_FLAG_KEY = "external-plugins" as const;
+
+/** Whether the external-plugin surface is enabled. */
+export function isExternalPluginsEnabled(config: AssistantConfig): boolean {
+  return isAssistantFeatureFlagEnabled(EXTERNAL_PLUGINS_FLAG_KEY, config);
+}

package/src/plugins/pipeline.ts

@@ -26,7 +26,9 @@
 
 import type { Logger } from "pino";
 
+import type { HookName } from "../plugin-api/constants.js";
 import { getLogger } from "../util/logger.js";
+import { getHooksFor } from "./registry.js";
 import {
   type Middleware,
   type PipelineName,
@@ -314,3 +316,38 @@ export async function runPipeline<A, R>(
     logger.info(record, "plugin.pipeline");
   }
 }
+
+// ─── Hook runner ────────────────────────────────────────────────────────────
+
+/**
+ * Execute a hook chain: walk every registered plugin's hook for `name` in
+ * registration order, threading `initialCtx` through each. Hooks may either
+ * mutate the context in place (returning `void`) or return a new context
+ * that replaces the threaded value for subsequent hooks. The final context
+ * after the chain settles is returned.
+ *
+ * `runHook` is the hook-side counterpart to {@link runPipeline}:
+ * `runPipeline` composes middleware around a terminal handler for stateful
+ * request/response pipelines (memory retrieval, history repair, etc.);
+ * `runHook` walks ordered hook functions for declarative chain-style
+ * context transformations (`user-prompt-submit` today).
+ *
+ * @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`, and when every
+ *          chained hook returns `void` (mutation-in-place style).
+ */
+export async function runHook<TCtx>(
+  name: HookName,
+  initialCtx: TCtx,
+): Promise<TCtx> {
+  let active = initialCtx;
+  for (const hook of getHooksFor<TCtx>(name)) {
+    const result = await hook(active);
+    if (result !== undefined) {
+      active = result;
+    }
+  }
+  return active;
+}

package/src/plugins/registry.ts

@@ -1,12 +1,13 @@
 /**
- * Plugin registry with manifest validation and capability-based API versioning.
+ * Plugin registry with manifest validation.
  *
- * Plugins declare the assistant capabilities they need via
- * `manifest.requires` (a `{ capability: version }` map). The registry checks
- * each entry against {@link ASSISTANT_API_VERSIONS} — the canonical table of
- * capability → supported-version-list pairs the assistant exposes — and
- * refuses to register plugins that ask for a version the assistant does not
- * support.
+ * Host-compat negotiation lives in the plugin's `package.json`
+ * `peerDependencies["@vellumai/plugin-api"]` semver range — the
+ * external-plugin loader checks it against the assistant version at
+ * load time. This module owns the rest of the manifest validation
+ * contract: name/version presence, duplicate-name detection, and the
+ * closed-registration latch that protects `bootstrapPlugins()` from
+ * late-arriving registrations.
  *
  * Registration is order-preserving: {@link getRegisteredPlugins},
  * {@link getMiddlewaresFor}, and (secondarily) {@link getInjectors} all reflect
@@ -26,49 +27,9 @@ import {
   type PipelineName,
   type Plugin,
   PluginExecutionError,
+  type PluginHookFn,
 } from "./types.js";
 
-/**
- * Capability table declaring which plugin-facing API versions the assistant
- * runtime exposes. Each capability maps to the list of supported semver-lite
- * tags (currently a single `"v1"` per capability).
- *
- * New capabilities must be added here AND in their corresponding pipeline /
- * runtime module so plugins can negotiate against them. Removing a version
- * tag is a breaking change — all consumers in the plugin ecosystem relying on
- * it will fail to register until they update their `requires` map.
- *
- * The `pluginRuntime` capability is the base runtime API every plugin must
- * negotiate for; the remaining entries mirror {@link PipelineName} and the
- * top-level context APIs plugins most commonly consume.
- */
-export const ASSISTANT_API_VERSIONS: Record<string, string[]> = {
-  // Runtime APIs every plugin interacts with at some level. `memoryApi` is the
-  // broader memory-subsystem capability (distinct from the `memoryRetrieval`
-  // pipeline, which gets its own `memoryRetrievalApi` entry below).
-  pluginRuntime: ["v1"],
-  memoryApi: ["v1"],
-  compactionApi: ["v1"],
-  persistenceApi: ["v1"],
-
-  // Per-pipeline APIs. One entry for every slot in {@link PipelineName} that
-  // isn't already covered by the runtime-APIs block above (`compaction` and
-  // `persistence` live there because plugins commonly interact with them
-  // outside a pipeline middleware context).
-  turnApi: ["v1"],
-  llmCallApi: ["v1"],
-  toolExecuteApi: ["v1"],
-  memoryRetrievalApi: ["v1"],
-  historyRepairApi: ["v1"],
-  tokenEstimateApi: ["v1"],
-  overflowReduceApi: ["v1"],
-  titleGenerateApi: ["v1"],
-  toolResultTruncateApi: ["v1"],
-  emptyResponseApi: ["v1"],
-  toolErrorApi: ["v1"],
-  circuitBreakerApi: ["v1"],
-};
-
 // ─── Internal state ──────────────────────────────────────────────────────────
 
 /**
@@ -96,11 +57,13 @@ let registrationClosed = false;
 /**
  * Validate and register a plugin. Throws {@link PluginExecutionError} if:
  *
- * - `manifest`, `manifest.name`, `manifest.version`, or `manifest.requires`
- *   are missing.
+ * - `manifest`, `manifest.name`, or `manifest.version` are missing.
  * - a plugin with the same name is already registered.
- * - any entry in `manifest.requires` names an unknown capability or a version
- *   the assistant does not expose.
+ * - registration has been closed by {@link closeRegistration}.
+ *
+ * Host-compat is checked upstream by the external-plugin loader against
+ * the plugin's `peerDependencies["@vellumai/plugin-api"]` semver range —
+ * the registry does not re-validate it here.
  *
  * On success the plugin is appended to the registry in the order this
  * function is called. This function does NOT invoke `plugin.init()` — that
@@ -144,13 +107,6 @@ export function registerPlugin(plugin: Plugin): void {
       name,
     );
   }
-  if (!manifest.requires || typeof manifest.requires !== "object") {
-    throw new PluginExecutionError(
-      `plugin ${name} manifest.requires is required`,
-      name,
-    );
-  }
-
   // Duplicate-name check — plugins must be uniquely addressable in logs,
   // storage paths, and error messages. Runs BEFORE the closed-registration
   // check so `registerDefaultPlugins()` (which replays every default even
@@ -174,27 +130,6 @@ export function registerPlugin(plugin: Plugin): void {
     );
   }
 
-  // Capability negotiation. Every plugin must negotiate against
-  // `pluginRuntime`; we enforce that by requiring an entry to exist rather
-  // than special-casing it here, so the per-entry mismatch error is uniform.
-  if (!("pluginRuntime" in manifest.requires)) {
-    throw new PluginExecutionError(
-      `plugin ${name} must declare requires.pluginRuntime (e.g. "v1")`,
-      name,
-    );
-  }
-
-  for (const [api, requiredVersion] of Object.entries(manifest.requires)) {
-    const supported = ASSISTANT_API_VERSIONS[api];
-    if (!supported || !supported.includes(requiredVersion)) {
-      const exposed = supported ? supported.join(", ") : "(none)";
-      throw new PluginExecutionError(
-        `plugin ${name} requires ${api}@${requiredVersion}, assistant exposes ${exposed}`,
-        name,
-      );
-    }
-  }
-
   registeredPlugins.set(name, plugin);
 }
 
@@ -230,6 +165,31 @@ export function getMiddlewaresFor<P extends PipelineName>(
   return out;
 }
 
+/**
+ * Collect every registered plugin's hook for the given name, in
+ * registration order. Plugins that don't declare a hook for `name` are
+ * skipped. Used by the daemon to invoke chain-style hooks like
+ * `user-prompt-submit` where each plugin's hook may transform a shared
+ * context.
+ *
+ * The `TCtx` generic mirrors {@link PluginHookFn}'s — callers parameterize
+ * over the concrete context type their hook receives. Hooks that mutate
+ * the context in place return `void`; hooks that return a new context
+ * replace the threaded value for the next hook in the chain.
+ */
+export function getHooksFor<TCtx = unknown>(
+  name: string,
+): PluginHookFn<TCtx>[] {
+  const out: PluginHookFn<TCtx>[] = [];
+  for (const plugin of registeredPlugins.values()) {
+    const hook = plugin.hooks?.[name];
+    if (hook) {
+      out.push(hook as PluginHookFn<TCtx>);
+    }
+  }
+  return out;
+}
+
 /**
  * Flatten every registered plugin's `injectors` array and sort the result by
  * `order` ascending. Two injectors with the same `order` retain their relative
@@ -275,6 +235,14 @@ export function unregisterPlugin(name: string): void {
   registeredPlugins.delete(name);
 }
 
+export function getRegisteredPlugin(name: string): Plugin | undefined {
+  return registeredPlugins.get(name);
+}
+
+export function setRegisteredPlugin(plugin: Plugin): void {
+  registeredPlugins.set(plugin.manifest.name, plugin);
+}
+
 // ─── Test hooks ──────────────────────────────────────────────────────────────
 
 /**