@vellumai/assistant 0.8.7-dev.202606052232.2ddc989 → 0.8.8

package/src/plugins/user-loader.ts

@@ -1,23 +1,39 @@
 /**
- * User plugin loader — discovers plugins under `<workspaceDir>/plugins/*` and
- * registers each one.
+ * User plugin loader — discovers plugins under `<workspaceDir>/plugins/*` via
+ * one of two paths, gated by the contents of each candidate directory.
  *
- * A plugin directory is recognized by a `package.json` manifest. The harness
- * delegates to {@link loadExternalPlugin}, which builds a `Plugin` from the
- * directory's interface dirs (`hooks/`, `tools/`) and registers it directly.
- * The full convention lives in
- * `assistant/src/plugins/external-plugin-loader.ts`. A directory with no
- * `package.json` is skipped silently.
+ * **External plugin framework path** (`package.json` present **and** no
+ * `register.{ts,js}`): the harness delegates to {@link loadExternalPlugin},
+ * which builds a `Plugin` from the directory's interface dirs (`hooks/`,
+ * `tools/`) and registers it directly. This path is opt-in by the plugin
+ * author and currently experimental — see
+ * `assistant/src/plugins/external-plugin-loader.ts` for the full
+ * convention.
+ *
+ * **Legacy path** (`register.{ts,js}` present): the file is dynamic-imported
+ * and expected to call {@link registerPlugin} at import time as a side
+ * effect, populating the registry before {@link bootstrapPlugins} runs.
+ *
+ * The legacy path takes precedence when a directory contains both
+ * `package.json` and `register.{ts,js}` — a migration-friendly default
+ * that keeps existing plugins (including the in-repo `examples/plugins/echo`
+ * reference) working unchanged while we iterate the external-plugin
+ * convention. A directory matching neither path is skipped silently.
  *
  * The loader deliberately:
  *
  * - Uses `getWorkspaceDir()` so each instance loads its own plugin set
  *   when `VELLUM_WORKSPACE_DIR` is set.
- * - Prefers `.js` over `.ts` per surface file (compiled-binary semantics);
- *   the rule is applied by {@link loadExternalPlugin}.
+ * - Prefers `.js` over `.ts` per surface file (compiled-binary semantics).
+ *   The external loader applies the same rule per surface file; the
+ *   legacy path picks between `register.js` and `register.ts`.
  * - Treats any error from a plugin load as a per-plugin isolation
- *   boundary. {@link loadExternalPlugin} owns its own try/catch/timeout, so
- *   one bad user plugin must not crash the daemon.
+ *   boundary. {@link loadExternalPlugin} owns its own try/catch/timeout;
+ *   the legacy path is wrapped here. One bad user plugin must not crash
+ *   the daemon.
+ * - Bounds each plugin load with {@link USER_PLUGIN_IMPORT_TIMEOUT_MS}
+ *   so a plugin whose top-level `await` hangs or whose module evaluation
+ *   never resolves cannot stall daemon startup.
  *
  * Call order relative to the rest of the plugin system:
  *
@@ -30,6 +46,7 @@
 
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { pathToFileURL } from "node:url";
 
 import { getLogger } from "../util/logger.js";
 import { getWorkspacePluginsDir } from "../util/platform.js";
@@ -40,24 +57,27 @@ import { closeRegistration } from "./registry.js";
 const log = getLogger("user-plugin-loader");
 
 /**
- * Upper bound on how long a single user plugin's load may take. A plugin with
- * a hanging top-level `await` (or a never-resolving module evaluation) would
- * otherwise block daemon startup indefinitely. Ten seconds is generous
- * relative to a typical plugin load (milliseconds) and matches the per-plugin
- * isolation contract: slow plugins get skipped the same way thrown-error
- * plugins do. Enforced by {@link loadExternalPlugin}.
+ * Upper bound on how long a single user plugin's dynamic `import()` may take.
+ * A plugin with a hanging top-level `await` (or a never-resolving module
+ * evaluation) would otherwise block daemon startup indefinitely, since a raw
+ * `try/catch` only isolates thrown errors — not hung promises. Ten seconds is
+ * generous relative to a typical side-effect registration (milliseconds) and
+ * matches the per-plugin isolation contract: slow plugins get skipped the
+ * same way thrown-error plugins do.
  */
 const USER_PLUGIN_IMPORT_TIMEOUT_MS = 10_000;
 
 /**
- * Scan `getWorkspaceDir()/plugins/` for subdirectories and dispatch each one
- * that carries a `package.json` to {@link loadExternalPlugin}.
+ * Scan `getWorkspaceDir()/plugins/` for subdirectories, then dispatch each
+ * one to the external loader (if `package.json` is present and there is no
+ * `register.{ts,js}`) or the legacy side-effect importer (if
+ * `register.{ts,js}` is present).
  *
  * Invariants:
  *
  * - No-ops when `getWorkspaceDir()/plugins/` does not exist — a clean install with
  *   zero user plugins must not generate errors.
- * - Per-plugin isolation: a failing load is logged and skipped. The
+ * - Per-plugin isolation: a failing import is logged and skipped. The
  *   function resolves normally even when every plugin fails to load.
  * - Does not return plugin instances. The registry is the single source of
  *   truth for who got registered, and the caller inspects it directly.
@@ -66,7 +86,7 @@ const USER_PLUGIN_IMPORT_TIMEOUT_MS = 10_000;
  *
  * - Must be invoked exactly once during daemon startup, before
  *   `bootstrapPlugins()` walks the registry.
- * - Holds no locks during the load — bun's dynamic `import()` resolution
+ * - Holds no locks during the import — bun's dynamic `import()` resolution
  *   is concurrency-safe.
  */
 export async function loadUserPlugins(
@@ -131,19 +151,96 @@ export async function loadUserPlugins(
     }
     if (!stats.isDirectory()) continue;
 
-    if (!existsSync(join(pluginDir, "package.json"))) {
-      log.debug({ pluginDir }, "loadUserPlugins: no package.json — skipping");
+    // Path selection: the legacy side-effect path takes precedence when
+    // both a `register.{ts,js}` and a `package.json` are present.
+    // Migration-friendly: any plugin in the wild today that happens to
+    // ship a `package.json` keeps loading via its existing register entry.
+    // The external-plugin path only fires when the directory is
+    // unambiguously the new convention.
+    const jsPath = join(pluginDir, "register.js");
+    const tsPath = join(pluginDir, "register.ts");
+    let registerPath: string | undefined;
+    if (existsSync(jsPath)) {
+      registerPath = jsPath;
+    } else if (existsSync(tsPath)) {
+      registerPath = tsPath;
+    }
+
+    if (registerPath === undefined) {
+      // External plugin framework path. `loadExternalPlugin` owns its own
+      // try/catch + timeout, so a `continue` is the entire branch here.
+      if (existsSync(join(pluginDir, "package.json"))) {
+        await loadExternalPlugin(pluginDir, { importTimeoutMs });
+        continue;
+      }
+      log.debug(
+        { pluginDir },
+        "loadUserPlugins: no register.{ts,js} or package.json — skipping",
+      );
       continue;
     }
 
-    // `loadExternalPlugin` owns its own try/catch + timeout, so a bare
-    // `await` is the entire branch here.
-    await loadExternalPlugin(pluginDir, { importTimeoutMs });
+    // Legacy side-effect import path. `import()` with a `file://` URL
+    // works identically under Node and bun and sidesteps platform-specific
+    // absolute-path quirks on Windows.
+    const moduleUrl = pathToFileURL(registerPath).href;
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    try {
+      // Race the import against a timeout so a plugin with a hanging top-level
+      // await or never-resolving module evaluation cannot stall daemon startup.
+      // The per-plugin try/catch already handles thrown errors; this extends
+      // the isolation boundary to cover hung promises as well.
+      const timeoutSentinel = Symbol("user-plugin-import-timeout");
+      const timeoutPromise = new Promise<typeof timeoutSentinel>((resolve) => {
+        timeoutHandle = setTimeout(
+          () => resolve(timeoutSentinel),
+          importTimeoutMs,
+        );
+      });
+      // Retain the import promise so we can attach a terminal `.catch` on the
+      // timeout branch. `Promise.race` does not cancel the losing promise —
+      // the module evaluation keeps running in the background even after we
+      // stop awaiting it, and if it eventually throws (either from the
+      // module body or from the late `registerPlugin()` hitting a closed
+      // registry) an unhandled rejection would crash the daemon.
+      const importPromise = import(moduleUrl);
+      const result = await Promise.race([importPromise, timeoutPromise]);
+      if (result === timeoutSentinel) {
+        importPromise.catch(() => {
+          // Abandoned import completed (or threw) after the timeout. The
+          // closed-registration latch in registry.ts guarantees any late
+          // `registerPlugin()` call is rejected, so swallowing the outcome
+          // here is the safe default.
+        });
+        log.warn(
+          { pluginDir, registerPath, timeoutMs: importTimeoutMs },
+          `Timed out loading user plugin ${pluginDir} after ${importTimeoutMs}ms — skipping`,
+        );
+      } else {
+        log.info(
+          { pluginDir, registerPath },
+          "loaded user plugin (side-effect import completed)",
+        );
+      }
+    } catch (err) {
+      // One plugin's failure must never prevent other plugins from loading
+      // or crash the daemon. Log with the directory name so operators can
+      // find the broken plugin quickly.
+      const message = err instanceof Error ? err.message : String(err);
+      log.error(
+        { err, pluginDir },
+        `Failed to load user plugin ${pluginDir}: ${message}`,
+      );
+    } finally {
+      if (timeoutHandle !== undefined) clearTimeout(timeoutHandle);
+    }
   }
 
   // Close the registration window once every candidate plugin has been
-  // awaited (or timed out). The per-plugin try/catch inside
-  // `loadExternalPlugin` guarantees no throw escapes the loop, so this line
-  // always runs and `bootstrapPlugins()` sees a fully populated registry.
+  // awaited (or timed out). The per-plugin try/catch guarantees no throw
+  // escapes the loop, so this line always runs. Any abandoned import that
+  // later resolves and reaches `registerPlugin()` is rejected by the latch,
+  // preserving the `bootstrapPlugins()` invariant that the registry is
+  // fully populated before it is walked.
   closeRegistration();
 }

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

@@ -7,7 +7,7 @@
  */
 
 import { createAssistantMessage } from "../agent/message-types.js";
-import { findConversation } from "../daemon/conversation-registry.js";
+import { findConversation } from "../daemon/conversation-store.js";
 import {
   conversationMessagesSyncTag,
   SYNC_TAGS,

package/src/proactive-artifact/job.test.ts

@@ -196,7 +196,7 @@ type MockConversation = {
 };
 let mockConversations: Map<string, MockConversation> = new Map();
 
-mock.module("../daemon/conversation-registry.js", () => ({
+mock.module("../daemon/conversation-store.js", () => ({
   findConversation: (id: string) => mockConversations.get(id),
 }));
 

package/src/prompts/__tests__/system-prompt.test.ts

@@ -148,11 +148,5 @@ describe("maybeReseedBootstrap — activation rail template", () => {
     // Propose: the extract-shape vs infer-shape example block.
     expect(content).toContain("extract-shape");
     expect(content).toContain("infer-shape");
-
-    // Port: prompt-writing guidance (JARVIS-1124).
-    expect(content).toContain("portable context brief, not a self-summary");
-    expect(content).toContain("load-bearing work in the next month");
-    expect(content).toContain("what to help with first");
-    expect(content).toContain("another tool or collaborator");
   });
 });

package/src/prompts/templates/BOOTSTRAP-ACTIVATION-RAIL.md

@@ -8,11 +8,9 @@ The user just finished pre-chat. You know their name and vibe; maybe their Googl
 
 Four moves. Goals, not steps.
 
-**Port.** Pull their existing assistant context with two pastes. About a minute, no upload, no export. You write a prompt, they paste it into Claude or ChatGPT, they paste the response back. Cheap signal, real signal.
+**Port.** Pull their existing assistant context with two pastes — about a minute, no upload, no export. You write a prompt, they paste it into Claude or ChatGPT, they paste the response back. Cheap signal, real signal.
 
-The prompt asks for a portable context brief, not a self-summary. Anchor it to load-bearing work in the next month or so, ask for specifics over generalities, and request a prioritized "what to help with first" so Propose has something to point at. Frame the destination as another tool or collaborator. Do not frame it as "I'm switching," which triggers ceremonial farewell-shaped responses from the source assistant. Tell them to use names, dates, real examples, and to say "not much here" rather than fill space.
-
-The prompt itself must be one-click copyable. Inline paragraph text the user has to select isn't. Neither is a custom-built widget with a fake copy button. If the affordance needs you to build an app or a new surface to render, you've over-built the move. Use what chat already gives you.
+The prompt should be one-click copyable. Inline paragraph text the user has to select isn't. Neither is a custom-built widget with a fake copy button. If the affordance needs you to build an app or a new surface to render, you've over-built the move. Use what chat already gives you.
 
 **Propose.** Don't organize what they already told you — infer what they didn't. Name the unstated thing sitting in their context and say *why* you think it: point at the specific surface that made you say it. "You didn't say this, but —". Then recommend, and lean one way; the recommendation IS the click, not a neutral menu of equally-weighted options.
 

package/src/runtime/__tests__/agent-wake.test.ts

@@ -432,7 +432,7 @@ describe("wakeAgentForOpportunity", () => {
     expect(target.runCalls).toHaveLength(0);
   });
 
-  test("builds a guardian turn context for explicit local-owner cleanup-mode wakes", async () => {
+  test("threads cleanup-mode injection context for explicit local-owner wakes", async () => {
     mockDiskPressureStatus = {
       enabled: true,
       state: "critical",
@@ -463,11 +463,11 @@ describe("wakeAgentForOpportunity", () => {
 
     expect(result).toEqual({ invoked: true, producedToolCalls: false });
     expect(target.runCalls).toHaveLength(1);
-    expect(target.runCalls[0]!.turnContext).toEqual({
-      requestId: "wake:local-cleanup",
+    expect(target.runCalls[0]!.turnContext).toMatchObject({
       conversationId: target.conversationId,
-      turnIndex: 0,
-      trust: { sourceChannel: "vellum", trustClass: "guardian" },
+      injectionInputs: {
+        diskPressureContext: { cleanupModeActive: true },
+      },
     });
   });
 

package/src/runtime/__tests__/interactive-ui.test.ts

@@ -50,7 +50,7 @@ let surfaceCalls: Array<{
   surfaceId: string;
 }> = [];
 
-mock.module("../../daemon/conversation-registry.js", () => ({
+mock.module("../../daemon/conversation-store.js", () => ({
   findConversation: (_conversationId: string) => {
     return mockConversation ?? undefined;
   },

package/src/runtime/agent-wake.ts

@@ -432,6 +432,9 @@ function buildWakeTurnContext(
         sourceChannel: opts.sourceChannel ?? "vellum",
         trustClass: "guardian",
       } satisfies TrustContext),
+    injectionInputs: {
+      diskPressureContext: { cleanupModeActive: true },
+    },
   };
 }
 

package/src/runtime/assistant-event-hub.ts

@@ -708,7 +708,7 @@ async function createCanonicalRequestForConfirmation(
       { DAEMON_INTERNAL_ASSISTANT_ID },
       { bridgeConfirmationRequestToGuardian },
     ] = await Promise.all([
-      import("../daemon/conversation-registry.js"),
+      import("../daemon/conversation-store.js"),
       import("../memory/canonical-guardian-store.js"),
       import("../security/secret-scanner.js"),
       import("../tools/tool-input-summary.js"),

package/src/runtime/channel-approvals.ts

@@ -9,7 +9,7 @@
  *   3. Consume user decisions and apply them to the underlying session
  */
 
-import { findConversation } from "../daemon/conversation-registry.js";
+import { findConversation } from "../daemon/conversation-store.js";
 import type { UserDecision } from "../permissions/types.js";
 import { composeApprovalMessage } from "./approval-message-composer.js";
 import type {

package/src/runtime/interactive-ui.ts

@@ -30,7 +30,7 @@
  *     `"timed_out"`.
  */
 
-import { findConversation } from "../daemon/conversation-registry.js";
+import { findConversation } from "../daemon/conversation-store.js";
 import { showStandaloneSurface } from "../daemon/conversation-surfaces.js";
 import { getLogger } from "../util/logger.js";
 import { mintDecisionToken } from "./decision-token.js";