@vellumai/assistant 0.11.3 → 0.11.4-dev.202608190019.b94dbf2

package/src/runtime/routes/stt-routes.ts

@@ -223,6 +223,35 @@ const STT_ERROR_MAP: Record<SttErrorCategory, () => RouteError> = {
   "provider-error": () => new BadGatewayError("STT provider error"),
 };
 
+/**
+ * Resolve the configured batch transcriber, or fail the request with a 503
+ * naming which kind of unavailability this is.
+ *
+ * A typed {@link SttError} already names the situation and its fix (a
+ * configured provider that cannot batch transcribe), so its message is
+ * surfaced verbatim. `null` means nothing is configured at all, and any other
+ * throw is an unexpected resolver failure.
+ */
+async function resolveBatchTranscriberOrUnavailable(): Promise<BatchTranscriber> {
+  let transcriber: BatchTranscriber | null;
+  try {
+    transcriber = await resolveBatchTranscriber();
+  } catch (err) {
+    if (err instanceof SttError) {
+      throw new ServiceUnavailableError(err.message);
+    }
+    log.error({ err }, "Failed to resolve STT transcriber");
+    throw new ServiceUnavailableError("STT provider is not available");
+  }
+
+  if (!transcriber) {
+    throw new ServiceUnavailableError(
+      "No speech-to-text provider is configured",
+    );
+  }
+  return transcriber;
+}
+
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
@@ -288,19 +317,7 @@ async function handleTranscribe({ body }: RouteHandlerArgs) {
   }
 
   // -- Resolve transcriber --------------------------------------------------
-  let transcriber;
-  try {
-    transcriber = await resolveBatchTranscriber();
-  } catch (err) {
-    log.error({ err }, "Failed to resolve STT transcriber");
-    throw new ServiceUnavailableError("STT provider is not available");
-  }
-
-  if (!transcriber) {
-    throw new ServiceUnavailableError(
-      "No speech-to-text provider is configured",
-    );
-  }
+  const transcriber = await resolveBatchTranscriberOrUnavailable();
 
   // -- Transcribe with timeout ----------------------------------------------
   const abortController = new AbortController();
@@ -358,18 +375,7 @@ async function handleTranscribeFile({ body }: RouteHandlerArgs) {
     );
   }
 
-  let transcriber;
-  try {
-    transcriber = await resolveBatchTranscriber();
-  } catch (err) {
-    log.error({ err }, "Failed to resolve STT transcriber");
-    throw new ServiceUnavailableError("STT provider is not available");
-  }
-  if (!transcriber) {
-    throw new ServiceUnavailableError(
-      "No speech-to-text provider is configured",
-    );
-  }
+  const transcriber = await resolveBatchTranscriberOrUnavailable();
 
   const startTime = Date.now();
   let wavPath: string | null = null;

package/src/runtime/routes/surface-action-routes.ts

@@ -37,26 +37,25 @@ const log = getLogger("surface-action-routes");
 
 /**
  * Resolve trust context for the actor principal from the gateway guardian
- * binding and set it on the conversation. A vellum principal is the guardian or
- * nobody, so the mapper yields guardian or unknown. Resolution (including the
- * dev-bypass principal translation and the mutating reset-drift repair) lives
- * in the shared {@link resolveVellumActorTrustContext} so the surface content
- * route's read-only requester scoping cannot drift from it.
+ * binding, and return it for the caller to attribute this action with. A vellum
+ * principal is the guardian or nobody, so the mapper yields guardian or
+ * unknown. Resolution (including the dev-bypass principal translation and the
+ * mutating reset-drift repair) lives in the shared
+ * {@link resolveVellumActorTrustContext} so the surface content route's
+ * read-only requester scoping cannot drift from it.
+ *
+ * Resolution only: the requester travels to `handleSurfaceAction` as an
+ * argument, and the conversation's slot is stamped there, at the point the
+ * click is committed to starting a turn. Stamping here instead would repoint
+ * the actor of a turn already in flight, or of a turn that starts between this
+ * call and the dispatch.
  */
-async function applyTrustContext(
-  conversation: {
-    setTrustContext?(ctx: TrustContext): void;
-  },
+async function resolveRequesterTrustContext(
   actorPrincipalId: string | undefined,
-): Promise<void> {
-  if (!conversation.setTrustContext) {
-    return;
-  }
-  conversation.setTrustContext(
-    await resolveVellumActorTrustContext(actorPrincipalId, {
-      healResetDrift: true,
-    }),
-  );
+): Promise<TrustContext> {
+  return resolveVellumActorTrustContext(actorPrincipalId, {
+    healResetDrift: true,
+  });
 }
 
 // ---------------------------------------------------------------------------
@@ -154,7 +153,8 @@ async function handleSurfaceAction({
   }
 
   const actorPrincipalId = headers?.["x-vellum-actor-principal-id"];
-  await applyTrustContext(conversation, actorPrincipalId);
+  const requesterTrustContext =
+    await resolveRequesterTrustContext(actorPrincipalId);
 
   // Translate dev-bypass → real guardian so the surface turn's principal matches
   // the SSE host-proxy client's registered principal; otherwise CU/app-control
@@ -170,6 +170,7 @@ async function handleSurfaceAction({
       actionId,
       data,
       resolvedActorPrincipalId,
+      requesterTrustContext,
     );
     const result =
       raw && typeof raw === "object" && "accepted" in raw

package/src/runtime/routes/surface-conversation-resolver.ts

@@ -64,6 +64,9 @@ export async function resolveSurfaceConversation(
   const escaped = surfaceId.replace(/[\\%_]/g, "\\$&");
   const row = rawGet<{ conversation_id: string }>(
     "surfaceResolver:resolveConversation",
+    // Unfinalized rows cannot match: their content is a { ref } pointer,
+    // never inline surface JSON, so the LIKE probes below see finalized
+    // content only by shape. No completeness predicate needed.
     `SELECT conversation_id FROM messages
      WHERE content LIKE ? ESCAPE '\\'
      ORDER BY created_at DESC

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

@@ -27,13 +27,17 @@
  * 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";
 
+import { runInPluginContext } from "../../plugins/plugin-execution-context.js";
 import { isRouteHostEnabled } from "../../routes/control.js";
 import {
   RouteHostClient,
@@ -47,6 +51,12 @@ import {
   type UserRouteContext,
 } from "./deprecated-route-context.js";
 import {
+  evictRouteSourceTree,
+  importRouteModule,
+  routeSourceRoot,
+} from "./user-route-import.js";
+import {
+  pluginNameForRoutePath,
   resolveHandlerFile,
   resolveRouteLocation,
 } from "./user-route-resolution.js";
@@ -134,7 +144,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}`,
@@ -142,11 +152,36 @@ export class UserRouteDispatcher {
       );
     }
 
+    // A plugin's own routes execute as that plugin, so the host APIs a handler
+    // reaches scope to it exactly as they do inside its hooks and tools. Both
+    // execution paths carry it: in-thread here, and the route host through the
+    // invoke params it marks its own execution with.
+    const pluginName = pluginNameForRoutePath(routePath);
+
     if (isRouteHostEnabled()) {
-      return this.dispatchViaHost(filePath, routePath, request);
+      return this.dispatchViaHost(filePath, routePath, request, pluginName);
     }
 
-    const mod = await this.loadModule(filePath);
+    // The context covers module evaluation, not just the handler call. A route
+    // module can reach a scoped host API at import time (a top-level `await`),
+    // and that import happens once per mtime, so a load left outside the
+    // context would take the unscoped branch and never be re-run scoped.
+    const serve = () =>
+      this.serveInThread(filePath, location.routesDir, routePath, request);
+    return pluginName ? runInPluginContext(pluginName, serve) : serve();
+  }
+
+  /**
+   * Load the handler module and run the method's handler in this thread.
+   * Called inside the owning plugin's execution context, when the route has one.
+   */
+  private async serveInThread(
+    filePath: string,
+    routesDir: string,
+    routePath: string,
+    request: Request,
+  ): Promise<Response> {
+    const mod = await this.loadModule(filePath, routesDir);
     const method = request.method as HttpMethod;
     const handler = mod.handlers[method];
 
@@ -172,6 +207,7 @@ export class UserRouteDispatcher {
     filePath: string,
     routePath: string,
     request: Request,
+    pluginName: string | undefined,
   ): Promise<Response> {
     const mtimeMs = statSync(filePath).mtimeMs;
 
@@ -193,6 +229,7 @@ export class UserRouteDispatcher {
           method: request.method,
           url: request.url,
           headers,
+          pluginName,
         },
         body,
       );
@@ -231,11 +268,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 +285,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 +312,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>;
+}

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

@@ -66,6 +66,23 @@ export interface RouteLocation {
   subPath: string;
 }
 
+/**
+ * The manifest name of the plugin whose namespace an `/x/` route path falls in,
+ * or undefined for a workspace route.
+ *
+ * The dispatcher marks that plugin as in context for the handler's execution,
+ * so host APIs a route handler reaches (`resolveCredential`,
+ * `indexDocument`) scope to the owning plugin exactly as they do inside its
+ * hooks and tools.
+ */
+export function pluginNameForRoutePath(routePath: string): string | undefined {
+  const segments = routePath.split("/");
+  if (segments[0] !== PLUGIN_ROUTE_SEGMENT) {
+    return undefined;
+  }
+  return segments[1] || undefined;
+}
+
 /**
  * Resolve an `/x/` route path to the base directory + sub-path the handler file
  * is looked up under.
@@ -87,7 +104,7 @@ export interface RouteLocation {
 export function resolveRouteLocation(routePath: string): RouteLocation | null {
   const segments = routePath.split("/");
   if (segments[0] === PLUGIN_ROUTE_SEGMENT) {
-    const pluginName = segments[1];
+    const pluginName = pluginNameForRoutePath(routePath);
     if (!pluginName) {
       return null;
     }

package/src/runtime/routes/workspace-routes.ts

@@ -19,7 +19,6 @@ import { basename, dirname, join } from "node:path";
 
 import { z } from "zod";
 
-import { rebindDocumentsToRenamedPath } from "../../documents/document-store.js";
 import { getWorkspaceDir } from "../../util/platform.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { publishSoundsConfigUpdated } from "../sync/resource-sync-events.js";
@@ -35,7 +34,6 @@ import {
   isTextMimeType,
   MAX_INLINE_TEXT_SIZE,
   resolveWorkspacePath,
-  toWorkspaceRelativePath,
   writeWorkspaceFile,
 } from "./workspace-utils.js";
 
@@ -505,13 +503,6 @@ function handleWorkspaceRename({ body, headers }: RouteHandlerArgs) {
 
   mkdirSync(dirname(resolvedNew), { recursive: true });
   renameSync(resolvedOld, resolvedNew);
-  // File-backed documents key off the canonical relative path, so they follow
-  // the file to its new name. The request strings are not canonical, hence the
-  // resolved paths.
-  rebindDocumentsToRenamedPath({
-    oldPath: toWorkspaceRelativePath(resolvedOld),
-    newPath: toWorkspaceRelativePath(resolvedNew),
-  });
   publishSoundsConfigUpdatedForPaths(
     [oldPath, newPath],
     headers?.["x-vellum-client-id"]?.trim() || undefined,

package/src/runtime/routes/workspace-utils.ts

@@ -6,7 +6,7 @@ import {
   statSync,
   writeFileSync,
 } from "node:fs";
-import { dirname, relative, resolve, sep } from "node:path";
+import { dirname, resolve, sep } from "node:path";
 
 import { getWorkspaceDir } from "../../util/platform.js";
 import { BadRequestError, ConflictError } from "./errors.js";
@@ -85,22 +85,12 @@ export function resolveWorkspacePath(
   return resolved;
 }
 
-/**
- * Normalise a workspace path to the canonical relative form used as a stable
- * key for the file — forward slashes, no `.`/`..` segments, no leading slash.
- * `absolutePath` must already have passed {@link resolveWorkspacePath}.
- */
-export function toWorkspaceRelativePath(absolutePath: string): string {
-  return relative(getWorkspaceDir(), absolutePath).split(sep).join("/");
-}
-
 /**
  * Write bytes to a workspace-relative path, enforcing the workspace boundary.
  *
  * This is the one write primitive behind every daemon-side workspace file
- * write: the workspace write route and the document store's write-through for
- * file-backed documents both go through it, so the traversal and
- * directory-conflict rules cannot drift apart.
+ * write, so the traversal and directory-conflict rules cannot drift apart
+ * between callers.
  *
  * Returns the number of bytes written. Throws {@link BadRequestError} when the
  * path escapes the workspace and {@link ConflictError} when it names a

package/src/runtime/services/conversation-serializer.ts

@@ -244,13 +244,18 @@ export function serializeConversationSummary(params: {
 
 /**
  * Build a full conversation detail response from a conversation ID.
- * Returns null if the conversation doesn't exist.
+ * Returns null if the conversation doesn't exist, or if it is a legacy
+ * `private` row: every listing hides those by type (see
+ * `standardListingVisibilitySql`) and migration cleanup deletes them, and the
+ * wire type collapses the value to `standard`, so serving one by id would let
+ * a client that only holds a stale id (a persisted last-viewed conversation)
+ * resurrect a row it can never see listed.
  */
 export function buildConversationDetailResponse(
   conversationId: string,
 ): { conversation: ReturnType<typeof serializeConversationSummary> } | null {
   const conversation = getConversation(conversationId);
-  if (!conversation) {
+  if (!conversation || conversation.conversationType === "private") {
     return null;
   }
 

package/src/schedule/__tests__/plugin-schedule-declarations.test.ts

@@ -487,11 +487,39 @@ describe("parsePluginScheduleDeclarations", () => {
       expect(after).not.toBe(before);
     });
 
-    test("changes when a helper file inside a directory declaration is edited or renamed", () => {
+    test("changes when config.json is edited", () => {
+      const pluginDir = makePlugin(FULL_DIGEST);
+      const before = parsePluginScheduleDeclarations(pluginDir, "p")
+        .declarations[0]!.definitionHash;
+      writeFileSync(
+        join(pluginDir, "schedules", "digest", "config.json"),
+        JSON.stringify({ expression: "0 10 * * *" }),
+      );
+      const after = parsePluginScheduleDeclarations(pluginDir, "p")
+        .declarations[0]!.definitionHash;
+      expect(after).not.toBe(before);
+    });
+
+    test("changes when the index.sh entrypoint is edited", () => {
+      const pluginDir = makePlugin({
+        "backup/config.json": JSON.stringify({ expression: "0 3 * * *" }),
+        "backup/index.sh": "echo v1\n",
+      });
+      const parse = () =>
+        parsePluginScheduleDeclarations(pluginDir, "p").declarations[0]!
+          .definitionHash;
+      const before = parse();
+      writeFileSync(
+        join(pluginDir, "schedules", "backup", "index.sh"),
+        "echo v2\n",
+      );
+      expect(parse()).not.toBe(before);
+    });
+
+    test("ignores every other file under the declaration directory", () => {
       const pluginDir = makePlugin({
         "backup/config.json": JSON.stringify({ expression: "0 3 * * *" }),
         "backup/index.sh": "sh lib/helper.sh\n",
-        "backup/lib/helper.sh": "echo v1\n",
       });
       const parse = () =>
         parsePluginScheduleDeclarations(pluginDir, "p").declarations[0]!
@@ -505,15 +533,50 @@ describe("parsePluginScheduleDeclarations", () => {
         "lib",
         "helper.sh",
       );
+      mkdirSync(dirname(helperPath), { recursive: true });
+      writeFileSync(helperPath, "echo v1\n");
+      const statePath = join(
+        pluginDir,
+        "schedules",
+        "backup",
+        "data",
+        "state.json",
+      );
+      mkdirSync(dirname(statePath), { recursive: true });
+      writeFileSync(statePath, JSON.stringify({ lastRun: 1 }));
+      expect(parse()).toBe(original);
+
       writeFileSync(helperPath, "echo v2\n");
-      const afterEdit = parse();
-      expect(afterEdit).not.toBe(original);
+      writeFileSync(statePath, JSON.stringify({ lastRun: 2 }));
+      expect(parse()).toBe(original);
 
       renameSync(
         helperPath,
         join(pluginDir, "schedules", "backup", "lib", "helper2.sh"),
       );
-      expect(parse()).not.toBe(afterEdit);
+      expect(parse()).toBe(original);
+
+      rmSync(join(pluginDir, "schedules", "backup", "data"), {
+        recursive: true,
+        force: true,
+      });
+      expect(parse()).toBe(original);
+    });
+
+    test("hashes a two-file declaration to its known value", () => {
+      const pluginDir = makePlugin({
+        "backup/config.json": JSON.stringify({ expression: "0 3 * * *" }),
+        "backup/index.sh": "echo backup\n",
+      });
+      // Pinned so stored rows keep their hash across upgrades. It holds only
+      // while the hashed paths stay `<name>/config.json` and
+      // `<name>/<entrypoint>`, relative to schedules/.
+      expect(
+        parsePluginScheduleDeclarations(pluginDir, "p").declarations[0]!
+          .definitionHash,
+      ).toBe(
+        "0b5722fc45abdd2c46672f275e3bcf548016ee5c0722da5a0588ef45fa7bbcab",
+      );
     });
 
     test("differs between two schedules with different names but same content", () => {