@vellumai/assistant 0.10.2-dev.202606241651.2d2b40d → 0.10.2-dev.202606241743.799fce7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.2-dev.202606241651.2d2b40d",
+  "version": "0.10.2-dev.202606241743.799fce7",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/mtime-cache.test.ts

@@ -7,7 +7,7 @@
  * cache miss (changed mtime → re-import), plugin deletion (eviction),
  * and hook collection across multiple plugins.
  */
-import { mkdirSync, rmSync, utimesSync,writeFileSync } from "node:fs";
+import { mkdirSync, rmSync, utimesSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
@@ -19,8 +19,8 @@ import {
   test,
 } from "bun:test";
 
+import { _inspectHookCacheForTests } from "../hooks/hook-loader.js";
 import {
-  _inspectHookCacheForTests,
   _inspectToolCacheForTests,
   getCachedUserTools,
   getUserHooksFor,
@@ -62,7 +62,15 @@ function writeHook(dir: string, hookName: string, body: string): void {
 function writeInstallMeta(dir: string, installedAt: string): void {
   writeFileSync(
     join(dir, "install-meta.json"),
-    JSON.stringify({ name: "test", installedAt, source: { kind: "github", owner: "test", repo: "test", ref: "main" } }, null, 2),
+    JSON.stringify(
+      {
+        name: "test",
+        installedAt,
+        source: { kind: "github", owner: "test", repo: "test", ref: "main" },
+      },
+      null,
+      2,
+    ),
   );
 }
 
@@ -72,6 +80,20 @@ function writeTool(dir: string, toolName: string, body: string): void {
   writeFileSync(join(toolsDir, `${toolName}.ts`), body);
 }
 
+/** The standalone workspace hooks directory (`<workspace>/hooks/`). */
+const WORKSPACE_HOOKS_DIR = join(ROOT, "hooks");
+
+function ensureWorkspaceHooksDir(): void {
+  rmSync(WORKSPACE_HOOKS_DIR, { recursive: true, force: true });
+  mkdirSync(WORKSPACE_HOOKS_DIR, { recursive: true });
+}
+
+/** Write a standalone hook file directly under `<workspace>/hooks/`. */
+function writeWorkspaceHook(hookName: string, body: string): void {
+  mkdirSync(WORKSPACE_HOOKS_DIR, { recursive: true });
+  writeFileSync(join(WORKSPACE_HOOKS_DIR, `${hookName}.ts`), body);
+}
+
 /**
  * Bump a file's mtime forward by ~2 seconds so the mtime cache detects a
  * change. Using utimesSync avoids race conditions with filesystem mtime
@@ -97,6 +119,7 @@ beforeAll(() => {
 
 beforeEach(() => {
   ensurePluginsDir();
+  ensureWorkspaceHooksDir();
   resetPluginCacheForTests();
 });
 
@@ -338,7 +361,9 @@ describe("plugin mtime cache (per-surface)", () => {
     expect(hooks).toHaveLength(2);
 
     // beta was installed earlier (Jan 1) so it should come first.
-    const results = hooks.map((fn) => (fn as unknown as () => { tag: string })());
+    const results = hooks.map((fn) =>
+      (fn as unknown as () => { tag: string })(),
+    );
     expect(results[0]!.tag).toBe("beta");
     expect(results[1]!.tag).toBe("alpha");
   });
@@ -368,8 +393,124 @@ describe("plugin mtime cache (per-surface)", () => {
     const hooks = await getUserHooksFor("user-prompt-submit");
     expect(hooks).toHaveLength(2);
 
-    const results = hooks.map((fn) => (fn as unknown as () => { tag: string })());
+    const results = hooks.map((fn) =>
+      (fn as unknown as () => { tag: string })(),
+    );
     expect(results[0]!.tag).toBe("dated");
     expect(results[1]!.tag).toBe("undated");
   });
 });
+
+describe("workspace hooks (<workspace>/hooks/)", () => {
+  test("getUserHooksFor loads a standalone workspace hook", async () => {
+    writeWorkspaceHook(
+      "user-prompt-submit",
+      `export default () => ({ ws: 1 });`,
+    );
+
+    await populateCacheAtBoot();
+
+    const hooks = await getUserHooksFor("user-prompt-submit");
+    expect(hooks).toHaveLength(1);
+  });
+
+  test("workspace hooks load even when no plugins directory exists", async () => {
+    rmSync(PLUGINS_DIR, { recursive: true, force: true });
+    writeWorkspaceHook("post-tool-use", `export default () => ({ ws: 1 });`);
+
+    await populateCacheAtBoot();
+
+    const hooks = await getUserHooksFor("post-tool-use");
+    expect(hooks).toHaveLength(1);
+    expect(getCachedUserTools()).toHaveLength(0);
+  });
+
+  // NB: each test below uses a distinct hook event name so the workspace
+  // hook file path is unique. Bun caches dynamic import() by URL and does not
+  // bust on content change, so reusing `<workspace>/hooks/<name>.ts` across
+  // tests would return a stale module (the existing plugin tests dodge this
+  // by using a fresh plugin directory per test).
+  test("plugin hooks run before the workspace hook for the same event", async () => {
+    const dir = freshPluginDir("ordering-plugin");
+    writePackageJson(dir, { ...SIMPLE_PKG, name: "ordering-plugin" });
+    writeHook(
+      dir,
+      "pre-model-call",
+      `export default () => ({ tag: "plugin" });`,
+    );
+    writeWorkspaceHook(
+      "pre-model-call",
+      `export default () => ({ tag: "workspace" });`,
+    );
+
+    await populateCacheAtBoot();
+
+    const hooks = await getUserHooksFor("pre-model-call");
+    expect(hooks).toHaveLength(2);
+    const results = hooks.map((fn) =>
+      (fn as unknown as () => { tag: string })(),
+    );
+    expect(results[0]!.tag).toBe("plugin");
+    expect(results[1]!.tag).toBe("workspace");
+  });
+
+  test("editing a workspace hook file triggers re-import", async () => {
+    const hookFile = join(WORKSPACE_HOOKS_DIR, "post-model-call.ts");
+    writeWorkspaceHook("post-model-call", `export default () => ({ v: 1 });`);
+
+    await populateCacheAtBoot();
+
+    const before = _inspectHookCacheForTests().find((c) =>
+      c.key.startsWith("__workspace__/"),
+    );
+    expect(before).toBeDefined();
+
+    touchFile(hookFile);
+    await getUserHooksFor("post-model-call");
+
+    const after = _inspectHookCacheForTests().find((c) =>
+      c.key.startsWith("__workspace__/"),
+    );
+    expect(after?.sourceMtime).not.toBe(before?.sourceMtime);
+  });
+
+  test("deleting a workspace hook file evicts it on next read", async () => {
+    const hookFile = join(WORKSPACE_HOOKS_DIR, "stop.ts");
+    writeWorkspaceHook("stop", `export default () => ({ v: 1 });`);
+
+    await populateCacheAtBoot();
+    expect(await getUserHooksFor("stop")).toHaveLength(1);
+
+    rmSync(hookFile, { force: true });
+
+    const hooks = await getUserHooksFor("stop");
+    expect(hooks).toHaveLength(0);
+  });
+
+  test("a newly added workspace hook is picked up without restart", async () => {
+    await populateCacheAtBoot();
+    expect(await getUserHooksFor("post-compact")).toHaveLength(0);
+
+    writeWorkspaceHook("post-compact", `export default () => ({ v: 1 });`);
+
+    expect(await getUserHooksFor("post-compact")).toHaveLength(1);
+  });
+
+  test("a workspace init hook runs once at boot", async () => {
+    // The init hook writes a sentinel file so we can observe it ran exactly
+    // once during populateCacheAtBoot.
+    const sentinel = join(ROOT, "ws-init-ran.txt");
+    rmSync(sentinel, { force: true });
+    writeWorkspaceHook(
+      "init",
+      `import { appendFileSync } from "node:fs";
+       export default () => { appendFileSync(${JSON.stringify(sentinel)}, "x"); };`,
+    );
+
+    await populateCacheAtBoot();
+
+    const { readFileSync: rf, existsSync: ex } = await import("node:fs");
+    expect(ex(sentinel)).toBe(true);
+    expect(rf(sentinel, "utf8")).toBe("x");
+  });
+});

package/src/__tests__/workspace-migration-remove-hooks.test.ts

@@ -11,7 +11,7 @@ let hooksDir: string;
 function freshWorkspace(): void {
   workspaceDir = join(
     tmpdir(),
-    `vellum-migration-046-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    `vellum-migration-048-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
   );
   hooksDir = join(workspaceDir, "hooks");
   mkdirSync(workspaceDir, { recursive: true });
@@ -30,29 +30,22 @@ afterEach(() => {
   }
 });
 
-describe("048-remove-workspace-hooks migration", () => {
+describe("048-remove-workspace-hooks migration (retained no-op)", () => {
   test("has correct migration id", () => {
     expect(removeWorkspaceHooksMigration.id).toBe("048-remove-workspace-hooks");
   });
 
-  test("removes a populated hooks directory", () => {
+  test("preserves a populated hooks directory now that it is a supported surface", () => {
     mkdirSync(hooksDir, { recursive: true });
-    mkdirSync(join(hooksDir, "my-hook"), { recursive: true });
-    writeFileSync(join(hooksDir, "my-hook", "manifest.json"), "{}");
-    writeFileSync(join(hooksDir, "my-hook", "run.sh"), "#!/bin/sh\n");
-    writeFileSync(join(hooksDir, "README.md"), "hooks live here");
+    writeFileSync(
+      join(hooksDir, "user-prompt-submit.ts"),
+      "export default () => {};",
+    );
 
     removeWorkspaceHooksMigration.run(workspaceDir);
 
-    expect(existsSync(hooksDir)).toBe(false);
-  });
-
-  test("removes an empty hooks directory", () => {
-    mkdirSync(hooksDir, { recursive: true });
-
-    removeWorkspaceHooksMigration.run(workspaceDir);
-
-    expect(existsSync(hooksDir)).toBe(false);
+    expect(existsSync(hooksDir)).toBe(true);
+    expect(existsSync(join(hooksDir, "user-prompt-submit.ts"))).toBe(true);
   });
 
   test("no-op when the hooks directory does not exist", () => {
@@ -65,35 +58,21 @@ describe("048-remove-workspace-hooks migration", () => {
     expect(existsSync(workspaceDir)).toBe(true);
   });
 
-  test("idempotent — safe to re-run after the directory is gone", () => {
+  test("idempotent — safe to re-run", () => {
     mkdirSync(hooksDir, { recursive: true });
-    writeFileSync(join(hooksDir, "stale.json"), "{}");
+    writeFileSync(join(hooksDir, "stop.ts"), "export default () => {};");
 
     removeWorkspaceHooksMigration.run(workspaceDir);
-    // Second invocation is a no-op and must not throw.
     removeWorkspaceHooksMigration.run(workspaceDir);
 
-    expect(existsSync(hooksDir)).toBe(false);
-  });
-
-  test("does not touch unrelated workspace entries", () => {
-    mkdirSync(hooksDir, { recursive: true });
-    writeFileSync(join(hooksDir, "stale.json"), "{}");
-    const skillsDir = join(workspaceDir, "skills");
-    mkdirSync(skillsDir, { recursive: true });
-    writeFileSync(join(skillsDir, "keep.md"), "keep me");
-
-    removeWorkspaceHooksMigration.run(workspaceDir);
-
-    expect(existsSync(hooksDir)).toBe(false);
-    expect(existsSync(skillsDir)).toBe(true);
-    expect(existsSync(join(skillsDir, "keep.md"))).toBe(true);
+    expect(existsSync(join(hooksDir, "stop.ts"))).toBe(true);
   });
 
   describe("down()", () => {
     test("is a no-op", () => {
+      mkdirSync(hooksDir, { recursive: true });
       removeWorkspaceHooksMigration.down(workspaceDir);
-      expect(existsSync(hooksDir)).toBe(false);
+      expect(existsSync(hooksDir)).toBe(true);
     });
   });
 });

package/src/daemon/conversation-surfaces.ts

@@ -583,12 +583,20 @@ function normalizeCardShowData(
           (typeof input[k] === "string" &&
             (input[k] as string).trim().length > 0),
       );
-      Sentry.addBreadcrumb({
-        category: "card-normalization",
-        message: `alias recovery: ${usedAliases.join(", ")} → body`,
-        level: "info",
-        data: { usedAliases, candidateCount: candidates.length },
-      });
+      try {
+        Sentry.withScope((scope) => {
+          scope.setLevel("info");
+          scope.setTag("card_normalization", "alias_recovery");
+          scope.setTag("target_field", "body");
+          scope.setContext("card_normalization", {
+            used_aliases: usedAliases,
+            candidate_count: candidates.length,
+          });
+          Sentry.captureMessage("card_normalization:alias_recovery:body");
+        });
+      } catch {
+        // Never let telemetry break card rendering.
+      }
     }
   }
   for (const key of bodyAliasKeys) {
@@ -605,11 +613,16 @@ function normalizeCardShowData(
     ]);
     if (aliased !== undefined) {
       normalized.title = aliased;
-      Sentry.addBreadcrumb({
-        category: "card-normalization",
-        message: `alias recovery: title`,
-        level: "info",
-      });
+      try {
+        Sentry.withScope((scope) => {
+          scope.setLevel("info");
+          scope.setTag("card_normalization", "alias_recovery");
+          scope.setTag("target_field", "title");
+          Sentry.captureMessage("card_normalization:alias_recovery:title");
+        });
+      } catch {
+        // Never let telemetry break card rendering.
+      }
     }
   }
   for (const key of titleAliasKeys) {
@@ -634,11 +647,16 @@ function normalizeCardShowData(
     ]);
     if (aliased !== undefined) {
       normalized.subtitle = aliased;
-      Sentry.addBreadcrumb({
-        category: "card-normalization",
-        message: `alias recovery: subtitle`,
-        level: "info",
-      });
+      try {
+        Sentry.withScope((scope) => {
+          scope.setLevel("info");
+          scope.setTag("card_normalization", "alias_recovery");
+          scope.setTag("target_field", "subtitle");
+          Sentry.captureMessage("card_normalization:alias_recovery:subtitle");
+        });
+      } catch {
+        // Never let telemetry break card rendering.
+      }
     }
   }
   for (const key of subtitleAliasKeys) {
@@ -688,12 +706,21 @@ function normalizeCardShowData(
       { droppedKeys },
       "ui_show card data carried keys the card contract does not model; their content will not render",
     );
-    Sentry.addBreadcrumb({
-      category: "card-normalization",
-      message: `dropped keys: ${droppedKeys.join(", ")}`,
-      level: "warning",
-      data: { droppedKeys },
-    });
+    try {
+      Sentry.withScope((scope) => {
+        scope.setLevel("warning");
+        scope.setTag("card_normalization", "dropped_keys");
+        scope.setContext("card_normalization", {
+          dropped_count: droppedKeys.length,
+        });
+        // Key names are model-controlled, so they ride in `extra`, which
+        // beforeSend redacts (it does not scrub `contexts`) — see instrument.ts.
+        scope.setExtra("dropped_keys", droppedKeys);
+        Sentry.captureMessage("card_normalization:dropped_keys");
+      });
+    } catch {
+      // Never let telemetry break card rendering.
+    }
   }
   const parsed = CardSurfaceDataSchema.safeParse(normalized);
   if (parsed.success) {
@@ -2912,18 +2939,27 @@ export async function surfaceProxyResolver(
         if (result.success) {
           valid.push(result.data);
         } else {
-          Sentry.addBreadcrumb({
-            category: "card-normalization",
-            message: "action parse failure (individual)",
-            level: "warning",
-            data: {
-              issuePaths: result.error.issues.map((i) => i.path.join(".")),
-              keys:
+          try {
+            Sentry.withScope((scope) => {
+              scope.setLevel("warning");
+              scope.setTag("card_normalization", "action_parse_failure");
+              scope.setContext("card_normalization", {
+                issue_paths: result.error.issues.map((i) => i.path.join(".")),
+              });
+              // raw object keys are model-controlled, so they ride in `extra`,
+              // which beforeSend redacts (it does not scrub `contexts`) — see
+              // instrument.ts.
+              scope.setExtra(
+                "raw_keys",
                 typeof raw === "object" && raw !== null
                   ? Object.keys(raw)
                   : [typeof raw],
-            },
-          });
+              );
+              Sentry.captureMessage("card_normalization:action_parse_failure");
+            });
+          } catch {
+            // Never let telemetry break card rendering.
+          }
         }
       }
       inputActions = valid.length > 0 ? valid : undefined;
@@ -2961,11 +2997,24 @@ export async function surfaceProxyResolver(
         !hasTemplate &&
         !hasActions
       ) {
-        Sentry.addBreadcrumb({
-          category: "card-normalization",
-          message: "empty card rejected",
-          level: "warning",
-        });
+        try {
+          Sentry.withScope((scope) => {
+            scope.setLevel("warning");
+            scope.setTag("card_normalization", "empty_card_rejected");
+            scope.setContext("card_normalization", {
+              surface_type: surfaceType,
+              has_title: hasTitle,
+              has_body: hasBody,
+              has_subtitle: hasSubtitle,
+              has_metadata: hasMetadata,
+              has_template: hasTemplate,
+              has_actions: hasActions,
+            });
+            Sentry.captureMessage("card_normalization:empty_card_rejected");
+          });
+        } catch {
+          // Never let telemetry break card rendering.
+        }
         return {
           content:
             "Error: ui_show card requires content — provide `data.body`, a `template` (e.g. task_progress with steps), `data.metadata`, `data.subtitle`, a `title`, or `actions`. The surface was not displayed because it carried no renderable content. Resend ui_show with populated card content.",