@vellumai/assistant 0.8.5 → 0.8.6

package/src/cli/commands/channels/__tests__/channels.test.ts

@@ -0,0 +1,143 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { Command } from "commander";
+
+// ---------------------------------------------------------------------------
+// Mock state
+// ---------------------------------------------------------------------------
+
+let mockCalls: Array<[string, Record<string, unknown> | undefined]> = [];
+let mockResponses: unknown[] = [];
+
+mock.module("../../../../ipc/cli-client.js", () => ({
+  cliIpcCall: async (method: string, params?: Record<string, unknown>) => {
+    mockCalls.push([method, params]);
+    return mockResponses.shift() ?? { ok: true, result: { success: true } };
+  },
+  exitFromIpcResult: (_r: unknown, _cmd: unknown) => {
+    throw new Error("exitFromIpcResult called");
+  },
+}));
+
+const { registerChannelsCommand } = await import("../index.js");
+
+function buildProgram(): Command {
+  const program = new Command();
+  program.exitOverride();
+  registerChannelsCommand(program);
+  return program;
+}
+
+async function runCli(...argv: string[]): Promise<string> {
+  const stdoutChunks: string[] = [];
+  const origWrite = process.stdout.write.bind(process.stdout);
+  process.stdout.write = ((chunk: unknown) => {
+    stdoutChunks.push(typeof chunk === "string" ? chunk : String(chunk));
+    return true;
+  }) as typeof process.stdout.write;
+  try {
+    await buildProgram().parseAsync(["node", "assistant", ...argv]);
+  } finally {
+    process.stdout.write = origWrite;
+  }
+  return stdoutChunks.join("");
+}
+
+function emptySnapshot(channel: string, overrides: Record<string, unknown> = {}) {
+  return {
+    channel,
+    ready: false,
+    setupStatus: "not_configured",
+    checkedAt: 0,
+    stale: false,
+    reasons: [],
+    localChecks: [],
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("assistant channels", () => {
+  beforeEach(() => {
+    mockCalls = [];
+    mockResponses = [];
+    process.exitCode = 0;
+  });
+
+  describe("list", () => {
+    test("calls channels_readiness_get with includeRemote=false by default", async () => {
+      mockResponses = [
+        { ok: true, result: { success: true, snapshots: [] } },
+      ];
+      await runCli("channels", "list", "--json");
+      expect(mockCalls).toHaveLength(1);
+      expect(mockCalls[0][0]).toBe("channels_readiness_get");
+      expect(mockCalls[0][1]).toEqual({
+        queryParams: { includeRemote: "false" },
+      });
+    });
+
+    test("--remote flips includeRemote to true (still GET, still cached)", async () => {
+      mockResponses = [
+        { ok: true, result: { success: true, snapshots: [] } },
+      ];
+      await runCli("channels", "list", "--remote", "--json");
+      expect(mockCalls[0][0]).toBe("channels_readiness_get");
+      expect(mockCalls[0][1]).toEqual({
+        queryParams: { includeRemote: "true" },
+      });
+    });
+  });
+
+  describe("get", () => {
+    test("always re-probes via the refresh route (live, never cached)", async () => {
+      mockResponses = [
+        {
+          ok: true,
+          result: {
+            success: true,
+            snapshots: [emptySnapshot("slack")],
+          },
+        },
+      ];
+      await runCli("channels", "get", "slack", "--json");
+      expect(mockCalls[0][0]).toBe("channels_readiness_refresh_post");
+      expect(mockCalls[0][1]).toEqual({
+        body: { channel: "slack", includeRemote: true },
+      });
+    });
+
+    test("requires a channel argument", async () => {
+      // commander throws via exitOverride when arg is missing
+      await expect(runCli("channels", "get")).rejects.toThrow();
+      expect(mockCalls).toHaveLength(0);
+    });
+
+    test("exits non-zero when channel has no registered probe", async () => {
+      mockResponses = [
+        { ok: true, result: { success: true, snapshots: [] } },
+      ];
+      await runCli("channels", "get", "nope", "--json");
+      expect(process.exitCode).toBe(1);
+    });
+
+    test("does NOT accept --refresh flag (every get is live)", async () => {
+      // commander rejects unknown options via exitOverride
+      await expect(
+        runCli("channels", "get", "slack", "--refresh"),
+      ).rejects.toThrow();
+    });
+  });
+
+  describe("refresh", () => {
+    test("is not registered (mutating verb deferred to its own PR)", async () => {
+      // commander throws via exitOverride for unknown subcommands
+      await expect(
+        runCli("channels", "refresh", "slack"),
+      ).rejects.toThrow();
+    });
+  });
+});

package/src/cli/commands/channels/index.ts

@@ -0,0 +1,229 @@
+/**
+ * `assistant channels` — inspect messaging channels.
+ *
+ *   list                     — overview of every channel + ready state
+ *   get <channel>            — detailed live snapshot of a single channel
+ *
+ * `get` always re-runs remote probes (it invalidates the readiness cache
+ * before reading), so the CLI answer matches the live source-of-truth.
+ *
+ * A mutating `refresh` verb (for reconnecting channels — e.g. supplying
+ * fresh Slack tokens) is intentionally not shipped here; it will land in
+ * its own PR.
+ */
+
+import type { Command } from "commander";
+
+import { cliIpcCall, exitFromIpcResult } from "../../../ipc/cli-client.js";
+import { registerCommand } from "../../lib/register-command.js";
+import { log } from "../../logger.js";
+import { shouldOutputJson, writeOutput } from "../../output.js";
+
+// ---------------------------------------------------------------------------
+// Snapshot shape (mirrors runtime/routes/channel-readiness-routes.ts)
+// ---------------------------------------------------------------------------
+
+interface ReadinessCheck {
+  name: string;
+  passed: boolean;
+  message: string;
+}
+
+interface ChannelSnapshot {
+  channel: string;
+  ready: boolean;
+  setupStatus: "not_configured" | "incomplete" | "ready";
+  checkedAt: number;
+  stale: boolean;
+  reasons: Array<{ code: string; text: string }>;
+  localChecks: ReadinessCheck[];
+  remoteChecks?: ReadinessCheck[];
+  channelHandle?: unknown;
+}
+
+interface ReadinessResponse {
+  success: boolean;
+  snapshots: ChannelSnapshot[];
+}
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+
+function statusGlyph(s: ChannelSnapshot): string {
+  if (s.ready) return "✅";
+  if (s.setupStatus === "not_configured") return "○ ";
+  return "⚠️ ";
+}
+
+function statusWord(s: ChannelSnapshot): string {
+  if (s.ready) return "ready";
+  if (s.setupStatus === "not_configured") return "not configured";
+  return "incomplete";
+}
+
+function renderList(snapshots: ChannelSnapshot[]): void {
+  const sorted = [...snapshots].sort((a, b) =>
+    a.channel.localeCompare(b.channel),
+  );
+  log.info("Channel        Status");
+  log.info("-------------  ------");
+  for (const s of sorted) {
+    log.info(`${statusGlyph(s)} ${s.channel.padEnd(12)}  ${statusWord(s)}`);
+  }
+}
+
+function renderSnapshot(s: ChannelSnapshot): void {
+  log.info(`${statusGlyph(s)} ${s.channel} — ${s.setupStatus}`);
+  if (s.reasons.length > 0) {
+    log.info("");
+    log.info("Reasons:");
+    for (const r of s.reasons) {
+      log.info(`  • [${r.code}] ${r.text}`);
+    }
+  }
+  if (s.localChecks.length > 0) {
+    log.info("");
+    log.info("Local checks:");
+    for (const c of s.localChecks) {
+      log.info(`  ${c.passed ? "✓" : "✗"} ${c.name} — ${c.message}`);
+    }
+  }
+  if (s.remoteChecks && s.remoteChecks.length > 0) {
+    log.info("");
+    log.info("Remote checks:");
+    for (const c of s.remoteChecks) {
+      log.info(`  ${c.passed ? "✓" : "✗"} ${c.name} — ${c.message}`);
+    }
+  }
+}
+
+/** All channel IDs the readiness service knows about. Mirrors channels/types.ts. */
+const KNOWN_CHANNELS = [
+  "telegram",
+  "phone",
+  "vellum",
+  "whatsapp",
+  "slack",
+  "email",
+  "platform",
+  "a2a",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+
+export function registerChannelsCommand(program: Command): void {
+  registerCommand(program, {
+    name: "channels",
+    transport: "ipc",
+    description:
+      "Inspect and repair messaging channels (slack, telegram, email, etc.)",
+    build: (channels) => {
+      channels.addHelpText(
+        "after",
+        `
+Channels are the messaging surfaces the assistant talks over — slack,
+telegram, whatsapp, email, phone, vellum, platform, a2a. Each channel
+has a probe that reports whether it's configured and reachable.
+
+  list                    Overview of every channel + ready state
+  get <channel>           Live snapshot of one channel (always re-probes)
+
+Examples:
+  $ assistant channels list
+  $ assistant channels get slack`,
+      );
+
+      // -----------------------------------------------------------------------
+      // list
+      // -----------------------------------------------------------------------
+
+      channels
+        .command("list")
+        .description("Show readiness state for every configured channel")
+        .option("--json", "Machine-readable compact JSON output")
+        .option(
+          "--remote",
+          "Include remote checks (live network round-trip per channel)",
+          false,
+        )
+        .action(
+          async (
+            opts: { json?: boolean; remote?: boolean },
+            cmd: Command,
+          ) => {
+            const r = await cliIpcCall<ReadinessResponse>(
+              "channels_readiness_get",
+              {
+                queryParams: {
+                  includeRemote: opts.remote ? "true" : "false",
+                },
+              },
+            );
+            if (!r.ok) {
+              return exitFromIpcResult(
+                { ok: false, error: r.error, statusCode: r.statusCode },
+                cmd,
+              );
+            }
+            if (shouldOutputJson(cmd)) {
+              writeOutput(cmd, { snapshots: r.result!.snapshots });
+            } else {
+              renderList(r.result!.snapshots);
+            }
+          },
+        );
+
+      // -----------------------------------------------------------------------
+      // get — always live (invalidates cache + re-runs remote checks)
+      // -----------------------------------------------------------------------
+
+      channels
+        .command("get")
+        .description(
+          "Live readiness snapshot for one channel (always re-probes; no caching)",
+        )
+        .argument(
+          "<channel>",
+          `Channel id: ${KNOWN_CHANNELS.join(", ")}`,
+        )
+        .option("--json", "Machine-readable compact JSON output")
+        .action(
+          async (
+            channel: string,
+            _opts: { json?: boolean },
+            cmd: Command,
+          ) => {
+            // `get` is always live: invalidate the cache and re-run remote
+            // checks. This matches what source code does when it needs to
+            // know the channel's current state — no stale snapshots.
+            const r = await cliIpcCall<ReadinessResponse>(
+              "channels_readiness_refresh_post",
+              { body: { channel, includeRemote: true } },
+            );
+            if (!r.ok) {
+              return exitFromIpcResult(
+                { ok: false, error: r.error, statusCode: r.statusCode },
+                cmd,
+              );
+            }
+            const snapshot = r.result!.snapshots.find(
+              (s) => s.channel === channel,
+            );
+            if (!snapshot) {
+              log.error(`No readiness probe registered for channel: ${channel}`);
+              process.exitCode = 1;
+              return;
+            }
+            if (shouldOutputJson(cmd)) {
+              writeOutput(cmd, snapshot);
+            } else {
+              renderSnapshot(snapshot);
+            }
+          },
+        );
+    },
+  });
+}

package/src/cli/commands/memory-v3-render.ts

@@ -14,6 +14,9 @@ import type {
   MemoryV3SimulateResult,
   MemoryV3TreeResult,
   MemoryV3ValidateResult,
+  SeedCoretrievalResult,
+  ShadowDiffResult,
+  ShadowDiffTurn,
 } from "../../runtime/routes/memory-v3-routes.js";
 
 /**
@@ -252,6 +255,135 @@ export function renderSimulation(result: MemoryV3SimulateResult): string {
   return lines.join("\n");
 }
 
+// ── Shadow-diff ───────────────────────────────────────────────────────────
+
+/** Max slugs to list per side of a per-turn detail block (full set in --json). */
+const SHADOW_DIFF_SLUG_CAP = 12;
+
+/** Format an epoch-ms timestamp as local `YYYY-MM-DD HH:MM:SS`. */
+function fmtTime(ms: number): string {
+  const d = new Date(ms);
+  const p = (n: number): string => String(n).padStart(2, "0");
+  return (
+    `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ` +
+    `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`
+  );
+}
+
+/** Render a lane/slug tally as `key: n` pairs, count-descending. */
+function renderTally(tally: Record<string, number>): string {
+  const entries = Object.entries(tally).sort(
+    (a, b) => b[1] - a[1] || a[0].localeCompare(b[0]),
+  );
+  if (entries.length === 0) return "none";
+  return entries.map(([k, v]) => `${k}: ${v}`).join("   ");
+}
+
+/** Render a capped slug list with an overflow note. */
+function renderSlugList(slugs: readonly string[]): string {
+  if (slugs.length === 0) return "—";
+  const shown = slugs.slice(0, SHADOW_DIFF_SLUG_CAP).join(", ");
+  const extra = slugs.length - SHADOW_DIFF_SLUG_CAP;
+  return extra > 0 ? `${shown}  (+${extra} more)` : shown;
+}
+
+/** Render one paired turn's sizes + the v3-only / v2-only slug lists. */
+function renderShadowDiffTurn(turn: ShadowDiffTurn, lines: string[]): void {
+  const dt = `${turn.deltaMs >= 0 ? "+" : ""}${(turn.deltaMs / 1000).toFixed(1)}s`;
+  lines.push(
+    `  [${turn.conversationId.slice(0, 12)}] ${fmtTime(turn.shadowAt)}  Δ${dt}`,
+  );
+  lines.push(
+    `    v2=${turn.v2Count}  v3=${turn.v3Count}  overlap=${turn.overlap.length}` +
+      `  jaccard=${turn.jaccard.toFixed(2)}  (v2 cached: ${turn.v2CachedCount})`,
+  );
+  lines.push(
+    `    v3-only (${turn.v3Only.length}): ${renderSlugList(turn.v3Only)}`,
+  );
+  lines.push(
+    `    v2-only (${turn.v2Only.length}): ${renderSlugList(turn.v2Only)}`,
+  );
+}
+
+/**
+ * Render a {@link ShadowDiffResult}: the read window, the aggregate v2-vs-v3
+ * comparison, the v3 lane breakdowns (extra recall + recovered overlap), the
+ * most-dropped / most-added slug lists, and the capped per-turn detail.
+ */
+export function renderShadowDiff(result: ShadowDiffResult): string {
+  const { agg } = result;
+  const lines: string[] = [
+    "Memory v3 Shadow Diff",
+    "=====================",
+    `Window: ${result.shadowRows} shadow row(s), ${result.turnsCompared} paired, ` +
+      `${result.unpaired.length} unpaired   (tolerance ${result.toleranceMs / 1000}s)`,
+  ];
+
+  if (result.turnsCompared === 0) {
+    lines.push(
+      "",
+      "No paired turns. Either v3 shadow mode has not run (no v3_shadow rows),",
+      "or no v2 router row landed within tolerance of a shadow row. Enable",
+      "memory.v3.enabled + memory.v3.shadow and let a few turns accrue.",
+    );
+    if (result.unpaired.length > 0) {
+      lines.push("", `Unpaired shadow rows (${result.unpaired.length}):`);
+      for (const u of result.unpaired) {
+        lines.push(
+          `  [${u.conversationId.slice(0, 12)}] ${fmtTime(u.shadowAt)}  v3=${u.v3Count}`,
+        );
+      }
+    }
+    return lines.join("\n");
+  }
+
+  lines.push(
+    "",
+    `Aggregate (${result.turnsCompared} turns):`,
+    `  v2 picked (injected):  mean ${agg.meanV2.toFixed(1)}   total ${agg.totalOverlap + agg.totalV2Only}`,
+    `  v3 selected:           mean ${agg.meanV3.toFixed(1)}   total ${agg.totalOverlap + agg.totalV3Only}`,
+    `  overlap:               mean ${agg.meanOverlap.toFixed(1)}   total ${agg.totalOverlap}   (mean Jaccard ${agg.meanJaccard.toFixed(2)})`,
+    `  v3-only (v3 added):    total ${agg.totalV3Only}`,
+    `  v2-only (v3 dropped):  total ${agg.totalV2Only}`,
+    "",
+    "v3 extra recall by lane (v3-only):",
+    `  ${renderTally(agg.v3OnlyByLane)}`,
+    "",
+    "overlap recovered by lane:",
+    `  ${renderTally(agg.overlapByLane)}`,
+  );
+
+  if (agg.v2OnlyTop.length > 0) {
+    lines.push("", "Most-dropped v2 pages (v2-only):");
+    for (const { slug, count } of agg.v2OnlyTop) {
+      lines.push(`  ${count}×  ${slug}`);
+    }
+  }
+  if (agg.v3OnlyTop.length > 0) {
+    lines.push("", "Most-frequent v3 extras (v3-only):");
+    for (const { slug, count } of agg.v3OnlyTop) {
+      lines.push(`  ${count}×  ${slug}`);
+    }
+  }
+
+  lines.push("", `Per-turn (newest first, showing ${result.turns.length}):`);
+  for (const turn of result.turns) {
+    lines.push("");
+    renderShadowDiffTurn(turn, lines);
+  }
+
+  if (result.unpaired.length > 0) {
+    lines.push("", `Unpaired shadow rows (${result.unpaired.length}):`);
+    for (const u of result.unpaired) {
+      lines.push(
+        `  [${u.conversationId.slice(0, 12)}] ${fmtTime(u.shadowAt)}  v3=${u.v3Count}`,
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
 // ── LLM-call capture ────────────────────────────────────────────────────────
 
 type CapturedMessage = LlmCallRecord["request"]["messages"][number];
@@ -342,3 +474,18 @@ export function renderLlmCalls(
   }
   return lines.join("\n");
 }
+
+/**
+ * Render a {@link SeedCoretrievalResult} into a one-block summary of the seeding
+ * run: how many router turns were scanned and how many nodes/edges were written.
+ */
+export function renderSeedEdges(result: SeedCoretrievalResult): string {
+  return [
+    "Memory v3 Co-Retrieval Edge Seed",
+    "================================",
+    `Router turns scanned: ${result.turnsScanned}`,
+    `Nodes (sources):      ${result.nodes}`,
+    `Edges written:        ${result.edgesWritten}`,
+    `Avg out-degree:       ${result.avgDegree.toFixed(1)}`,
+  ].join("\n");
+}