@vellumai/assistant 0.11.3-dev.202608131925.65f1085 → 0.11.3-dev.202608132218.8ea1f84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.3-dev.202608131925.65f1085",
+  "version": "0.11.3-dev.202608132218.8ea1f84",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/routes/worker.ts

@@ -25,6 +25,11 @@ import type { IpcEnvelope } from "@vellumai/ipc-server-utils";
 import { IpcFrameReader, writeMessage } from "@vellumai/ipc-server-utils";
 
 import { disableStreamSeqStamping } from "../runtime/assistant-stream-state.js";
+import {
+  evictRouteSourceTree,
+  importRouteModule,
+  sourceRootForHandler,
+} from "../runtime/routes/user-route-import.js";
 import { getLogger } from "../util/logger.js";
 import {
   ensureProcDir,
@@ -43,6 +48,9 @@ import {
 
 const log = getLogger("route-host");
 
+/** Last entry-file mtime imported in this process, keyed by handler path. */
+const lastHandlerMtime = new Map<string, number>();
+
 const socketPath = getProcSocketPath(ROUTE_HOST_PROC_NAME);
 const pidPath = getProcPidPath(ROUTE_HOST_PROC_NAME);
 
@@ -110,11 +118,15 @@ async function handleInvoke(
   params: RouteInvokeParams,
   body: Uint8Array | undefined,
 ): Promise<void> {
-  // Each worker has its own module cache; cache-bust per mtime so an edited
-  // handler is re-imported.
-  const mod = (await import(
-    `${params.filePath}?t=${params.mtimeMs}`
-  )) as Record<string, unknown>;
+  // Each worker has its own module cache. When the entry file's mtime
+  // moves, evict the whole source tree so a new handler cannot bind to a
+  // stale helper, then re-import.
+  const lastMtime = lastHandlerMtime.get(params.filePath);
+  if (lastMtime !== params.mtimeMs) {
+    evictRouteSourceTree(sourceRootForHandler(params.filePath));
+    lastHandlerMtime.set(params.filePath, params.mtimeMs);
+  }
+  const mod = await importRouteModule(params.filePath);
 
   const handler = mod[params.method];
   if (typeof handler !== "function") {

package/src/runtime/routes/__tests__/user-route-dispatcher.test.ts

@@ -1,5 +1,5 @@
 import { mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
 // ---------------------------------------------------------------------------
@@ -574,4 +574,65 @@ describe("plugin routes", () => {
     );
     expect(other.status).toBe(404);
   });
+
+  test("a new route export is not bound to a stale helper after upgrade", async () => {
+    // Reproduces the browser plugin 500: `/frame` loaded `src/http.ts`
+    // first, then an upgrade added `requireNumber` to http.ts and a new
+    // `/input` that imports it. Cache-busting only the entry file rebound
+    // input.ts to the cached http.ts, which had no such export.
+    const plugin = "stale-helper";
+    const helperPath = join(getWorkspacePluginsDir(), plugin, "src", "http.ts");
+    mkdirSync(dirname(helperPath), { recursive: true });
+    writeFileSync(
+      helperPath,
+      `export function label() { return "v1"; }\n`,
+    );
+    writePluginHandler(
+      plugin,
+      "frame.ts",
+      `import { label } from "../src/http.js";
+       export function GET() { return Response.json({ label: label() }); }`,
+    );
+    writePluginHandler(
+      plugin,
+      "input.ts",
+      `import { label } from "../src/http.js";
+       export function POST() { return Response.json({ label: label() }); }`,
+    );
+
+    const dispatcher = makeDispatcher();
+    const frame1 = await dispatcher.dispatch(
+      `plugins/${plugin}/frame`,
+      makeRequest("GET"),
+    );
+    expect(frame1.status).toBe(200);
+    expect((await frame1.json()).label).toBe("v1");
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    writeFileSync(
+      helperPath,
+      `export function label() { return "v2"; }
+       export function extra() { return true; }\n`,
+    );
+    writePluginHandler(
+      plugin,
+      "input.ts",
+      `import { extra } from "../src/http.js";
+       export function POST() { return Response.json({ extra: extra() }); }`,
+    );
+
+    const input = await dispatcher.dispatch(
+      `plugins/${plugin}/input`,
+      makeRequest("POST"),
+    );
+    expect(input.status).toBe(200);
+    expect((await input.json()).extra).toBe(true);
+
+    const frame2 = await dispatcher.dispatch(
+      `plugins/${plugin}/frame`,
+      makeRequest("GET"),
+    );
+    expect(frame2.status).toBe(200);
+    expect((await frame2.json()).label).toBe("v2");
+  });
 });

package/src/runtime/routes/user-route-dispatcher.ts

@@ -27,9 +27,12 @@
  * shows no route depends on it.
  *
  * Modules are lazily loaded on first request and cached by file path +
- * mtime. When a file changes on disk, the next request reloads it via
- * Bun's dynamic `import()` with a cache-busting query parameter. A request
- * whose file does not exist 404s — nothing is registered ahead of time.
+ * mtime. When a file changes on disk, the next request evicts the whole
+ * source tree that file belongs to (plugin root, or the workspace
+ * `routes/` directory) and re-imports the entry. Cache-busting only the
+ * entry file would re-bind it to stale helpers still in Bun's registry.
+ * A request whose file does not exist 404s. Nothing is registered ahead
+ * of time.
  */
 
 import { statSync } from "node:fs";
@@ -46,6 +49,11 @@ import {
   buildDeprecatedRouteContext,
   type UserRouteContext,
 } from "./deprecated-route-context.js";
+import {
+  evictRouteSourceTree,
+  importRouteModule,
+  routeSourceRoot,
+} from "./user-route-import.js";
 import {
   resolveHandlerFile,
   resolveRouteLocation,
@@ -134,7 +142,7 @@ export class UserRouteDispatcher {
       ? resolveHandlerFile(location.routesDir, location.subPath)
       : null;
 
-    if (!filePath) {
+    if (!location || !filePath) {
       return httpError(
         "NOT_FOUND",
         `No route handler found for /x/${routePath}`,
@@ -146,7 +154,7 @@ export class UserRouteDispatcher {
       return this.dispatchViaHost(filePath, routePath, request);
     }
 
-    const mod = await this.loadModule(filePath);
+    const mod = await this.loadModule(filePath, location.routesDir);
     const method = request.method as HttpMethod;
     const handler = mod.handlers[method];
 
@@ -231,11 +239,15 @@ export class UserRouteDispatcher {
   /**
    * Load a handler module, using the mtime-based cache when possible.
    *
-   * On cache miss or stale mtime, the module is re-imported via Bun's
-   * dynamic `import()` with a cache-busting query parameter derived
-   * from the file's current mtime.
+   * On cache miss or stale mtime, every source file in the handler's tree
+   * is evicted first so a new entry cannot import a helper that is still
+   * the pre-upgrade module. Then the entry is re-imported with an mtime
+   * query parameter.
    */
-  private async loadModule(filePath: string): Promise<CachedModule> {
+  private async loadModule(
+    filePath: string,
+    routesDir: string,
+  ): Promise<CachedModule> {
     const stat = statSync(filePath);
     const mtimeMs = stat.mtimeMs;
 
@@ -244,11 +256,11 @@ export class UserRouteDispatcher {
       return cached;
     }
 
-    // Cache-bust Bun's module cache by appending mtime as a query param.
-    const mod = (await import(`${filePath}?t=${mtimeMs}`)) as Record<
-      string,
-      unknown
-    >;
+    const sourceRoot = routeSourceRoot(routesDir);
+    evictRouteSourceTree(sourceRoot);
+    this.dropCachedModulesUnder(sourceRoot);
+
+    const mod = await importRouteModule(filePath);
 
     const handlers: Partial<Record<HttpMethod, RouteHandler>> = {};
     for (const method of HTTP_METHODS) {
@@ -271,6 +283,19 @@ export class UserRouteDispatcher {
     return entry;
   }
 
+  /**
+   * Drop every cached handler under `sourceRoot`. Sibling routes must not
+   * keep closures over the helpers we just evicted.
+   */
+  private dropCachedModulesUnder(sourceRoot: string): void {
+    const prefix = sourceRoot.endsWith("/") ? sourceRoot : `${sourceRoot}/`;
+    for (const path of this.moduleCache.keys()) {
+      if (path === sourceRoot || path.startsWith(prefix)) {
+        this.moduleCache.delete(path);
+      }
+    }
+  }
+
   /**
    * Execute a handler function with a per-request timeout and error boundary.
    */

package/src/runtime/routes/user-route-import.ts

@@ -0,0 +1,108 @@
+/**
+ * Import a user/plugin route module so its helpers match the files on disk.
+ *
+ * Bun caches every imported helper independently. Cache-busting only the
+ * entry file (`import(file?t=mtime)`) re-binds it to whatever helpers are
+ * already in the registry. That is how a new route that imports a new export
+ * from `src/http.ts` 500s with "Export named 'requireNumber' not found" while
+ * `/frame` (still on the old http.ts surface) keeps answering 200.
+ *
+ * Hooks and tools already treat the whole plugin directory as the reload
+ * unit (`plugins/source-fingerprint.ts`). Routes must do the same: when the
+ * entry file's mtime moves, evict every source file in that tree before the
+ * next import, so the new entry cannot pair with a stale helper.
+ */
+
+import { statSync } from "node:fs";
+import { dirname, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { snapshotPluginSource } from "../../plugins/source-fingerprint.js";
+import { evictModule } from "../../plugins/surface-import.js";
+import { getWorkspaceRoutesDir } from "../../util/platform.js";
+
+/**
+ * Directory whose source files must stay mutually consistent with this
+ * handler. An installed or default plugin uses the plugin root (so `src/`
+ * helpers evict with `routes/`). Workspace routes use the workspace
+ * `routes/` directory.
+ */
+export function routeSourceRoot(routesDir: string): string {
+  if (routesDir === getWorkspaceRoutesDir()) {
+    return routesDir;
+  }
+  return dirname(routesDir);
+}
+
+/**
+ * Infer the source root from a handler path when the caller has no
+ * {@link routeSourceRoot} (the route-host worker only sees `filePath`).
+ */
+export function sourceRootForHandler(filePath: string): string {
+  const marker = `${sep}routes${sep}`;
+  const idx = filePath.lastIndexOf(marker);
+  if (idx !== -1) {
+    return filePath.slice(0, idx);
+  }
+  return dirname(filePath);
+}
+
+/**
+ * Drop every source module under `sourceRoot` from the runtime registry,
+ * including query-string aliases (`file.ts?t=mtime`) the dispatcher uses to
+ * cache-bust the entry file.
+ */
+export function evictRouteSourceTree(sourceRoot: string): void {
+  const { evictionPaths } = snapshotPluginSource(sourceRoot);
+  for (const path of evictionPaths) {
+    evictModule(path);
+  }
+  evictRegistryAliases(sourceRoot);
+}
+
+function evictRegistryAliases(sourceRoot: string): void {
+  const prefix = sourceRoot.endsWith("/") ? sourceRoot : `${sourceRoot}/`;
+  const fileUrlPrefix = pathToFileURL(prefix).href;
+  for (const key of Object.keys(require.cache)) {
+    if (!keyBelongsToTree(key, sourceRoot, prefix, fileUrlPrefix)) {
+      continue;
+    }
+    delete require.cache[key];
+  }
+}
+
+function keyBelongsToTree(
+  key: string,
+  sourceRoot: string,
+  prefix: string,
+  fileUrlPrefix: string,
+): boolean {
+  const bare = key.split("?")[0] ?? key;
+  if (bare.includes("/node_modules/") || bare.includes("/node_modules?")) {
+    return false;
+  }
+  if (
+    bare === sourceRoot ||
+    bare.startsWith(prefix) ||
+    bare.startsWith(fileUrlPrefix)
+  ) {
+    return true;
+  }
+  if (bare.startsWith("file:")) {
+    try {
+      const asPath = fileURLToPath(bare);
+      return asPath === sourceRoot || asPath.startsWith(prefix);
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+/** Dynamic-import a handler, cache-busted by the file's current mtime. */
+export async function importRouteModule(
+  filePath: string,
+): Promise<Record<string, unknown>> {
+  const mtimeMs = statSync(filePath).mtimeMs;
+  return (await import(`${filePath}?t=${mtimeMs}`)) as Record<string, unknown>;
+}