@vellumai/assistant 0.10.2-dev.202606250916.8422b74 → 0.10.2-dev.202606251257.2eba8a4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.2-dev.202606250916.8422b74",
+  "version": "0.10.2-dev.202606251257.2eba8a4",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/mtime-cache.test.ts

@@ -7,7 +7,14 @@
  * cache miss (changed mtime → re-import), plugin deletion (eviction),
  * and hook collection across multiple plugins.
  */
-import { mkdirSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  utimesSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
@@ -27,6 +34,11 @@ import {
   populateCacheAtBoot,
   resetPluginCacheForTests,
 } from "../plugins/mtime-cache.js";
+import {
+  getAllToolDefinitions,
+  getPluginToolDefinitions,
+  getToolOwner,
+} from "../tools/registry.js";
 
 // ─── Test fixtures ───────────────────────────────────────────────────────────
 
@@ -514,3 +526,120 @@ describe("workspace hooks (<workspace>/hooks/)", () => {
     expect(rf(sentinel, "utf8")).toBe("x");
   });
 });
+
+// ─── Runtime activation (hot-reload without a daemon restart) ──────────────────
+
+/**
+ * Write a hook that appends `token` to `markerPath` each time it runs, so a
+ * test can count how many times `init`/`shutdown` fired.
+ */
+function writeMarkerHook(
+  dir: string,
+  hookName: string,
+  markerPath: string,
+  token: string,
+): void {
+  writeHook(
+    dir,
+    hookName,
+    `import { appendFileSync } from "node:fs";\nexport default () => { appendFileSync(${JSON.stringify(markerPath)}, ${JSON.stringify(`${token}\n`)}); };`,
+  );
+}
+
+const TOOL_SRC = (name: string) =>
+  `export default { name: ${JSON.stringify(name)}, description: "test", parameters: { type: "object", properties: {} } };`;
+
+/**
+ * Simulate the per-turn plugin hook dispatch that drives runtime reconciliation
+ * in production: any `getUserHooksFor` call runs `scanPlugins`, which activates
+ * newly present plugins and deactivates removed ones. The hook name is
+ * irrelevant — the scan runs regardless of whether a plugin defines that hook.
+ */
+async function triggerScan(): Promise<void> {
+  await getUserHooksFor("user-prompt-submit");
+}
+
+describe("plugin runtime activation", () => {
+  test("a plugin installed after boot becomes live on the next scan", async () => {
+    await populateCacheAtBoot(); // empty plugins dir
+    expect(getAllToolDefinitions().some((t) => t.name === "late-tool")).toBe(
+      false,
+    );
+
+    const dir = freshPluginDir("late-plugin");
+    writePackageJson(dir, { ...SIMPLE_PKG, name: "late-plugin" });
+    writeTool(dir, "late-tool", TOOL_SRC("late-tool"));
+    const initMarker = join(ROOT, "late-init.log");
+    writeMarkerHook(dir, "init", initMarker, "init");
+
+    await triggerScan();
+
+    // Registered into the global registry as a plugin-owned tool, and exposed
+    // to the per-turn resolver via getPluginToolDefinitions().
+    expect(getToolOwner("late-tool")).toEqual({
+      kind: "plugin",
+      id: "late-plugin",
+    });
+    expect(getAllToolDefinitions().some((t) => t.name === "late-tool")).toBe(
+      true,
+    );
+    expect(getPluginToolDefinitions().some((t) => t.name === "late-tool")).toBe(
+      true,
+    );
+    // init ran exactly once.
+    expect(readFileSync(initMarker, "utf8").trim().split("\n")).toHaveLength(1);
+  });
+
+  test("activation is idempotent — repeated scans do not re-run init", async () => {
+    const dir = freshPluginDir("idem-plugin");
+    writePackageJson(dir, { ...SIMPLE_PKG, name: "idem-plugin" });
+    writeTool(dir, "idem-tool", TOOL_SRC("idem-tool"));
+    const initMarker = join(ROOT, "idem-init.log");
+    writeMarkerHook(dir, "init", initMarker, "init");
+
+    await populateCacheAtBoot();
+    await triggerScan();
+    await triggerScan();
+
+    expect(readFileSync(initMarker, "utf8").trim().split("\n")).toHaveLength(1);
+    // Registered exactly once (no refcount inflation from re-registration).
+    expect(getToolOwner("idem-tool")).toEqual({
+      kind: "plugin",
+      id: "idem-plugin",
+    });
+  });
+
+  test("removing a plugin directory deactivates it (unregister + shutdown)", async () => {
+    const dir = freshPluginDir("temp-plugin");
+    writePackageJson(dir, { ...SIMPLE_PKG, name: "temp-plugin" });
+    writeTool(dir, "temp-tool", TOOL_SRC("temp-tool"));
+    const shutdownMarker = join(ROOT, "temp-shutdown.log");
+    writeMarkerHook(dir, "shutdown", shutdownMarker, "bye");
+
+    await populateCacheAtBoot();
+    expect(getToolOwner("temp-tool")?.kind).toBe("plugin");
+
+    rmSync(dir, { recursive: true, force: true });
+    await triggerScan();
+
+    expect(getToolOwner("temp-tool")).toBeUndefined();
+    expect(getPluginToolDefinitions().some((t) => t.name === "temp-tool")).toBe(
+      false,
+    );
+    expect(existsSync(shutdownMarker)).toBe(true);
+  });
+
+  test("disabling a plugin at runtime tears down its tools", async () => {
+    const dir = freshPluginDir("disable-plugin");
+    writePackageJson(dir, { ...SIMPLE_PKG, name: "disable-plugin" });
+    writeTool(dir, "disable-tool", TOOL_SRC("disable-tool"));
+
+    await populateCacheAtBoot();
+    expect(getToolOwner("disable-tool")?.kind).toBe("plugin");
+
+    writeFileSync(join(dir, ".disabled"), "");
+    await triggerScan();
+
+    expect(getToolOwner("disable-tool")).toBeUndefined();
+  });
+});

package/src/__tests__/plugin-bootstrap.test.ts

@@ -2,7 +2,7 @@
  * Tests for plugin bootstrap (PR 14).
  *
  * Covers:
- * - A noop `init()` fires with a valid `PluginInitContext` that exposes every
+ * - A noop `init()` fires with a valid `InitContext` that exposes every
  *   documented field.
  * - Version-mismatch registration fails with an error that names the plugin
  *   (the registry enforces this at `registerPlugin` time, so bootstrap never
@@ -29,7 +29,7 @@ import {
   registerPlugin,
   resetPluginRegistryForTests,
 } from "../plugins/registry.js";
-import { type Plugin, type PluginInitContext } from "../plugins/types.js";
+import { type InitContext, type Plugin } from "../plugins/types.js";
 import { APP_VERSION } from "../version.js";
 import { setOverridesForTesting } from "./feature-flag-test-helpers.js";
 
@@ -51,7 +51,7 @@ function buildPlugin(
   name: string,
   extras: Partial<Omit<Plugin, "manifest" | "hooks">> & {
     hooks?: Plugin["hooks"];
-    init?: (ctx: PluginInitContext) => Promise<void>;
+    init?: (ctx: InitContext) => Promise<void>;
     onShutdown?: () => Promise<void>;
   } = {},
   options: {
@@ -98,8 +98,8 @@ describe("plugin bootstrap", () => {
     await rm(TEST_WORKSPACE_DIR, { recursive: true, force: true });
   });
 
-  test("noop plugin: init fires with a fully-populated PluginInitContext", async () => {
-    let received: PluginInitContext | undefined;
+  test("noop plugin: init fires with a fully-populated InitContext", async () => {
+    let received: InitContext | undefined;
     const plugin: Plugin = buildPlugin("alpha", {
       async init(ctx) {
         received = ctx;

package/src/__tests__/plugin-route-contribution.test.ts

@@ -38,7 +38,7 @@ import {
   registerPlugin,
   resetPluginRegistryForTests,
 } from "../plugins/registry.js";
-import type { Plugin, PluginInitContext } from "../plugins/types.js";
+import type { InitContext, Plugin } from "../plugins/types.js";
 import {
   matchSkillRoute,
   resetSkillRoutesForTests,
@@ -64,7 +64,7 @@ function buildPlugin(
   name: string,
   extras: Partial<Omit<Plugin, "manifest" | "hooks">> & {
     hooks?: Plugin["hooks"];
-    init?: (ctx: PluginInitContext) => Promise<void>;
+    init?: (ctx: InitContext) => Promise<void>;
     onShutdown?: () => Promise<void>;
   } = {},
 ): Plugin {

package/src/__tests__/plugin-tool-contribution.test.ts

@@ -33,7 +33,7 @@ import {
   registerPlugin,
   resetPluginRegistryForTests,
 } from "../plugins/registry.js";
-import type { Plugin, PluginInitContext } from "../plugins/types.js";
+import type { InitContext, Plugin } from "../plugins/types.js";
 import {
   __clearRegistryForTesting,
   __resetRegistryForTesting,
@@ -82,7 +82,7 @@ function buildPlugin(
   name: string,
   extras: Partial<Omit<Plugin, "manifest" | "hooks">> & {
     hooks?: Plugin["hooks"];
-    init?: (ctx: PluginInitContext) => Promise<void>;
+    init?: (ctx: InitContext) => Promise<void>;
     onShutdown?: () => Promise<void>;
   } = {},
 ): Plugin {

package/src/__tests__/plugin-types.test.ts

@@ -13,9 +13,9 @@ import { describe, expect, test } from "bun:test";
 import type { TrustContext } from "../daemon/trust-context.js";
 import { RiskLevel } from "../permissions/types.js";
 import {
+  type InitContext,
   type Plugin,
   PluginExecutionError,
-  type PluginInitContext,
   type PluginManifest,
   type TurnContext,
 } from "../plugins/types.js";
@@ -57,7 +57,7 @@ describe("plugin core types", () => {
     const plugin = {
       manifest,
       hooks: {
-        async init(ctx: PluginInitContext) {
+        async init(ctx: InitContext) {
           // Touch every field so refactors that rename any of them break here.
           void ctx.config;
           void ctx.logger;

package/src/cli/commands/plugins.ts

@@ -161,7 +161,6 @@ Examples:
               console.log(
                 `Installed plugin "${result.name}" (${result.fileCount} file${result.fileCount === 1 ? "" : "s"})${pinned} → ${result.target}`,
               );
-              console.log("Restart the assistant to pick up the new plugin.");
             } catch (err) {
               if (err instanceof PluginAlreadyInstalledError) {
                 console.error(`${err.message}\nPass --force to overwrite.`);
@@ -245,9 +244,7 @@ Examples:
 
       plugins
         .command("list")
-        .description(
-          "List plugins installed in your workspace.",
-        )
+        .description("List plugins installed in your workspace.")
         .option("--json", "Emit machine-readable JSON instead of a table")
         .option(
           "--all",
@@ -276,8 +273,7 @@ Examples:
             const nameW = Math.max(4, ...rows.map((r) => r.name.length));
             const versionW = Math.max(7, ...rows.map((r) => r.version.length));
             const sourceW = Math.max(6, ...rows.map((r) => r.source.length));
-            const pad = (s: string, w: number) =>
-              s + " ".repeat(w - s.length);
+            const pad = (s: string, w: number) => s + " ".repeat(w - s.length);
             console.log(
               `${pad("NAME", nameW)}  ${pad("VERSION", versionW)}  ${pad("SOURCE", sourceW)}  STATUS`,
             );
@@ -294,9 +290,7 @@ Examples:
             console.log(
               `${all.length} plugin${all.length === 1 ? "" : "s"} ` +
                 `(${userCount} user, ${defaultCount} default` +
-                (disabledCount > 0
-                  ? `, ${disabledCount} disabled`
-                  : "") +
+                (disabledCount > 0 ? `, ${disabledCount} disabled` : "") +
                 `).`,
             );
             return;
@@ -540,7 +534,6 @@ Examples:
             console.log(
               `Uninstalled plugin "${result.name}" from ${result.target}`,
             );
-            console.log("Restart the assistant to drop the plugin.");
           } catch (err) {
             if (err instanceof InvalidPluginNameError) {
               console.error(err.message);
@@ -561,15 +554,13 @@ Examples:
       plugins
         .command("disable <name>")
         .description(
-          "Disable a plugin by creating a .disabled sentinel file. Works for both user-installed and default plugins. Restart the assistant for the change to take effect.",
+          "Disable a plugin by creating a .disabled sentinel file. Works for both user-installed and default plugins. Takes effect immediately in a running assistant.",
         )
         .action((name: string) => {
           try {
             const result = disablePlugin(name);
             log.info({ name: result.name }, "plugin disabled");
-            console.log(
-              `Disabled plugin "${result.name}". Restart the assistant for the change to take effect.`,
-            );
+            console.log(`Disabled plugin "${result.name}".`);
           } catch (err) {
             if (
               err instanceof PluginAlreadyInStateException ||
@@ -589,15 +580,13 @@ Examples:
       plugins
         .command("enable <name>")
         .description(
-          "Re-enable a disabled plugin by removing the .disabled sentinel file. Restart the assistant for the change to take effect.",
+          "Re-enable a disabled plugin by removing the .disabled sentinel file. Takes effect immediately.",
         )
         .action((name: string) => {
           try {
             const result = enablePlugin(name);
             log.info({ name: result.name }, "plugin enabled");
-            console.log(
-              `Enabled plugin "${result.name}". Restart the assistant for the change to take effect.`,
-            );
+            console.log(`Enabled plugin "${result.name}".`);
           } catch (err) {
             if (
               err instanceof PluginAlreadyInStateException ||

package/src/daemon/__tests__/conversation-tool-setup-exclude.test.ts

@@ -12,6 +12,7 @@ import type { ToolDefinition } from "../../providers/types.js";
 import {
   __clearRegistryForTesting,
   registerMcpTools,
+  registerPluginTools,
 } from "../../tools/registry.js";
 import type { Tool } from "../../tools/types.js";
 import { createResolveToolsCallback } from "../conversation-tool-setup.js";
@@ -33,6 +34,14 @@ function mcpTool(name: string): Tool {
   } as unknown as Tool;
 }
 
+function pluginTool(name: string): Tool {
+  return {
+    name,
+    description: name,
+    input_schema: def(name).input_schema,
+  } as unknown as Tool;
+}
+
 function makeCtx(
   overrides: Partial<SkillProjectionContext> = {},
 ): SkillProjectionContext {
@@ -139,6 +148,32 @@ describe("createResolveToolsCallback — config.tools.exclude", () => {
     expect(names).toEqual(["recall", "file_read"]);
   });
 
+  test("plugin tool registered after resolver creation is picked up next turn", () => {
+    getConfigSpy = withExclude([]);
+    // Resolver created when only a core tool exists — no plugin yet, mirroring
+    // a conversation that started before the plugin was installed.
+    const resolver = createResolveToolsCallback([def("file_read")], makeCtx());
+    expect(resolver!([]).map((d) => d.name)).toEqual(["file_read"]);
+
+    // A plugin installed + activated mid-conversation lands its tool in the
+    // registry. The resolver must surface it on the next turn without the
+    // conversation being recreated (the plugin equivalent of `mcp reload`).
+    registerPluginTools("late-plugin", [pluginTool("admin_copilot_prefs")]);
+    const names = resolver!([]).map((d) => d.name);
+    expect(names).toContain("admin_copilot_prefs");
+    expect(names).toContain("file_read");
+  });
+
+  test("excluded plugin tool is omitted from the resolved tool list", () => {
+    registerPluginTools("ex-plugin", [pluginTool("ex_plugin_tool")]);
+    getConfigSpy = withExclude(["ex_plugin_tool"]);
+    const resolver = createResolveToolsCallback(
+      [def("file_read"), def("ex_plugin_tool")],
+      makeCtx(),
+    );
+    expect(resolver!([]).map((d) => d.name)).toEqual(["file_read"]);
+  });
+
   test("excluded tool stays excluded under disk-pressure cleanup mode", () => {
     // `bash` is a cleanup-safe tool and would normally survive cleanup mode;
     // the exclude filter must still suppress it.

package/src/daemon/conversation-tool-setup.ts

@@ -24,6 +24,7 @@ import { registerConversationSender } from "../tools/browser/browser-screencast.
 import type { ToolExecutor } from "../tools/executor.js";
 import {
   getMcpToolDefinitions,
+  getPluginToolDefinitions,
   getTool,
   getWorkspaceToolDefinitions,
   getWorkspaceToolNames,
@@ -674,14 +675,21 @@ export function createResolveToolsCallback(
 ): ((history: Message[]) => ToolDefinition[]) | undefined {
   if (toolDefs.length === 0) return undefined;
 
-  // Separate the initial tool defs into core (stable) and the two dynamic
-  // categories (MCP, workspace). We keep core tools from the snapshot and
-  // re-read MCP + workspace tools from the registry each turn.
+  // Separate the initial tool defs into core (stable) and the dynamic
+  // categories (MCP, workspace, plugin). We keep core tools from the snapshot
+  // and re-read the dynamic categories from the registry each turn. They differ
+  // downstream: plugin tools flow through the same context filter + subagent
+  // allowlist as core, while MCP and workspace tools are added raw.
   const initialMcpDefs = getMcpToolDefinitions();
+  const initialPluginDefs = getPluginToolDefinitions();
   const initialMcpNames = new Set(initialMcpDefs.map((d) => d.name));
   const initialWorkspaceNames = new Set(getWorkspaceToolNames());
+  const initialPluginNames = new Set(initialPluginDefs.map((d) => d.name));
   const coreToolDefs = toolDefs.filter(
-    (d) => !initialMcpNames.has(d.name) && !initialWorkspaceNames.has(d.name),
+    (d) =>
+      !initialMcpNames.has(d.name) &&
+      !initialWorkspaceNames.has(d.name) &&
+      !initialPluginNames.has(d.name),
   );
   log.debug(
     {
@@ -689,6 +697,8 @@ export function createResolveToolsCallback(
       mcpCount: initialMcpDefs.length,
       mcpTools: initialMcpDefs.map((d) => d.name),
       workspaceCount: initialWorkspaceNames.size,
+      pluginCount: initialPluginDefs.length,
+      pluginTools: initialPluginDefs.map((d) => d.name),
     },
     "Conversation tool resolver initialized",
   );
@@ -709,11 +719,18 @@ export function createResolveToolsCallback(
     // serialized, so the registry settles for a subsequent turn to read.
     void loadWorkspaceTools();
 
-    // Filter core tools based on current conversation context so that tools
-    // irrelevant to this turn (e.g. UI tools when no client is connected)
+    // Re-read plugin tool definitions from the registry each turn so a plugin
+    // installed/removed at runtime (activated by the per-turn scan in
+    // `plugins/mtime-cache.ts`) is picked up without recreating the
+    // conversation. Plugin tools share core's context filter + allowlist path,
+    // so combine them with the core snapshot before filtering.
+    const currentPluginDefs = getPluginToolDefinitions();
+
+    // Filter core + plugin tools based on current conversation context so that
+    // tools irrelevant to this turn (e.g. UI tools when no client is connected)
     // are omitted from the definitions sent to the provider.
-    const filteredCoreDefs = coreToolDefs.filter((d) =>
-      isToolActiveForContext(d.name, ctx),
+    const filteredCoreDefs = [...coreToolDefs, ...currentPluginDefs].filter(
+      (d) => isToolActiveForContext(d.name, ctx),
     );
 
     // When the conversation is acting as a subagent, restrict core tools to

package/src/daemon/external-plugins-bootstrap.ts

@@ -24,7 +24,7 @@
  *    (Zod schemas with `.parse()` are supported; anything else is passed
  *    through untouched).
  * 5. Creates `<workspaceDir>/plugins-data/<plugin>/` on demand for per-plugin
- *    writable state and exposes it via {@link PluginInitContext.pluginStorageDir}.
+ *    writable state and exposes it via {@link InitContext.pluginStorageDir}.
  * 6. For each surviving plugin, registers its contributed tools and routes
  *    into their global registries via {@link registerPluginTools} and
  *    {@link registerSkillRoute}. Contributions land BEFORE `init()` so
@@ -64,7 +64,7 @@ import { getRegisteredPlugins, unregisterPlugin } from "../plugins/registry.js";
 import {
   type Plugin,
   PluginExecutionError,
-  type PluginShutdownContext,
+  type ShutdownContext,
 } from "../plugins/types.js";
 import { loadUserPlugins } from "../plugins/user-loader.js";
 import {
@@ -222,8 +222,8 @@ export async function bootstrapPlugins(): Promise<void> {
   // Shutdown context is identical for every plugin in this boot — construct
   // once and reuse across the per-plugin teardown and the normal shutdown
   // hook below. Only `assistantVersion` is exposed today; future additions
-  // live on {@link PluginShutdownContext}.
-  const shutdownContext: PluginShutdownContext = {
+  // live on {@link ShutdownContext}.
+  const shutdownContext: ShutdownContext = {
     assistantVersion: APP_VERSION,
   };
 
@@ -407,7 +407,7 @@ async function initializePlugin(
 async function teardownPlugin(
   active: ActivePlugin,
   reason: string,
-  shutdownContext: PluginShutdownContext,
+  shutdownContext: ShutdownContext,
 ): Promise<void> {
   const { plugin, routeHandles } = active;
   const name = plugin.manifest.name;

package/src/hooks/hook-loader.ts

@@ -25,9 +25,9 @@ import { join } from "node:path";
 import { getConfig } from "../config/loader.js";
 import { HOOKS } from "../plugin-api/constants.js";
 import type {
-  PluginHookFn,
-  PluginInitContext,
-  PluginShutdownContext,
+  HookFunction,
+  InitContext,
+  ShutdownContext,
 } from "../plugin-api/types.js";
 import { listSurfaceDir } from "../plugins/external-plugin-loader.js";
 import { getMtime, importWithTimeout } from "../plugins/surface-import.js";
@@ -53,7 +53,7 @@ export const WORKSPACE_HOOKS_OWNER = "__workspace__";
  * mtime changes, the hook is re-imported and the entry is replaced.
  */
 interface CachedHook {
-  readonly hook: PluginHookFn;
+  readonly hook: HookFunction;
   /** mtimeMs of the source file this hook was imported from. */
   readonly sourceMtime: number;
 }
@@ -83,7 +83,7 @@ async function resolveCachedHook<TCtx>(
   ownerName: string,
   hookName: string,
   filePath: string,
-): Promise<PluginHookFn<TCtx> | undefined> {
+): Promise<HookFunction<TCtx> | undefined> {
   const key = hookKey(ownerName, hookName);
   const currentMtime = getMtime(filePath);
 
@@ -94,7 +94,7 @@ async function resolveCachedHook<TCtx>(
     cached.sourceMtime === currentMtime &&
     currentMtime > 0
   ) {
-    return cached.hook as PluginHookFn<TCtx>;
+    return cached.hook as HookFunction<TCtx>;
   }
 
   // Cache miss — re-import.
@@ -105,7 +105,7 @@ async function resolveCachedHook<TCtx>(
   }
 
   try {
-    const hook = await importWithTimeout<PluginHookFn>(filePath);
+    const hook = await importWithTimeout<HookFunction>(filePath);
     if (hook === undefined || typeof hook !== "function") {
       log.error(
         { plugin: ownerName, hook: hookName, path: filePath },
@@ -114,7 +114,7 @@ async function resolveCachedHook<TCtx>(
       return undefined;
     }
     hookCache.set(key, { hook, sourceMtime: currentMtime });
-    return hook as PluginHookFn<TCtx>;
+    return hook as HookFunction<TCtx>;
   } catch (err) {
     log.error(
       { err, plugin: ownerName, hook: hookName, path: filePath },
@@ -141,8 +141,8 @@ async function resolveCachedHook<TCtx>(
 export async function collectUserHooks<TCtx = unknown>(
   hookName: string,
   pluginDirs: Iterable<readonly [string, string]>,
-): Promise<PluginHookFn<TCtx>[]> {
-  const out: PluginHookFn<TCtx>[] = [];
+): Promise<HookFunction<TCtx>[]> {
+  const out: HookFunction<TCtx>[] = [];
 
   for (const [pluginDir, pluginName] of pluginDirs) {
     const hookFile = listSurfaceDir(join(pluginDir, "hooks")).find(
@@ -191,7 +191,7 @@ export async function preImportHooksDir(
     if (currentMtime === 0) continue;
 
     try {
-      const hook = await importWithTimeout<PluginHookFn>(file.path);
+      const hook = await importWithTimeout<HookFunction>(file.path);
       if (hook !== undefined && typeof hook === "function") {
         hookCache.set(key, { hook, sourceMtime: currentMtime });
       }
@@ -233,7 +233,7 @@ export async function runInitHook(ownerName: string): Promise<void> {
   if (initHookEntry === undefined) return;
 
   try {
-    const initContext: PluginInitContext = {
+    const initContext: InitContext = {
       config: getConfig().plugins?.[ownerName],
       logger: log.child({ plugin: ownerName }),
       pluginStorageDir: ensureHookStorageDir(ownerName),
@@ -256,7 +256,7 @@ export async function runInitHook(ownerName: string): Promise<void> {
  */
 export async function runShutdownHook(
   ownerName: string,
-  context: PluginShutdownContext,
+  context: ShutdownContext,
   reason: string,
 ): Promise<void> {
   const shutdownHookEntry = hookCache.get(hookKey(ownerName, HOOKS.SHUTDOWN));

package/src/plugin-api/index.ts

@@ -37,8 +37,8 @@
  *   (optionally overriding the profile) and run inference through the
  *   workspace's configured profiles and credentials — no plugin-supplied API key
  *
- * - {@link PluginInitContext} — passed to `init` hook at bootstrap
- * - {@link PluginShutdownContext} — passed to `shutdown` hook at teardown
+ * - {@link InitContext} — passed to `init` hook at bootstrap
+ * - {@link ShutdownContext} — 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 PostCompactContext} — passed to `post-compact` hook, fired after
@@ -55,7 +55,7 @@
  * - {@link PostModelCallContext} — passed to `post-model-call` hook, fired at
  *   every model-call outcome (a finalized reply or a provider rejection) to
  *   transform content and decide whether to retry
- * - {@link PluginHookFn} — signature every lifecycle hook implements
+ * - {@link HookFunction} — signature every lifecycle hook implements
  * - {@link PluginLogger} — pino-compatible logger shape on the contexts
  * - {@link ToolDefinition} — author-facing tool spec (default-export shape
  *   for both plugin tool files and workspace tool files)
@@ -98,16 +98,16 @@ export type {
 export type { LLMCallSite } from "../config/schemas/llm.js";
 export type {
   AgentLoopExitReason,
+  HookFunction,
+  InitContext,
   ModelProfileInfo,
-  PluginHookFn,
-  PluginInitContext,
   PluginLogger,
-  PluginShutdownContext,
   PostCompactContext,
   PostModelCallContext,
   PostModelCallDecision,
   PostToolUseContext,
   PreModelCallContext,
+  ShutdownContext,
   StopContext,
   ToolContext,
   ToolDefinition,