@vellumai/assistant 0.10.9 → 0.10.10-dev.202607162206.d08e98e

package/src/cli/commands/memory/index.help.ts

@@ -26,6 +26,7 @@ model (section-grain lanes cached as live shadow state). Each subgroup exposes
 operator-facing maintenance verbs — reindexing, backfills, validation, and evals.
 
 Examples:
+  $ assistant memory nodes stats
   $ assistant memory nodes list --search "coffee"
   $ assistant memory nodes delete "User prefers TypeScript"
   $ assistant memory nodes update "User prefers TypeScript" "User prefers TypeScript and Bun"
@@ -48,11 +49,33 @@ a remembered fact without first looking up its ID.
 All subcommands require memory v2 to be enabled and the assistant to be running.
 
 Examples:
+  $ assistant memory nodes stats
   $ assistant memory nodes list
   $ assistant memory nodes list --search "TypeScript" --limit 20
   $ assistant memory nodes delete "User prefers TypeScript"
   $ assistant memory nodes update "User prefers TypeScript" "User prefers TypeScript and Bun"`,
       subcommands: [
+        {
+          name: "stats",
+          description: "Show a health overview of the memory v2 graph",
+          options: [
+            {
+              flags: "--json",
+              description: "Machine-readable compact JSON output",
+            },
+          ],
+          helpText: `
+Behavior:
+  Scans all active memory graph nodes in a single pass and reports:
+  total count, breakdown by type and fidelity (with an ASCII bar chart),
+  nodes at risk of decay (significance < 15%), average significance,
+  oldest/newest node timestamps, last reinforcement, and the top 5 nodes
+  by significance. Does not require the daemon to be running.
+
+Examples:
+  $ assistant memory nodes stats
+  $ assistant memory nodes stats --json`,
+        },
         {
           name: "list",
           description: "List active memory graph nodes",

package/src/cli/commands/memory/nodes.ts

@@ -203,4 +203,150 @@ export function registerMemoryNodesCommand(memory: Command): void {
       log.info(result.message);
     },
   );
+
+  // ── stats ─────────────────────────────────────────────────────────────
+
+  subcommand(nodes, "stats").action(
+    async (opts: { json?: boolean }, cmd: Command) => {
+      // Deferred: loads config and the graph stats handler in-process.
+      // No daemon needed — reads directly from the workspace SQLite DB.
+      const [{ handleStatsMemory }, { getConfig }] = await Promise.all([
+        import("../../../plugins/defaults/memory/graph/tool-handlers.js") as Promise<
+          typeof import("../../../plugins/defaults/memory/graph/tool-handlers.js")
+        >,
+        import("../../../config/loader.js") as Promise<
+          typeof import("../../../config/loader.js")
+        >,
+      ]);
+
+      const result = handleStatsMemory(getConfig());
+
+      if (!result.success) {
+        log.error(result.message);
+        process.exitCode = 1;
+        return;
+      }
+
+      if (opts.json) {
+        writeOutput(cmd, result.stats);
+        return;
+      }
+
+      printStats(result.stats!);
+    },
+  );
+}
+
+const MEMORY_TYPES = [
+  "episodic",
+  "semantic",
+  "procedural",
+  "emotional",
+  "prospective",
+  "behavioral",
+  "narrative",
+  "shared",
+] as const;
+
+interface StatsData {
+  total: number;
+  byType: { [key: string]: number | undefined };
+  byFidelity: { vivid: number; clear: number; faded: number; gist: number };
+  atRisk: number;
+  edgeCount: number;
+  oldestCreated: number | null;
+  newestCreated: number | null;
+  lastReinforced: number | null;
+  avgSignificance: number;
+  topNodes: ReadonlyArray<{ content: string; significance: number }>;
+}
+
+function printStats(s: StatsData): void {
+  const n = s.total;
+  const e = s.edgeCount;
+
+  console.log(
+    `\nMemory graph  ${n} node${n === 1 ? "" : "s"} · ${e} edge${e === 1 ? "" : "s"}\n`,
+  );
+
+  if (n === 0) {
+    console.log("  The memory graph is empty.");
+    console.log("");
+    return;
+  }
+
+  // ── by type ─────────────────────────────────────────────────────────────
+
+  console.log("BY TYPE");
+  for (const t of MEMORY_TYPES) {
+    const count = s.byType[t] ?? 0;
+    if (count > 0) {
+      console.log(`  ${t.padEnd(12)}  ${count}`);
+    }
+  }
+
+  // ── by fidelity (with ASCII bar) ─────────────────────────────────────────
+
+  console.log("\nBY FIDELITY");
+  const fidelities = ["vivid", "clear", "faded", "gist"] as const;
+  for (const f of fidelities) {
+    const count = s.byFidelity[f];
+    const barLen = n > 0 ? Math.round((count / n) * 20) : 0;
+    const bar = "█".repeat(barLen);
+    console.log(`  ${f.padEnd(6)}  ${String(count).padStart(4)}  ${bar}`);
+  }
+
+  // ── significance ─────────────────────────────────────────────────────────
+
+  console.log("\nSIGNIFICANCE");
+  console.log(`  average    ${(s.avgSignificance * 100).toFixed(1)}%`);
+  if (s.atRisk > 0) {
+    console.log(
+      `  at risk    ${s.atRisk} node${s.atRisk === 1 ? "" : "s"} fading (significance < 15%)`,
+    );
+  }
+
+  // ── timeline ─────────────────────────────────────────────────────────────
+
+  console.log("\nTIMELINE");
+  const dateOpts: Intl.DateTimeFormatOptions = {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+  };
+  if (s.oldestCreated) {
+    console.log(
+      `  oldest      ${new Date(s.oldestCreated).toLocaleString("en-US", dateOpts)}`,
+    );
+  }
+  if (s.newestCreated) {
+    console.log(
+      `  newest      ${new Date(s.newestCreated).toLocaleString("en-US", dateOpts)}`,
+    );
+  }
+  if (s.lastReinforced) {
+    console.log(
+      `  reinforced  ${new Date(s.lastReinforced).toLocaleString("en-US", {
+        ...dateOpts,
+        hour: "numeric",
+        minute: "2-digit",
+      })}`,
+    );
+  }
+
+  // ── top nodes ────────────────────────────────────────────────────────────
+
+  if (s.topNodes.length > 0) {
+    console.log("\nTOP NODES BY SIGNIFICANCE");
+    const WIDTH = 60;
+    const trunc = (str: string) =>
+      str.length > WIDTH ? str.slice(0, WIDTH - 1) + "…" : str;
+    for (const node of s.topNodes) {
+      console.log(
+        `  ${(node.significance * 100).toFixed(0).padStart(3)}%  ${trunc(node.content)}`,
+      );
+    }
+  }
+
+  console.log("");
 }

package/src/cli/commands/notifications.help.ts

@@ -48,9 +48,9 @@ source channel, event name, and attention hints. The decision engine evaluates
 whether and where to deliver the notification based on connected channels,
 urgency, and user preferences.
 
-Minimal usage: only --message is required. Add --urgent for a push + visual
-flag in the inbox. Source channel/event name fall back to assistant_tool /
-assistant.share when omitted.
+Minimal usage: only --message is required. Add --urgent for a push +
+visual flag in the Vellum Home feed. Source channel/event name fall back
+to assistant_tool / assistant.share when omitted.
 
 Examples:
   $ assistant notifications send --message "Build finished"
@@ -71,7 +71,7 @@ Examples:
         {
           flags: "--urgent",
           description:
-            "Mark this notification as urgent (fires push + visual flag in inbox)",
+            "Mark this notification as urgent (fires push + visual flag in Vellum Home)",
           defaultValue: false,
         },
         {
@@ -176,7 +176,7 @@ Examples:
     {
       name: "list",
       description:
-        "List notifications surfaced to the user via the home feed. Excludes dismissed items by default.",
+        "List Vellum Home feed notifications surfaced by the assistant. Excludes dismissed items by default.",
       options: [
         {
           flags: "--all",
@@ -231,11 +231,11 @@ Examples:
         },
       ],
       helpText: `
-Reads the home feed at $VELLUM_WORKSPACE_DIR/data/home-feed.json — the
-user's notification inbox. Items are ordered by priority then recency,
-matching what the user sees in the macOS Home page. The home feed covers
-background/async notifications mirrored from the unified pipeline;
-real-time chat pushes that did not mirror to the feed will not appear.
+Reads Vellum's Home feed at $VELLUM_WORKSPACE_DIR/data/home-feed.json.
+Items are ordered by priority then recency, matching what the user sees
+in the macOS Home page. This is only the assistant's Vellum notification
+feed; it does not read email inboxes, Gmail, Outlook, or other external
+message providers. Use OAuth/provider-specific commands for external mail.
 
 Examples:
   $ assistant notifications list

package/src/cli/commands/oauth/connect-surface-guidance.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildOAuthConnectSurfaceRedirect,
+  isModelSpawnedConversationShell,
+  oauthConnectSurfaceHint,
+} from "./connect-surface-guidance.js";
+
+describe("OAuth connect surface guidance", () => {
+  test("builds the oauth_connect next action payload", () => {
+    expect(buildOAuthConnectSurfaceRedirect("google")).toEqual({
+      ok: false,
+      code: "use_oauth_connect_surface",
+      provider: "google",
+      hint: oauthConnectSurfaceHint("google"),
+      nextAction: {
+        type: "ui_show",
+        surfaceType: "oauth_connect",
+        data: { providerKey: "google" },
+      },
+    });
+  });
+
+  test("detects model-spawned conversation shells", () => {
+    expect(
+      isModelSpawnedConversationShell({ __CONVERSATION_ID: "conv-123" }),
+    ).toBe(true);
+    expect(isModelSpawnedConversationShell({ __CONVERSATION_ID: "   " })).toBe(
+      false,
+    );
+    expect(isModelSpawnedConversationShell({})).toBe(false);
+  });
+
+  test("hint tells the model not to paste OAuth URLs", () => {
+    const hint = oauthConnectSurfaceHint("google");
+    expect(hint).toContain('surface_type "oauth_connect"');
+    expect(hint).toContain('data.providerKey "google"');
+    expect(hint).toContain("paste an OAuth URL");
+  });
+});

package/src/cli/commands/oauth/connect-surface-guidance.ts

@@ -0,0 +1,54 @@
+export interface OAuthConnectSurfaceNextAction {
+  type: "ui_show";
+  surfaceType: "oauth_connect";
+  data: { providerKey: string };
+}
+
+export interface OAuthConnectSurfaceRedirect {
+  ok: false;
+  code: "use_oauth_connect_surface";
+  provider: string;
+  hint: string;
+  nextAction: OAuthConnectSurfaceNextAction;
+}
+
+export function oauthConnectSurfaceHint(provider: string): string {
+  return (
+    `To let the user connect, render the connect button: call ` +
+    `\`ui_show\` with surface_type "oauth_connect" and ` +
+    `data.providerKey "${provider}". That surface is always available — do ` +
+    `not run further \`oauth\`/\`channels\` commands, paste an OAuth URL, or ` +
+    `load a setup skill just to display it.`
+  );
+}
+
+export function buildOAuthConnectSurfaceNextAction(
+  provider: string,
+): OAuthConnectSurfaceNextAction {
+  return {
+    type: "ui_show",
+    surfaceType: "oauth_connect",
+    data: { providerKey: provider },
+  };
+}
+
+export function buildOAuthConnectSurfaceRedirect(
+  provider: string,
+): OAuthConnectSurfaceRedirect {
+  return {
+    ok: false,
+    code: "use_oauth_connect_surface",
+    provider,
+    hint: oauthConnectSurfaceHint(provider),
+    nextAction: buildOAuthConnectSurfaceNextAction(provider),
+  };
+}
+
+export function isModelSpawnedConversationShell(
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  return (
+    typeof env.__CONVERSATION_ID === "string" &&
+    env.__CONVERSATION_ID.trim().length > 0
+  );
+}

package/src/cli/commands/oauth/connect.test.ts

@@ -0,0 +1,126 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+const ipcCalls: Array<{ method: string; params?: Record<string, unknown> }> =
+  [];
+const openedUrls: string[] = [];
+
+mock.module("../../../ipc/cli-client.js", () => ({
+  cliIpcCall: async (method: string, params?: Record<string, unknown>) => {
+    ipcCalls.push({ method, params });
+    if (method === "oauth_providers_by_providerKey_get") {
+      return {
+        ok: true,
+        result: {
+          provider: { authUrl: "https://accounts.example.com/oauth" },
+        },
+      };
+    }
+    if (method === "oauth_mode_get") {
+      return { ok: true, result: { ok: true, mode: "managed" } };
+    }
+    if (method === "oauth_managed_connect_start") {
+      return {
+        ok: true,
+        result: { ok: true, connect_url: "https://connect.example.com" },
+      };
+    }
+    return { ok: false, error: `Unexpected IPC method ${method}` };
+  },
+  exitFromIpcResult: (r: { error?: string }) => {
+    throw new Error(r.error ?? "IPC error");
+  },
+}));
+
+mock.module("../../lib/open-browser.js", () => ({
+  openInHostBrowser: (url: string) => {
+    openedUrls.push(url);
+  },
+}));
+
+mock.module("../../logger.js", () => ({
+  getCliLogger: () => ({
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+  }),
+}));
+
+import { Command } from "commander";
+
+import { applyCommandHelp } from "../../lib/cli-command-help.js";
+import { registerConnectCommand } from "./connect.js";
+import { oauthHelp } from "./index.help.js";
+
+const originalConversationId = process.env.__CONVERSATION_ID;
+
+beforeEach(() => {
+  ipcCalls.length = 0;
+  openedUrls.length = 0;
+  process.exitCode = 0;
+  process.env.__CONVERSATION_ID = "conv-123";
+});
+
+afterEach(() => {
+  if (originalConversationId === undefined) {
+    delete process.env.__CONVERSATION_ID;
+  } else {
+    process.env.__CONVERSATION_ID = originalConversationId;
+  }
+  process.exitCode = 0;
+});
+
+async function runConnectCommand(): Promise<{
+  stdout: string;
+  exitCode: number;
+}> {
+  const chunks: string[] = [];
+  const originalWrite = process.stdout.write;
+  process.stdout.write = ((chunk: string | Buffer) => {
+    chunks.push(typeof chunk === "string" ? chunk : chunk.toString());
+    return true;
+  }) as typeof process.stdout.write;
+
+  try {
+    const program = new Command();
+    program.exitOverride();
+    const oauth = program.command("oauth").description(oauthHelp.description);
+    applyCommandHelp(oauth, oauthHelp);
+    registerConnectCommand(oauth);
+    await program.parseAsync([
+      "node",
+      "test",
+      "oauth",
+      "--json",
+      "connect",
+      "google",
+    ]);
+  } catch {
+    // Commander may throw under exitOverride for parse errors; the assertions
+    // below verify the command behavior we care about.
+  } finally {
+    process.stdout.write = originalWrite;
+  }
+
+  return { stdout: chunks.join(""), exitCode: Number(process.exitCode ?? 0) };
+}
+
+describe("oauth connect", () => {
+  test("managed provider in a conversation shell returns oauth_connect guidance without opening a browser", async () => {
+    const { stdout, exitCode } = await runConnectCommand();
+
+    expect(exitCode).toBe(1);
+    const parsed = JSON.parse(stdout) as Record<string, unknown>;
+    expect(parsed.code).toBe("use_oauth_connect_surface");
+    expect(parsed.nextAction).toEqual({
+      type: "ui_show",
+      surfaceType: "oauth_connect",
+      data: { providerKey: "google" },
+    });
+    expect(openedUrls).toEqual([]);
+    expect(ipcCalls.map((call) => call.method)).toEqual([
+      "oauth_providers_by_providerKey_get",
+      "oauth_mode_get",
+    ]);
+  });
+});

package/src/cli/commands/oauth/connect.ts

@@ -5,6 +5,10 @@ import { subcommand } from "../../lib/cli-command-help.js";
 import { openInHostBrowser } from "../../lib/open-browser.js";
 import { getCliLogger } from "../../logger.js";
 import { shouldOutputJson, writeOutput } from "../../output.js";
+import {
+  buildOAuthConnectSurfaceRedirect,
+  isModelSpawnedConversationShell,
+} from "./connect-surface-guidance.js";
 
 const log = getCliLogger("cli");
 
@@ -125,7 +129,9 @@ export function registerConnectCommand(oauth: Command): void {
             queryParams: { provider },
           });
 
-          if (!modeResult.ok) return exitFromIpcResult(modeResult);
+          if (!modeResult.ok) {
+            return exitFromIpcResult(modeResult);
+          }
 
           const managed = modeResult.result?.mode === "managed";
 
@@ -134,6 +140,13 @@ export function registerConnectCommand(oauth: Command): void {
             // MANAGED PATH
             // =============================================================
 
+            if (isModelSpawnedConversationShell()) {
+              const redirect = buildOAuthConnectSurfaceRedirect(provider);
+              writeOutput(cmd, redirect);
+              process.exitCode = 1;
+              return;
+            }
+
             if (opts.clientId) {
               log.info(
                 `Warning: --client-id is ignored for platform-managed providers. The platform manages OAuth apps for "${provider}".`,
@@ -152,7 +165,9 @@ export function registerConnectCommand(oauth: Command): void {
               body: startBody,
             });
 
-            if (!startResult.ok) return exitFromIpcResult(startResult);
+            if (!startResult.ok) {
+              return exitFromIpcResult(startResult);
+            }
 
             const connectUrl = startResult.result!.connect_url;
 
@@ -169,7 +184,9 @@ export function registerConnectCommand(oauth: Command): void {
                 queryParams: { provider },
               });
 
-              if (!snapshotResult.ok) return exitFromIpcResult(snapshotResult);
+              if (!snapshotResult.ok) {
+                return exitFromIpcResult(snapshotResult);
+              }
 
               const snapshotIds = new Set(
                 (snapshotResult.result?.connections ?? []).map((e) => e.id),
@@ -207,7 +224,9 @@ export function registerConnectCommand(oauth: Command): void {
                   queryParams: { provider },
                 });
 
-                if (!currentResult.ok || !currentResult.result) continue;
+                if (!currentResult.ok || !currentResult.result) {
+                  continue;
+                }
 
                 const found = currentResult.result.connections.find(
                   (e) => !snapshotIds.has(e.id),
@@ -282,8 +301,12 @@ export function registerConnectCommand(oauth: Command): void {
               service: provider,
               callbackTransport: opts.callbackTransport,
             };
-            if (opts.clientId) startBody.clientId = opts.clientId;
-            if (opts.scopes) startBody.requestedScopes = opts.scopes;
+            if (opts.clientId) {
+              startBody.clientId = opts.clientId;
+            }
+            if (opts.scopes) {
+              startBody.requestedScopes = opts.scopes;
+            }
 
             const startResult = await cliIpcCall<{
               auth_url: string;

package/src/cli/commands/oauth/index.help.ts

@@ -655,7 +655,7 @@ Examples:
       name: "connect",
       args: "<provider>",
       description:
-        "Initiate an OAuth authorization flow for a specified provider",
+        "Initiate a terminal/headless OAuth authorization flow for a specified provider",
       options: [
         {
           flags: "--scopes <scopes...>",
@@ -687,6 +687,12 @@ By default, the browser opens automatically and the command waits for
 completion. Use --no-browser to print the URL instead (useful for headless
 or SSH sessions).
 
+Important for chat/UI turns: do not run this command just to let the user
+connect a managed provider. Render the first-class connect surface instead:
+call \`ui_show\` with surface_type "oauth_connect" and data.providerKey set to
+the provider (for example, "google"). That surface starts the managed OAuth UI
+and avoids pasting raw authorization links into the conversation.
+
 Examples:
   $ assistant oauth connect google
   $ assistant oauth connect google --no-browser

package/src/cli/commands/oauth/status.test.ts

@@ -1,12 +1,16 @@
 import { afterEach, describe, expect, test } from "bun:test";
 
-import { noConnectionsMessage } from "./status.js";
+import { oauthHelp } from "./index.help.js";
+import { decorateStatusJsonForModel, noConnectionsMessage } from "./status.js";
 
 const original = process.env.__RESOLVED_MODEL;
 
 afterEach(() => {
-  if (original === undefined) delete process.env.__RESOLVED_MODEL;
-  else process.env.__RESOLVED_MODEL = original;
+  if (original === undefined) {
+    delete process.env.__RESOLVED_MODEL;
+  } else {
+    process.env.__RESOLVED_MODEL = original;
+  }
 });
 
 describe("noConnectionsMessage", () => {
@@ -31,6 +35,68 @@ describe("noConnectionsMessage", () => {
     const msg = await noConnectionsMessage("google");
     expect(msg).toContain('surface_type "oauth_connect"');
     expect(msg).toContain('data.providerKey "google"');
+    expect(msg).toContain("paste an OAuth URL");
     expect(msg).not.toContain("assistant oauth connect google");
   });
+
+  test("weak open models are not steered to oauth_connect for BYO mode", async () => {
+    process.env.__RESOLVED_MODEL = "accounts/fireworks/models/minimax-m3";
+    const msg = await noConnectionsMessage("google", "byo");
+    expect(msg).not.toContain('surface_type "oauth_connect"');
+    expect(msg).toContain("assistant oauth connect google");
+  });
+
+  test("weak open model JSON status includes oauth_connect next action", async () => {
+    process.env.__RESOLVED_MODEL = "accounts/fireworks/models/glm-5p2";
+    const result = await decorateStatusJsonForModel({
+      ok: true,
+      provider: "google",
+      mode: "managed",
+      connections: [],
+    });
+    expect(result.hint).toContain('surface_type "oauth_connect"');
+    expect(result.hint).toContain("paste an OAuth URL");
+    expect(result.nextAction).toEqual({
+      type: "ui_show",
+      surfaceType: "oauth_connect",
+      data: { providerKey: "google" },
+    });
+  });
+
+  test("weak open model JSON status stays compact for BYO mode", async () => {
+    process.env.__RESOLVED_MODEL = "accounts/fireworks/models/glm-5p2";
+    const result = await decorateStatusJsonForModel({
+      ok: true,
+      provider: "google",
+      mode: "byo",
+      connections: [],
+    });
+    expect(result.hint).toBeUndefined();
+    expect(result.nextAction).toBeUndefined();
+  });
+
+  test("capable model JSON status stays compact", async () => {
+    process.env.__RESOLVED_MODEL = "claude-opus-4-8";
+    const result = await decorateStatusJsonForModel({
+      ok: true,
+      provider: "google",
+      mode: "managed",
+      connections: [],
+    });
+    expect(result.hint).toBeUndefined();
+    expect(result.nextAction).toBeUndefined();
+  });
+});
+
+describe("oauth connect help", () => {
+  test("steers chat turns to the oauth_connect surface", () => {
+    const connectHelp = oauthHelp.subcommands?.find(
+      (command) => command.name === "connect",
+    );
+    expect(connectHelp?.description).toContain("terminal/headless");
+    expect(connectHelp?.helpText).toContain('surface_type "oauth_connect"');
+    expect(connectHelp?.helpText).toContain(
+      "avoids pasting raw authorization links",
+    );
+  });
 });