@vellumai/assistant 0.8.3 → 0.8.5

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

@@ -0,0 +1,344 @@
+/**
+ * Text rendering for `assistant memory v3 validate` and `... tree`.
+ *
+ * Both functions are pure presentation: they take the daemon route's response
+ * shape and return a terminal-ready string. They live CLI-side (mirroring
+ * `memory-v2-compare-render.ts`) and import only the response *types* from the
+ * daemon route — `cli/no-daemon-internals` permits type-only imports but
+ * forbids pulling in daemon runtime modules.
+ */
+
+import type {
+  DescentPass,
+  LlmCallRecord,
+  MemoryV3SimulateResult,
+  MemoryV3TreeResult,
+  MemoryV3ValidateResult,
+} from "../../runtime/routes/memory-v3-routes.js";
+
+/**
+ * Render a {@link MemoryV3ValidateResult} into a counts summary plus the
+ * offending ids for each non-empty category. Categories with zero entries
+ * print `none` so a clean tree reads at a glance.
+ */
+export function renderValidationReport(report: MemoryV3ValidateResult): string {
+  const lines: string[] = [
+    "Memory v3 Tree Validation",
+    "=========================",
+    `Dangling child refs: ${report.danglingChildRefCount || "none"}`,
+  ];
+  for (const d of report.danglingChildRefs) {
+    lines.push(`  - ${d.node} → ${d.kind}:${d.ref}`);
+  }
+
+  lines.push(`Orphan pages: ${report.orphanPageCount || "none"}`);
+  for (const slug of report.orphanPages) {
+    lines.push(`  - ${slug}`);
+  }
+
+  lines.push(`Cycles: ${report.cycleCount || "none"}`);
+  for (const c of report.cycles) {
+    lines.push(`  - ${c.from} → ${c.to}`);
+  }
+
+  lines.push(`Stale index: ${report.staleIndexCount || "none"}`);
+  for (const s of report.staleIndex) {
+    lines.push(`  - ${s.node} (older than child ${s.child})`);
+  }
+
+  lines.push(
+    `Unknown edge targets: ${report.unknownEdgeTargetCount || "none"}`,
+  );
+  for (const e of report.unknownEdgeTargets) {
+    lines.push(`  - ${e.from} → ${e.to}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Whether the validation report has any defect in any category. The CLI uses
+ * this to set a non-zero exit code so `validate` is scriptable as a check.
+ */
+export function reportHasDefects(report: MemoryV3ValidateResult): boolean {
+  return (
+    report.danglingChildRefCount > 0 ||
+    report.orphanPageCount > 0 ||
+    report.cycleCount > 0 ||
+    report.staleIndexCount > 0 ||
+    report.unknownEdgeTargetCount > 0
+  );
+}
+
+/**
+ * Render a {@link MemoryV3TreeResult} as an indented tree rooted at `view.root`,
+ * descending `node:` children depth-first. A node reached more than once
+ * (shared DAG sub-node) is printed once with a `(↑ …)` re-entry marker rather
+ * than re-expanded, which also bounds output when the structure contains a
+ * cycle. `page:` children are printed as leaves under their parent node.
+ */
+export function renderTree(view: MemoryV3TreeResult): string {
+  const childrenById = new Map<string, MemoryV3TreeResult["nodes"][number]>();
+  for (const node of view.nodes) {
+    childrenById.set(node.id, node);
+  }
+
+  const lines: string[] = [];
+  const expanded = new Set<string>();
+
+  const walk = (nodeId: string, depth: number): void => {
+    const indent = "  ".repeat(depth);
+    const node = childrenById.get(nodeId);
+
+    if (!node) {
+      lines.push(`${indent}node:${nodeId} (missing)`);
+      return;
+    }
+
+    if (expanded.has(nodeId)) {
+      // Shared DAG sub-node (or a cycle's back-edge): print the reference but
+      // do not re-expand, so output stays finite and the re-entry is visible.
+      lines.push(`${indent}node:${nodeId} (↑ already shown)`);
+      return;
+    }
+    expanded.add(nodeId);
+    lines.push(`${indent}node:${nodeId}`);
+
+    for (const child of node.children) {
+      if (child.kind === "page") {
+        lines.push(`${"  ".repeat(depth + 1)}page:${child.ref}`);
+      } else {
+        walk(child.ref, depth + 1);
+      }
+    }
+  };
+
+  walk(view.root, 0);
+
+  if (lines.length === 0) {
+    lines.push("(empty tree)");
+  }
+
+  // Surface nodes that exist on disk but were never reached from the root —
+  // they would otherwise be invisible in a root-anchored print.
+  const unreached = view.nodes
+    .map((n) => n.id)
+    .filter((id) => !expanded.has(id))
+    .sort();
+  if (unreached.length > 0) {
+    lines.push("", `Unreachable nodes (${unreached.length}):`);
+    for (const id of unreached) {
+      lines.push(`  - node:${id}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/** Canonical print order for the loop's provenance lanes. */
+const SIMULATE_LANE_ORDER = ["hot", "sparse", "dense", "tree", "edge"] as const;
+
+/** Render the effective lane toggles as a one-line `on` / restricted summary. */
+function renderEffectiveLanes(
+  lanes: MemoryV3SimulateResult["effectiveConfig"]["lanes"],
+): string {
+  const on = Object.entries(lanes)
+    .filter(([, enabled]) => enabled)
+    .map(([name]) => name);
+  const off = Object.entries(lanes)
+    .filter(([, enabled]) => !enabled)
+    .map(([name]) => name);
+  if (off.length === 0) return on.join(", ");
+  return `${on.join(", ")}  (off: ${off.join(", ")})`;
+}
+
+/** Render one pass's scout / tree / edge / gate breakdown into `lines`. */
+function renderPass(pass: DescentPass, lines: string[]): void {
+  lines.push(`Pass ${pass.passNumber}`);
+
+  if (pass.scouts && pass.scouts.length > 0) {
+    const summary = pass.scouts
+      .map((s) => `${s.lane}=${s.slugs.length}`)
+      .join("  ");
+    lines.push(`  scouts: ${summary}`);
+  }
+
+  if (pass.treeLevels && pass.treeLevels.length > 0) {
+    lines.push(`  tree: ${pass.treeLevels.length} level(s)`);
+    for (const level of pass.treeLevels) {
+      const node = level.node === "" ? "[root]" : level.node;
+      lines.push(
+        `    ${node}: considered ${level.considered.length}, descended ${level.descended.length}, skipped ${level.skipped.length}`,
+      );
+      if (level.descended.length > 0) {
+        lines.push(`      → ${level.descended.join(", ")}`);
+      }
+      if (level.reasoning.trim().length > 0) {
+        lines.push(`      reason: ${level.reasoning.trim()}`);
+      }
+    }
+  }
+
+  if (pass.edgeExpansions && pass.edgeExpansions.length > 0) {
+    const pulled = pass.edgeExpansions.reduce((n, e) => n + e.pulled.length, 0);
+    lines.push(
+      `  edges: ${pass.edgeExpansions.length} seed(s) expanded, ${pulled} pulled`,
+    );
+  }
+
+  if (pass.gate) {
+    lines.push(`  gate: ${pass.gate.decision}`);
+    for (const q of pass.gate.questions ?? []) {
+      lines.push(`    ? ${q}`);
+    }
+  }
+}
+
+/**
+ * Render a {@link MemoryV3SimulateResult} into a query echo, effective config,
+ * per-pass descent breakdown, and the final selection grouped by provenance
+ * lane (in fanout order). Mirrors the grouped layout of `memory v2 simulate`.
+ */
+export function renderSimulation(result: MemoryV3SimulateResult): string {
+  const lines: string[] = [
+    "Memory v3 Retrieval Simulation",
+    "==============================",
+    `Query: ${JSON.stringify(result.query)}`,
+    "",
+    "Config (effective):",
+    `  passCap: ${result.effectiveConfig.passCap}`,
+    `  lanes: ${renderEffectiveLanes(result.effectiveConfig.lanes)}`,
+    "",
+  ];
+
+  const passes = result.trace.passes;
+  lines.push(`Passes: ${passes.length || "none"}`);
+  for (const pass of passes) {
+    lines.push("");
+    renderPass(pass, lines);
+  }
+  lines.push("");
+
+  lines.push(`Selected: ${result.selectedSlugs.length} page(s)`);
+  const grouped = new Map<string, string[]>();
+  for (const slug of result.selectedSlugs) {
+    const lane = result.sourceBySlug[slug] ?? "unknown";
+    const bucket = grouped.get(lane) ?? [];
+    bucket.push(slug);
+    grouped.set(lane, bucket);
+  }
+  const laneRank = (lane: string): number => {
+    const i = SIMULATE_LANE_ORDER.indexOf(
+      lane as (typeof SIMULATE_LANE_ORDER)[number],
+    );
+    return i === -1 ? SIMULATE_LANE_ORDER.length : i;
+  };
+  const lanes = [...grouped.keys()].sort((a, b) => laneRank(a) - laneRank(b));
+  for (const lane of lanes) {
+    const slugs = grouped.get(lane)!;
+    lines.push(`  ${lane} (${slugs.length})`);
+    for (const slug of slugs) {
+      lines.push(`    - ${slug}`);
+    }
+  }
+
+  if (result.cost.ms !== undefined) {
+    lines.push("", `Cost: ${result.cost.ms} ms`);
+  }
+  if (result.failureReason) {
+    lines.push(`Failure: ${result.failureReason}`);
+  }
+
+  return lines.join("\n");
+}
+
+// ── LLM-call capture ────────────────────────────────────────────────────────
+
+type CapturedMessage = LlmCallRecord["request"]["messages"][number];
+type CapturedBlock = LlmCallRecord["response"]["content"][number];
+
+/** Concatenate the text blocks of a message (non-text blocks are ignored). */
+function messageText(message: CapturedMessage): string {
+  return message.content
+    .filter(
+      (b): b is Extract<CapturedBlock, { type: "text" }> => b.type === "text",
+    )
+    .map((b) => b.text)
+    .join("\n");
+}
+
+/** The forced-tool block from a response, if the model returned one. */
+function toolUseOf(
+  call: LlmCallRecord,
+): Extract<CapturedBlock, { type: "tool_use" }> | undefined {
+  return call.response.content.find(
+    (b): b is Extract<CapturedBlock, { type: "tool_use" }> =>
+      b.type === "tool_use",
+  );
+}
+
+function truncate(s: string, max: number): string {
+  const oneLine = s.replace(/\s+/g, " ").trim();
+  return oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine;
+}
+
+function indent(s: string, by = "    "): string {
+  return s
+    .split("\n")
+    .map((line) => by + line)
+    .join("\n");
+}
+
+/**
+ * Render the captured v3 LLM calls. Compact (default): one line per call —
+ * pass/lane/node, input size, round-trip ms, and the forced-tool summary. Full
+ * (`--show-llm`): the system prompt, every message, the tool names, and the
+ * tool_use input for each call. Grouped in call order (which is pass order).
+ */
+export function renderLlmCalls(
+  calls: readonly LlmCallRecord[],
+  opts: { full: boolean },
+): string {
+  if (calls.length === 0) return "LLM calls: none";
+
+  const lines: string[] = [`LLM calls (${calls.length}):`];
+  for (const call of calls) {
+    const label =
+      `pass${call.pass} · ${call.lane}` +
+      (call.node ? ` · node=${call.node}` : "");
+    const inputChars =
+      call.request.systemPrompt.length +
+      call.request.messages.reduce((n, m) => n + messageText(m).length, 0);
+    const tool = toolUseOf(call);
+    const toolSummary = tool
+      ? `${tool.name}(${truncate(JSON.stringify(tool.input), 80)})`
+      : `no tool_use (stop=${call.response.stopReason})`;
+
+    if (!opts.full) {
+      lines.push(
+        `  ${label} · in ${inputChars}c · ${call.ms}ms · ${truncate(toolSummary, 100)}`,
+      );
+      continue;
+    }
+
+    lines.push("", `── ${label}  (${call.callSite}, ${call.ms}ms) ──`);
+    lines.push("system:", indent(call.request.systemPrompt));
+    lines.push("messages:");
+    for (const message of call.request.messages) {
+      lines.push(
+        indent(`[${message.role}]`),
+        indent(messageText(message), "      "),
+      );
+    }
+    lines.push(`tools: ${call.request.tools.map((t) => t.name).join(", ")}`);
+    lines.push("output:");
+    lines.push(
+      indent(
+        tool
+          ? `${tool.name} ${JSON.stringify(tool.input, null, 2)}`
+          : `(no tool_use, stop=${call.response.stopReason})`,
+      ),
+    );
+  }
+  return lines.join("\n");
+}

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

@@ -0,0 +1,316 @@
+/**
+ * `assistant memory v3` CLI subgroup.
+ *
+ * Operator-facing read-only inspection of the v3 memory tree — the DAG overlay
+ * the v2 → v3 data-migration hand-authors over the flat concept pages.
+ *
+ * Subcommands:
+ *
+ *   - `validate` — print a structural health report (dangling refs, orphan
+ *     pages, cycles, stale indexes, unknown edge targets). Exits non-zero when
+ *     any defect is found so it is scriptable as a check.
+ *   - `tree` — print the tree as an indented outline rooted at the tree root,
+ *     marking shared-DAG re-entries.
+ *   - `simulate` — dry-run the v3 retrieval loop against an ad-hoc query and
+ *     print the per-pass descent trace plus the lane-grouped selection.
+ *
+ * All are read-only: they mutate nothing. `validate`/`tree` run no LLM;
+ * `simulate` invokes the loop (filter + gate LLM calls) but persists nothing.
+ * `--json` emits the raw daemon payload for any subcommand.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { Command } from "commander";
+
+import { cliIpcCall } from "../../ipc/cli-client.js";
+import type {
+  MemoryV3SimulateResult,
+  MemoryV3TreeResult,
+  MemoryV3ValidateResult,
+} from "../../runtime/routes/memory-v3-routes.js";
+import { registerCommand } from "../lib/register-command.js";
+import { log } from "../logger.js";
+import {
+  renderLlmCalls,
+  renderSimulation,
+  renderTree,
+  renderValidationReport,
+  reportHasDefects,
+} from "./memory-v3-render.js";
+
+/** Valid lane names accepted by `--lanes` (matches memory.v3.lanes keys). */
+const V3_LANE_NAMES = ["hot", "sparse", "dense", "tree", "edges"] as const;
+
+export function registerMemoryV3Command(program: Command): void {
+  // Reuse an existing `memory` parent if a sibling registrar (e.g. v2)
+  // attached it first; otherwise create one. Keeps registration order between
+  // sibling memory registrars unconstrained.
+  const memory =
+    program.commands.find((c) => c.name() === "memory") ??
+    program
+      .command("memory")
+      .description("Manage the memory subsystem (concept-page model)");
+
+  registerCommand(memory, {
+    name: "v3",
+    transport: "ipc",
+    description: "Memory v3 subsystem operations (tree-DAG overlay)",
+    build: (v3) => {
+      v3.addHelpText(
+        "after",
+        `
+The v3 memory subsystem layers a hand-authored DAG of tree nodes over the
+flat v2 concept pages. Each node lives under /workspace/memory/tree/ and
+its frontmatter 'children' list references sub-nodes (node:<id>) and leaf
+concept pages (page:<slug>). The structure is authored by the v2 → v3
+data-migration, so these subcommands are read-only inspection only — they
+mutate nothing and run no LLM.
+
+Examples:
+  $ assistant memory v3 validate
+  $ assistant memory v3 tree
+  $ assistant memory v3 tree --json | jq '.nodes | length'
+  $ assistant memory v3 simulate -q "what should we ship next"`,
+      );
+
+      // ── validate ──────────────────────────────────────────────────────────
+
+      v3.command("validate")
+        .description(
+          "Print a structural health report of the v3 tree (read-only)",
+        )
+        .option("--json", "Emit raw JSON instead of a formatted report")
+        .addHelpText(
+          "after",
+          `
+Walks the hand-authored v3 tree DAG and reports:
+  - Dangling child refs (node:/page: targets that do not exist)
+  - Orphan pages (concept pages not reachable from the tree root)
+  - Cycles (back-edges in the node:/node: adjacency)
+  - Stale indexes (a node older than a child it composes)
+  - Unknown edge targets (page edges: pointing at a missing slug)
+
+Read-only — mutates nothing. Exits non-zero if any defect is reported, so it
+is usable as a pre-flight check while the v2 → v3 migration is in flight.
+
+Examples:
+  $ assistant memory v3 validate
+  $ assistant memory v3 validate --json | jq '.orphanPageCount'`,
+        )
+        .action(async (opts: { json?: boolean }) => {
+          const result = await cliIpcCall<MemoryV3ValidateResult>(
+            "memory_v3_validate",
+            { body: {} },
+          );
+
+          if (!result.ok) {
+            log.error(result.error ?? "Failed to validate memory v3 tree");
+            process.exitCode = 1;
+            return;
+          }
+
+          const report = result.result!;
+
+          if (opts.json === true) {
+            log.info(JSON.stringify(report, null, 2));
+          } else {
+            log.info(renderValidationReport(report));
+          }
+
+          if (reportHasDefects(report)) {
+            process.exitCode = 1;
+          }
+        });
+
+      // ── tree ──────────────────────────────────────────────────────────────
+
+      v3.command("tree")
+        .description(
+          "Print the v3 tree as an indented outline from the root (read-only)",
+        )
+        .option("--json", "Emit raw JSON instead of a formatted tree")
+        .addHelpText(
+          "after",
+          `
+Descends the v3 tree depth-first from its root node, printing one line per
+node:/page: ref with indentation by depth. A node reached more than once
+(shared DAG sub-node or a cycle back-edge) is printed once with a re-entry
+marker rather than re-expanded, so output is finite. Nodes that exist on disk
+but are unreachable from the root are listed separately.
+
+Read-only — mutates nothing.
+
+Examples:
+  $ assistant memory v3 tree
+  $ assistant memory v3 tree --json | jq '.root'`,
+        )
+        .action(async (opts: { json?: boolean }) => {
+          const result = await cliIpcCall<MemoryV3TreeResult>(
+            "memory_v3_tree",
+            {
+              body: {},
+            },
+          );
+
+          if (!result.ok) {
+            log.error(result.error ?? "Failed to read memory v3 tree");
+            process.exitCode = 1;
+            return;
+          }
+
+          const view = result.result!;
+
+          if (opts.json === true) {
+            log.info(JSON.stringify(view, null, 2));
+            return;
+          }
+
+          log.info(renderTree(view));
+        });
+
+      // ── simulate ────────────────────────────────────────────────────────────
+
+      v3.command("simulate")
+        .description(
+          "Dry-run the v3 retrieval loop against an ad-hoc query (read-only)",
+        )
+        .requiredOption(
+          "-q, --query <text>",
+          "User query to run a single synthetic retrieval turn against",
+        )
+        .option(
+          "--pass-cap <n>",
+          "Override memory.v3.passCap for this run (positive integer)",
+        )
+        .option(
+          "--lanes <list>",
+          `Restrict to a comma-separated allowlist of lanes (others off): ${V3_LANE_NAMES.join(", ")}`,
+        )
+        .option("--json", "Emit raw JSON instead of a formatted report")
+        .option(
+          "--show-llm",
+          "Print the full input + output of every v3 LLM call (filter / descender / gate)",
+        )
+        .option(
+          "--dump-llm <dir>",
+          "Write one JSON file per v3 LLM call into <dir> (full request + raw response)",
+        )
+        .addHelpText(
+          "after",
+          `
+Runs the v3 multi-lane bounded-descent loop read-only against the live page
+index + tree DAG, building a single synthetic turn from the query plus the live
+NOW context. Prints the per-pass descent trace (scouts / tree levels / edge
+expansions / gate verdict) and the final selection grouped by provenance lane.
+
+The loop is invoked directly — it does NOT require memory.v3.enabled or
+memory.v3.shadow, so you can probe v3 retrieval before the flags flip. Writes
+nothing (co-activation persistence is forced off), but each pass still spends
+the loop's dense-filter + gate LLM calls, so pass-cap is the cost knob.
+
+Examples:
+  $ assistant memory v3 simulate -q "what should we ship next"
+  $ assistant memory v3 simulate -q "..." --lanes tree,edges
+  $ assistant memory v3 simulate -q "..." --pass-cap 1 --json | jq '.selectedSlugs'
+  $ assistant memory v3 simulate -q "..." --show-llm
+  $ assistant memory v3 simulate -q "..." --dump-llm /tmp/v3-calls`,
+        )
+        .action(
+          async (opts: {
+            query: string;
+            passCap?: string;
+            lanes?: string;
+            json?: boolean;
+            showLlm?: boolean;
+            dumpLlm?: string;
+          }) => {
+            let passCap: number | undefined;
+            if (opts.passCap !== undefined) {
+              const parsed = Number(opts.passCap);
+              if (!Number.isInteger(parsed) || parsed < 1) {
+                log.error(
+                  `--pass-cap must be a positive integer (got "${opts.passCap}")`,
+                );
+                process.exitCode = 1;
+                return;
+              }
+              passCap = parsed;
+            }
+
+            let lanes: string[] | undefined;
+            if (opts.lanes !== undefined) {
+              const requested = opts.lanes
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+              const invalid = requested.filter(
+                (l) =>
+                  !V3_LANE_NAMES.includes(l as (typeof V3_LANE_NAMES)[number]),
+              );
+              if (invalid.length > 0) {
+                log.error(
+                  `--lanes contains unknown lane(s): ${invalid.join(", ")}. Valid: ${V3_LANE_NAMES.join(", ")}`,
+                );
+                process.exitCode = 1;
+                return;
+              }
+              if (requested.length === 0) {
+                log.error("--lanes must list at least one lane");
+                process.exitCode = 1;
+                return;
+              }
+              lanes = requested;
+            }
+
+            const result = await cliIpcCall<MemoryV3SimulateResult>(
+              "memory_v3_simulate",
+              {
+                body: {
+                  query: opts.query,
+                  ...(passCap !== undefined ? { passCap } : {}),
+                  ...(lanes !== undefined ? { lanes } : {}),
+                },
+              },
+            );
+
+            if (!result.ok) {
+              log.error(result.error ?? "Failed to simulate v3 retrieval");
+              process.exitCode = 1;
+              return;
+            }
+
+            const payload = result.result!;
+            if (opts.json === true) {
+              log.info(JSON.stringify(payload, null, 2));
+              return;
+            }
+            log.info(renderSimulation(payload));
+
+            log.info("");
+            log.info(
+              renderLlmCalls(payload.llmCalls, { full: opts.showLlm === true }),
+            );
+
+            if (opts.dumpLlm !== undefined) {
+              mkdirSync(opts.dumpLlm, { recursive: true });
+              for (const call of payload.llmCalls) {
+                const nodePart = call.node
+                  ? `-${call.node.replace(/\//g, "_")}`
+                  : "";
+                const file = join(
+                  opts.dumpLlm,
+                  `pass${call.pass}-${call.lane}${nodePart}.json`,
+                );
+                writeFileSync(file, JSON.stringify(call, null, 2));
+              }
+              log.info(
+                `\nWrote ${payload.llmCalls.length} LLM-call file(s) to ${opts.dumpLlm}`,
+              );
+            }
+          },
+        );
+    },
+  });
+}