@vellumai/assistant 0.10.0 → 0.10.1-dev.202606240317.ea25efe

package/src/plugins/pipeline.ts

@@ -2,12 +2,16 @@
  * Plugin hook runner.
  *
  * A "hook" is a named lifecycle event (`user-prompt-submit`, `post-tool-use`,
- * …) that every registered plugin may handle. The runner walks each plugin's
+ * ...) that every registered plugin may handle. The runner walks each plugin's
  * hook for a given event in registration order, threading a context value
  * through the chain so hooks can observe and transform it. A hook either
  * mutates the context in place (returning `void`) or returns a partial
  * context whose fields are merged onto the threaded value.
  *
+ * `getHooksFor` is now async — it pulls user-land hooks from the mtime
+ * cache (filesystem-as-truth) and default plugin hooks from the registry
+ * in a single unified call.
+ *
  * Design doc: `.private/plans/agent-plugin-system.md`.
  */
 
@@ -34,8 +38,9 @@ export async function runHook<TCtx>(
   name: HookName,
   initialCtx: TCtx,
 ): Promise<TCtx> {
+  const hooks = await getHooksFor<TCtx>(name);
   let active = initialCtx;
-  for (const hook of getHooksFor<TCtx>(name)) {
+  for (const hook of hooks) {
     const result = await hook(active);
     if (result !== undefined) {
       active = { ...active, ...result };

package/src/plugins/registry.ts

@@ -19,6 +19,7 @@
  * Design doc: `.private/plans/agent-plugin-system.md`.
  */
 
+import { getUserHooksFor } from "./mtime-cache.js";
 import {
   type Plugin,
   PluginExecutionError,
@@ -145,22 +146,32 @@ export function getRegisteredPlugins(): Plugin[] {
  * `user-prompt-submit` where each plugin's hook may transform a shared
  * context.
  *
+ * This function is async because it pulls user-land hooks from the mtime
+ * cache (filesystem-as-truth), which may need to re-import changed surface
+ * files. First-party default plugin hooks are read synchronously from the
+ * registry and prepended.
+ *
  * 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>(
+export async function getHooksFor<TCtx = unknown>(
   name: string,
-): PluginHookFn<TCtx>[] {
-  const out: PluginHookFn<TCtx>[] = [];
+): Promise<PluginHookFn<TCtx>[]> {
+  // First-party defaults from the registry (synchronous).
+  const defaultHooks: PluginHookFn<TCtx>[] = [];
   for (const plugin of registeredPlugins.values()) {
     const hook = plugin.hooks?.[name];
     if (hook) {
-      out.push(hook as PluginHookFn<TCtx>);
+      defaultHooks.push(hook as PluginHookFn<TCtx>);
     }
   }
-  return out;
+
+  // User-land hooks from the mtime cache (async, may re-import).
+  const userHooks = await getUserHooksFor<TCtx>(name);
+
+  return [...defaultHooks, ...userHooks];
 }
 
 /**

package/src/plugins/user-loader.ts

@@ -1,41 +1,35 @@
 /**
  * User plugin loader — discovers plugins under `<workspaceDir>/plugins/*` and
- * registers each one.
+ * populates the mtime cache.
  *
- * 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.
+ * A plugin directory is recognized by a `package.json` manifest. The loader
+ * delegates to the mtime cache's `populateCacheAtBoot`, which builds each
+ * plugin via `buildExternalPlugin` and stores it keyed by mtime. The cache
+ * is the single source of truth for user plugin state — the registry is no
+ * longer used for user plugins (only for first-party defaults).
  *
  * 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}.
+ *   the rule is applied by `buildExternalPlugin`.
  * - Treats any error from a plugin load as a per-plugin isolation
- *   boundary. {@link loadExternalPlugin} owns its own try/catch/timeout, so
+ *   boundary. `buildExternalPlugin` 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:
  *
  *     first-party default registrations (explicit, at daemon startup)
- *       → loadUserPlugins()          ← this module (closes registration)
- *         → bootstrapPlugins()       (init for everyone registered so far)
+ *       → loadUserPlugins()          ← this module (populates mtime cache)
+ *         → bootstrapPlugins()       (init for defaults registered so far)
  *
  * Design doc: `.private/plans/agent-plugin-system.md` (PR 29).
  */
 
-import { existsSync, readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
-
 import { getLogger } from "../util/logger.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";
+import { populateCacheAtBoot } from "./mtime-cache.js";
 
 const log = getLogger("user-plugin-loader");
 
@@ -45,13 +39,13 @@ const log = getLogger("user-plugin-loader");
  * 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}.
+ * plugins do. Enforced by `buildExternalPlugin`.
  */
 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 and populate the mtime
+ * cache with each plugin found.
  *
  * Invariants:
  *
@@ -59,13 +53,14 @@ const USER_PLUGIN_IMPORT_TIMEOUT_MS = 10_000;
  *   zero user plugins must not generate errors.
  * - 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.
+ * - Does not return plugin instances. The mtime cache is the single source
+ *   of truth for user plugin state, and consumers read from it directly.
  *
  * Caller responsibilities:
  *
  * - Must be invoked exactly once during daemon startup, before
- *   `bootstrapPlugins()` walks the registry.
+ *   `bootstrapPlugins()` walks the registry (which now only contains
+ *   first-party defaults).
  * - Holds no locks during the load — bun's dynamic `import()` resolution
  *   is concurrency-safe.
  */
@@ -93,57 +88,8 @@ export async function loadUserPlugins(
     );
   }
 
-  const pluginsDir = getWorkspacePluginsDir();
-
-  if (!existsSync(pluginsDir)) {
-    // The clean-install case. Closing the registration window keeps the
-    // post-loader invariant uniform: `bootstrapPlugins()` may rely on the
-    // registry being final by the time `loadUserPlugins()` resolves.
-    closeRegistration();
-    return;
-  }
-
-  let entries: string[];
-  try {
-    entries = readdirSync(pluginsDir);
-  } catch (err) {
-    // Permissions error, transient FS issue, etc. Log and bail without
-    // crashing startup — the daemon must come up even when the plugins dir
-    // is unreadable.
-    log.warn(
-      { err, pluginsDir },
-      "loadUserPlugins: failed to read plugins directory",
-    );
-    closeRegistration();
-    return;
-  }
-
-  for (const entry of entries) {
-    const pluginDir = join(pluginsDir, entry);
-
-    // Only directories are candidates. Plain files (readmes, stray configs)
-    // are silently ignored.
-    let stats;
-    try {
-      stats = statSync(pluginDir);
-    } catch {
-      continue;
-    }
-    if (!stats.isDirectory()) continue;
-
-    if (!existsSync(join(pluginDir, "package.json"))) {
-      log.debug({ pluginDir }, "loadUserPlugins: no package.json — skipping");
-      continue;
-    }
-
-    // `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 inside
-  // `loadExternalPlugin` guarantees no throw escapes the loop, so this line
-  // always runs and `bootstrapPlugins()` sees a fully populated registry.
-  closeRegistration();
+  // Populate the mtime cache. This scans the plugins directory, builds
+  // each plugin via buildExternalPlugin, and stores the results keyed by
+  // mtime. The cache is the source of truth — no registry calls needed.
+  await populateCacheAtBoot({ importTimeoutMs });
 }

package/src/prompts/persona-resolver.ts

@@ -68,6 +68,29 @@ function readPersonaFile(filePath: string): string | null {
 
 // ── User filename resolution ──────────────────────────────────────
 
+/**
+ * Resolve the guardian's persona `userFile` (INFO) for a guardian-trust turn.
+ *
+ * The guardian identity comes from the verdict-derived trust context
+ * (`guardianExternalUserId`): the info read is keyed on that address so it
+ * matches the gateway's guardian binding. When the context carries no guardian
+ * address (desktop / native turns), fall back to the channel's guardian
+ * contact. Returns `"guardian.md"` when the resolved guardian has no userFile.
+ */
+function resolveGuardianUserFile(trustContext: TrustContext): string | null {
+  if (trustContext.guardianExternalUserId) {
+    const guardianContact = findContactByAddress(
+      trustContext.sourceChannel,
+      trustContext.guardianExternalUserId,
+    );
+    if (guardianContact) {
+      return guardianContact.userFile ?? "guardian.md";
+    }
+  }
+  const guardian = findGuardianForChannel(trustContext.sourceChannel);
+  return guardian ? (guardian.contact.userFile ?? "guardian.md") : null;
+}
+
 /**
  * Resolve the raw userFile filename for the current actor's contact.
  * Returns the validated filename (e.g. "alice.md") or null.
@@ -97,22 +120,17 @@ function resolveUserFilename(
       } else if (trustContext.trustClass === "guardian") {
         // Managed desktop: the JWT principal ID used as requesterExternalUserId
         // may differ from the contact channel's address (they are separate
-        // identity concepts). Fall back to the channel-type guardian.
-        const guardian = findGuardianForChannel(trustContext.sourceChannel);
-        if (guardian) {
-          filename = guardian.contact.userFile ?? "guardian.md";
-        }
+        // identity concepts). Read the guardian's user file keyed by the
+        // verdict-bound guardian identity.
+        filename = resolveGuardianUserFile(trustContext);
       }
     } else if (trustContext.trustClass === "guardian") {
       // Guardian-trust turn carrying no requester identity — background and
       // scheduled turns (heartbeat, scheduled pulses) run under the guardian
       // trust class but have no per-actor address to look up. Resolve the
-      // channel's guardian user file so they load the same persona as a
-      // foreground guardian turn instead of falling back to users/default.md.
-      const guardian = findGuardianForChannel(trustContext.sourceChannel);
-      if (guardian) {
-        filename = guardian.contact.userFile ?? "guardian.md";
-      }
+      // guardian's user file so they load the same persona as a foreground
+      // guardian turn instead of falling back to users/default.md.
+      filename = resolveGuardianUserFile(trustContext);
     }
   } catch (err) {
     // Contacts table may be absent — happens during early bootstrap

package/src/prompts/system-prompt.ts

@@ -274,7 +274,7 @@ export function maybeReseedBootstrap(templateFileName: string): boolean {
  * Marking happens here — at the single point where the bootstrap selection is
  * known — so it lands BEFORE the agent loop resolves tools and BEFORE the model
  * can call the emit tool on the first activation-rail turn. (`resolveTools`
- * runs before `resolveSystemPrompt` in the loop, so the system-prompt build is
+ * runs before the system-prompt build in the loop, so the system-prompt build is
  * too late to be the *only* marking site.) The marker write is best-effort and
  * idempotent (`markActivationSession` swallows errors and dedups on the PK), so
  * calling this from both `setOnboardingContext` and `buildSystemPrompt` is safe.

package/src/prompts/templates/system-sections.ts

@@ -317,13 +317,13 @@ Run \`assistant --help\` to see all available commands, or \`assistant <command>
     id: "04-attachment",
     body: `## Sending Files to the User
 
-To deliver files to the user, include \`<vellum-attachment source="sandbox" path="scratch/output.png" />\` in your response text. This tag is the ONLY way files reach the user - omitting it means the user won't see the file.
+To share a workspace file, use a markdown link with the \`vellum://\` scheme:
 
-Use \`source="host"\` with an absolute path for host filesystem files. Optional attributes: \`filename\` (display name override), \`mime_type\` (override auto-detection).
+\`[report.pdf](vellum://workspace/scratch/report.pdf)\`
 
-Image and video attachments can render inline in chat. If the user asks to preview a media file here, attach it instead of only printing its path.
+The path after \`workspace/\` is relative to your working directory. The file renders as a downloadable attachment. For host filesystem files, use \`vellum://host/absolute/path\`.
 
-Embed images/GIFs inline using markdown: \`![description](URL)\`.
+Embed images/GIFs inline using standard markdown: \`![description](URL)\`.
 `,
   },
   {

package/src/providers/__tests__/count-tokens-forwarding.test.ts

@@ -0,0 +1,98 @@
+/**
+ * The production conversation provider is wrapped (CallSiteRouting → RateLimit
+ * → Retry → UsageTracking → adapter). `Provider.countInputTokens` is optional,
+ * so each wrapper must forward it or the capability is lost partway up the
+ * chain and `/compact` silently falls back to the local estimate. These tests
+ * pin the forwarding.
+ */
+import { describe, expect, mock, test } from "bun:test";
+
+function makeLoggerStub(): Record<string, unknown> {
+  const stub: Record<string, unknown> = {};
+  for (const m of [
+    "info",
+    "warn",
+    "error",
+    "debug",
+    "trace",
+    "fatal",
+    "silent",
+    "child",
+  ]) {
+    stub[m] = m === "child" ? () => makeLoggerStub() : () => {};
+  }
+  return stub;
+}
+mock.module("../../util/logger.js", () => ({
+  getLogger: () => makeLoggerStub(),
+}));
+
+import { CallSiteRoutingProvider } from "../call-site-routing.js";
+import { RateLimitProvider } from "../ratelimit.js";
+import { RetryProvider } from "../retry.js";
+import type { Message, Provider } from "../types.js";
+import { UsageTrackingProvider } from "../usage-tracking.js";
+
+function providerWithCount(): Provider {
+  return {
+    name: "inner",
+    sendMessage: async () => ({
+      content: [],
+      model: "m",
+      usage: { inputTokens: 0, outputTokens: 0 },
+      stopReason: "end_turn",
+    }),
+    countInputTokens: async () => 4242,
+  };
+}
+
+function providerWithoutCount(): Provider {
+  const p = providerWithCount();
+  delete p.countInputTokens;
+  return p;
+}
+
+const msgs: Message[] = [
+  { role: "user", content: [{ type: "text", text: "hi" }] },
+];
+
+const wrappers: Array<[string, (inner: Provider) => Provider]> = [
+  ["RetryProvider", (inner) => new RetryProvider(inner)],
+  ["UsageTrackingProvider", (inner) => new UsageTrackingProvider(inner)],
+  [
+    "RateLimitProvider",
+    (inner) => new RateLimitProvider(inner, { maxRequestsPerMinute: 0 }),
+  ],
+  [
+    "CallSiteRoutingProvider",
+    (inner) => new CallSiteRoutingProvider(inner, async () => null),
+  ],
+];
+
+describe("countInputTokens forwarding through provider wrappers", () => {
+  for (const [name, wrap] of wrappers) {
+    test(`${name} forwards the count when the inner provider supports it`, async () => {
+      const wrapped = wrap(providerWithCount());
+      expect(typeof wrapped.countInputTokens).toBe("function");
+      expect(await wrapped.countInputTokens!(msgs, "sys", undefined)).toBe(
+        4242,
+      );
+    });
+
+    test(`${name} omits the count when the inner provider lacks it`, () => {
+      const wrapped = wrap(providerWithoutCount());
+      expect(wrapped.countInputTokens).toBeUndefined();
+    });
+  }
+
+  test("capability survives the full nested wrapper chain", () => {
+    const chain = new CallSiteRoutingProvider(
+      new RateLimitProvider(
+        new RetryProvider(new UsageTrackingProvider(providerWithCount())),
+        { maxRequestsPerMinute: 0 },
+      ),
+      async () => null,
+    );
+    expect(typeof chain.countInputTokens).toBe("function");
+  });
+});