@vellumai/assistant 0.7.0 → 0.7.2

package/src/cli/commands/memory-v2.ts

@@ -4,21 +4,19 @@
  * Operator-facing subcommands for the v2 memory subsystem (concept-page
  * activation model). All commands are thin wrappers over two IPC routes:
  *
- *   - `memory_v2/backfill` — enqueues one of four mutating jobs against the
- *     memory job queue (`migrate`, `rebuild-edges`, `reembed`,
- *     `activation-recompute`). Returns a `jobId` so the operator can poll
- *     status from the regular memory subsystem.
+ *   - `memory_v2/backfill` — enqueues one of three mutating jobs against the
+ *     memory job queue (`migrate`, `reembed`, `activation-recompute`).
+ *     Returns a `jobId` so the operator can poll status from the regular
+ *     memory subsystem.
  *   - `memory_v2/validate` — read-only structural validation of the v2
- *     workspace state (concept pages + `memory/edges.json`). Returns an
- *     aggregate report of orphan edges, oversized pages, and parse failures.
+ *     workspace state. Returns an aggregate report of orphan outgoing-edge
+ *     targets, oversized pages, and parse failures.
  *
  * Subcommands:
  *
  *   - `migrate [--force]` — one-shot v1->v2 synthesis. Refuses to run a
  *     second time unless `--force` is passed (the migration handler writes a
  *     sentinel after a successful first run).
- *   - `rebuild-edges` — recompute every concept page's `edges:` frontmatter
- *     from the canonical `memory/edges.json` index.
  *   - `reembed` — fan out an `embed_concept_page` job per page slug to
  *     refresh dense + sparse vectors in Qdrant.
  *   - `activation` — refresh persisted activation state for every
@@ -38,6 +36,10 @@ import { cliIpcCall } from "../../ipc/cli-client.js";
 import type {
   MemoryV2BackfillOp,
   MemoryV2BackfillResult,
+  MemoryV2ExplainSimilarityResult,
+  MemoryV2ExplainSimilarityStats,
+  MemoryV2FitAnisotropyResult,
+  MemoryV2RebuildCorpusStatsResult,
   MemoryV2ReembedSkillsResult,
   MemoryV2ValidateResult,
 } from "../../runtime/routes/memory-v2-routes.js";
@@ -75,6 +77,74 @@ async function runBackfillOp(
   log.info(`Queued ${op} job: ${result.result!.jobId}`);
 }
 
+/** Format a number for table output. */
+function fmt(n: number | null, decimals: number): string {
+  if (n === null) return "—";
+  return n.toFixed(decimals);
+}
+
+/** Render the per-channel breakdown table + stats for the explain command. */
+function printExplainResult(result: MemoryV2ExplainSimilarityResult): void {
+  log.info(
+    `dense_weight=${result.config.dense_weight}  sparse_weight=${result.config.sparse_weight}`,
+  );
+
+  for (const channel of result.channels) {
+    log.info("");
+    log.info(`── channel: ${channel.channel} ──`);
+    log.info(`text: ${channel.textPreview}`);
+    log.info(
+      `maxSparse (used for normalization): ${channel.maxSparse.toFixed(4)}`,
+    );
+    log.info(
+      `effective: dw=${channel.effectiveDenseWeight.toFixed(3)} sw=${channel.effectiveSparseWeight.toFixed(3)} (sparseSpread=${channel.sparseSpread.toFixed(3)})`,
+    );
+    log.info("");
+    log.info(
+      "slug".padEnd(48) +
+        "dense".padStart(10) +
+        "sparseRaw".padStart(12) +
+        "sparseNorm".padStart(12) +
+        "fused".padStart(10),
+    );
+    log.info("─".repeat(92));
+    for (const row of channel.rows) {
+      const slugCol =
+        row.slug.length > 47 ? `${row.slug.slice(0, 46)}…` : row.slug;
+      log.info(
+        slugCol.padEnd(48) +
+          fmt(row.denseScore, 4).padStart(10) +
+          fmt(row.sparseRaw, 4).padStart(12) +
+          fmt(row.sparseNorm, 4).padStart(12) +
+          fmt(row.fused, 4).padStart(10),
+      );
+    }
+    log.info("");
+    log.info("Stats (per channel):");
+    log.info(`  ${formatStatLine("dense       ", channel.stats.dense)}`);
+    log.info(`  ${formatStatLine("sparseRaw   ", channel.stats.sparseRaw)}`);
+    log.info(`  ${formatStatLine("sparseNorm  ", channel.stats.sparseNorm)}`);
+    log.info(`  ${formatStatLine("fused       ", channel.stats.fused)}`);
+  }
+}
+
+function formatStatLine(
+  label: string,
+  stats: MemoryV2ExplainSimilarityStats,
+): string {
+  if (stats.count === 0) {
+    return `${label} n=0`;
+  }
+  const range = stats.max - stats.min;
+  return (
+    `${label} n=${String(stats.count).padStart(3)}` +
+    ` range=[${stats.min.toFixed(4)}, ${stats.max.toFixed(4)}]` +
+    ` (Δ=${range.toFixed(4)})` +
+    ` mean=${stats.mean.toFixed(4)}` +
+    ` std=${stats.stddev.toFixed(4)}`
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Registration
 // ---------------------------------------------------------------------------
@@ -101,17 +171,16 @@ export function registerMemoryV2Command(program: Command): void {
     "after",
     `
 The v2 subsystem replaces the v1 graph + PKB with prose concept pages,
-bidirectional edges in memory/edges.json, and activation-based retrieval.
-v2 stays gated behind the memory-v2-enabled feature flag — these subcommands
-remain useful operator tools regardless of whether the flag is on.
+directed edges stored in each page's frontmatter, and activation-based
+retrieval. v2 stays gated behind the memory-v2-enabled feature flag —
+these subcommands remain useful operator tools regardless of whether
+the flag is on.
 
 Subcommands fall into three groups:
 
   Mutating (return a jobId enqueued on the memory job queue):
     migrate          One-shot v1->v2 synthesis. Refuses to overwrite an
                      existing v2 state without --force.
-    rebuild-edges    Regenerate every concept page's edges: frontmatter from
-                     memory/edges.json.
     reembed          Refresh dense + sparse vectors for every concept page.
     activation       Refresh persisted activation state for every conversation.
 
@@ -119,17 +188,21 @@ Subcommands fall into three groups:
     reembed-skills   Re-seed v2 skill entries from the current skill catalog.
 
   Read-only:
-    validate         Print a diagnostic report of orphan edges, oversized
-                     pages, and parse failures.
+    validate         Print a diagnostic report of orphan outgoing-edge
+                     targets, oversized pages, and parse failures.
+
+  Calibration:
+    fit-anisotropy   Fit Mu & Viswanath's all-but-the-top correction so
+                     embedding cosines stop clustering in a narrow band.
 
 Examples:
   $ assistant memory v2 validate
   $ assistant memory v2 migrate
   $ assistant memory v2 migrate --force
-  $ assistant memory v2 rebuild-edges
   $ assistant memory v2 reembed
   $ assistant memory v2 reembed-skills
-  $ assistant memory v2 activation`,
+  $ assistant memory v2 activation
+  $ assistant memory v2 fit-anisotropy`,
   );
 
   // ── migrate ───────────────────────────────────────────────────────────
@@ -143,10 +216,10 @@ Examples:
     .addHelpText(
       "after",
       `
-Synthesises v2 concept pages from the v1 graph + PKB and writes
-memory/edges.json. The migration handler stores a sentinel at
-memory/.v2-state/.migration-complete-v1-to-v2 after a successful run and
-refuses to run again unless --force is passed.
+Synthesises v2 concept pages from the v1 graph + PKB, writing each page's
+outgoing directed edges directly into its frontmatter. The migration handler
+stores a sentinel at memory/.v2-state/.migration-complete-v1-to-v2 after a
+successful run and refuses to run again unless --force is passed.
 
 The job runs on the background memory worker — this command returns once
 the job is enqueued. Track progress via 'assistant memory status' or the
@@ -160,30 +233,6 @@ Examples:
       await runBackfillOp("migrate", { force: opts.force });
     });
 
-  // ── rebuild-edges ─────────────────────────────────────────────────────
-
-  v2.command("rebuild-edges")
-    .description(
-      "Regenerate every concept page's edges: frontmatter from memory/edges.json",
-    )
-    .addHelpText(
-      "after",
-      `
-Walks every concept page and rewrites the edges: frontmatter list to match
-the canonical memory/edges.json index. Useful after a manual edit to
-edges.json or to recover from a partially-written page that drifted from
-the index.
-
-The job runs on the background memory worker — this command returns once
-the job is enqueued.
-
-Examples:
-  $ assistant memory v2 rebuild-edges`,
-    )
-    .action(async () => {
-      await runBackfillOp("rebuild-edges");
-    });
-
   // ── reembed ───────────────────────────────────────────────────────────
 
   v2.command("reembed")
@@ -269,6 +318,224 @@ Examples:
       await runBackfillOp("activation-recompute");
     });
 
+  // ── explain ───────────────────────────────────────────────────────────
+
+  v2.command("explain")
+    .description(
+      "Diagnose dense vs sparse score distributions for a query (read-only)",
+    )
+    .requiredOption(
+      "--text <text>",
+      "Query text to embed and score against the concept-page collection (the user channel).",
+    )
+    .option(
+      "--assistant-text <text>",
+      "Optional second query text — scored independently as the assistant channel.",
+    )
+    .option(
+      "--now-text <text>",
+      "Optional third query text — scored independently as the now channel.",
+    )
+    .option(
+      "--top <n>",
+      "Number of top hits to fetch per channel (default 25)",
+      "25",
+    )
+    .addHelpText(
+      "after",
+      `
+Embeds the supplied text(s), runs the hybrid dense + sparse query against
+the v2 concept-page Qdrant collection, and prints per-slug raw dense, raw
+sparse, normalized sparse, and fused scores plus per-channel summary
+statistics (range, mean, stddev). Use this to identify whether dense
+embedding compression (anisotropy) or per-batch sparse normalization is
+the dominant cause of score compression at the head of the activation
+distribution.
+
+Read-only: does not mutate Qdrant, the workspace, or the activation log.
+
+Interpretation:
+  Dense range  < 0.1  AND sparseNorm range > 0.5 → embedding anisotropy
+  Dense range  > 0.2  AND sparseNorm range < 0.1 → sparse max-normalization
+  Both compressed                                → both contribute
+  Both wide                                      → channel mixing is the cause
+
+Examples:
+  $ assistant memory v2 explain --text "what's bothering me"
+  $ assistant memory v2 explain --text "..." --top 50
+  $ assistant memory v2 explain --text "..." --assistant-text "..." --now-text "..."`,
+    )
+    .action(
+      async (opts: {
+        text: string;
+        assistantText?: string;
+        nowText?: string;
+        top: string;
+      }) => {
+        const top = Number.parseInt(opts.top, 10);
+        if (!Number.isFinite(top) || top < 1) {
+          log.error("--top must be a positive integer");
+          process.exitCode = 1;
+          return;
+        }
+
+        const result = await cliIpcCall<MemoryV2ExplainSimilarityResult>(
+          "memory_v2_explain_similarity",
+          {
+            body: {
+              userText: opts.text,
+              assistantText: opts.assistantText,
+              nowText: opts.nowText,
+              top,
+            },
+          },
+        );
+
+        if (!result.ok) {
+          log.error(result.error ?? "Failed to run similarity diagnostic");
+          process.exitCode = 1;
+          return;
+        }
+
+        printExplainResult(result.result!);
+      },
+    );
+
+  // ── rebuild-corpus-stats ──────────────────────────────────────────────
+
+  v2.command("rebuild-corpus-stats")
+    .description(
+      "Rebuild the BM25 corpus stats (DF table + avg doc length) used by the sparse channel",
+    )
+    .addHelpText(
+      "after",
+      `
+Walks every concept page on disk and recomputes the document-frequency
+table and average document length used to weight BM25 sparse vectors.
+Atomic swap — the previous stats stay live until the new ones are ready.
+
+Run after bulk content imports, after manually editing many pages, or to
+recover from a startup rebuild that errored.
+
+Note: this only refreshes the in-memory stats used to *construct* new
+document-side sparse vectors. Existing sparse vectors stored in Qdrant
+are not refreshed by this command — pair with 'assistant memory v2
+reembed' if document-side weights need updating.
+
+Examples:
+  $ assistant memory v2 rebuild-corpus-stats`,
+    )
+    .action(async () => {
+      const result = await cliIpcCall<MemoryV2RebuildCorpusStatsResult>(
+        "memory_v2_rebuild_corpus_stats",
+        { body: {} },
+      );
+
+      if (!result.ok) {
+        log.error(result.error ?? "Failed to rebuild corpus stats");
+        process.exitCode = 1;
+        return;
+      }
+
+      const r = result.result!;
+      log.info(`Rebuilt BM25 corpus stats: ${r.totalDocs} docs.`);
+      log.info(`  avg doc length: ${r.avgDl.toFixed(2)} tokens`);
+      log.info(`  vocabulary buckets: ${r.vocabularyBuckets.toLocaleString()}`);
+    });
+
+  // ── fit-anisotropy ────────────────────────────────────────────────────
+
+  v2.command("fit-anisotropy")
+    .description(
+      "Fit the embedding anisotropy correction (Mu & Viswanath 'all-but-the-top')",
+    )
+    .option(
+      "--k <n>",
+      "Number of leading principal components to project out (default 1; raise to 2-3 only if PC2/PC3 also explain >5% variance)",
+      "1",
+    )
+    .option(
+      "--sample <n>",
+      "Maximum stored dense vectors to pull for the fit (default 5000)",
+      "5000",
+    )
+    .addHelpText(
+      "after",
+      `
+Modern transformer embeddings (Gemini in particular) are anisotropic — every
+vector lives in a narrow cone of the embedding space, which compresses cosine
+similarities into a tight band (typically 0.4-0.7) and lets a few dominant
+directions drown out semantic signal.
+
+This command samples stored dense vectors from the concept-page Qdrant
+collection, fits a corpus mean + top-k principal components, and persists the
+calibration. Subsequent embeds and queries apply the correction automatically:
+
+  vec' = vec - mean
+  for each pc_i: vec' = vec' - (vec' · pc_i) pc_i
+  vec' = vec' / ||vec'||
+
+After fitting, run 'assistant memory v2 reembed' to re-process every stored
+concept page through the new calibration. Until then, queries are corrected
+but stored vectors are not — the score range stays the same and retrieval may
+degrade. The calibration is keyed by (provider, model, dim), so changing
+embedding model invalidates it.
+
+Recommended k:
+  k=1   safest default. Removes the dominant common direction.
+  k=2-3 only when explained-variance ratios show PC2/PC3 each above ~5%.
+  k>3   not justified without a labeled retrieval eval set.
+
+Examples:
+  $ assistant memory v2 fit-anisotropy
+  $ assistant memory v2 fit-anisotropy --k 2
+  $ assistant memory v2 fit-anisotropy --sample 10000`,
+    )
+    .action(async (opts: { k: string; sample: string }) => {
+      const k = Number.parseInt(opts.k, 10);
+      const sample = Number.parseInt(opts.sample, 10);
+      if (!Number.isFinite(k) || k < 1) {
+        log.error("--k must be a positive integer");
+        process.exitCode = 1;
+        return;
+      }
+      if (!Number.isFinite(sample) || sample < 1) {
+        log.error("--sample must be a positive integer");
+        process.exitCode = 1;
+        return;
+      }
+
+      const result = await cliIpcCall<MemoryV2FitAnisotropyResult>(
+        "memory_v2_fit_anisotropy",
+        { body: { k, sample } },
+      );
+
+      if (!result.ok) {
+        log.error(result.error ?? "Failed to fit anisotropy calibration");
+        process.exitCode = 1;
+        return;
+      }
+
+      const r = result.result!;
+      log.info(
+        `Fit anisotropy calibration: ${r.provider}/${r.model} (dim=${r.dim})`,
+      );
+      log.info(`  samples: ${r.sampleCount}`);
+      log.info(`  total variance: ${r.totalVariance.toFixed(6)}`);
+      log.info("  explained variance per component:");
+      for (let i = 0; i < r.componentVariance.length; i++) {
+        const ratio = (r.explainedVarianceRatio[i] * 100).toFixed(2);
+        log.info(
+          `    PC${i + 1}: ${r.componentVariance[i].toFixed(6)} (${ratio}%)`,
+        );
+      }
+      log.info(`  written to: ${r.path}`);
+      log.info("");
+      log.info(
+        "Next step: run 'assistant memory v2 reembed' so every stored concept page is re-written under the new calibration. Until then, query-side correction operates on stored vectors that were embedded without it.",
+      );
+    });
+
   // ── validate ──────────────────────────────────────────────────────────
 
   v2.command("validate")
@@ -276,13 +543,13 @@ Examples:
     .addHelpText(
       "after",
       `
-Walks every concept page and the memory/edges.json index, returning an
-aggregate report of:
+Walks every concept page and aggregates outgoing edges from each page's
+frontmatter, returning a diagnostic report of:
 
   pageCount             Number of concept pages successfully parsed.
-  edgeCount             Number of edges in memory/edges.json.
-  missingEdgeEndpoints  Edges whose endpoints reference a slug that no
-                        concept page exists for (orphan endpoints).
+  edgeCount             Total number of directed outgoing edges across pages.
+  missingEdgeEndpoints  Outgoing edges whose target slug has no
+                        corresponding concept page (orphan targets).
   oversizedPages        Pages whose body exceeds memory.v2.max_page_chars
                         (a soft cap; consolidation will eventually split).
   parseFailures         Pages whose YAML frontmatter or schema validation
@@ -312,13 +579,13 @@ Examples:
       log.info(`Edges: ${report.edgeCount}`);
 
       if (report.missingEdgeEndpoints.length === 0) {
-        log.info("Missing edge endpoints: none");
+        log.info("Missing outgoing edge targets: none");
       } else {
         log.info(
-          `Missing edge endpoints: ${report.missingEdgeEndpoints.length}`,
+          `Missing outgoing edge targets: ${report.missingEdgeEndpoints.length}`,
         );
         for (const { from, to } of report.missingEdgeEndpoints) {
-          log.info(`  ${from} <-> ${to}`);
+          log.info(`  ${from} -> ${to}`);
         }
       }
 

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

@@ -1,11 +1,6 @@
 import type { Command } from "commander";
 
-import { getIsPlatform } from "../../../config/env-registry.js";
-import {
-  getConfig,
-  getNestedValue,
-  loadRawConfig,
-} from "../../../config/loader.js";
+import { getConfig } from "../../../config/loader.js";
 import {
   getServiceMode,
   type Services,
@@ -45,13 +40,6 @@ export function getManagedServiceConfigKey(provider: string): string | null {
 
 /**
  * Determine whether a provider is running in platform-managed mode.
- *
- * When `IS_PLATFORM=true` and the provider supports managed mode, this
- * defaults to `true` unless the user has explicitly set the service mode
- * to `"your-own"` in the raw config file. This lets platform instances
- * use platform-managed OAuth credentials out of the box without requiring
- * a manual `assistant oauth mode <provider> --set managed` step.
- *
  * Returns false if config is unavailable (e.g. in test environments).
  */
 export function isManagedMode(provider: string): boolean {
@@ -59,22 +47,7 @@ export function isManagedMode(provider: string): boolean {
   if (!managedKey) return false;
   try {
     const services: Services = getConfig().services;
-    const mode = getServiceMode(services, managedKey as keyof Services);
-    if (mode === "managed") return true;
-
-    // On platform instances, default to managed mode for providers that
-    // support it — unless the user explicitly opted into "your-own".
-    if (getIsPlatform()) {
-      const rawMode = getNestedValue(
-        loadRawConfig(),
-        `services.${managedKey}.mode`,
-      );
-      // If the raw config doesn't have an explicit mode entry, the "your-own"
-      // value came from the schema default — override it to managed on platform.
-      if (rawMode === undefined) return true;
-    }
-
-    return false;
+    return getServiceMode(services, managedKey as keyof Services) === "managed";
   } catch {
     return false;
   }

package/src/cli/commands/pending.ts

@@ -0,0 +1,102 @@
+import type { Command } from "commander";
+
+import { cliIpcCall } from "../../ipc/cli-client.js";
+import { log } from "../logger.js";
+
+interface PendingInteractionEntry {
+  requestId: string;
+  conversationId: string;
+  kind: string;
+  toolName?: string;
+  riskLevel?: string;
+}
+
+interface PendingInteractionsResponse {
+  interactions: PendingInteractionEntry[];
+}
+
+export function registerPendingCommand(program: Command): void {
+  const pending = program
+    .command("pending")
+    .description(
+      "Inspect pending interactions (confirmations, secrets, host proxy requests)",
+    );
+
+  pending
+    .command("list")
+    .alias("ls")
+    .description("List all pending interactions across all conversations")
+    .option(
+      "--kind <kind>",
+      "Filter by kind (confirmation, secret, host_bash, etc.)",
+    )
+    .option("--conversation <id>", "Filter by conversation ID")
+    .option("--json", "Output as JSON")
+    .action(
+      async (opts: {
+        kind?: string;
+        conversation?: string;
+        json?: boolean;
+      }) => {
+        try {
+          const response =
+            await cliIpcCall<PendingInteractionsResponse>(
+              "pending_interactions",
+            );
+
+          if (!response.ok || !response.result) {
+            log.error(
+              `Failed to list pending interactions: ${response.error ?? "unknown error"}`,
+            );
+            process.exitCode = 1;
+            return;
+          }
+
+          let interactions = response.result.interactions;
+
+          if (opts.kind) {
+            interactions = interactions.filter(
+              (i: PendingInteractionEntry) => i.kind === opts.kind,
+            );
+          }
+          if (opts.conversation) {
+            interactions = interactions.filter(
+              (i: PendingInteractionEntry) =>
+                i.conversationId === opts.conversation,
+            );
+          }
+
+          if (opts.json) {
+            console.log(JSON.stringify(interactions, null, 2));
+            return;
+          }
+
+          if (interactions.length === 0) {
+            console.log("No pending interactions.");
+            return;
+          }
+
+          const kindWidth = Math.max(
+            4,
+            ...interactions.map((i: PendingInteractionEntry) => i.kind.length),
+          );
+          const header = `${"KIND".padEnd(kindWidth)}  ${"REQUEST ID".padEnd(36)}  ${"CONVERSATION".padEnd(36)}  DETAILS`;
+          console.log(header);
+
+          for (const i of interactions) {
+            const details = i.toolName
+              ? `${i.toolName} (${i.riskLevel ?? "?"})`
+              : "";
+            console.log(
+              `${i.kind.padEnd(kindWidth)}  ${i.requestId.padEnd(36)}  ${i.conversationId.padEnd(36)}  ${details}`,
+            );
+          }
+
+          console.log(`\n${interactions.length} pending interaction(s)`);
+        } catch (err) {
+          log.error({ err }, "Failed to list pending interactions");
+          process.exitCode = 1;
+        }
+      },
+    );
+}

package/src/cli/commands/platform/__tests__/callback-routes-list.test.ts

@@ -61,7 +61,6 @@ mock.module("../../../../config/loader.js", () => ({
   }),
   loadConfig: () => ({}),
   invalidateConfigCache: () => {},
-  saveConfig: () => {},
   loadRawConfig: () => ({}),
   saveRawConfig: () => {},
 }));

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

@@ -88,13 +88,11 @@ mock.module("../../../../config/loader.js", () => ({
   }),
   loadConfig: () => ({}),
   invalidateConfigCache: () => {},
-  saveConfig: () => {},
   loadRawConfig: () => ({}),
   saveRawConfig: () => {},
   getNestedValue: () => undefined,
   setNestedValue: () => {},
   applyNestedDefaults: (config: unknown) => config,
-  deepMergeMissing: () => false,
   deepMergeOverwrite: () => {},
   mergeDefaultWorkspaceConfig: () => {},
 }));

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

@@ -109,13 +109,11 @@ mock.module("../../../../config/loader.js", () => ({
   }),
   loadConfig: () => ({}),
   invalidateConfigCache: () => {},
-  saveConfig: () => {},
   loadRawConfig: () => ({}),
   saveRawConfig: () => {},
   getNestedValue: () => undefined,
   setNestedValue: () => {},
   applyNestedDefaults: (config: unknown) => config,
-  deepMergeMissing: () => false,
   deepMergeOverwrite: () => {},
   mergeDefaultWorkspaceConfig: () => {},
 }));