@vellumai/assistant 0.9.0 → 0.10.0-staging.2

package/src/cli/commands/{memory-v2.ts → memory/memory-v2.ts}

@@ -18,8 +18,8 @@
 
 import type { Command } from "commander";
 
-import { cliIpcCall } from "../../ipc/cli-client.js";
-import type { ComparisonReport } from "../../memory/v2/harness/runner.js";
+import { cliIpcCall } from "../../../ipc/cli-client.js";
+import type { ComparisonReport } from "../../../memory/v2/harness/runner.js";
 import type {
   MemoryV2BackfillOp,
   MemoryV2BackfillResult,
@@ -27,9 +27,9 @@ import type {
   MemoryV2ReembedSkillsResult,
   MemoryV2SimulateRouterResult,
   MemoryV2ValidateResult,
-} from "../../runtime/routes/memory-v2-routes.js";
-import { registerCommand } from "../lib/register-command.js";
-import { log } from "../logger.js";
+} from "../../../runtime/routes/memory-v2-routes.js";
+import { registerCommand } from "../../lib/register-command.js";
+import { log } from "../../logger.js";
 import {
   renderComparisonReport,
   renderTurnTrace,
@@ -63,16 +63,7 @@ async function runBackfillOp(op: MemoryV2BackfillOp): Promise<void> {
 // Registration
 // ---------------------------------------------------------------------------
 
-export function registerMemoryV2Command(program: Command): void {
-  // Reuse an existing `memory` parent if some other registrar attached to it
-  // first; otherwise create one. This keeps the registration order between
-  // sibling memory registrars unconstrained.
-  const memory =
-    program.commands.find((c) => c.name() === "memory") ??
-    program
-      .command("memory")
-      .description("Manage the v2 memory subsystem (concept-page model)");
-
+export function registerMemoryV2Command(memory: Command): void {
   registerCommand(memory, {
     name: "v2",
     transport: "ipc",

package/src/cli/commands/{memory-v3.ts → memory/memory-v3.ts}

@@ -17,13 +17,14 @@
 
 import type { Command } from "commander";
 
-import { cliIpcCall } from "../../ipc/cli-client.js";
+import { cliIpcCall } from "../../../ipc/cli-client.js";
+import type { MemoryEvalRunResult } from "../../../runtime/routes/memory-eval-routes.js";
 import type {
   MemoryV3BackfillSectionsResult,
   MemoryV3RebuildIndexResult,
-} from "../../runtime/routes/memory-v3-routes.js";
-import { registerCommand } from "../lib/register-command.js";
-import { log } from "../logger.js";
+} from "../../../runtime/routes/memory-v3-routes.js";
+import { registerCommand } from "../../lib/register-command.js";
+import { log } from "../../logger.js";
 
 /**
  * IPC timeout for `backfill-sections`. The one-time full-corpus section embed
@@ -34,14 +35,14 @@ import { log } from "../logger.js";
  */
 const BACKFILL_IPC_TIMEOUT_MS = 30 * 60 * 1000;
 
-export function registerMemoryV3Command(program: Command): void {
-  // Reuse an existing `memory` parent if some other registrar attached to it
-  // first; otherwise create one. This keeps the registration order between
-  // sibling memory registrars unconstrained.
-  const memory =
-    program.commands.find((c) => c.name() === "memory") ??
-    program.command("memory").description("Manage the memory subsystem");
+/**
+ * IPC timeout for `eval`. Embedding both corpora's sections runs through the
+ * embedder and easily outlasts the default 60s, so allow the same generous
+ * ceiling as the backfill.
+ */
+const EVAL_IPC_TIMEOUT_MS = 30 * 60 * 1000;
 
+export function registerMemoryV3Command(memory: Command): void {
   registerCommand(memory, {
     name: "v3",
     transport: "ipc",
@@ -134,6 +135,91 @@ Examples:
                 : "."),
           );
         });
+
+      // ── eval ──────────────────────────────────────────────────────────────
+
+      v3.command("eval")
+        .description(
+          "Build blinded A/B retrieval-eval packets (snapshot corpus vs staged wiki)",
+        )
+        .requiredOption(
+          "--staging <dir>",
+          "Staged v3 wiki dir (relative to the workspace, or absolute)",
+        )
+        .requiredOption(
+          "--snapshot <dir>",
+          "Read-only v2 snapshot dir (relative to the workspace, or absolute)",
+        )
+        .requiredOption("--out <dir>", "Output dir for packets.json + key.json")
+        .option("--turns <n>", "Number of recent turns to mine", "30")
+        .option("--k <n>", "Pages per memory set", "8")
+        .option(
+          "--seed <n>",
+          "Blinding seed (reproducible A/B assignment)",
+          "1",
+        )
+        .option(
+          "--no-dense",
+          "Needle-only: skip section embedding (fast, cheaper, lower fidelity)",
+        )
+        .option("--json", "Emit raw JSON instead of a formatted summary")
+        .addHelpText(
+          "after",
+          `
+Mines recent user turns, retrieves the top pages from each corpus per turn, and
+writes blinded A/B packets (plus a separate unblinding key) for a blind-judge
+workflow. Both corpora are read in memory — nothing in the live lanes or Qdrant
+is touched. With the dense lane on (default) it embeds every section of both
+corpora, which can take a while on a large corpus; use --no-dense for a fast
+lexical-only pass.
+
+Examples:
+  $ assistant memory v3 eval --snapshot .mv3/snapshot/concepts --staging .mv3/staging --out .mv3/eval
+  $ assistant memory v3 eval --snapshot .mv3/snapshot/concepts --staging .mv3/staging --out .mv3/eval --turns 50 --no-dense`,
+        )
+        .action(
+          async (opts: {
+            staging: string;
+            snapshot: string;
+            out: string;
+            turns: string;
+            k: string;
+            seed: string;
+            dense: boolean;
+            json?: boolean;
+          }) => {
+            const result = await cliIpcCall<MemoryEvalRunResult>(
+              "memory_eval_run",
+              {
+                body: {
+                  stagingDir: opts.staging,
+                  snapshotDir: opts.snapshot,
+                  outDir: opts.out,
+                  turns: Number(opts.turns),
+                  k: Number(opts.k),
+                  seed: Number(opts.seed),
+                  dense: opts.dense,
+                },
+              },
+              { timeoutMs: EVAL_IPC_TIMEOUT_MS },
+            );
+            if (!result.ok) {
+              log.error(result.error ?? "Failed to build eval packets");
+              process.exitCode = 1;
+              return;
+            }
+            const payload = result.result!;
+            if (opts.json === true) {
+              log.info(JSON.stringify(payload, null, 2));
+              return;
+            }
+            log.info(
+              `Wrote ${payload.packetsWritten} packets from ${payload.turnsMined} turns ` +
+                `(snapshot ${payload.snapshotPages} pages vs staged ${payload.stagingPages} pages, ` +
+                `dense=${payload.dense}).\n  packets: ${payload.packetsPath}\n  key:     ${payload.keyPath}`,
+            );
+          },
+        );
     },
   });
 }

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

@@ -0,0 +1,36 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { 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;
+});
+
+describe("noConnectionsMessage", () => {
+  test("capable models get the terse default", () => {
+    process.env.__RESOLVED_MODEL = "claude-opus-4-8";
+    const msg = noConnectionsMessage("google");
+    expect(msg).toBe(
+      "No active connections for google.\n" +
+        "Connect with `assistant oauth connect google`.\n",
+    );
+  });
+
+  test("no resolved model falls back to the terse default", () => {
+    delete process.env.__RESOLVED_MODEL;
+    expect(noConnectionsMessage("google")).toContain(
+      "Connect with `assistant oauth connect google`.",
+    );
+  });
+
+  test("weak open models are steered to the oauth_connect surface", () => {
+    process.env.__RESOLVED_MODEL = "accounts/fireworks/models/minimax-m3";
+    const msg = noConnectionsMessage("google");
+    expect(msg).toContain('surface_type "oauth_connect"');
+    expect(msg).toContain('data.providerKey "google"');
+    expect(msg).not.toContain("assistant oauth connect google");
+  });
+});

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

@@ -1,8 +1,30 @@
 import type { Command } from "commander";
 
 import { cliIpcCall, exitFromIpcResult } from "../../../ipc/cli-client.js";
+import { isWeakOpenModel } from "../../../providers/weak-open-model.js";
 import { shouldOutputJson, writeOutput } from "../../output.js";
 
+/**
+ * Message shown when a provider has no active connections. Weak open models
+ * loop through redundant discovery commands (channel checks, `oauth providers
+ * get`, loading the OAuth setup skill) before rendering the connect button, so
+ * they get an explicit single next action: render the core `oauth_connect`
+ * surface directly. Capable models keep the terse default.
+ */
+export function noConnectionsMessage(provider: string): string {
+  const base = `No active connections for ${provider}.`;
+  if (isWeakOpenModel(process.env.__RESOLVED_MODEL)) {
+    return (
+      `${base}\nTo 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 or load a setup skill ` +
+      `just to display it.\n`
+    );
+  }
+  return `${base}\nConnect with \`assistant oauth connect ${provider}\`.\n`;
+}
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -91,9 +113,7 @@ Examples:
 
           // Text output
           if (connections.length === 0) {
-            process.stdout.write(
-              `No active connections for ${provider}.\nConnect with \`assistant oauth connect ${provider}\`.\n`,
-            );
+            process.stdout.write(noConnectionsMessage(provider));
             return;
           }
 

package/src/cli/commands/plugins.ts

@@ -10,6 +10,11 @@
 import type { Command } from "commander";
 
 import { confirmPrompt } from "../lib/confirm-prompt.js";
+import {
+  diffPlugin,
+  type PluginDiffResult,
+  PluginDiffUnavailableError,
+} from "../lib/diff-plugin.js";
 import {
   inspectPlugin,
   type PluginInspection,
@@ -35,8 +40,12 @@ import {
   uninstallPlugin,
 } from "../lib/uninstall-plugin.js";
 import {
+  DEFAULT_PLUGIN_UPGRADE_STRATEGY,
+  PLUGIN_UPGRADE_STRATEGIES,
+  PluginMergeBaselineError,
   PluginNotUpgradableError,
   type PluginUpgradeResult,
+  type PluginUpgradeStrategy,
   upgradePlugin,
 } from "../lib/upgrade-plugin.js";
 import { getCliLogger } from "../logger.js";
@@ -60,8 +69,13 @@ Examples:
   $ assistant plugins list --json
   $ assistant plugins inspect example
   $ assistant plugins inspect example --json
+  $ assistant plugins diff example
+  $ assistant plugins diff example --json
   $ assistant plugins upgrade example
   $ assistant plugins upgrade example --dry-run
+  $ assistant plugins upgrade example --strategy ours
+  $ assistant plugins upgrade example --strategy theirs
+  $ assistant plugins upgrade example --strategy assistant
   $ assistant plugins search example
   $ assistant plugins search "^example"
   $ assistant plugins search example --json
@@ -166,7 +180,7 @@ Examples:
       plugins
         .command("inspect <name>")
         .description(
-          "Show a plugin's local install metadata and the marketplace pin, and whether an update is available",
+          "Show a plugin's local install metadata, the marketplace pin, whether an update is available, and the surfaces (skills, hooks, tools) it contributes",
         )
         .option("--json", "Emit machine-readable JSON instead of a summary")
         .action(async (name: string, opts: { json?: boolean }) => {
@@ -212,6 +226,73 @@ Examples:
           }
         });
 
+      plugins
+        .command("diff <name>")
+        .description(
+          "Show a unified diff of local edits to an installed plugin against the commit it was installed at",
+        )
+        .option(
+          "--json",
+          "Emit the machine-readable diff result as JSON (files: { path, status, diff, binary, reconstructed }[]) instead of a unified diff",
+        )
+        .addHelpText(
+          "after",
+          `
+Arguments:
+  name   Install name (kebab-case directory under the workspace plugins dir);
+         run 'assistant plugins list' to see installed names.
+
+The baseline is the exact commit the plugin was installed at (recorded in its
+install-meta.json), re-materialized through the install pipeline — so an
+install-time adapter transform never reads as a local change. To compare
+against the marketplace's current pin instead, use 'plugins upgrade --dry-run'.
+
+Examples:
+  $ assistant plugins diff example
+  $ assistant plugins diff example --json`,
+        )
+        .action(async (name: string, opts: { json?: boolean }) => {
+          try {
+            const result = await diffPlugin(
+              { name },
+              { fetch: globalThis.fetch.bind(globalThis) },
+            );
+
+            if (opts.json) {
+              process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+              return;
+            }
+
+            // Logged after the JSON early-return: the CLI logger writes
+            // info to stdout, which would otherwise corrupt --json output.
+            log.info(
+              {
+                name: result.name,
+                clean: result.clean,
+                files: result.files.length,
+              },
+              "plugin diff",
+            );
+
+            for (const line of formatDiff(result)) {
+              console.log(line);
+            }
+          } catch (err) {
+            if (
+              err instanceof PluginNotInstalledError ||
+              err instanceof PluginDiffUnavailableError ||
+              err instanceof InvalidPluginNameError
+            ) {
+              console.error(err.message);
+              process.exitCode = 1;
+              return;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Plugin diff failed: ${message}`);
+            process.exitCode = 1;
+          }
+        });
+
       plugins
         .command("search <query>")
         .description(
@@ -327,12 +408,36 @@ Examples:
           "--dry-run",
           "Show what would change without modifying the install",
         )
+        .option(
+          "--strategy <strategy>",
+          `How to reconcile local edits with the pin: ${PLUGIN_UPGRADE_STRATEGIES.join(", ")} (default: ${DEFAULT_PLUGIN_UPGRADE_STRATEGY})`,
+        )
         .option("--json", "Emit machine-readable JSON instead of a summary")
         .action(
-          async (name: string, opts: { dryRun?: boolean; json?: boolean }) => {
+          async (
+            name: string,
+            opts: { dryRun?: boolean; strategy?: string; json?: boolean },
+          ) => {
+            const strategy = opts.strategy;
+            if (
+              strategy !== undefined &&
+              !(PLUGIN_UPGRADE_STRATEGIES as readonly string[]).includes(
+                strategy,
+              )
+            ) {
+              console.error(
+                `Invalid --strategy "${strategy}". Expected one of: ${PLUGIN_UPGRADE_STRATEGIES.join(", ")}.`,
+              );
+              process.exitCode = 1;
+              return;
+            }
             try {
               const result = await upgradePlugin(
-                { name, dryRun: opts.dryRun },
+                {
+                  name,
+                  dryRun: opts.dryRun,
+                  strategy: strategy as PluginUpgradeStrategy | undefined,
+                },
                 { fetch: globalThis.fetch.bind(globalThis) },
               );
 
@@ -360,6 +465,7 @@ Examples:
               if (
                 err instanceof PluginNotInstalledError ||
                 err instanceof PluginNotUpgradableError ||
+                err instanceof PluginMergeBaselineError ||
                 err instanceof InvalidPluginNameError
               ) {
                 console.error(err.message);
@@ -443,12 +549,20 @@ function remoteLocation(remote: PluginRemoteInfo): string {
  * `location`, with a `drift` line under the installed copy.
  */
 function formatInspection(inspection: PluginInspection): string[] {
-  const { name, status, local, remote, remoteError } = inspection;
+  const { name, status, local, remote, remoteError, surfaces } = inspection;
   const lines: string[] = [name, "─".repeat(44)];
   const topRow = (label: string, value: string) =>
     lines.push(`${label.padEnd(11)} ${value}`);
   const blockRow = (label: string, value: string) =>
     lines.push(`  ${label.padEnd(9)} ${value}`);
+  // A surface block: the surface type as a heading, then its items indented
+  // under it. Omitted entirely when the plugin contributes none of that type,
+  // so the listing only ever shows what the plugin actually contributes.
+  const surfaceBlock = (label: string, items: readonly string[]) => {
+    if (items.length === 0) return;
+    lines.push(label);
+    for (const item of items) lines.push(`  ${item}`);
+  };
 
   topRow("status", statusLine(status));
 
@@ -483,6 +597,12 @@ function formatInspection(inspection: PluginInspection): string[] {
   const description = remote?.description ?? local?.description ?? null;
   if (description) topRow("description", description);
 
+  if (surfaces) {
+    surfaceBlock("skills", surfaces.skills);
+    surfaceBlock("hooks", surfaces.hooks);
+    surfaceBlock("tools", surfaces.tools);
+  }
+
   for (const issue of local?.issues ?? []) topRow("issue", issue);
 
   return lines;
@@ -521,14 +641,87 @@ function formatUpgrade(result: PluginUpgradeResult): string[] {
         result.fileCount === null
           ? ""
           : `(${result.fileCount} file${result.fileCount === 1 ? "" : "s"}) `;
+      const hasConflicts =
+        result.conflicts.length > 0 || result.binaryConflicts.length > 0;
+
+      // Under `assistant`, an unresolved merge leaves conflicts in the tree —
+      // the plugin would fail to load while any remain, so the usual "restart
+      // now" guidance is replaced with resolution instructions. Most conflicts
+      // carry git markers, but a modify/delete divergence (a file edited on one
+      // side and deleted on the other) keeps the surviving content with no
+      // markers, so the guidance covers both rather than assuming markers.
+      if (result.strategy === "assistant" && hasConflicts) {
+        const lines = [
+          `Merged "${name}" ${move} with conflicts`,
+          "",
+          `${count}→ ${result.target}`,
+        ];
+        if (result.conflicts.length > 0) {
+          lines.push(
+            "",
+            `Resolve ${result.conflicts.length} conflicted file${result.conflicts.length === 1 ? "" : "s"} (open each: resolve its git conflict markers, or — if a modify/delete divergence kept the file with none — decide whether to keep or remove it):`,
+            ...result.conflicts.map((p) => `  ${p}`),
+          );
+        }
+        if (result.binaryConflicts.length > 0) {
+          lines.push(
+            "",
+            `Binary conflict${result.binaryConflicts.length === 1 ? "" : "s"} (kept the local copy — choose a version manually):`,
+            ...result.binaryConflicts.map((p) => `  ${p}`),
+          );
+        }
+        lines.push(
+          "",
+          "Resolve the conflicts, then restart the assistant to pick up the upgrade.",
+        );
+        if (provenanceNote) lines.push(provenanceNote);
+        return lines;
+      }
+
+      const mergeNote =
+        result.strategy === "ours" || result.strategy === "theirs"
+          ? `Local edits were merged (--strategy ${result.strategy}).`
+          : result.strategy === "assistant"
+            ? "Local edits were merged with no conflicts (--strategy assistant)."
+            : null;
       const lines = [
         `Upgraded "${name}" ${move}`,
         "",
         `${count}→ ${result.target}`,
         "Restart the assistant to pick up the upgrade.",
       ];
+      if (mergeNote) lines.push(mergeNote);
       if (provenanceNote) lines.push(provenanceNote);
       return lines;
     }
   }
 }
+
+/**
+ * Render a diff result: a one-line "no local changes" when clean, otherwise a
+ * header naming the install-commit baseline followed by each file's unified
+ * diff (blank-line separated, mirroring how `git diff` stacks file patches).
+ */
+function formatDiff(result: PluginDiffResult): string[] {
+  const baseline = `${formatTimestamp(result.committedAt)} (${shortSha(result.commit)})`;
+  if (result.clean) {
+    return [
+      `"${result.name}" has no local changes (matches install commit ${baseline}).`,
+    ];
+  }
+  const count = result.files.length;
+  const lines = [
+    `"${result.name}" — ${count} file${count === 1 ? "" : "s"} changed vs install commit ${baseline}`,
+    "",
+  ];
+  for (const file of result.files) {
+    // A non-reconstructed baseline carries an explanatory marker, not a patch
+    // with `a/`–`b/` headers, so name the file it refers to.
+    if (!file.reconstructed) {
+      lines.push(`${file.path}: ${file.diff.trimEnd()}`, "");
+      continue;
+    }
+    lines.push(file.diff.trimEnd(), "");
+  }
+  return lines;
+}