@vellumai/assistant 0.5.16 → 0.6.0

package/src/cli/commands/avatar.ts

@@ -35,7 +35,7 @@ The avatar system supports two modes:
   2. Custom image — an externally provided image file placed directly in the
      avatar directory. Custom images are not managed through this CLI.
 
-Files are stored in ~/.vellum/workspace/data/avatar/:
+Files are stored in $VELLUM_WORKSPACE_DIR/data/avatar/:
   character-traits.json   Current trait selection (bodyShape, eyeStyle, color)
   avatar-image.png        Rendered PNG of the character
   character-ascii.txt     ASCII art representation (best-effort; may not be written)
@@ -61,7 +61,7 @@ Generates an avatar image using AI based on the provided text description
 and saves it as the assistant's avatar PNG. This replaces any existing
 native character avatar — the character traits and ASCII files are removed.
 
-On success, writes avatar-image.png to ~/.vellum/workspace/data/avatar/
+On success, writes avatar-image.png to $VELLUM_WORKSPACE_DIR/data/avatar/
 and removes character-traits.json and character-ascii.txt if they exist.
 
 Examples:
@@ -155,7 +155,7 @@ The --color flag sets the body fill color. Valid values:
   green, orange, pink, purple, teal, yellow
 
 On success, writes character-traits.json and avatar-image.png to
-~/.vellum/workspace/data/avatar/. character-ascii.txt is written on a
+$VELLUM_WORKSPACE_DIR/data/avatar/. character-ascii.txt is written on a
 best-effort basis and may be skipped if ASCII rendering fails.
 
 Examples:

package/src/cli/commands/config.ts

@@ -10,6 +10,7 @@ import {
 import { AssistantConfigSchema } from "../../config/schema.js";
 import { getSchemaAtPath } from "../../config/schema-utils.js";
 import { log } from "../logger.js";
+import { requirePlatformConnection } from "./oauth/shared.js";
 
 /**
  * Flatten a nested config object into dotted key paths.
@@ -34,6 +35,9 @@ function flattenConfig(
   return result;
 }
 
+/** Matches config paths like `services.inference.mode`, `services.image-generation.mode`, etc. */
+const SERVICE_MODE_PATH_RE = /^services\.[^.]+\.mode$/;
+
 export function registerConfigCommand(program: Command): void {
   const config = program.command("config").description("Manage configuration");
 
@@ -80,19 +84,28 @@ Examples:
   $ assistant config set services.inference.provider anthropic
   $ assistant config set calls.enabled true`,
     )
-    .action((key: string, value: string) => {
-      const raw = loadRawConfig();
-      // Try to parse as JSON for booleans/numbers, fall back to string
-      let parsed: unknown = value;
-      try {
-        parsed = JSON.parse(value);
-      } catch {
-        // keep as string
-      }
-      setNestedValue(raw, key, parsed);
-      saveRawConfig(raw);
-      log.info(`Set ${key} = ${JSON.stringify(parsed)}`);
-    });
+    .action(
+      async (key: string, value: string, _opts: unknown, cmd: Command) => {
+        // Try to parse as JSON for booleans/numbers, fall back to string
+        let parsed: unknown = value;
+        try {
+          parsed = JSON.parse(value);
+        } catch {
+          // keep as string
+        }
+
+        // Require platform connection when setting a service mode to "managed"
+        if (SERVICE_MODE_PATH_RE.test(key) && parsed === "managed") {
+          const connected = await requirePlatformConnection(cmd);
+          if (!connected) return;
+        }
+
+        const raw = loadRawConfig();
+        setNestedValue(raw, key, parsed);
+        saveRawConfig(raw);
+        log.info(`Set ${key} = ${JSON.stringify(parsed)}`);
+      },
+    );
 
   config
     .command("get <key>")

package/src/cli/commands/doctor.ts

@@ -39,7 +39,7 @@ Diagnostic checks performed:
   2.  API key configured         Checks for a valid provider API key in secure storage
   3.  Assistant reachable         HTTP health check against the assistant server
   4.  Database exists/readable   Opens the SQLite database and runs a test query
-  5.  Directory structure        Verifies required ~/.vellum/ directories exist
+  5.  Directory structure        Verifies required workspace directories exist
   6.  Disk space                 Ensures at least 100MB free on the data partition
   7.  Log file size              Warns if the log file exceeds 50MB
   8.  Database integrity         Runs SQLite PRAGMA integrity_check
@@ -129,7 +129,7 @@ Examples:
         fail("Database exists and readable", `not found at ${dbPath}`);
       }
 
-      // 5. ~/.vellum/ directory structure (workspace layout)
+      // 5. Workspace directory structure
       const protectedDir = getProtectedDir();
       const dataDir = getDataDir();
       const workspaceDir = getWorkspaceDir();

package/src/cli/commands/memory.ts

@@ -36,7 +36,7 @@ Key concepts:
 Examples:
   $ assistant memory status
   $ assistant memory query "What is the project deadline?"
-  $ assistant memory backfill`,
+  $ assistant memory backfill`
   );
 
   memory
@@ -52,15 +52,13 @@ Fields shown:
                      degraded mode (e.g. missing embedding backend)
   embedding backend  The provider/model pair used for vector embeddings (or "none")
   segments           Total conversation segments indexed
-  items              Total distilled fact items stored
+  graph nodes        Total memory graph nodes stored
   summaries          Total compressed conversation summaries
   embeddings         Total vector embeddings computed
-  cleanup backlogs   Number of superseded items pending cleanup
-  cleanup throughput Number of cleanup operations completed in the last 24 hours
   jobs               Status of background jobs (backfill, cleanup, rebuild-index)
 
 Examples:
-  $ assistant memory status`,
+  $ assistant memory status`
     )
     .action(async () => {
       initializeDb();
@@ -74,15 +72,9 @@ Examples:
         log.info("Embedding backend: none");
       }
       log.info(`Segments: ${status.counts.segments.toLocaleString()}`);
-      log.info(`Items: ${status.counts.items.toLocaleString()}`);
+      log.info(`Graph nodes: ${status.counts.graphNodes.toLocaleString()}`);
       log.info(`Summaries: ${status.counts.summaries.toLocaleString()}`);
       log.info(`Embeddings: ${status.counts.embeddings.toLocaleString()}`);
-      log.info(
-        `Cleanup backlog (superseded items): ${status.cleanup.supersededBacklog.toLocaleString()}`,
-      );
-      log.info(
-        `Cleanup throughput 24h (superseded items): ${status.cleanup.supersededCompleted24h.toLocaleString()}`,
-      );
       log.info("Jobs:");
       for (const [key, value] of Object.entries(status.jobs)) {
         log.info(`  ${key}: ${value}`);
@@ -106,7 +98,7 @@ useful after bulk imports or if the incremental state has become inconsistent.
 
 Examples:
   $ assistant memory backfill
-  $ assistant memory backfill --force`,
+  $ assistant memory backfill --force`
     )
     .action((opts: { force?: boolean }) => {
       initializeDb();
@@ -119,7 +111,7 @@ Examples:
     .description("Queue cleanup jobs for stale superseded items")
     .option(
       "--retention-ms <ms>",
-      "Optional retention threshold in milliseconds",
+      "Optional retention threshold in milliseconds"
     )
     .addHelpText(
       "after",
@@ -133,19 +125,17 @@ default retention period is used.
 
 Examples:
   $ assistant memory cleanup
-  $ assistant memory cleanup --retention-ms 86400000`,
+  $ assistant memory cleanup --retention-ms 86400000`
     )
     .action((opts: { retentionMs?: string }) => {
       initializeDb();
       const retentionMs = opts.retentionMs
         ? Number.parseInt(opts.retentionMs, 10)
         : undefined;
-      const jobs = requestMemoryCleanup(
-        Number.isFinite(retentionMs) ? retentionMs : undefined,
-      );
-      log.info(
-        `Queued cleanup_stale_superseded_items job: ${jobs.staleSupersededItemsJobId}`,
+      requestMemoryCleanup(
+        Number.isFinite(retentionMs) ? retentionMs : undefined
       );
+      log.info("Memory cleanup requested (legacy items table dropped)");
     });
 
   memory
@@ -156,7 +146,7 @@ Examples:
       "after",
       `
 Removes segments shorter than the minimum character threshold from both
-SQLite and Qdrant. Short fragments (e.g. "Collar Touched") burn embedding
+SQLite and Qdrant. Short fragments (e.g. "OK sounds good") burn embedding
 budget, retrieval slots, and injection tokens without adding value.
 
 New segments are already filtered at creation time. This command cleans up
@@ -164,19 +154,21 @@ existing short segments that were stored before the filter was added.
 
 Examples:
   $ assistant memory cleanup-segments
-  $ assistant memory cleanup-segments --dry-run`,
+  $ assistant memory cleanup-segments --dry-run`
     )
     .action(async (opts: { dryRun?: boolean }) => {
       initializeDb();
       const result = await cleanupShortSegments({ dryRun: opts.dryRun });
       if (opts.dryRun) {
         log.info(
-          `Dry run: ${result.dryRunCount} short segment(s) would be removed.`,
+          `Dry run: ${result.dryRunCount} short segment(s) would be removed.`
         );
       } else {
         log.info(`Removed ${result.removed} short segment(s).`);
         if (result.failed > 0) {
-          log.warn(`${result.failed} segment(s) skipped — Qdrant deletion failed. Re-run when Qdrant is available.`);
+          log.warn(
+            `${result.failed} segment(s) skipped — Qdrant deletion failed. Re-run when Qdrant is available.`
+          );
         }
       }
     });
@@ -184,7 +176,7 @@ Examples:
   memory
     .command("query <text>")
     .description(
-      "Run a memory recall query and print the injected memory payload",
+      "Run a memory recall query and print the injected memory payload"
     )
     .option("-c, --conversation <id>", "Optional conversation ID")
     .addHelpText(
@@ -205,7 +197,7 @@ context-aware recall. If omitted, the most recent conversation is used.
 Examples:
   $ assistant memory query "What is the project deadline?"
   $ assistant memory query "preferred communication style" --conversation conv_abc123
-  $ assistant memory query "API rate limits"`,
+  $ assistant memory query "API rate limits"`
     )
     .action(async (text: string, opts?: { conversation?: string }) => {
       initializeDb();
@@ -215,18 +207,21 @@ Examples:
         conversationId = latest?.id ?? "";
       }
       const result = await queryMemory(text, conversationId ?? "");
-      if (result.degraded) {
-        log.info(`Memory degraded: ${result.reason ?? "unknown reason"}`);
-      }
-      log.info(`Semantic hits: ${result.semanticHits}`);
-      log.info(`Merged count: ${result.mergedCount}`);
-      log.info(`Injected tokens: ${result.injectedTokens}`);
-      log.info(`Latency: ${result.latencyMs}ms`);
-      if (result.injectedText.length > 0) {
+      log.info(`Results: ${result.results.length}`);
+      log.info(`Mode: ${result.mode}`);
+      if (result.results.length > 0) {
         log.info("");
-        log.info(result.injectedText);
+        for (const r of result.results) {
+          log.info(
+            `[${r.type}] (confidence: ${r.confidence.toFixed(
+              2
+            )}, score: ${r.score.toFixed(3)})`
+          );
+          log.info(r.content);
+          log.info("");
+        }
       } else {
-        log.info("No memory injected.");
+        log.info("No results found.");
       }
     });
 
@@ -246,7 +241,7 @@ status" to monitor job progress.
 
 Examples:
   $ assistant memory rebuild-index
-  $ assistant memory status`,
+  $ assistant memory status`
     )
     .action(() => {
       initializeDb();
@@ -257,18 +252,15 @@ Examples:
   memory
     .command("re-extract")
     .description(
-      "Re-extract memories from conversations using the latest extraction prompt",
+      "Re-extract memories from conversations using the latest extraction prompt"
     )
     .option(
       "-c, --conversation <id>",
       "Target a specific conversation by ID (repeatable)",
       (val: string, prev: string[]) => [...prev, val],
-      [] as string[],
-    )
-    .option(
-      "-t, --top <n>",
-      "Auto-select top N conversations by message count",
+      [] as string[]
     )
+    .option("-t, --top <n>", "Auto-select top N conversations by message count")
     .option("--dry-run", "Show what would be re-extracted without doing it")
     .addHelpText(
       "after",
@@ -289,14 +281,10 @@ background worker).
 Examples:
   $ assistant memory re-extract --top 20
   $ assistant memory re-extract --conversation conv_abc123
-  $ assistant memory re-extract --top 10 --dry-run`,
+  $ assistant memory re-extract --top 10 --dry-run`
     )
     .action(
-      (opts: {
-        conversation?: string[];
-        top?: string;
-        dryRun?: boolean;
-      }) => {
+      (opts: { conversation?: string[]; top?: string; dryRun?: boolean }) => {
         initializeDb();
 
         const targets = [];
@@ -333,7 +321,7 @@ Examples:
 
         if (targets.length === 0) {
           log.info(
-            "No targets specified. Use --conversation <id> or --top <n>.",
+            "No targets specified. Use --conversation <id> or --top <n>."
           );
           return;
         }
@@ -342,9 +330,7 @@ Examples:
         log.info(`\nRe-extraction targets (${targets.length}):`);
         for (const t of targets) {
           const title = t.title ?? "(untitled)";
-          log.info(
-            `  ${t.conversationId}  ${t.messageCount} msgs  "${title}"`,
-          );
+          log.info(`  ${t.conversationId}  ${t.messageCount} msgs  "${title}"`);
         }
 
         if (opts.dryRun) {
@@ -354,8 +340,8 @@ Examples:
 
         const { jobIds } = requestReextract(targets);
         log.info(
-          `\nQueued ${jobIds.length} re-extraction job(s). The assistant will process them in the background.`,
+          `\nQueued ${jobIds.length} re-extraction job(s). The assistant will process them in the background.`
         );
-      },
+      }
     );
 }

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

@@ -88,7 +88,7 @@ mock.module("../../../../platform/client.js", () => ({
 }));
 
 mock.module("../../../../util/browser.js", () => ({
-  openInBrowser: (url: string) => {
+  openInHostBrowser: async (url: string) => {
     mockOpenInBrowserCalls.push(url);
   },
 }));
@@ -127,7 +127,7 @@ mock.module("../shared.js", () => ({
         JSON.stringify({
           ok: false,
           error:
-            "Platform prerequisites not met (not logged in or missing assistant ID)",
+            "Not connected to Vellum platform. Run `vellum platform connect` to connect first.",
         }) + "\n",
       );
       return null;

package/src/cli/commands/oauth/__tests__/disconnect.test.ts

@@ -112,7 +112,7 @@ mock.module("../../../../platform/client.js", () => ({
 }));
 
 mock.module("../../../../util/browser.js", () => ({
-  openInBrowser: () => {},
+  openInHostBrowser: async () => {},
 }));
 
 mock.module("../../../../util/logger.js", () => ({
@@ -162,7 +162,7 @@ mock.module("../shared.js", () => ({
         JSON.stringify({
           ok: false,
           error:
-            "Platform prerequisites not met (not logged in or missing assistant ID)",
+            "Not connected to Vellum platform. Run `vellum platform connect` to connect first.",
         }) + "\n",
       );
       return null;

package/src/cli/commands/oauth/__tests__/mode.test.ts

@@ -34,6 +34,10 @@ let mockSetNestedValueCalls: Array<{
 
 let mockConfigServices: Record<string, unknown> = {};
 
+let mockRequirePlatformConnection: (
+  cmd: unknown,
+) => Promise<boolean> = async () => true;
+
 // ---------------------------------------------------------------------------
 // Mocks
 // ---------------------------------------------------------------------------
@@ -120,6 +124,8 @@ mock.module("../shared.js", () => ({
   isManagedMode: () => false,
   getManagedServiceConfigKey: (key: string) =>
     mockGetManagedServiceConfigKey(key),
+  requirePlatformConnection: (cmd: unknown) =>
+    mockRequirePlatformConnection(cmd),
   requirePlatformClient: async (_cmd: Command) => {
     if (
       !mockPlatformClientResult ||
@@ -130,7 +136,7 @@ mock.module("../shared.js", () => ({
         JSON.stringify({
           ok: false,
           error:
-            "Platform prerequisites not met (not logged in or missing assistant ID)",
+            "Not connected to Vellum platform. Run `vellum platform connect` to connect first.",
         }) + "\n",
       );
       return null;
@@ -244,6 +250,7 @@ describe("assistant oauth mode", () => {
     mockSaveRawConfigCalls = [];
     mockSetNestedValueCalls = [];
     mockConfigServices = {};
+    mockRequirePlatformConnection = async () => true;
     process.exitCode = 0;
   });
 

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

@@ -71,7 +71,7 @@ mock.module("../../../../platform/client.js", () => ({
 }));
 
 mock.module("../../../../util/browser.js", () => ({
-  openInBrowser: () => {},
+  openInHostBrowser: async () => {},
 }));
 
 mock.module("../../../../util/logger.js", () => ({
@@ -107,7 +107,7 @@ mock.module("../shared.js", () => ({
         JSON.stringify({
           ok: false,
           error:
-            "Platform prerequisites not met (not logged in or missing assistant ID)",
+            "Not connected to Vellum platform. Run `vellum platform connect` to connect first.",
         }) + "\n",
       );
       return null;

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

@@ -9,7 +9,7 @@ import {
   getProvider,
 } from "../../../oauth/oauth-store.js";
 import { renderOAuthCompletionPage } from "../../../security/oauth-completion-page.js";
-import { openInBrowser } from "../../../util/browser.js";
+import { openInHostBrowser } from "../../../util/browser.js";
 import { getSecureKeyViaDaemon } from "../../lib/daemon-credential-client.js";
 import { getCliLogger } from "../../logger.js";
 import { shouldOutputJson, writeOutput } from "../../output.js";
@@ -199,9 +199,14 @@ Examples:
 
               if (!response.ok) {
                 const errorText = await response.text().catch(() => "");
-                writeError(
-                  `Platform returned HTTP ${response.status}${errorText ? `: ${errorText}` : ""}`,
-                );
+                const baseMsg = `Platform returned HTTP ${response.status}${errorText ? `: ${errorText}` : ""}`;
+                if (response.status === 401 || response.status === 403) {
+                  writeError(
+                    `${baseMsg}. Your platform session may have expired. Run \`vellum platform connect\` to reconnect.`,
+                  );
+                } else {
+                  writeError(baseMsg);
+                }
                 return;
               }
 
@@ -229,7 +234,7 @@ Examples:
                 }
                 const snapshotIds = new Set(snapshotEntries.map((e) => e.id));
 
-                openInBrowser(result.connect_url);
+                await openInHostBrowser(result.connect_url);
 
                 if (!jsonMode) {
                   log.info(
@@ -374,7 +379,7 @@ Examples:
               clientSecret,
               callbackTransport: opts.callbackTransport,
               isInteractive: opts.browser !== false,
-              openUrl: opts.browser !== false ? openInBrowser : undefined,
+              openUrl: opts.browser !== false ? openInHostBrowser : undefined,
               ...(opts.scopes ? { requestedScopes: opts.scopes } : {}),
             });
 

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

@@ -17,6 +17,7 @@ import { shouldOutputJson, writeOutput } from "../../output.js";
 import {
   fetchActiveConnections,
   getManagedServiceConfigKey,
+  requirePlatformConnection,
 } from "./shared.js";
 
 /**
@@ -180,6 +181,12 @@ Examples:
           return;
         }
 
+        // Require platform connection when switching to managed mode
+        if (newMode === "managed") {
+          const connected = await requirePlatformConnection(cmd);
+          if (!connected) return;
+        }
+
         // Read current mode
         const services: Services = getConfig().services;
         const currentMode = services[managedKey as keyof Services].mode;

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

@@ -59,11 +59,20 @@ export async function requirePlatformClient(
   cmd: Command,
 ): Promise<VellumPlatformClient | null> {
   const client = await VellumPlatformClient.create();
-  if (!client || !client.platformAssistantId) {
+  if (!client) {
     writeOutput(cmd, {
       ok: false,
       error:
-        "Platform prerequisites not met (not logged in or missing assistant ID)",
+        "Not connected to Vellum platform. Run `vellum platform connect` to connect first.",
+    });
+    process.exitCode = 1;
+    return null;
+  }
+  if (!client.platformAssistantId) {
+    writeOutput(cmd, {
+      ok: false,
+      error:
+        "Connected to Vellum platform but no assistant ID is configured. Ensure the assistant is registered on the platform.",
     });
     process.exitCode = 1;
     return null;
@@ -71,6 +80,29 @@ export async function requirePlatformClient(
   return client;
 }
 
+/**
+ * Verify that the user has connected to the Vellum platform (has stored
+ * credentials). Unlike `requirePlatformClient`, this does NOT require a
+ * platform assistant ID — it only checks that credentials exist.
+ *
+ * Writes an error and sets exitCode=1 when the user is not connected.
+ */
+export async function requirePlatformConnection(
+  cmd: Command,
+): Promise<boolean> {
+  const client = await VellumPlatformClient.create();
+  if (!client) {
+    writeOutput(cmd, {
+      ok: false,
+      error:
+        "Not connected to Vellum platform. Run `vellum platform connect` to connect first.",
+    });
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}
+
 /**
  * Fetch active platform connections for a provider. Returns the parsed entries
  * or writes an error and returns null.
@@ -94,9 +126,13 @@ export async function fetchActiveConnections(
 
   if (!response.ok) {
     if (!options?.silent) {
+      const hint =
+        response.status === 401 || response.status === 403
+          ? `. Your platform session may have expired. Run \`vellum platform connect\` to reconnect.`
+          : "";
       writeOutput(cmd, {
         ok: false,
-        error: `Platform returned HTTP ${response.status}`,
+        error: `Platform returned HTTP ${response.status}${hint}`,
       });
       process.exitCode = 1;
     }

package/src/cli/commands/platform/__tests__/connect.test.ts

@@ -30,7 +30,7 @@ mock.module("../../../lib/daemon-credential-client.js", () => ({
 
 mock.module("../../../../inbound/platform-callback-registration.js", () => ({
   resolvePlatformCallbackRegistrationContext: async () => ({
-    containerized: false,
+    isPlatform: false,
     platformBaseUrl: "",
     assistantId: "",
     hasInternalApiKey: false,

package/src/cli/commands/platform/__tests__/disconnect.test.ts

@@ -36,7 +36,7 @@ mock.module("../../../../config/env-registry.js", () => ({
 
 mock.module("../../../../inbound/platform-callback-registration.js", () => ({
   resolvePlatformCallbackRegistrationContext: async () => ({
-    containerized: false,
+    isPlatform: false,
     platformBaseUrl: "",
     assistantId: "",
     hasInternalApiKey: false,

package/src/cli/commands/platform/__tests__/status.test.ts

@@ -11,7 +11,7 @@ let mockGetSecureKeyViaDaemon: (
 let mockResolvePlatformCallbackRegistrationContext: () => Promise<
   Record<string, unknown>
 > = async () => ({
-  containerized: false,
+  isPlatform: false,
   platformBaseUrl: "",
   assistantId: "",
   hasInternalApiKey: false,
@@ -138,7 +138,7 @@ describe("assistant platform status", () => {
   beforeEach(() => {
     mockGetSecureKeyViaDaemon = async () => undefined;
     mockResolvePlatformCallbackRegistrationContext = async () => ({
-      containerized: false,
+      isPlatform: false,
       platformBaseUrl: "",
       assistantId: "",
       hasInternalApiKey: false,
@@ -158,7 +158,7 @@ describe("assistant platform status", () => {
 
     // GIVEN a containerized environment with platform configuration
     mockResolvePlatformCallbackRegistrationContext = async () => ({
-      containerized: true,
+      isPlatform: true,
       platformBaseUrl: "https://platform.vellum.ai",
       assistantId: "asst-abc-123",
       hasInternalApiKey: true,
@@ -191,7 +191,7 @@ describe("assistant platform status", () => {
 
     // AND the output contains the expected status fields
     const parsed = JSON.parse(stdout);
-    expect(parsed.containerized).toBe(true);
+    expect(parsed.isPlatform).toBe(true);
     expect(parsed.baseUrl).toBe("https://platform.vellum.ai");
     expect(parsed.assistantId).toBe("asst-abc-123");
     expect(parsed.hasInternalApiKey).toBe(true);
@@ -211,7 +211,7 @@ describe("assistant platform status", () => {
 
     // GIVEN a disconnected environment with no stored credentials
     mockResolvePlatformCallbackRegistrationContext = async () => ({
-      containerized: false,
+      isPlatform: false,
       platformBaseUrl: "",
       assistantId: "",
       hasInternalApiKey: false,