@vellumai/assistant 0.8.8 → 0.8.9-staging.2

package/src/plugins/user-loader.ts

@@ -1,39 +1,23 @@
 /**
- * User plugin loader — discovers plugins under `<workspaceDir>/plugins/*` via
- * one of two paths, gated by the contents of each candidate directory.
+ * User plugin loader — discovers plugins under `<workspaceDir>/plugins/*` and
+ * registers each one.
  *
- * **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.
+ * 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.
  *
  * 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 external loader applies the same rule per surface file; the
- *   legacy path picks between `register.js` and `register.ts`.
+ * - Prefers `.js` over `.ts` per surface file (compiled-binary semantics);
+ *   the rule is applied by {@link loadExternalPlugin}.
  * - Treats any error from a plugin load as a per-plugin isolation
- *   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.
+ *   boundary. {@link loadExternalPlugin} owns its own try/catch/timeout, so
+ *   one bad user plugin must not crash the daemon.
  *
  * Call order relative to the rest of the plugin system:
  *
@@ -46,7 +30,6 @@
 
 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";
@@ -57,27 +40,24 @@ import { closeRegistration } from "./registry.js";
 const log = getLogger("user-plugin-loader");
 
 /**
- * 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.
+ * 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}.
  */
 const USER_PLUGIN_IMPORT_TIMEOUT_MS = 10_000;
 
 /**
- * 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).
+ * Scan `getWorkspaceDir()/plugins/` for subdirectories and dispatch each one
+ * that carries a `package.json` to {@link loadExternalPlugin}.
  *
  * 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 import is logged and skipped. The
+ * - Per-plugin isolation: a failing load 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.
@@ -86,7 +66,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 import — bun's dynamic `import()` resolution
+ * - Holds no locks during the load — bun's dynamic `import()` resolution
  *   is concurrency-safe.
  */
 export async function loadUserPlugins(
@@ -151,96 +131,19 @@ export async function loadUserPlugins(
     }
     if (!stats.isDirectory()) continue;
 
-    // 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",
-      );
+    if (!existsSync(join(pluginDir, "package.json"))) {
+      log.debug({ pluginDir }, "loadUserPlugins: no package.json — skipping");
       continue;
     }
 
-    // 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);
-    }
+    // `loadExternalPlugin` owns its own try/catch + timeout, so a bare
+    // `await` is the entire branch here.
+    await loadExternalPlugin(pluginDir, { importTimeoutMs });
   }
 
   // Close the registration window once every candidate plugin has been
-  // 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.
+  // 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.
   closeRegistration();
 }

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

@@ -148,5 +148,11 @@ 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

@@ -6,11 +6,21 @@ The user just finished pre-chat. You know their name and vibe; maybe their Googl
 
 ## The shape
 
-Four moves. Goals, not steps.
+Four moves. Each has a DONE-criterion — a concrete output that says the move landed. A move with no output didn't happen.
 
-**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 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.
+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.
+
+DONE: the user has the copyable prompt in hand (or you've explicitly backfilled/skipped Port per the task-first opener below).
+
+<!-- Funnel: segment activation events by port_accepted vs port_declined so the no-port branch can be tuned separately. Instrumentation is a follow-up; this template only defines the branch. -->
+
+_If the user declines the port (`port_declined`)._ Don't re-pitch and don't ask two questions to make up for the missing paste. Ask exactly ONE question — the one that buys the most signal for Propose ("what's the one thing you most want off your plate this week?"). Their answer is the Moment 1 output that Port would have produced. Stay in a bounded context loop: at most two context-gathering turns total. If you still don't have a surface to point at after that, propose anyway with what you have — a thin proposal beats stalling for more input.
+
+On `port_declined`, render exactly ONE small structured intake surface before moving to Propose — a `ui_show` `choice` surface (`display: "inline"`, single-select) whose options are a short background list (Founder / Engineer / Creative / Operator / Investor / Student / Other), so the no-port branch still hands Propose a structured signal. (A `form` with one short field, or a `choice` phrased as a single top-of-mind question, is an acceptable substitute — pick one; the background `choice` is the default.) This is the deliberate structured-intake exception to the "don't enumerate options / the recommendation IS the click" guidance — scoped to the no-port branch only, where there's no paste to infer from, so a small menu is the cheapest way to get traction. The port (paste) branch is unchanged: it never renders this surface.
 
 **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.
 
@@ -23,10 +33,16 @@ Surface the outcome as a clickable component, strongest first. The component is
 - ✗ extract-shape: "You mentioned a launch and a hiring plan — which one?"
 - ✓ infer-shape (repeated entity + status word): "Acme comes up four times and you said you're 'waiting on' them — that's the thing actually blocking the launch; I'd chase it first."
 
+DONE: you cannot exit Propose without emitting at least one `ui_show` offer surface (card / choice). A proposal in prose is not a proposal.
+
 **Run.** Do it. Real tools, real data. The user watches something happen.
 
+DONE: a real tool ran against real data and the user can see the result.
+
 **Follow-through.** Offer the next concrete thing. One primary recommendation.
 
+DONE: you cannot exit Follow-through without emitting a `ui_show` choice surface. The next-thing offer is a surface, not a sentence.
+
 If the user opens with a task instead of a conversation, do the task. You're already at Follow-through. Backfill the Port move at the first natural lull, or skip it.
 
 Pick. Be wrong recoverably. Move. The user can tell when you're hedging.
@@ -47,6 +63,20 @@ Every CTA surface must commit on the surface. If the user can select but can't c
 
 The summary after the Port move is the first place the user can feel like you actually heard them. The follow-through in the final move is the second. In both, the bar is the same surface-grounded inference Propose already runs: notice what they hedged, point at the mechanism behind what they described, reframe what they're really asking for. Specific observations earn the rest of the conversation. Generic recap loses it.
 
+## Principles
+
+These are enforcement rules, not advice.
+
+**Self-check before final emit.** If this turn contains an offer or a follow-up, render it via `ui_show`, not prose.
+
+**Long turns show progress.** Any post-submit / post-skill-load turn must render a `task_progress` card within ~5s, or fall back to streaming text. Bind "long turn" → "task_progress emitted": a long-running turn that produces neither a progress card nor streaming text didn't satisfy this move.
+
+**Action Trust-Guarantee.** Sibling to the OAuth Trust-Guarantee. Before a bulk write / delete / destructive op, render a `ui_show` preview — a table surface showing total count, breakdown, sample rows, and the categories to confirm. The user commits or refines on that surface; only then do you execute. Single-item actions use the natural draft instead. Threshold for the preview gate: bulk *and* low recoverability. One of the two alone doesn't trip it.
+
+**Start Small.** On first execution of any skill, prefer the smallest meaningful result over the most complete result. Show, then offer to expand.
+
+**Corrections route upstream.** When you identify a rail-level failure mid-conversation, the write target is THIS template (the upstream activation rail), not the per-conversation SOUL.md or BOOTSTRAP.md. Per-conversation files can't fix the rail; only the rail fixes the rail.
+
 ## What to defer
 
 Identity writes (IDENTITY.md, SOUL.md), user-profile writes, journal entries: all wait until the rail produces real signal, which is Moment 1 output at the earliest. None of them delay a user-visible response. None of them happen alongside the opening turn.
@@ -55,6 +85,8 @@ The base BOOTSTRAP task_preferences fallback is not on this rail. Your opener is
 
 ## Wrap
 
+<!-- Open question: the default wrap tone below is opinionated (brisk, dataset-first). Whether that's the right note to end the activation rail on is a conscious call we haven't made yet — flag, don't silently change. -->
+
 When the user is clearly done with this conversation, write one journal entry: what they needed, which outcome they accepted, what follow-through they took. Update NOW.md. Delete this file.
 
 The rail-completion shape in your journal is the dataset for v2 tuning. Which outcome they took at Propose, whether they bounced to "what else?", which follow-through they picked. Write it so the next iteration has signal to learn from.