@vellumai/assistant 0.10.8-dev.202607141535.d82d641 → 0.10.8-dev.202607141817.ebca77a

package/AGENTS.md

@@ -73,6 +73,14 @@ Some routes are IPC-only (defined in `src/ipc/routes/`, not in the shared array)
 
 The module-level dependency-injection pattern (`registerFooDeps()`) used by some IPC routes is a known antipattern. New IPC-only routes should avoid it.
 
+## Telemetry wire contract
+
+`src/telemetry/telemetry-wire.generated.ts` is generated from the platform's telemetry ingest serializers and auto-synced here on platform merges (the platform's `sync-telemetry-wire.yaml` workflow). **Never edit it by hand** — contract changes belong in `vellum-assistant-platform` at `django/app/assistant/self_hosted_local/serializers.py`.
+
+`src/telemetry/types.ts` is the override layer on top of it: simple events flow through `WireEventMap` without restating fields — they use the generated types directly, so their construction sites get excess-property/missing-field errors when the contract moves. Events where the daemon's type is intentionally richer live in `Overrides`, each pinned to the wire type by compile-time guards covering both drift directions: `_*Narrows` (daemon values stay wire-assignable — catches wire-side tightening) and `_*KeysExist` (the daemon emits no field the wire no longer declares — catches platform-side field removals/renames, which structural subtyping would otherwise let through silently). Daemon-only events live in `Extensions`. A red guard or a failing `types.test.ts` on a sync PR means the platform contract moved — reconcile the override to the new wire shape, don't loosen the guard.
+
+Pre-flush validation (`src/telemetry/telemetry-wire-validation.ts`) checks outgoing events against the wire schemas and logs any the server would silently drop; it is observability only and never blocks or mutates the batch.
+
 ## Code comments
 
 When writing or updating comments, **do not reference code that has been removed.** Comments should describe the current state of the codebase, not narrate its history. Avoid phrases like "no longer does X", "previously used Y", or "was removed in PR Z" — future readers should not need to understand past implementations to understand the current code.

package/knip.json

@@ -9,10 +9,7 @@
     "src/config/bundled-skills/**/tools/**/*.ts!"
   ],
   "project": ["src/**/*.ts!", "src/**/*.tsx!", "scripts/**/*.ts"],
-  "ignore": [
-    "src/config/preloaded-apps/**",
-    "src/telemetry/telemetry-wire.generated.ts"
-  ],
+  "ignore": ["src/config/preloaded-apps/**"],
   "ignoreDependencies": [
     "@microsoft/api-extractor",
     "@vellumai/ces-client",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.8-dev.202607141535.d82d641",
+  "version": "0.10.8-dev.202607141817.ebca77a",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/oauth-provider-profiles.test.ts

@@ -23,7 +23,7 @@ describe("oauth provider profiles (DB-seeded)", () => {
     );
   });
 
-  test("google provider row contains bearer injection templates for 3 Google API hosts", () => {
+  test("google provider row contains bearer injection templates for 4 Google API hosts", () => {
     const provider = getProvider("google");
 
     expect(provider).toBeDefined();
@@ -36,7 +36,7 @@ describe("oauth provider profiles (DB-seeded)", () => {
       valuePrefix: string;
     }>;
 
-    expect(templates).toHaveLength(3);
+    expect(templates).toHaveLength(4);
 
     const byHost = new Map(templates.map((t) => [t.hostPattern, t]));
 
@@ -44,6 +44,7 @@ describe("oauth provider profiles (DB-seeded)", () => {
       "gmail.googleapis.com",
       "www.googleapis.com",
       "people.googleapis.com",
+      "docs.googleapis.com",
     ]) {
       const tpl = byHost.get(host);
       expect(tpl).toBeDefined();

package/src/cli/lib/__tests__/plugin-catalog-local.test.ts

@@ -37,6 +37,7 @@ describe("buildBundledPluginCatalog", () => {
       category: "productivity",
       homepage: "https://github.com/JuliusBrussee/caveman",
       license: "MIT",
+      icon: "🦴",
       source: {
         kind: "github",
         repo: "JuliusBrussee/caveman",

package/src/cli/lib/bundled-marketplace.json

@@ -76,19 +76,21 @@
       "description": "Ultra-compressed communication mode that strips filler words to cut token usage.",
       "category": "productivity",
       "homepage": "https://github.com/JuliusBrussee/caveman",
-      "license": "MIT"
+      "license": "MIT",
+      "icon": "🦴"
     },
     {
       "name": "coffee-aficionado",
       "source": {
         "source": "github",
         "repo": "vellum-ai/coffee-aficionado",
-        "ref": "b37a0b5adc2bda5559d3b21abe38e436093c1ff3"
+        "ref": "facd5a03979605edc894ea61e9a45f7b6a53214a"
       },
       "description": "Find great coffee beans and machines matched to your taste profile, budget, and kitchen. Persistent memory learns your preferences over time.",
       "category": "lifestyle",
       "homepage": "https://github.com/vellum-ai/coffee-aficionado",
-      "license": "MIT"
+      "license": "MIT",
+      "icon": "☕"
     },
     {
       "name": "cofounder",
@@ -391,4 +393,4 @@
       "license": "MIT"
     }
   ]
-}
+}

package/src/config/feature-flag-registry.json

@@ -311,7 +311,7 @@
       "scope": "assistant",
       "key": "memory-concept-graph",
       "label": "Memory concept graph",
-      "description": "Gates the Obsidian-style memory concept graph on the assistant identity page and the backend-agnostic /memory-graph + /memory-graph-node routes that feed it. When off, the identity page shows the skills constellation instead. Only produces a graph on memory-v3 backends. Default off.",
+      "description": "Gates the Obsidian-style memory concept graph on its own Memory tab (/assistant/memory) and the backend-agnostic /memory-graph + /memory-graph-node routes that feed it. When off, the Memory tab is hidden; the identity page keeps the skills constellation. Only produces a graph on memory-v3 backends. Default off.",
       "defaultEnabled": false
     },
     {

package/src/oauth/seed-providers.ts

@@ -131,6 +131,12 @@ export const PROVIDER_SEED_DATA: Record<
         headerName: "Authorization",
         valuePrefix: "Bearer ",
       },
+      {
+        hostPattern: "docs.googleapis.com",
+        injectionType: "header",
+        headerName: "Authorization",
+        valuePrefix: "Bearer ",
+      },
     ],
     revokeUrl: "https://oauth2.googleapis.com/revoke",
     revokeBodyTemplate: { token: "{access_token}" },

package/src/plugins/defaults/memory/graph-topology/__tests__/build-memory-graph.test.ts

@@ -4,7 +4,10 @@ import type { PageIndexEntry } from "../../v2/page-index.js";
 import type { Slug } from "../../v3/types.js";
 import { assembleMemoryGraph } from "../build-memory-graph.js";
 
-function entry(slug: string, over: Partial<PageIndexEntry> = {}): PageIndexEntry {
+function entry(
+  slug: string,
+  over: Partial<PageIndexEntry> = {},
+): PageIndexEntry {
   return {
     id: 0,
     slug,
@@ -40,7 +43,9 @@ describe("assembleMemoryGraph", () => {
         entry("skills/agent-mail", { modifiedAt: 0 }),
         entry("send-email", { modifiedAt: 0 }),
       ],
-      staticAdjacency: adjacency([["my-concept", "skills/agent-mail", undefined]]),
+      staticAdjacency: adjacency([
+        ["my-concept", "skills/agent-mail", undefined],
+      ]),
     });
 
     const byId = new Map(nodes.map((n) => [n.id, n]));
@@ -127,4 +132,78 @@ describe("assembleMemoryGraph", () => {
       expect(nodes.some((n) => n.id === edge.target)).toBe(true);
     }
   });
+
+  it("prunes disconnected functionality nodes but keeps connected ones and all concepts", () => {
+    const { nodes } = assembleMemoryGraph({
+      entries: [
+        entry("lonely-concept"), // concept, degree 0 → kept
+        entry("linked-concept"), // concept, links to a skill
+        entry("skills/connected", { modifiedAt: 0 }), // skill, degree 1 → kept
+        entry("skills/orphan", { modifiedAt: 0 }), // skill, degree 0 → pruned
+        entry("cli-commands/orphan", { modifiedAt: 0 }), // capability, degree 0 → pruned
+      ],
+      staticAdjacency: adjacency([
+        ["linked-concept", "skills/connected", undefined],
+      ]),
+      pruneDisconnectedNonConcepts: true,
+    });
+
+    expect(nodes.map((n) => n.id).sort()).toEqual([
+      "linked-concept",
+      "lonely-concept",
+      "skills/connected",
+    ]);
+  });
+
+  it("keeps disconnected functionality nodes when pruning is off (default)", () => {
+    const { nodes } = assembleMemoryGraph({
+      entries: [entry("a"), entry("skills/orphan", { modifiedAt: 0 })],
+      staticAdjacency: adjacency([]),
+    });
+    expect(nodes.map((n) => n.id).sort()).toEqual(["a", "skills/orphan"]);
+  });
+
+  it("re-prunes a functionality node stranded by truncation", () => {
+    const { nodes, edges, truncated } = assembleMemoryGraph({
+      entries: [
+        entry("hub"),
+        entry("h1"),
+        entry("h2"),
+        entry("h3"),
+        entry("p"),
+        entry("q"),
+        entry("skills/s", { modifiedAt: 0 }),
+      ],
+      // hub has degree 3; skills/s has degree 2 (p, q). The cap keeps the top 2
+      // by degree (hub, skills/s) but drops every one of skills/s's neighbors.
+      staticAdjacency: adjacency([
+        ["hub", "h1", undefined],
+        ["hub", "h2", undefined],
+        ["hub", "h3", undefined],
+        ["skills/s", "p", undefined],
+        ["skills/s", "q", undefined],
+      ]),
+      maxNodes: 2,
+      pruneDisconnectedNonConcepts: true,
+    });
+
+    expect(truncated).toBe(true);
+    // skills/s survived the cap but lost both neighbors → re-pruned as isolated;
+    // the isolated concept hub is kept (concepts always survive).
+    expect(nodes.map((n) => n.id)).toEqual(["hub"]);
+    expect(edges).toEqual([]);
+  });
+
+  it("treats a real page under a reserved prefix as a concept, not a prunable skill", () => {
+    // A non-colliding user page like `skills/my-notes` survives the page index
+    // with a real mtime; it must classify as a concept (by modifiedAt, not the
+    // slug prefix) and therefore never be pruned as a disconnected skill.
+    const { nodes } = assembleMemoryGraph({
+      entries: [entry("skills/my-notes", { modifiedAt: 5 })],
+      staticAdjacency: adjacency([]),
+      pruneDisconnectedNonConcepts: true,
+    });
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0]).toMatchObject({ id: "skills/my-notes", kind: "concept" });
+  });
 });

package/src/plugins/defaults/memory/graph-topology/build-memory-graph.ts

@@ -22,7 +22,10 @@ import { getWorkspaceDir } from "../paths.js";
 import { getPageIndex, type PageIndexEntry } from "../v2/page-index.js";
 import { readPage, renderPageContent } from "../v2/page-store.js";
 import { isSkillSlug } from "../v2/skill-store.js";
-import { isCapabilitySlug } from "../v3/capabilities.js";
+import {
+  isCapabilitySlug,
+  renderCapabilityContent,
+} from "../v3/capabilities.js";
 import { buildEdgeGraph } from "../v3/edge.js";
 import { computeLearnedEdgeGraph } from "../v3/learned-edges.js";
 import type { Slug } from "../v3/types.js";
@@ -78,24 +81,18 @@ function humanizeSlug(slug: string): string {
   return words.replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
-/** Node taxonomy tag used for coloring. Synthetic capability slugs (skills /
- * CLI commands) carry `modifiedAt: 0`; real concept pages carry a file mtime. */
+/** Node taxonomy tag used for coloring. Only synthetic rows (`modifiedAt: 0`)
+ * are functionality: skills carry the `skills/` prefix, other synthetics (CLI
+ * commands) are capabilities. A real on-disk page keeps a file mtime and is a
+ * concept even when it happens to sit under a reserved prefix (e.g. a user page
+ * `skills/my-notes` with no matching skill survives the page index). */
 function nodeKind(entry: PageIndexEntry): string {
-  if (isSkillSlug(entry.slug)) {
-    return "skill";
-  }
   if (entry.modifiedAt <= 0) {
-    return "capability";
+    return isSkillSlug(entry.slug) ? "skill" : "capability";
   }
   return "concept";
 }
 
-/** A real concept page: on-disk (has an mtime) and not a synthetic skill or
- * CLI-command capability slug. The graph shows concepts only. */
-function isConceptEntry(entry: PageIndexEntry): boolean {
-  return entry.modifiedAt > 0 && !isCapabilitySlug(entry.slug);
-}
-
 export interface AssembleMemoryGraphInput {
   /** Every article node in the corpus (page-index entries). */
   entries: readonly PageIndexEntry[];
@@ -105,6 +102,12 @@ export interface AssembleMemoryGraphInput {
   learnedAdjacency?: Adjacency;
   /** Node cap; defaults to {@link DEFAULT_MAX_NODES}. */
   maxNodes?: number;
+  /**
+   * When set, drop functionality nodes (kind `skill` / `capability`) that ended
+   * up with no edges — a skill nobody links to or co-selects is inert clutter.
+   * Concept nodes are always kept, even when isolated.
+   */
+  pruneDisconnectedNonConcepts?: boolean;
 }
 
 /**
@@ -199,6 +202,12 @@ export function assembleMemoryGraph(input: AssembleMemoryGraphInput): {
     return node;
   });
 
+  // Prune disconnected functionality nodes (see the option's doc). `weight` is
+  // the node's degree, so weight 0 ⇒ no incident edges ⇒ no edge cleanup needed.
+  if (input.pruneDisconnectedNonConcepts) {
+    nodes = nodes.filter((n) => n.kind === "concept" || (n.weight ?? 0) > 0);
+  }
+
   if (nodes.length <= maxNodes) {
     return { nodes, edges };
   }
@@ -211,6 +220,20 @@ export function assembleMemoryGraph(input: AssembleMemoryGraphInput): {
   const keptEdges = edges.filter(
     (e) => kept.has(e.source) && kept.has(e.target),
   );
+
+  // Truncation can strand a functionality node whose only neighbors were
+  // dropped. Re-prune against post-truncation degree so the connected-only
+  // guarantee holds even in a capped graph. An isolated node touches no kept
+  // edge by definition, so no further edge cleanup is needed.
+  if (input.pruneDisconnectedNonConcepts) {
+    const connected = new Set<string>();
+    for (const e of keptEdges) {
+      connected.add(e.source);
+      connected.add(e.target);
+    }
+    nodes = nodes.filter((n) => n.kind === "concept" || connected.has(n.id));
+  }
+
   return { nodes, edges: keptEdges, truncated: true };
 }
 
@@ -228,15 +251,28 @@ export async function getMemoryGraph(
 
   const workspaceDir = getWorkspaceDir();
   const pageIndex = await getPageIndex(workspaceDir);
-  // Concepts only: exclude synthetic skill / CLI-command slugs so the graph is
-  // purely the assistant's learned/authored concept pages. Edges to excluded
-  // slugs drop out downstream because they aren't in the node set.
-  const conceptEntries = pageIndex.entries.filter(isConceptEntry);
+  // Concepts plus functionality (skills / CLI-command capabilities). Feeding the
+  // full set to the edge builders is what lets a concept's `[[skills/foo]]` link
+  // and skill↔concept co-selections resolve to real edges — buildEdgeGraph and
+  // computeLearnedEdgeGraph both drop endpoints outside the set they're given.
+  // Functionality nodes that end up disconnected are pruned in assembleMemoryGraph.
+  const entries = pageIndex.entries;
+
+  // Synthetic rows (skills / CLI commands) carry `modifiedAt: 0` and have no
+  // on-disk page. Keyed by slug (not prefix) so a real user page that happens
+  // to live under a reserved prefix is NOT mistaken for a synthetic one.
+  const syntheticSlugs = new Set(
+    entries.filter((e) => e.modifiedAt <= 0).map((e) => e.slug),
+  );
 
   // Raw (frontmatter + body) page reader, matching the v3 lane build. A read
   // that rejects drops that article's authored/wikilink edges but keeps its
-  // numeric fallbacks.
+  // numeric fallbacks. Synthetic capability rows have no page, so short-circuit
+  // their guaranteed-miss read; a real page is read so its links are captured.
   const pageRaw = async (slug: Slug): Promise<string> => {
+    if (syntheticSlugs.has(slug)) {
+      return "";
+    }
     const page = await readPage(workspaceDir, slug);
     if (!page) {
       throw new Error(`page not found: ${slug}`);
@@ -244,7 +280,7 @@ export async function getMemoryGraph(
     return renderPageContent(page);
   };
 
-  const staticGraph = await buildEdgeGraph(conceptEntries, pageRaw, {
+  const staticGraph = await buildEdgeGraph(entries, pageRaw, {
     hubDegree: config.memory.v3.edge.hubDegree,
   });
 
@@ -265,39 +301,50 @@ export async function getMemoryGraph(
       maxPerPage: Math.max(learned.maxPerPage, GRAPH_LEARNED_MIN_MAX_PER_PAGE),
       now: Date.now(),
       windowMs: LEARNED_EDGES_WINDOW_DAYS * DAY_MS,
-      knownSlugs: new Set(conceptEntries.map((e) => e.slug)),
+      knownSlugs: new Set(entries.map((e) => e.slug)),
     },
   );
 
   const assembled = assembleMemoryGraph({
-    entries: conceptEntries,
+    entries,
     staticAdjacency: staticGraph.adjacency,
     learnedAdjacency: learnedGraph.adjacency,
+    pruneDisconnectedNonConcepts: true,
   });
 
   return { backend: BACKEND_MEMORY_V3, supported: true, ...assembled };
 }
 
 /**
- * Fetch a single concept node's content (its markdown body) by id. Used when a
- * user opens a node in the graph. Concepts only — skill/capability slugs and
- * unreadable pages return `{ found: false }`.
+ * Fetch a single node's content by id. Used when a user opens a node in the
+ * graph. Concept nodes return their page's markdown body; functionality nodes
+ * (skills / CLI commands) return the rendered capability statement. Unknown or
+ * unreadable ids return `{ found: false }`.
  */
 export async function getMemoryGraphNode(
   config: AssistantConfig,
   id: string,
 ): Promise<MemoryGraphNodeDetail> {
-  if (
-    !isMemoryConceptGraphEnabled(config) ||
-    !isMemoryV3Live(config) ||
-    !id ||
-    isCapabilitySlug(id)
-  ) {
+  if (!isMemoryConceptGraphEnabled(config) || !isMemoryV3Live(config) || !id) {
     return { found: false };
   }
+  // Seeded skill/CLI capabilities take precedence over any on-disk page at the
+  // same slug: the page index drops a colliding page and lets the synthetic win
+  // (v2/page-index.ts), so a `skills/foo` node built as the capability must not
+  // surface a stale disk page. renderCapabilityContent returns the rendered
+  // statement for a seeded capability, "" for an unseeded reserved-prefix slug
+  // (a real user page), and null for a normal concept slug.
+  if (isCapabilitySlug(id)) {
+    const content = renderCapabilityContent(id);
+    if (content) {
+      return { found: true, title: humanizeSlug(id), content };
+    }
+  }
+  // A real on-disk page: a concept, or a user page under a reserved prefix that
+  // isn't a seeded capability (kept in the index with a real mtime).
   const page = await readPage(getWorkspaceDir(), id).catch(() => null);
-  if (!page) {
-    return { found: false };
+  if (page) {
+    return { found: true, title: humanizeSlug(id), content: page.body };
   }
-  return { found: true, title: humanizeSlug(id), content: page.body };
+  return { found: false };
 }

package/src/providers/speech-to-text/__tests__/vellum-managed-realtime.test.ts

@@ -204,7 +204,7 @@ describe("VellumManagedRealtimeTranscriber", () => {
       expect.objectContaining({
         type: "error",
         category: "auth",
-        message: expect.stringContaining("platform connect"),
+        message: expect.stringContaining("VELAY_BASE_URL"),
       }),
     );
   });

package/src/providers/speech-to-text/__tests__/vellum-speech-relay-connection.test.ts

@@ -54,7 +54,10 @@ describe("resolveSpeechRelayConnection", () => {
 
 describe("mapVelayError", () => {
   test("maps the relay contract's codes onto categories", () => {
-    expect(mapVelayError({ code: "invalid_key" }).category).toBe("auth");
+    expect(mapVelayError({ code: "invalid_key" })).toMatchObject({
+      category: "auth",
+      message: expect.stringContaining("VELAY_BASE_URL"),
+    });
     expect(
       mapVelayError({ code: "missing_platform_connection" }),
     ).toMatchObject({

package/src/providers/speech-to-text/vellum-speech-relay-connection.ts

@@ -99,6 +99,11 @@ export function mapVelayError(error: VelayErrorInfo): {
 } {
   switch (error.code) {
     case "invalid_key":
+      return {
+        category: "auth",
+        message:
+          "The Vellum speech relay rejected this assistant's API key — the assistant's platform environment may not match the relay it is dialing (set VELAY_BASE_URL on the gateway to the matching environment, e.g. https://velay-staging.vellum.ai for staging).",
+      };
     case "missing_platform_connection":
       return {
         category: "auth",