@vellumai/assistant 0.8.1 → 0.8.2

package/src/platform/client.test.ts

@@ -15,7 +15,7 @@ let mockAssistantId = "";
 // Module mocks
 // ---------------------------------------------------------------------------
 
-mock.module("../providers/managed-proxy/context.js", () => ({
+mock.module("../providers/platform-proxy/context.js", () => ({
   resolveManagedProxyContext: async () => mockManagedProxyCtx,
 }));
 

package/src/platform/client.ts

@@ -6,7 +6,7 @@
  */
 
 import { getPlatformAssistantId } from "../config/env.js";
-import { resolveManagedProxyContext } from "../providers/managed-proxy/context.js";
+import { resolveManagedProxyContext } from "../providers/platform-proxy/context.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";

package/src/plugin-api/constants.ts

@@ -0,0 +1,26 @@
+/**
+ * Public hook-name constants.
+ *
+ * Plugin authors reference hooks by name in two places: the keys on
+ * `Plugin.hooks` and the daemon's `runHook(name, ctx)` call sites.
+ * Centralizing the string literals here keeps the typo surface minimal
+ * and lets call sites import a typed constant instead of repeating a
+ * free-form string.
+ *
+ * New hooks land here as additional `HOOKS.*` entries. The runtime
+ * `runHook(name, ctx)` accepts any string (so test fixtures and
+ * forward-compat hooks can still chain through), but call sites in
+ * first-party code should always reach for a `HOOKS.*` constant.
+ */
+
+export const HOOKS = {
+  /** Plugin bootstrap. Fires once when the daemon loads the plugin. */
+  INIT: "init",
+  /** Plugin teardown. Fires once when the daemon unloads the plugin. */
+  SHUTDOWN: "shutdown",
+  /** Fires once per user turn, immediately before the agent loop receives `runMessages`. */
+  USER_PROMPT_SUBMIT: "user-prompt-submit",
+} as const;
+
+/** Union of every hook name declared in {@link HOOKS}. */
+export type HookName = (typeof HOOKS)[keyof typeof HOOKS];

package/src/plugin-api/index.ts

@@ -8,6 +8,39 @@
  *
  * Keep this file's surface stable across minor/patch releases. Anything
  * exported here is part of the public contract.
+ *
+ * ## Surface today
+ *
+ * The public package is intentionally **declarative**: a plugin is a
+ * directory whose `package.json` is the manifest and whose `hooks/` /
+ * `tools/` / `skills/` / `routes/` subdirectories are the contributions.
+ * The host introspects the directory at load time and wires it into the
+ * runtime — plugin authors never call a runtime registration function.
+ *
+ * What this module exposes is therefore types-only: the context shapes
+ * the host hands to plugin hooks, and the logger shape they include.
+ *
+ * - {@link PluginInitContext} — passed to `init` hook at bootstrap
+ * - {@link PluginShutdownContext} — passed to `shutdown` hook at teardown
+ * - {@link UserPromptSubmitContext} — passed to `user-prompt-submit` hook,
+ *   fired immediately before the agent loop receives a user's prompt
+ * - {@link PluginLogger} — pino-compatible logger shape on the contexts
+ * - {@link ToolContext} — passed to a plugin tool's `execute` method
+ * - {@link ToolExecutionResult} — return shape of a plugin tool's `execute`
+ *
+ * Pipeline-argument types (`LLMCallArgs`, `MemoryArgs`, etc.) currently
+ * live in `assistant/src/plugins/types.ts` and have not yet migrated into
+ * this package. A follow-up PR will move them into this surface as the
+ * per-pipeline schemas stabilize.
  */
 
-export type { PluginInitContext, PluginShutdownContext } from "./types.js";
+export type { HookName } from "./constants.js";
+export { HOOKS } from "./constants.js";
+export type {
+  PluginInitContext,
+  PluginLogger,
+  PluginShutdownContext,
+  ToolContext,
+  ToolExecutionResult,
+  UserPromptSubmitContext,
+} from "./types.js";

package/src/plugin-api/types.ts

@@ -1,21 +1,64 @@
 /**
  * Public plugin-API types.
  *
- * This module is the source-of-truth for types that plugin authors depend on.
- * The rest of the assistant imports from here via relative paths
- * (`../plugin-api/types.js`). At publish time, this file's contents are
- * bundled into the `@vellumai/plugin-api` npm package; at runtime in the
- * assistant binary, the same source is reachable to user plugins via a
- * boot-time shim that re-exports from the embedded bundle.
- *
- * Today this module is intentionally narrow — only `PluginInitContext` and
- * `PluginShutdownContext`. Additional public types migrate over in
- * follow-up PRs as the surface stabilizes.
- *
- * Internal-only types (pipeline shapes, middleware, manifest validation,
- * etc.) stay in `assistant/src/plugins/types.ts` until they're ready to
- * become public.
+ * This module is the entry point plugin authors land on when they import
+ * from `@vellumai/plugin-api`. The shapes here are the canonical public
+ * contract — anything exported is part of the surface that semver gates.
+ *
+ * ## Tool-execution types
+ *
+ * `ToolContext` and `ToolExecutionResult` are re-exports of the narrow,
+ * stable bases defined alongside their daemon-internal counterparts in
+ * `assistant/src/tools/types.ts`. The daemon-internal `ToolContext` /
+ * `ToolExecutionResult` (with CES, trust classification, lifecycle
+ * events, sensitive-output bindings, risk metadata, etc.) `extends`
+ * the public bases, so the runtime can hand plugins the full value
+ * without a manual cast and tsc enforces the structural relationship.
+ * Plugin tools see the narrow surface only — they MUST NOT set fields
+ * that belong to the daemon-internal extension.
+ *
+ * ## Hook contexts
+ *
+ * The init / shutdown hook contexts are owned by this module directly.
+ * They have no daemon-internal extension today (the daemon constructs
+ * and hands them straight through), so there's nothing to inherit from.
+ *
+ * ## Compatibility
+ *
+ * Adding fields to any public shape is non-breaking. Renaming or
+ * removing fields is breaking and gated on a major bump of
+ * `@vellumai/plugin-api`.
+ */
+
+import type { Message } from "../providers/types.js";
+
+// ─── Tool-execution types (re-exported from daemon source-of-truth) ──────────
+
+export type {
+  PluginToolContext as ToolContext,
+  PluginToolExecutionResult as ToolExecutionResult,
+} from "../tools/types.js";
+
+// ─── Logger ──────────────────────────────────────────────────────────────────
+
+/**
+ * Minimal pino-compatible logger surface handed to plugin hooks. The host
+ * supplies a pino child logger bound to `{ plugin: <name> }`; this
+ * interface intentionally captures only the two call shapes plugin code
+ * needs (structured object + optional message), so the public surface
+ * doesn't take a dependency on pino's full type machinery.
+ *
+ * Each method accepts a structured-fields object followed by an optional
+ * message string. Plugin authors that need pino's wider API (`child()`,
+ * `level`, etc.) can cast to their own narrower interface in plugin code
+ * — but the canonical contract here covers the 99% case.
  */
+export interface PluginLogger {
+  info(obj: Record<string, unknown>, msg?: string): void;
+  warn(obj: Record<string, unknown>, msg?: string): void;
+  error(obj: Record<string, unknown>, msg?: string): void;
+  debug(obj: Record<string, unknown>, msg?: string): void;
+}
 
 // ─── Init context ────────────────────────────────────────────────────────────
 
@@ -29,17 +72,17 @@ export interface PluginInitContext {
   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;
+  /** Pino-compatible child logger bound to `{ plugin: <name> }`. */
+  logger: PluginLogger;
   /** Absolute path to `<workspaceDir>/plugins-data/<plugin>/` (created by bootstrap). */
   pluginStorageDir: string;
-  /** Assistant semver for compatibility checks inside the plugin. */
+  /**
+   * Assistant semver. Plugins can compare against this for defensive
+   * runtime checks — but the canonical compat contract is the host
+   * version against the plugin's `peerDependencies["@vellumai/plugin-api"]`
+   * semver range, enforced at load time by the external-plugin loader.
+   */
   assistantVersion: string;
-  /** Capability → version-list map (`ASSISTANT_API_VERSIONS`) for defensive runtime checks. */
-  apiVersions: Record<string, string[]>;
 }
 
 // ─── Shutdown context ────────────────────────────────────────────────────────
@@ -60,3 +103,42 @@ export interface PluginShutdownContext {
   /** Assistant semver for compatibility checks inside the plugin. */
   assistantVersion: string;
 }
+
+// ─── User-prompt-submit hook context ─────────────────────────────────────────
+
+/**
+ * Context passed to the `user-prompt-submit` hook. Fires once per user
+ * turn, after the agent loop has prepared the message list (PKB / NOW /
+ * memory-graph injections, history repair, overflow reduction all already
+ * applied) and immediately before the messages are handed to the agent
+ * loop's tool/LLM iteration.
+ *
+ * The hook may transform `latestMessages` either by mutating it in place
+ * (`push` / `splice` / `length = 0`) or by returning a new context with
+ * a fresh `latestMessages` array — see {@link PluginHookFn}'s polymorphic
+ * return shape. The daemon threads the final `latestMessages` value into
+ * `agentLoop.run()` as the run-messages argument.
+ *
+ * `originalMessages` is the user's original message list, frozen for the
+ * hook. Plugins should treat it as a stable reference point if they need
+ * to recover from earlier transformations or compare against the pristine
+ * state.
+ *
+ * Multiple plugins' hooks chain in registration order — each plugin's
+ * hook sees the previous plugin's mutations (whether by reassignment or
+ * in-place mutation).
+ */
+export interface UserPromptSubmitContext {
+  /** Conversation ID the user prompt was submitted on. */
+  readonly conversationId: string;
+  /**
+   * The user's original message list, immutable for the hook. Plugins
+   * may snapshot or compare against this but MUST NOT mutate it.
+   */
+  readonly originalMessages: ReadonlyArray<Message>;
+  /**
+   * The working message list that flows into `agentLoop.run`. Plugins
+   * may mutate this in place or replace it by returning a new context.
+   */
+  latestMessages: Message[];
+}

package/src/plugins/defaults/circuit-breaker.ts

@@ -55,11 +55,6 @@ export const defaultCircuitBreakerPlugin: Plugin = {
   manifest: {
     name: "default-circuit-breaker",
     version: "1.0.0",
-    provides: { circuitBreakerApi: "v1" },
-    requires: {
-      pluginRuntime: "v1",
-      circuitBreakerApi: "v1",
-    },
   },
 
   middleware: {

package/src/plugins/defaults/compaction.ts

@@ -112,10 +112,6 @@ export const defaultCompactionPlugin: Plugin = {
   manifest: {
     name: DEFAULT_COMPACTION_PLUGIN_NAME,
     version: "1.0.0",
-    requires: {
-      pluginRuntime: "v1",
-      compactionApi: "v1",
-    },
   },
   middleware: {
     compaction: defaultCompactionMiddleware,

package/src/plugins/defaults/empty-response.ts

@@ -95,8 +95,6 @@ export const defaultEmptyResponsePlugin: Plugin = {
   manifest: {
     name: "default-empty-response",
     version: "1.0.0",
-    provides: { emptyResponseApi: "v1" },
-    requires: { pluginRuntime: "v1", emptyResponseApi: "v1" },
   },
   middleware: {
     emptyResponse: passthrough,

package/src/plugins/defaults/history-repair.ts

@@ -54,8 +54,6 @@ export const defaultHistoryRepairPlugin: Plugin = {
   manifest: {
     name: "default-history-repair",
     version: "1.0.0",
-    provides: { historyRepair: "v1" },
-    requires: { pluginRuntime: "v1", historyRepairApi: "v1" },
   },
   middleware: {
     historyRepair: passthrough,

package/src/plugins/defaults/injectors.ts

@@ -19,6 +19,7 @@
  * | `pkb-reminder`           | 35    | after-memory-prefix     |
  * | `memory-v2-static`       | 38    | after-memory-prefix     |
  * | `now-md`                 | 40    | after-memory-prefix     |
+ * | `active-documents`       | 45    | prepend-user-tail       |
  * | `subagent-status`        | 50    | append-user-tail        |
  * | `slack-messages`         | 60    | replace-run-messages    |
  * | `thread-focus`           | 70    | append-user-tail        |
@@ -91,6 +92,7 @@ export const DEFAULT_INJECTOR_ORDER = {
   pkbReminder: 35,
   memoryV2Static: 38,
   nowMd: 40,
+  activeDocuments: 45,
   subagentStatus: 50,
   slackMessages: 60,
   threadFocus: 70,
@@ -438,6 +440,39 @@ const nowMdInjector: Injector = {
   },
 };
 
+/**
+ * `active-documents` injector — order 45, prepend-user-tail.
+ *
+ * Injects an `<active_documents>` block listing open documents in the
+ * conversation so the assistant can target them with `document_update`
+ * instead of creating duplicates via `document_create`.
+ *
+ * Gating:
+ *  - `mode === "full"`.
+ *  - `activeDocuments` has at least one entry.
+ */
+const activeDocumentsInjector: Injector = {
+  name: "active-documents",
+  order: DEFAULT_INJECTOR_ORDER.activeDocuments,
+  async produce(ctx: TurnContext): Promise<InjectionBlock | null> {
+    const inputs = readInjectionInputs(ctx);
+    const mode = inputs.mode ?? "full";
+    if (mode !== "full") return null;
+    const docs = inputs.activeDocuments;
+    if (!docs || docs.length === 0) return null;
+    const lines = docs.map(
+      (d) =>
+        `- surface_id: "${d.surfaceId}", title: "${d.title}", words: ${d.wordCount}`,
+    );
+    const text = `<active_documents>\nThe following documents are open in this conversation. Use document_update with the surface_id to edit them — do NOT call document_create for documents that already exist.\n${lines.join("\n")}\n</active_documents>`;
+    return {
+      id: "active-documents",
+      text,
+      placement: "prepend-user-tail",
+    };
+  },
+};
+
 /**
  * `subagent-status` injector — order 50, append-user-tail.
  *
@@ -562,9 +597,6 @@ export const defaultInjectorsPlugin: Plugin = {
   manifest: {
     name: "default-injectors",
     version: "1.0.0",
-    requires: {
-      pluginRuntime: "v1",
-    },
   },
   injectors: [
     diskPressureWarningInjector,
@@ -574,6 +606,7 @@ export const defaultInjectorsPlugin: Plugin = {
     pkbReminderInjector,
     memoryV2StaticInjector,
     nowMdInjector,
+    activeDocumentsInjector,
     subagentStatusInjector,
     slackMessagesInjector,
     threadFocusInjector,

package/src/plugins/defaults/llm-call.ts

@@ -42,8 +42,6 @@ export const defaultLlmCallPlugin: Plugin = {
   manifest: {
     name: "default-llm-call",
     version: "1.0.0",
-    provides: { llmCall: "v1" },
-    requires: { pluginRuntime: "v1" },
   },
   middleware: {
     llmCall: async function defaultLlmCall(

package/src/plugins/defaults/memory-retrieval.ts

@@ -190,7 +190,6 @@ export const defaultMemoryRetrievalPlugin: Plugin = {
   manifest: {
     name: "default-memory-retrieval",
     version: "0.0.1",
-    requires: { pluginRuntime: "v1", memoryApi: "v1" },
   },
   middleware: {
     memoryRetrieval: defaultMemoryRetrievalMiddleware,

package/src/plugins/defaults/overflow-reduce.ts

@@ -156,7 +156,6 @@ export const defaultOverflowReducePlugin: Plugin = {
   manifest: {
     name: "default-overflow-reduce",
     version: "1.0.0",
-    requires: { pluginRuntime: "v1", overflowReduceApi: "v1" },
   },
   middleware: {
     overflowReduce: defaultOverflowReduceMiddleware,

package/src/plugins/defaults/persistence.ts

@@ -98,8 +98,6 @@ export const defaultPersistencePlugin: Plugin = {
   manifest: {
     name: "default-persistence",
     version: "1.0.0",
-    provides: { persistence: "v1" },
-    requires: { pluginRuntime: "v1" },
   },
   middleware: {
     persistence: passthrough,

package/src/plugins/defaults/title-generate.ts

@@ -64,11 +64,6 @@ export const defaultTitleGeneratePlugin: Plugin = {
   manifest: {
     name: "default-title-generate",
     version: "1.0.0",
-    provides: { titleGenerate: "v1" },
-    requires: {
-      pluginRuntime: "v1",
-      titleGenerateApi: "v1",
-    },
   },
 };
 

package/src/plugins/defaults/token-estimate.ts

@@ -72,8 +72,6 @@ export const defaultTokenEstimatePlugin: Plugin = {
   manifest: {
     name: "default-token-estimate",
     version: "1.0.0",
-    provides: { tokenEstimate: "v1" },
-    requires: { pluginRuntime: "v1", tokenEstimateApi: "v1" },
   },
   middleware: {
     tokenEstimate: passthrough,

package/src/plugins/defaults/tool-error.ts

@@ -90,13 +90,6 @@ export const defaultToolErrorPlugin: Plugin = {
   manifest: {
     name: "default-tool-error",
     version: "1.0.0",
-    requires: {
-      pluginRuntime: "v1",
-      toolErrorApi: "v1",
-    },
-    provides: {
-      toolError: "v1",
-    },
   },
   middleware: {
     toolError: defaultToolErrorMiddleware,

package/src/plugins/defaults/tool-execute.ts

@@ -58,8 +58,6 @@ export const defaultToolExecutePlugin: Plugin = {
   manifest: {
     name: "default-tool-execute",
     version: "1.0.0",
-    provides: { toolExecuteApi: "v1" },
-    requires: { pluginRuntime: "v1", toolExecuteApi: "v1" },
   },
   middleware: {
     toolExecute: defaultToolExecute,

package/src/plugins/defaults/tool-result-truncate.ts

@@ -55,10 +55,6 @@ export const defaultToolResultTruncatePlugin: Plugin = {
   manifest: {
     name: "default-tool-result-truncate",
     version: "1.0.0",
-    requires: {
-      pluginRuntime: "v1",
-      toolResultTruncateApi: "v1",
-    },
   },
   middleware: {
     toolResultTruncate: passthrough,

package/src/plugins/ensure-plugin-api-shim.ts

@@ -0,0 +1,96 @@
+/**
+ * Materializes the workspace-level `@vellumai/plugin-api` shim so that
+ * user plugins under `<workspaceDir>/plugins/<name>/` can resolve a
+ * standard bare import:
+ *
+ *     import { ... } from "@vellumai/plugin-api";
+ *
+ * Bun's Node-style resolution walks up from the plugin directory and
+ * finds `<workspaceDir>/node_modules/@vellumai/plugin-api/` — a tiny
+ * shim package whose `index.js` re-binds the plugin-api namespace that
+ * the assistant already loaded into its module graph (and parked on
+ * `globalThis` under {@link PLUGIN_API_REGISTRY_KEY}).
+ *
+ * This avoids duplicating the plugin-api package per plugin while still
+ * letting the assistant's compiled binary be the single source of truth
+ * for the public API. The runtime mechanism is uniform across:
+ *   - JIT / Docker: plugin-api loads from source, shim re-binds via globalThis
+ *   - `bun --compile` (macOS bare-metal): plugin-api ships inside the
+ *     binary's regular code graph (Bun's bundler resolves
+ *     `import * as pluginApi from "../plugin-api/index.js"` at compile
+ *     time, inlining relative imports), shim re-binds via globalThis
+ *
+ * Idempotent: safe to call repeatedly. The shim's contents are
+ * deterministic given the runtime export list — fresh exports (added in
+ * later PRs) automatically expand the generated `index.js`.
+ *
+ * Called from {@link loadUserPlugins} at the top of its body so the
+ * ordering constraint (shim exists before any plugin's
+ * `import "@vellumai/plugin-api"` is parsed) is enforced by code, not
+ * by a docstring in `lifecycle.ts`.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import assistantPkg from "../../package.json" with { type: "json" };
+import {
+  PLUGIN_API_EXPORTS,
+  PLUGIN_API_REGISTRY_KEY,
+} from "../embedded/plugin-api.js";
+import { getLogger } from "../util/logger.js";
+import { getWorkspaceDir } from "../util/platform.js";
+
+const log = getLogger("plugin-api-shim");
+
+const PACKAGE_NAME = "@vellumai/plugin-api";
+
+/**
+ * Build the body of the workspace shim's `index.js`. Exported so the
+ * smoke test can assert against the same generator the daemon uses.
+ */
+export function buildShimSource(
+  exports: readonly string[] = PLUGIN_API_EXPORTS,
+  registryKey: symbol = PLUGIN_API_REGISTRY_KEY,
+): string {
+  const description = registryKey.description ?? "";
+  const lines = [
+    `const api = globalThis[Symbol.for(${JSON.stringify(description)})];`,
+    ...exports.map((name) => `export const ${name} = api.${name};`),
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+export async function ensurePluginApiShim(opts?: {
+  /** Override the workspace root. Defaults to `getWorkspaceDir()`. */
+  workspaceDir?: string;
+}): Promise<void> {
+  const workspaceDir = opts?.workspaceDir ?? getWorkspaceDir();
+  const shimDir = join(workspaceDir, "node_modules", PACKAGE_NAME);
+
+  await mkdir(shimDir, { recursive: true });
+
+  const indexJs = buildShimSource();
+  const packageJson = `${JSON.stringify(
+    {
+      name: PACKAGE_NAME,
+      version: assistantPkg.version,
+      type: "module",
+      main: "./index.js",
+    },
+    null,
+    2,
+  )}\n`;
+
+  await writeFile(join(shimDir, "index.js"), indexJs);
+  await writeFile(join(shimDir, "package.json"), packageJson);
+
+  log.info(
+    {
+      shimDir,
+      exports: PLUGIN_API_EXPORTS,
+      version: assistantPkg.version,
+    },
+    "plugin-api shim materialized",
+  );
+}

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];
+}