@vellumai/assistant 0.8.3 → 0.8.5

package/src/memory/v3/validate.ts

@@ -0,0 +1,300 @@
+/**
+ * Memory v3 — Tree structure validator.
+ *
+ * The v3 tree is hand-authored by a data-migration during the v2 → v3 rollout
+ * (nodes reference pages and sub-nodes by `page:`/`node:` refs). Because the
+ * structure is authored, not derived, it can drift: a ref can dangle, a page
+ * can be left unwired, two nodes can reference each other into a cycle, a
+ * parent node's compositional summary can fall behind a freshly-edited child,
+ * or a page `edges:` entry can point at a slug with no page.
+ *
+ * `validateTree` is the read-only report the migration (and any later
+ * structure-health probe) runs to surface those defects. It is deliberately
+ * **non-throwing**: the migration is in progress, so an incomplete tree is
+ * expected — the report is informational, and the caller decides what (if
+ * anything) is fatal. It builds the three indices it needs (tree, page, edge),
+ * walks the DAG, and returns counts plus the offending ids for each category.
+ *
+ * Categories:
+ *   - `danglingChildRefs` — a node `children` entry (`node:`/`page:`) whose
+ *     target node/page does not exist on disk.
+ *   - `orphanPages` — concept pages present in the page index but not reachable
+ *     from the tree root by descending every `node:` child. Informational while
+ *     the migration is mid-flight (not every page is wired in yet). Synthetic
+ *     page-index entries (skills, CLI commands) are excluded — they are never
+ *     tree members.
+ *   - `cycles` — back-edges found during a full DFS over `node:` adjacency
+ *     (A → B → A). A cycle would make a naive descent loop forever.
+ *   - `staleIndex` — a node whose own file mtime predates one of its `node:`
+ *     children's mtime, hinting its compositional index/summary may be out of
+ *     date relative to the child it composes.
+ *   - `unknownEdgeTargets` — page `edges:` targets with no corresponding page
+ *     index slug, reusing v2's `validateEdgeTargets`.
+ */
+
+import { CLI_COMMAND_SLUG_PREFIX } from "../v2/cli-command-store.js";
+import { getEdgeIndex, validateEdgeTargets } from "../v2/edge-index.js";
+import { getPageIndex } from "../v2/page-index.js";
+import { SKILL_SLUG_PREFIX } from "../v2/skill-store.js";
+import { getTreeIndex, type TreeIndex } from "./tree-index.js";
+import { getNodeMtimeMs } from "./tree-store.js";
+
+/**
+ * A `node:` child whose mtime is newer than the parent node that composes it.
+ * `node` is the parent, `child` the fresher child, and the two `*MtimeMs`
+ * fields are their epoch-ms mtimes (parent < child triggers the report).
+ */
+export interface StaleIndexEntry {
+  node: string;
+  child: string;
+  nodeMtimeMs: number;
+  childMtimeMs: number;
+}
+
+/**
+ * Read-only health report over the v3 tree + its referenced pages/edges.
+ * Every list is sorted for deterministic output; `*Count` fields mirror the
+ * corresponding list length so callers can summarize without re-counting.
+ */
+export interface TreeValidationReport {
+  /** `node:`/`page:` children whose target does not exist. */
+  danglingChildRefs: Array<{
+    node: string;
+    ref: string;
+    kind: "node" | "page";
+  }>;
+  danglingChildRefCount: number;
+  /** Concept pages not reachable from the root by descending all node children. */
+  orphanPages: string[];
+  orphanPageCount: number;
+  /** Back-edges (`from → to`) closing a cycle during the full DFS descent. */
+  cycles: Array<{ from: string; to: string }>;
+  cycleCount: number;
+  /** Nodes whose mtime predates a child node's mtime. */
+  staleIndex: StaleIndexEntry[];
+  staleIndexCount: number;
+  /** Page `edges:` targets with no corresponding page-index slug. */
+  unknownEdgeTargets: Array<{ from: string; to: string }>;
+  unknownEdgeTargetCount: number;
+}
+
+/** True when a page-index slug is a synthetic (non-concept-page) entry. */
+function isSyntheticSlug(slug: string): boolean {
+  return (
+    slug.startsWith(SKILL_SLUG_PREFIX) ||
+    slug.startsWith(CLI_COMMAND_SLUG_PREFIX)
+  );
+}
+
+/**
+ * Collect dangling `node:`/`page:` child refs: every node child whose target
+ * node id is absent from `tree.nodes`, and every page child whose slug is
+ * absent from `knownPageSlugs`. Sorted by `(node, kind, ref)`.
+ */
+function collectDanglingChildRefs(
+  tree: TreeIndex,
+  knownPageSlugs: ReadonlySet<string>,
+): Array<{ node: string; ref: string; kind: "node" | "page" }> {
+  const dangling: Array<{ node: string; ref: string; kind: "node" | "page" }> =
+    [];
+  for (const [nodeId, children] of tree.childrenByNode) {
+    for (const child of children) {
+      const exists =
+        child.kind === "node"
+          ? tree.nodes.has(child.ref)
+          : knownPageSlugs.has(child.ref);
+      if (!exists) {
+        dangling.push({ node: nodeId, ref: child.ref, kind: child.kind });
+      }
+    }
+  }
+  dangling.sort(
+    (a, b) =>
+      a.node.localeCompare(b.node) ||
+      a.kind.localeCompare(b.kind) ||
+      a.ref.localeCompare(b.ref),
+  );
+  return dangling;
+}
+
+/**
+ * Resolve the existing `node:` children of `nodeId`, in `children` order. Refs
+ * to absent nodes are skipped (those are reported separately as dangling) so
+ * the descent never recurses into a node that isn't on disk.
+ */
+function nodeChildrenOf(tree: TreeIndex, nodeId: string): string[] {
+  const children = tree.childrenByNode.get(nodeId) ?? [];
+  const out: string[] = [];
+  for (const child of children) {
+    if (child.kind === "node" && tree.nodes.has(child.ref)) {
+      out.push(child.ref);
+    }
+  }
+  return out;
+}
+
+/**
+ * Full DFS over `node:` adjacency from `tree.root`. Returns the set of
+ * reachable node ids (for orphan-page reachability) and the back-edges that
+ * close a cycle. A back-edge is an edge into a node still on the active
+ * recursion stack (classic gray-node cycle detection); `visited` (black)
+ * prevents re-walking shared DAG sub-nodes.
+ */
+function descend(tree: TreeIndex): {
+  reachableNodes: Set<string>;
+  cycles: Array<{ from: string; to: string }>;
+} {
+  const reachableNodes = new Set<string>();
+  const onStack = new Set<string>();
+  const cycles: Array<{ from: string; to: string }> = [];
+
+  // Iterative DFS with an explicit stack so deep trees don't blow the call
+  // stack. Each frame tracks its child cursor; we push a child frame, and on
+  // exhaustion pop the parent off the recursion stack (`onStack`).
+  type Frame = { node: string; children: string[]; cursor: number };
+  const stack: Frame[] = [];
+
+  function enter(nodeId: string): void {
+    reachableNodes.add(nodeId);
+    onStack.add(nodeId);
+    stack.push({
+      node: nodeId,
+      children: nodeChildrenOf(tree, nodeId),
+      cursor: 0,
+    });
+  }
+
+  if (tree.nodes.has(tree.root)) {
+    enter(tree.root);
+  }
+
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1];
+    if (frame.cursor >= frame.children.length) {
+      onStack.delete(frame.node);
+      stack.pop();
+      continue;
+    }
+    const child = frame.children[frame.cursor++];
+    if (onStack.has(child)) {
+      // Edge into an ancestor still on the stack → cycle-closing back-edge.
+      cycles.push({ from: frame.node, to: child });
+      continue;
+    }
+    if (reachableNodes.has(child)) {
+      // Already fully explored via another parent (shared DAG sub-node).
+      continue;
+    }
+    enter(child);
+  }
+
+  cycles.sort(
+    (a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to),
+  );
+  return { reachableNodes, cycles };
+}
+
+/**
+ * Concept pages reachable from the tree: every `page:` child of a reachable
+ * node. Pages hanging off unreachable nodes are *not* counted reachable — they
+ * only become reachable once their parent chain links back to the root.
+ */
+function reachablePages(
+  tree: TreeIndex,
+  reachableNodes: ReadonlySet<string>,
+): Set<string> {
+  const pages = new Set<string>();
+  for (const nodeId of reachableNodes) {
+    for (const child of tree.childrenByNode.get(nodeId) ?? []) {
+      if (child.kind === "page") pages.add(child.ref);
+    }
+  }
+  return pages;
+}
+
+/**
+ * Nodes whose own mtime predates one of their `node:` children's mtime. A
+ * missing node file reads as mtime 0 (oldest), so the check never flags a
+ * parent against an absent child. Sorted by `(node, child)`.
+ */
+async function collectStaleIndex(
+  workspaceDir: string,
+  tree: TreeIndex,
+): Promise<StaleIndexEntry[]> {
+  const ids = [...tree.nodes.keys()];
+  const mtimes = new Map<string, number>();
+  await Promise.all(
+    ids.map(async (id) => {
+      mtimes.set(id, await getNodeMtimeMs(workspaceDir, id));
+    }),
+  );
+
+  const stale: StaleIndexEntry[] = [];
+  for (const node of ids) {
+    const nodeMtimeMs = mtimes.get(node) ?? 0;
+    for (const child of nodeChildrenOf(tree, node)) {
+      const childMtimeMs = mtimes.get(child) ?? 0;
+      if (nodeMtimeMs < childMtimeMs) {
+        stale.push({ node, child, nodeMtimeMs, childMtimeMs });
+      }
+    }
+  }
+  stale.sort(
+    (a, b) => a.node.localeCompare(b.node) || a.child.localeCompare(b.child),
+  );
+  return stale;
+}
+
+/**
+ * Validate the hand-authored v3 tree structure for `workspaceDir` and return a
+ * {@link TreeValidationReport}. Builds the tree, page, and edge indices, walks
+ * the DAG from the root, and reports the five defect categories. Never throws —
+ * it is a report, not an assertion.
+ */
+export async function validateTree(
+  workspaceDir: string,
+): Promise<TreeValidationReport> {
+  const [tree, pageIndex, edgeIndex] = await Promise.all([
+    getTreeIndex(workspaceDir),
+    getPageIndex(workspaceDir),
+    getEdgeIndex(workspaceDir),
+  ]);
+
+  const knownPageSlugs = new Set(pageIndex.bySlug.keys());
+
+  // Kick off the stale-index mtime stats up front — it only depends on the
+  // tree, not on the DAG walk below — so its filesystem reads overlap the
+  // (synchronous) descent rather than running strictly after it.
+  const staleIndexPromise = collectStaleIndex(workspaceDir, tree);
+
+  const danglingChildRefs = collectDanglingChildRefs(tree, knownPageSlugs);
+
+  const { reachableNodes, cycles } = descend(tree);
+
+  const reached = reachablePages(tree, reachableNodes);
+  const orphanPages = [...knownPageSlugs]
+    .filter((slug) => !isSyntheticSlug(slug) && !reached.has(slug))
+    .sort();
+
+  const staleIndex = await staleIndexPromise;
+
+  // Edge graph is page-only; knownSlugs is the full page-index slug set so an
+  // edge pointing at a skill/CLI entry is not spuriously flagged unknown.
+  const unknownEdgeTargets = validateEdgeTargets(
+    edgeIndex,
+    knownPageSlugs,
+  ).missing;
+
+  return {
+    danglingChildRefs,
+    danglingChildRefCount: danglingChildRefs.length,
+    orphanPages,
+    orphanPageCount: orphanPages.length,
+    cycles,
+    cycleCount: cycles.length,
+    staleIndex,
+    staleIndexCount: staleIndex.length,
+    unknownEdgeTargets,
+    unknownEdgeTargetCount: unknownEdgeTargets.length,
+  };
+}

package/src/messaging/providers/index.ts

@@ -174,8 +174,14 @@ async function deliverSlack(
       channel,
       threadTs: statusThreadTs,
       status,
+      loadingMessages,
     } = payload.assistantThreadStatus;
-    await sendSlackAssistantThreadStatus(channel, statusThreadTs, status);
+    await sendSlackAssistantThreadStatus(
+      channel,
+      statusThreadTs,
+      status,
+      loadingMessages,
+    );
     return { ok: true };
   }
 

package/src/messaging/providers/slack/__tests__/adapter-mention-rendering.test.ts

@@ -21,7 +21,7 @@ mock.module("../../../../oauth/oauth-store.js", () => ({
   isProviderConnected: async () => false,
 }));
 
-const findContactChannelMock = mock(() => undefined);
+const findContactChannelMock = mock((): unknown => undefined);
 const upsertContactChannelMock = mock(() => {});
 mock.module("../../../../contacts/contact-store.js", () => ({
   findContactChannel: findContactChannelMock,
@@ -30,9 +30,13 @@ mock.module("../../../../contacts/contacts-write.js", () => ({
   upsertContactChannel: upsertContactChannelMock,
 }));
 
-import { slackProvider } from "../adapter.js";
+import {
+  __resetSlackUserInfoCacheForTests,
+  slackProvider,
+} from "../adapter.js";
 
 const originalFetch = globalThis.fetch;
+let userInfoCalls: string[] = [];
 
 function installFetchStub() {
   globalThis.fetch = (async (
@@ -60,6 +64,73 @@ function fakeSlackResponse(url: string): Record<string, unknown> {
   const method = parsed.pathname.split("/").at(-1);
 
   if (method === "conversations.history") {
+    if (parsed.searchParams.get("channel") === "C_USERINFO_FAIL") {
+      return {
+        ok: true,
+        has_more: false,
+        messages: [
+          {
+            type: "message",
+            ts: "1700000006.000700",
+            user: "UMISSING",
+            text: "Fallback sender message",
+          },
+        ],
+      };
+    }
+
+    if (parsed.searchParams.get("channel") === "C_USERINFO_RETRY") {
+      return {
+        ok: true,
+        has_more: false,
+        messages: [
+          {
+            type: "message",
+            ts: "1700000007.000800",
+            user: "URETRY",
+            text: "Retry sender message",
+          },
+        ],
+      };
+    }
+
+    if (parsed.searchParams.get("channel") === "C_TIMEZONE_CACHE") {
+      return {
+        ok: true,
+        has_more: false,
+        messages: [
+          {
+            type: "message",
+            ts: "1700000004.000500",
+            user: "USENDER",
+            text: "First timezone-bearing message",
+          },
+          {
+            type: "message",
+            ts: "1700000005.000600",
+            user: "USENDER",
+            text: "Second timezone-bearing message",
+          },
+        ],
+      };
+    }
+
+    if (parsed.searchParams.get("channel") === "C_BOT_HISTORY") {
+      return {
+        ok: true,
+        has_more: false,
+        messages: [
+          {
+            type: "message",
+            subtype: "bot_message",
+            ts: "1700000003.000400",
+            bot_id: "B_ASSISTANT",
+            text: "Bot-authored history",
+          },
+        ],
+      };
+    }
+
     return {
       ok: true,
       has_more: false,
@@ -117,7 +188,9 @@ function fakeSlackResponse(url: string): Record<string, unknown> {
   }
 
   if (method === "users.info") {
-    return fakeUserInfoResponse(parsed.searchParams.get("user") ?? "");
+    const userId = parsed.searchParams.get("user") ?? "";
+    userInfoCalls.push(userId);
+    return fakeUserInfoResponse(userId);
   }
 
   return { ok: true };
@@ -141,6 +214,9 @@ function fakeUserInfoResponse(userId: string): Record<string, unknown> {
       user: {
         id: "USENDER",
         name: "sender",
+        tz: "America/New_York",
+        tz_label: "Eastern Time",
+        tz_offset: -18000,
         profile: { display_name: "Sender" },
       },
     };
@@ -157,11 +233,93 @@ function fakeUserInfoResponse(userId: string): Record<string, unknown> {
     };
   }
 
+  if (userId === "URETRY") {
+    const retryCalls = userInfoCalls.filter((call) => call === userId).length;
+    if (retryCalls === 1) {
+      return { ok: false, error: "temporarily_unavailable" };
+    }
+    return {
+      ok: true,
+      user: {
+        id: "URETRY",
+        name: "retry_sender",
+        tz: "America/Chicago",
+        tz_label: "Central Time",
+        tz_offset: -21600,
+        profile: { display_name: "Retry Sender" },
+      },
+    };
+  }
+
   return { ok: false, error: "user_not_found" };
 }
 
+function makeOAuthConnection(
+  id: string,
+  accountInfo: string,
+  displayName: string,
+  timezone: string,
+  timezoneLabel: string,
+  timezoneOffsetSeconds: number,
+): OAuthConnection {
+  return {
+    id,
+    provider: "slack",
+    accountInfo,
+    request: async (req) => {
+      if (req.path === "/conversations.history") {
+        return {
+          status: 200,
+          headers: {},
+          body: {
+            ok: true,
+            has_more: false,
+            messages: [
+              {
+                type: "message",
+                ts: "1700000008.000900",
+                user: "USAME",
+                text: "Account scoped sender",
+              },
+            ],
+          },
+        };
+      }
+      if (req.path === "/users.info") {
+        const userId = req.query?.user;
+        userInfoCalls.push(`${id}:${userId}`);
+        return {
+          status: 200,
+          headers: {},
+          body: {
+            ok: true,
+            user: {
+              id: "USAME",
+              name: displayName.toLowerCase().replaceAll(" ", "_"),
+              tz: timezone,
+              tz_label: timezoneLabel,
+              tz_offset: timezoneOffsetSeconds,
+              profile: { display_name: displayName },
+            },
+          },
+        };
+      }
+      return {
+        status: 200,
+        headers: {},
+        body: { ok: true },
+      };
+    },
+    withToken: async <T>(_fn: (token: string) => Promise<T>): Promise<T> => {
+      throw new Error("withToken was not expected");
+    },
+  };
+}
+
 describe("Slack adapter mention rendering", () => {
   beforeEach(async () => {
+    __resetSlackUserInfoCacheForTests();
+    userInfoCalls = [];
     getSecureKeyAsyncMock.mockReset();
     getSecureKeyAsyncMock.mockImplementation(async (key: string) => {
       if (key === credentialKey("slack_channel", "bot_token")) {
@@ -190,6 +348,174 @@ describe("Slack adapter mention rendering", () => {
     expect(messages[0].reactions).toEqual([{ name: "eyes", count: 1 }]);
   });
 
+  test("getHistory preserves bot ids for bot-authored Slack messages", async () => {
+    const messages = await slackProvider.getHistory(undefined, "C_BOT_HISTORY");
+
+    expect(messages).toHaveLength(1);
+    expect(messages[0].sender).toEqual({ id: "B_ASSISTANT", name: "unknown" });
+    expect(messages[0].metadata).toEqual({
+      isBot: true,
+      slackBotId: "B_ASSISTANT",
+    });
+  });
+
+  test("getHistory caches Slack user info and maps timezone metadata", async () => {
+    const messages = await slackProvider.getHistory(
+      undefined,
+      "C_TIMEZONE_CACHE",
+    );
+
+    expect(messages).toHaveLength(2);
+    expect(userInfoCalls.filter((userId) => userId === "USENDER")).toHaveLength(
+      1,
+    );
+    expect(messages.map((message) => message.sender)).toEqual([
+      { id: "USENDER", name: "Sender" },
+      { id: "USENDER", name: "Sender" },
+    ]);
+    expect(messages.map((message) => message.metadata)).toEqual([
+      {
+        actorTimezone: "America/New_York",
+        actorTimezoneLabel: "Eastern Time",
+        actorTimezoneOffsetSeconds: -18000,
+      },
+      {
+        actorTimezone: "America/New_York",
+        actorTimezoneLabel: "Eastern Time",
+        actorTimezoneOffsetSeconds: -18000,
+      },
+    ]);
+  });
+
+  test("getHistory prefers contact display names while still fetching Slack timezone facts", async () => {
+    findContactChannelMock.mockImplementationOnce(() => ({
+      contact: { displayName: "Saved Sender" },
+    }));
+
+    const messages = await slackProvider.getHistory(
+      undefined,
+      "C_TIMEZONE_CACHE",
+    );
+
+    expect(userInfoCalls.filter((userId) => userId === "USENDER")).toHaveLength(
+      1,
+    );
+    expect(messages[0].sender).toEqual({
+      id: "USENDER",
+      name: "Saved Sender",
+    });
+    expect(messages[0].metadata).toEqual({
+      actorTimezone: "America/New_York",
+      actorTimezoneLabel: "Eastern Time",
+      actorTimezoneOffsetSeconds: -18000,
+    });
+  });
+
+  test("getHistory caches fallback user info for permanent users.info failures", async () => {
+    const firstMessages = await slackProvider.getHistory(
+      undefined,
+      "C_USERINFO_FAIL",
+    );
+    const secondMessages = await slackProvider.getHistory(
+      undefined,
+      "C_USERINFO_FAIL",
+    );
+
+    expect(firstMessages).toHaveLength(1);
+    expect(secondMessages).toHaveLength(1);
+    expect(
+      userInfoCalls.filter((userId) => userId === "UMISSING"),
+    ).toHaveLength(1);
+    expect(firstMessages[0].sender).toEqual({
+      id: "UMISSING",
+      name: "UMISSING",
+    });
+    expect(secondMessages[0].sender).toEqual({
+      id: "UMISSING",
+      name: "UMISSING",
+    });
+    expect(firstMessages[0].metadata).toBeUndefined();
+    expect(secondMessages[0].metadata).toBeUndefined();
+  });
+
+  test("getHistory does not cache fallback user info after transient users.info failures", async () => {
+    const firstMessages = await slackProvider.getHistory(
+      undefined,
+      "C_USERINFO_RETRY",
+    );
+    const secondMessages = await slackProvider.getHistory(
+      undefined,
+      "C_USERINFO_RETRY",
+    );
+
+    expect(userInfoCalls.filter((userId) => userId === "URETRY")).toHaveLength(
+      2,
+    );
+    expect(firstMessages[0].sender).toEqual({
+      id: "URETRY",
+      name: "URETRY",
+    });
+    expect(firstMessages[0].metadata).toBeUndefined();
+    expect(secondMessages[0].sender).toEqual({
+      id: "URETRY",
+      name: "Retry Sender",
+    });
+    expect(secondMessages[0].metadata).toEqual({
+      actorTimezone: "America/Chicago",
+      actorTimezoneLabel: "Central Time",
+      actorTimezoneOffsetSeconds: -21600,
+    });
+  });
+
+  test("getHistory scopes Slack user info cache by OAuth connection", async () => {
+    const workspaceA = makeOAuthConnection(
+      "conn-workspace-a",
+      "workspace-a",
+      "Workspace A Sender",
+      "America/Los_Angeles",
+      "Pacific Time",
+      -28800,
+    );
+    const workspaceB = makeOAuthConnection(
+      "conn-workspace-b",
+      "workspace-b",
+      "Workspace B Sender",
+      "Europe/London",
+      "Greenwich Mean Time",
+      0,
+    );
+
+    const messagesA = await slackProvider.getHistory(
+      workspaceA,
+      "C_ACCOUNT_SCOPE",
+    );
+    const messagesB = await slackProvider.getHistory(
+      workspaceB,
+      "C_ACCOUNT_SCOPE",
+    );
+
+    expect(userInfoCalls).toContain("conn-workspace-a:USAME");
+    expect(userInfoCalls).toContain("conn-workspace-b:USAME");
+    expect(messagesA[0].sender).toEqual({
+      id: "USAME",
+      name: "Workspace A Sender",
+    });
+    expect(messagesA[0].metadata).toEqual({
+      actorTimezone: "America/Los_Angeles",
+      actorTimezoneLabel: "Pacific Time",
+      actorTimezoneOffsetSeconds: -28800,
+    });
+    expect(messagesB[0].sender).toEqual({
+      id: "USAME",
+      name: "Workspace B Sender",
+    });
+    expect(messagesB[0].metadata).toEqual({
+      actorTimezone: "Europe/London",
+      actorTimezoneLabel: "Greenwich Mean Time",
+      actorTimezoneOffsetSeconds: 0,
+    });
+  });
+
   test("getThreadReplies renders Slack user mentions for model-facing text without changing sender identity", async () => {
     const messages = await slackProvider.getThreadReplies!(
       undefined,