@vellumai/assistant 0.8.6 → 0.8.7

package/src/memory/v3/tree.ts

@@ -0,0 +1,174 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { parse as parseYaml } from "yaml";
+
+import { getWorkspaceDir } from "../../util/platform.js";
+import type {
+  LeafFrontmatter,
+  LeafNode,
+  LeafPath,
+  LeafTree,
+  Slug,
+} from "./types.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** Bundled stub data shipped alongside the loader. */
+const BUNDLED_DATA_DIR = join(HERE, "data");
+
+/**
+ * Resolve the directory the loaders should read leaf-tree artifacts from.
+ *
+ * Prefers a maintainer's per-instance workspace override
+ * (`<workspace>/memory/v3/data/`) when present, otherwise falls back to the
+ * generic bundled stub shipped in this package.
+ *
+ * The public {@link loadLeafTree} API still takes an explicit `dataDir` for
+ * testability; orchestrators that want the runtime default call this helper.
+ */
+export function resolveDataDir(): string {
+  const workspaceData = join(getWorkspaceDir(), "memory", "v3", "data");
+  if (existsSync(workspaceData)) return workspaceData;
+  return BUNDLED_DATA_DIR;
+}
+
+/** Recursively collect every `*.md` file under `dir`. */
+async function collectMarkdownFiles(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await collectMarkdownFiles(full)));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * Split a leaf `.md` file into its YAML frontmatter and body.
+ *
+ * Frontmatter is the `---`-delimited block at the top of the file; everything
+ * after the closing delimiter is the description body.
+ */
+function splitFrontmatter(raw: string): { frontmatter: string; body: string } {
+  const normalized = raw.replace(/^/, "");
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(normalized);
+  if (!match) {
+    throw new Error("leaf markdown is missing YAML frontmatter");
+  }
+  return { frontmatter: match[1], body: match[2] };
+}
+
+function parseLeafFrontmatter(yaml: string, file: string): LeafFrontmatter {
+  const parsed = parseYaml(yaml) as unknown;
+  if (parsed === null || typeof parsed !== "object") {
+    throw new Error(`leaf ${file} frontmatter is not a mapping`);
+  }
+  const record = parsed as Record<string, unknown>;
+  if (typeof record.path !== "string") {
+    throw new Error(`leaf ${file} frontmatter is missing a string \`path\``);
+  }
+  if (typeof record.in_core !== "boolean") {
+    throw new Error(
+      `leaf ${file} frontmatter is missing a boolean \`in_core\``,
+    );
+  }
+  return {
+    path: record.path,
+    in_core: record.in_core,
+    ...(typeof record.id === "string" ? { id: record.id } : {}),
+  };
+}
+
+/** Derive the canonical leaf path from a file's location under `leaves/`. */
+function pathFromLocation(leavesDir: string, file: string): LeafPath {
+  return relative(leavesDir, file).replace(/\.md$/, "").split(sep).join("/");
+}
+
+/**
+ * Load the leaf tree from `dataDir`. READ-ONLY: walks `leaves/**\/*.md` and
+ * reads `assignments.json` without mutating anything on disk.
+ *
+ * Builds:
+ * - `leaves`: leaf path → {@link LeafNode} (frontmatter, description, domain,
+ *   and the slugs assigned to it).
+ * - `byPage`: slug → the leaf paths it is assigned to (inverted assignments).
+ *
+ * Page→leaf membership precedence is per-page: when `pageLeaves` supplies a
+ * non-empty array for a slug, those frontmatter-derived leaves win for that
+ * page; slugs absent from `pageLeaves` (or mapped to an empty array) fall back
+ * to `assignments.json`. Omitting `pageLeaves` reproduces the legacy
+ * assignments.json-only behavior exactly (used by the bundled stub and tests);
+ * orchestrators supply `pageLeaves` from the page index.
+ */
+export async function loadLeafTree(
+  dataDir: string,
+  pageLeaves?: Map<Slug, LeafPath[]>,
+): Promise<LeafTree> {
+  const leavesDir = join(dataDir, "leaves");
+  const files = await collectMarkdownFiles(leavesDir);
+
+  const nodes = await Promise.all(
+    files.map(async (file): Promise<LeafNode> => {
+      const raw = await readFile(file, "utf8");
+      const { frontmatter, body } = splitFrontmatter(raw);
+      const path = pathFromLocation(leavesDir, file);
+      return {
+        path,
+        frontmatter: parseLeafFrontmatter(frontmatter, file),
+        description: body.trim(),
+        members: [],
+        domain: path.split("/")[0],
+      };
+    }),
+  );
+
+  const leaves = new Map<LeafPath, LeafNode>(
+    nodes.map((node) => [node.path, node]),
+  );
+
+  const assignmentsRaw = await readFile(
+    join(dataDir, "assignments.json"),
+    "utf8",
+  );
+  const assignments = JSON.parse(assignmentsRaw) as Record<Slug, LeafPath[]>;
+
+  const slugs = new Set<Slug>(Object.keys(assignments));
+  if (pageLeaves) for (const slug of pageLeaves.keys()) slugs.add(slug);
+
+  const byPage = new Map<Slug, LeafPath[]>();
+  for (const slug of slugs) {
+    const fromFrontmatter = pageLeaves?.get(slug);
+    const leafPaths =
+      fromFrontmatter && fromFrontmatter.length > 0
+        ? fromFrontmatter
+        : (assignments[slug] ?? []);
+    byPage.set(slug, [...leafPaths]);
+    for (const leafPath of leafPaths) {
+      leaves.get(leafPath)?.members.push(slug);
+    }
+  }
+
+  return { leaves, byPage };
+}
+
+/** The slugs assigned to a leaf. */
+export function membersOf(tree: LeafTree, leaf: LeafPath): Slug[] {
+  return tree.leaves.get(leaf)?.members ?? [];
+}
+
+/** The leaf paths a slug is assigned to. */
+export function leavesOf(tree: LeafTree, slug: Slug): LeafPath[] {
+  return tree.byPage.get(slug) ?? [];
+}
+
+/** The unique slugs owned by every leaf in `core` (expand leaf-paths → slugs). */
+export function coreSlugs(tree: LeafTree, core: Set<LeafPath>): Set<Slug> {
+  return new Set([...core].flatMap((leaf) => membersOf(tree, leaf)));
+}

package/src/memory/v3/types.ts

@@ -1,65 +1,51 @@
-// ---------------------------------------------------------------------------
-// Memory v3 — Shared types
-// ---------------------------------------------------------------------------
-//
-// Types shared across the v3 memory subsystem. Like v2, every value here
-// crosses a serialization boundary — YAML frontmatter on disk — so it ships as
-// a Zod schema with an inferred TypeScript type so runtime validation runs
-// wherever a node is read.
-//
-// This file must not import from any other `memory/v3/*` module — it is the
-// leaf of the v3 dependency graph.
-
-import { z } from "zod";
-
-// ---------------------------------------------------------------------------
-// Tree nodes
-// ---------------------------------------------------------------------------
+export type LeafPath = string; // dot- or slash-pathed taxonomy node
+export type Slug = string;
 
 /**
- * YAML frontmatter at the top of a v3 tree node (`memory/tree/<id>.md`).
- *
- * The v3 tree is a DAG *overlay* over the existing flat `memory/concepts/`
- * pages. A node organizes a region of the graph: its markdown body is the
- * node's full self-description and `children` is the list of outgoing edges.
- *
- * `children` is the canonical, ordered list of child *references*. Each entry
- * is either:
- *   - `"page:<page-slug>"` — a leaf concept page (canonical content stays in
- *     `memory/concepts/<page-slug>.md`, shared and untouched by v3), or
- *   - `"node:<node-id>"` — a sub-node in the v3 tree.
- *
- * This reference list IS the DAG edge — it is the portable replacement for the
- * filesystem symlinks an earlier design would have used. A page or node may be
- * referenced by more than one parent (hence DAG, not tree).
- *
- * `routing_hints` is a thin, hand-written line of cross-branch disambiguation
- * — e.g. "for *work* relationships see people/colleagues, not this node".
- * Kept deliberately small so it stays cheap to inject during routing.
- *
- * `summary` is the node's self-description headline (1-line); the markdown body
- * is the full self-description. Optional so a freshly authored node with only a
- * body still parses.
+ * Injection-block id for the v3 live `<memory>` block. Shared between the
+ * producer (the v3 injector in `shadow-plugin.ts`) and the v2-suppression
+ * consumer (`conversation-runtime-assembly.ts`), which keys off this id to
+ * detect that v3 actually produced a block this turn. Keeping it in one place
+ * makes a rename a compile error on both sides instead of a silent
+ * suppression bypass.
  */
-export const TreeNodeFrontmatterSchema = z
-  .object({
-    children: z.array(z.string()).default([]),
-    routing_hints: z.string().optional(),
-    summary: z.string().optional(),
-  })
-  .strict();
+export const MEMORY_V3_BLOCK_ID = "memory-v3" as const;
 
-export type TreeNodeFrontmatter = z.infer<typeof TreeNodeFrontmatterSchema>;
+export interface LeafFrontmatter {
+  path: LeafPath;
+  in_core: boolean;
+  /**
+   * Optional stable identifier for the leaf, independent of its taxonomy path.
+   * Older leaves predate this field and omit it, so it is optional.
+   */
+  id?: string;
+}
 
-/**
- * A single tree node on disk. The id is the relative path from
- * `memory/tree/` minus `.md`, using forward slashes — so `people` and
- * `people/colleagues` are both valid ids. The id is the stable identity used
- * in `children` references (`node:<id>`) and is the portable node handle a
- * future data-migration authors by hand.
- */
-export type TreeNode = {
-  id: string;
-  frontmatter: TreeNodeFrontmatter;
-  body: string;
-};
+export interface LeafNode {
+  path: LeafPath;
+  frontmatter: LeafFrontmatter;
+  description: string;
+  members: Slug[];
+  domain: string;
+}
+
+export interface LeafTree {
+  leaves: Map<LeafPath, LeafNode>;
+  byPage: Map<Slug, LeafPath[]>;
+}
+
+export interface WorkingSetEntry {
+  slug: Slug;
+  selectedAtTurn: number;
+  pinned: boolean;
+  lastSeenTurn: number;
+}
+
+export interface TurnContext {
+  conversationId: string;
+  turnNumber: number;
+  currentMessage: string;
+  recentContext: string;
+}
+
+export type SelectionSource = "l1+l2" | "core+l2" | "needle" | "carry-forward";

package/src/memory/v3/working-set.ts

@@ -0,0 +1,88 @@
+import { Slug, WorkingSetEntry } from "./types.js";
+
+/**
+ * Scores a working-set entry for cap eviction. Lower score = more evictable.
+ * This is the pluggable seam for a future salience-weighted policy; the
+ * default is plain LRU on `lastSeenTurn`.
+ */
+export type ScoreFn = (entry: WorkingSetEntry) => number;
+
+/** Default eviction score: least-recently-seen entries evict first. */
+function lruScore(entry: WorkingSetEntry): number {
+  return entry.lastSeenTurn;
+}
+
+export class WorkingSet {
+  private entries = new Map<Slug, WorkingSetEntry>();
+
+  constructor(
+    private readonly maxPages = 150,
+    private readonly evictWindow = 5,
+    private readonly scoreFn: ScoreFn = lruScore,
+  ) {}
+
+  recordSelection(slug: Slug, turn: number, pinned: boolean): void {
+    const existing = this.entries.get(slug);
+    this.entries.set(slug, {
+      slug,
+      selectedAtTurn: existing?.selectedAtTurn ?? turn,
+      pinned: existing?.pinned || pinned,
+      lastSeenTurn: turn,
+    });
+  }
+
+  union(): Set<Slug> {
+    return new Set(this.entries.keys());
+  }
+
+  size(): number {
+    return this.entries.size;
+  }
+
+  /**
+   * Prune the working set, in order:
+   *   1. Core slugs never belong here — drop any entry whose slug is core.
+   *   2. Pinned entries never evict.
+   *   3. Window eviction: drop a non-pinned entry unseen for more than
+   *      `evictWindow` turns.
+   *   4. Cap eviction: while over `maxPages`, evict the lowest-scoring
+   *      non-pinned entry first (ties broken deterministically).
+   */
+  evict(currentTurn: number, coreSlugs: Set<Slug>): void {
+    // 1. Core slugs are owned by core, not the working set.
+    for (const slug of this.entries.keys()) {
+      if (coreSlugs.has(slug)) {
+        this.entries.delete(slug);
+      }
+    }
+
+    // 2 + 3. Window eviction for stale non-pinned entries.
+    for (const [slug, entry] of this.entries) {
+      if (
+        !entry.pinned &&
+        currentTurn - entry.lastSeenTurn > this.evictWindow
+      ) {
+        this.entries.delete(slug);
+      }
+    }
+
+    // 4. Cap eviction: evict the lowest-scoring non-pinned entry until the
+    // set fits. Sort once (ascending score, then slug for determinism) and
+    // walk the candidates.
+    if (this.entries.size <= this.maxPages) {
+      return;
+    }
+    const evictable = [...this.entries.values()]
+      .filter((entry) => !entry.pinned)
+      .sort(
+        (a, b) =>
+          this.scoreFn(a) - this.scoreFn(b) || (a.slug < b.slug ? -1 : 1),
+      );
+    for (const entry of evictable) {
+      if (this.entries.size <= this.maxPages) {
+        break;
+      }
+      this.entries.delete(entry.slug);
+    }
+  }
+}

package/src/messaging/providers/slack/render-transcript.test.ts

@@ -200,7 +200,7 @@ describe("renderSlackTranscript — basics", () => {
         "user",
         "[mar 4 2026 8:37 PM MT aaron] nm, i wonder how my assistant is doing",
       ),
-      textMsg("assistant", "[mar 4 2026 8:38 PM MT assistant] i'm good"),
+      textMsg("assistant", "i'm good"),
       textMsg("user", "[mar 4 2026 8:39 PM MT jordan (ET)] ayeeeee"),
     ]);
   });

package/src/messaging/providers/slack/render-transcript.ts

@@ -348,7 +348,7 @@ function maxNullableSlackTs(a: string | null, b: string | null): string | null {
 function renderMessage(msg: RenderableSlackMessage): string {
   const meta = msg.metadata;
 
-  if (msg.role === "assistant" && !hasTimestampTimezone(meta)) {
+  if (msg.role === "assistant") {
     if (msg.metadata?.deletedAt !== undefined) return "[deleted]";
     return appendSlackFileMarkers(msg.content, msg.metadata?.slackFiles);
   }
@@ -704,7 +704,7 @@ export function renderSlackTranscriptWithProvenance(
       },
       sourceChannelTs: meta?.channelTs ?? null,
       tagLineProvenance:
-        hasRenderedText && hasTimestampTimezone(meta)
+        m.role !== "assistant" && hasRenderedText && hasTimestampTimezone(meta)
           ? "slack-timezone-message"
           : "none",
     });

package/src/messaging/style-analyzer.ts

@@ -49,7 +49,7 @@ Also identify recurring contacts (people appearing in 3+ messages) and note how
 
 You MUST respond using the \`store_style_analysis\` tool. Do not respond with text.`;
 
-const storeStyleAnalysisTool: ToolDefinition = {
+const storeStyleAnalysisTool = {
   name: "store_style_analysis",
   description:
     "Store extracted writing style patterns and relationship observations",
@@ -94,7 +94,7 @@ const storeStyleAnalysisTool: ToolDefinition = {
     },
     required: ["style_patterns"],
   },
-};
+} satisfies ToolDefinition;
 
 /**
  * Build a text corpus from provider messages for LLM analysis.
@@ -143,15 +143,12 @@ export async function extractStylePatterns(
     },
   ];
 
-  const response = await provider.sendMessage(
-    promptMessages,
-    [storeStyleAnalysisTool],
-    STYLE_EXTRACTION_SYSTEM_PROMPT,
-    {
-      signal: AbortSignal.timeout(30_000),
-      config: { callSite: "styleAnalyzer" },
-    },
-  );
+  const response = await provider.sendMessage(promptMessages, {
+    tools: [storeStyleAnalysisTool],
+    systemPrompt: STYLE_EXTRACTION_SYSTEM_PROMPT,
+    signal: AbortSignal.timeout(30_000),
+    config: { callSite: "styleAnalyzer" },
+  });
 
   const toolBlock = response.content.find((b) => b.type === "tool_use");
   if (!toolBlock || toolBlock.type !== "tool_use") {

package/src/notifications/conversation-pairing.ts

@@ -21,6 +21,7 @@
 import type { ConversationStrategy } from "../channels/config.js";
 import { getConversationStrategy } from "../channels/config.js";
 import type { ChannelId } from "../channels/types.js";
+import { isHomePageEnabled } from "../home/feature-gate.js";
 import {
   addMessage,
   createConversation,
@@ -122,10 +123,16 @@ export async function pairDeliveryWithConversation(
     // seed message leaves a graveyard entry in the sidebar; skip it unless
     // the producer opted in via `requiresConversation` or the decision engine
     // requested explicit reuse of a target conversation.
+    //
+    // Gated on `home-page`: the home feed is the surface that hosts passive
+    // notifications, so when the flag is off there is nowhere for them to
+    // land — fall through and create a conversation (the pre-home-feed
+    // behavior) to preserve the notification's only surface.
     if (
       strategy === "start_new_conversation" &&
       !signal.requiresConversation &&
-      conversationAction?.action !== "reuse_existing"
+      conversationAction?.action !== "reuse_existing" &&
+      isHomePageEnabled()
     ) {
       return {
         conversationId: null,
@@ -166,7 +173,6 @@ export async function pairDeliveryWithConversation(
           existing.id,
           "assistant",
           messageContent,
-          undefined,
           { skipIndexing: true },
         );
 
@@ -225,7 +231,6 @@ export async function pairDeliveryWithConversation(
         conversation.id,
         "assistant",
         messageContent,
-        undefined,
         { skipIndexing: true },
       );
 
@@ -283,7 +288,6 @@ export async function pairDeliveryWithConversation(
             inboundConversation.id,
             "assistant",
             messageContent,
-            undefined,
             { skipIndexing: true },
           );
 
@@ -332,7 +336,6 @@ export async function pairDeliveryWithConversation(
             boundConversation.id,
             "assistant",
             messageContent,
-            undefined,
             { skipIndexing: true },
           );
 
@@ -396,7 +399,6 @@ export async function pairDeliveryWithConversation(
       conversation.id,
       "assistant",
       messageContent,
-      undefined,
       { skipIndexing: true },
     );
 

package/src/notifications/decision-engine.ts

@@ -957,22 +957,19 @@ async function classifyWithLLM(
   const tool = buildDecisionTool(availableChannels);
 
   try {
-    const response = await provider.sendMessage(
-      [userMessage(prompt)],
-      [tool],
+    const response = await provider.sendMessage([userMessage(prompt)], {
+      tools: [tool],
       systemPrompt,
-      {
-        config: {
-          callSite: "notificationDecision",
-          max_tokens: 2048,
-          tool_choice: {
-            type: "tool" as const,
-            name: "record_notification_decision",
-          },
+      config: {
+        callSite: "notificationDecision",
+        max_tokens: 2048,
+        tool_choice: {
+          type: "tool" as const,
+          name: "record_notification_decision",
         },
-        signal: abortSignal,
       },
-    );
+      signal: abortSignal,
+    });
     cleanup();
 
     const toolBlock = extractToolUse(response);

package/src/notifications/preference-extractor.ts

@@ -148,22 +148,19 @@ export async function extractPreferences(
   const { signal, cleanup } = createTimeout(EXTRACTION_TIMEOUT_MS);
 
   try {
-    const response = await provider.sendMessage(
-      [userMessage(message)],
-      [EXTRACTION_TOOL],
-      SYSTEM_PROMPT,
-      {
-        config: {
-          callSite: "preferenceExtraction",
-          max_tokens: 1024,
-          tool_choice: {
-            type: "tool" as const,
-            name: "extract_notification_preferences",
-          },
+    const response = await provider.sendMessage([userMessage(message)], {
+      tools: [EXTRACTION_TOOL],
+      systemPrompt: SYSTEM_PROMPT,
+      config: {
+        callSite: "preferenceExtraction",
+        max_tokens: 1024,
+        tool_choice: {
+          type: "tool" as const,
+          name: "extract_notification_preferences",
         },
-        signal,
       },
-    );
+      signal,
+    });
     cleanup();
 
     const toolBlock = extractToolUse(response);