@vellumai/assistant 0.8.1 → 0.8.2

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
@@ -40,8 +43,10 @@ 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 { getLogger } from "../util/logger.js";
 import { registerPlugin } from "./registry.js";
 import type {
@@ -52,6 +57,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 +68,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 +81,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();
 
@@ -213,12 +217,49 @@ 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);
@@ -244,16 +285,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 +310,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 ──────────────────────────────────────────────────────────────
 
 /**

package/src/plugins/types.ts

@@ -42,7 +42,11 @@ import type {
   ToolDefinition,
 } from "../providers/types.js";
 import type { SkillRoute } from "../runtime/skill-route-registry.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../tools/types.js";
+import type {
+  PluginTool,
+  ToolContext,
+  ToolExecutionResult,
+} from "../tools/types.js";
 import { AssistantError, ErrorCode } from "../util/errors.js";
 
 // ─── Manifest ────────────────────────────────────────────────────────────────
@@ -60,22 +64,13 @@ import { AssistantError, ErrorCode } from "../util/errors.js";
 export interface PluginManifest {
   /** Unique plugin identifier (kebab-case). Duplicate names fail registration. */
   name: string;
-  /** Plugin version (semver). Informational — the registry compares
-   *  capability versions via `requires`, not this field. */
-  version: string;
   /**
-   * Capabilities this plugin exposes to other plugins.
-   *
-   * **Reserved for future cross-plugin composition — not currently consumed
-   * by any runtime code.** The field is declared so future cross-plugin work
-   * can land without a manifest version bump, but today nothing reads it and
-   * plugins must not depend on it for capability discovery. See
-   * `assistant/docs/plugins.md` (Cross-plugin communication) for the
-   * rationale.
+   * Plugin version (semver). Informational. Host-compat negotiation lives
+   * in the plugin's `package.json` `peerDependencies["@vellumai/plugin-api"]`
+   * range — checked by the external-plugin loader against the assistant's
+   * own version at load time.
    */
-  provides?: Record<string, string>;
-  /** Capabilities this plugin needs from the assistant runtime. */
-  requires: Record<string, string>;
+  version: string;
   /** Credential keys the plugin needs resolved before `init()` runs. */
   requiresCredential?: string[];
   /**
@@ -844,6 +839,17 @@ export interface TurnInjectionInputs {
    * knows no human is present to answer clarification questions.
    */
   readonly isNonInteractive?: boolean;
+  /**
+   * Active documents open in this conversation — surfaced by the
+   * `active-documents` injector so the assistant can target existing docs
+   * with `document_update` instead of creating duplicates.
+   */
+  readonly activeDocuments?: ReadonlyArray<{
+    surfaceId: string;
+    title: string;
+    wordCount: number;
+    updatedAt: number;
+  }> | null;
 }
 
 export interface DiskPressureInjectionContext {
@@ -995,15 +1001,16 @@ export interface Injector {
 // catalog-discoverable skills today.
 
 /**
- * Tool registration contributed by a plugin. Uses the canonical {@link Tool}
- * interface from the tool registry — the bootstrap stamps `origin: "plugin"`
- * and `ownerPluginId: <plugin.name>` before handing the batch to
- * `registerPluginTools`, which keeps plugin ref-counts and conflict detection
- * in a namespace disjoint from real skills. Plugin authors supply the
- * functional fields (`name`, `description`, `getDefinition`, `execute`, etc.)
- * and leave the ownership metadata to the bootstrap to set authoritatively.
+ * Tool registration contributed by a plugin. Uses the narrow
+ * {@link PluginTool} shape — plugin authors declare functional fields
+ * (`name`, `description`, `input_schema`, `execute`, etc.) and leave category
+ * / ownership metadata to the bootstrap, which stamps `category: "plugin"`,
+ * `origin: "plugin"`, and `ownerPluginId: <plugin.name>` before handing the
+ * batch to `registerPluginTools`. The registration boundary synthesizes
+ * `getDefinition()` from `{name, description, input_schema}` so the canonical
+ * {@link Tool} interface used by the internal registry stays unchanged.
  */
-export type PluginToolRegistration = Tool;
+export type PluginToolRegistration = PluginTool;
 /**
  * HTTP route registration contributed by a plugin. Plugins express routes as
  * {@link SkillRoute} values — the same shape the skill-route registry
@@ -1075,9 +1082,7 @@ export interface PluginSkillRegistration {
  * 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>;
+export type PluginHookFn<TCtx = unknown> = (ctx: TCtx) => Promise<TCtx | void>;
 
 /**
  * Map of lifecycle hooks contributed by a plugin. Keys match file

package/src/plugins/user-loader.ts

@@ -49,7 +49,8 @@ import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { getLogger } from "../util/logger.js";
-import { getWorkspaceDir } from "../util/platform.js";
+import { getWorkspacePluginsDir } from "../util/platform.js";
+import { ensurePluginApiShim } from "./ensure-plugin-api-shim.js";
 import { loadExternalPlugin } from "./external-plugin-loader.js";
 import { closeRegistration } from "./registry.js";
 
@@ -93,7 +94,25 @@ export async function loadUserPlugins(
 ): Promise<void> {
   const importTimeoutMs = options.importTimeoutMs ?? USER_PLUGIN_IMPORT_TIMEOUT_MS;
 
-  const pluginsDir = join(getWorkspaceDir(), "plugins");
+  // Materialize the workspace-level `@vellumai/plugin-api` shim *before*
+  // we dynamic-import any user plugins. The shim file must exist on disk
+  // before the first plugin's `import "@vellumai/plugin-api"` is parsed.
+  //
+  // Wrapped in try/catch because per `AGENTS.md` the daemon must never
+  // block startup. A shim-write failure (ENOSPC, read-only workspace,
+  // perms) is logged and we continue — plugins that try to import the
+  // public specifier will fail individually inside the per-plugin import
+  // loop below, which is already isolated.
+  try {
+    await ensurePluginApiShim();
+  } catch (err) {
+    log.warn(
+      { err },
+      "loadUserPlugins: plugin-api shim materialization failed — continuing with degraded plugin support",
+    );
+  }
+
+  const pluginsDir = getWorkspacePluginsDir();
 
   if (!existsSync(pluginsDir)) {
     // The clean-install case. Closing the registration window keeps the

package/src/proactive-artifact/aux-message-injector.ts

@@ -8,6 +8,10 @@
 
 import { createAssistantMessage } from "../agent/message-types.js";
 import { findConversation } from "../daemon/conversation-store.js";
+import {
+  conversationMessagesSyncTag,
+  SYNC_TAGS,
+} from "../daemon/message-types/sync.js";
 import { addMessage } from "../memory/conversation-crud.js";
 import type { BroadcastFn } from "../notifications/adapters/macos.js";
 import { getLogger } from "../util/logger.js";
@@ -71,4 +75,11 @@ export async function injectAuxAssistantMessage(params: {
     type: "conversation_list_invalidated",
     reason: "reordered",
   });
+  params.broadcastMessage({
+    type: "sync_changed",
+    tags: [
+      SYNC_TAGS.conversationsList,
+      conversationMessagesSyncTag(params.conversationId),
+    ],
+  });
 }