@jaguilar87/gaia 5.1.0 → 5.1.1

package/bin/cli/query.py

@@ -105,6 +105,57 @@ def _render_grouped_count(rows: list[dict], group_by: str | None) -> None:
         print(f"{(str(r.get(group_by) or '')):<{key_w}}  {r['count']}")
 
 
+def _fmt_int(n) -> str:
+    return "-" if n is None else f"{int(n):,}"
+
+
+def _render_metrics_agg(rows: list[dict], group_by: str | None) -> None:
+    """Render aggregate_metrics() output: avg compliance + token sums per group."""
+    if not rows:
+        print("(no results)")
+        return
+    key = group_by or "group"
+    key_vals = [str(r.get(group_by) or "(all)") if group_by else "(all)" for r in rows]
+    key_w = max(len(key.upper()), max(len(v) for v in key_vals))
+    header = (f"{key.upper():<{key_w}}  {'COUNT':>6}  {'AVG_COMPL':>9}  "
+              f"{'AVG_MS':>8}  {'IN_TOK':>12}  {'OUT_TOK':>12}  {'CACHE_RD':>14}")
+    print(header)
+    print("-" * len(header))
+    for r, kv in zip(rows, key_vals):
+        avg_c = "-" if r.get("avg_compliance_score") is None else f"{r['avg_compliance_score']:.1f}"
+        avg_ms = _fmt_int(r.get("avg_duration_ms"))
+        print(
+            f"{kv:<{key_w}}  {r['count']:>6}  {avg_c:>9}  {avg_ms:>8}  "
+            f"{_fmt_int(r.get('input_tokens')):>12}  "
+            f"{_fmt_int(r.get('output_tokens_real')):>12}  "
+            f"{_fmt_int(r.get('cache_read_tokens')):>14}"
+        )
+
+
+def _render_metrics_rows(rows: list[dict]) -> None:
+    """Render per-episode --metrics rows (agent, compliance, tokens, model)."""
+    if not rows:
+        print("(no results)")
+        return
+    agent_w = max(len("AGENT"), max(len(r.get("agent") or "") for r in rows))
+    header = (f"{'TIMESTAMP':<19}  {'AGENT':<{agent_w}}  {'COMPL':>5}  "
+              f"{'GR':>2}  {'IN_TOK':>10}  {'OUT_REAL':>10}  MODEL")
+    print(header)
+    print("-" * len(header))
+    for r in rows:
+        raw = r.get("raw") or {}
+        ts = (r.get("timestamp") or "")[:19]
+        cs = raw.get("compliance_score")
+        cs_s = "-" if cs is None else str(cs)
+        grade = raw.get("compliance_grade") or "-"
+        print(
+            f"{ts:<19}  {(r.get('agent') or ''):<{agent_w}}  {cs_s:>5}  "
+            f"{grade:>2}  {_fmt_int(raw.get('input_tokens')):>10}  "
+            f"{_fmt_int(raw.get('output_tokens_real')):>10}  "
+            f"{raw.get('model_used') or '-'}"
+        )
+
+
 # ---------------------------------------------------------------------------
 # Entry point
 # ---------------------------------------------------------------------------
@@ -114,6 +165,7 @@ def cmd_query(args) -> int:
     from gaia.store.reader import (
         cross_surface_query,
         group_and_count,
+        aggregate_metrics,
         _extract_text_needle,
         _highlight_snippet,
         _row_text_for_snippet,
@@ -127,6 +179,12 @@ def cmd_query(args) -> int:
     group_by = getattr(args, "group_by", None)
     do_count = bool(getattr(args, "count", False))
     do_snippets = bool(getattr(args, "snippets", False))
+    do_metrics = bool(getattr(args, "metrics", False))
+
+    # --metrics projects context_metrics telemetry, which only lives on the
+    # episodes surface -- scope the query to it so the projection applies.
+    if do_metrics:
+        surface = "episodes"
 
     try:
         rows = cross_surface_query(
@@ -139,10 +197,32 @@ def cmd_query(args) -> int:
             agent=getattr(args, "agent", None),
             command_like=getattr(args, "command_like", None),
             failed=getattr(args, "failed", False),
+            metrics=do_metrics,
         )
     except ValueError as exc:
         return _err(str(exc), as_json=as_json)
 
+    # --metrics: project + optionally aggregate the per-turn telemetry.
+    if do_metrics:
+        if do_count or group_by:
+            try:
+                agg = aggregate_metrics(rows, group_by=group_by)
+            except ValueError as exc:
+                return _err(str(exc), as_json=as_json)
+            if as_json or fmt == "json":
+                print(json.dumps(agg, indent=2, default=str))
+                return 0
+            _render_metrics_agg(agg, group_by)
+            return 0
+        if as_json or fmt == "json":
+            print(json.dumps(rows, indent=2, default=str))
+            return 0
+        if fmt == "count":
+            print(len(rows))
+            return 0
+        _render_metrics_rows(rows)
+        return 0
+
     # --snippets: rewrite the summary field with highlighted fragments.
     # Applies only when there is a textual filter (command_like / type / agent).
     if do_snippets:
@@ -189,6 +269,8 @@ _QUERY_EPILOG = """\
 Examples:
   gaia query --since=24h --failed
   gaia query --since=7d --command-like='%git push%' --group-by=day
+  gaia query --metrics --since=7d --group-by=agent
+  gaia query --metrics --agent=developer --since=24h
 """
 
 
@@ -256,6 +338,13 @@ def register(subparsers) -> None:
         help="Replace summary with [bracketed] fragments around the textual "
              "filter. No-op without --command-like / --type / --agent.",
     )
+    p.add_argument(
+        "--metrics", action="store_true", default=False,
+        help="Project per-turn telemetry from episodes.context_metrics "
+             "(compliance_score, token counts, duration_ms, tool/api calls, "
+             "model). Forces --surface=episodes. Combine with --group-by / "
+             "--count for avg-compliance + token-sum rollups per agent/day/type.",
+    )
     p.add_argument(
         "--format", default="table",
         choices=("table", "json", "count"),

package/bin/cli/scan.py

@@ -68,9 +68,35 @@ def _render_human(report, *, dry_run: bool) -> None:
         print(f"{prefix}projects:")
         for p in report.projects:
             applied = "applied" if p["applied"] else ("would-apply" if dry_run else "not-applied")
+            # Show the workspace -> proyecto (container) -> repo hierarchy plus
+            # the repo's own absolute path (M2-T4/T5). ``project`` (the DB
+            # storage slot) is shown only when it differs from the proyecto
+            # (i.e. when M1 collision-disambiguation renamed the slot).
+            container = p.get("container", p["project"])
+            slot = p["project"]
+            slot_note = f" slot={slot}" if slot != container else ""
             print(
-                f"  - repo={p['repo']} project={p['project']} "
-                f"workspace={p['workspace']} [{applied}]"
+                f"  - workspace={p['workspace']} project={container} "
+                f"repo={p['repo']}{slot_note} path={p.get('path')} [{applied}]"
+            )
+            # M3/T8 (AC-6): the stack fingerprint (facet rows) for this repo.
+            facets = p.get("facets") or []
+            if facets:
+                summary = ", ".join(
+                    f"{f['scope']}:{f['key']}"
+                    + (f"={f['value']}" if f.get("value") else "")
+                    for f in facets
+                )
+                print(f"      facets: {summary}")
+
+    if report.warnings:
+        # M2-T6 (AC-5): would-be collisions are surfaced explicitly, never
+        # silently merged/renamed.
+        print(f"{prefix}WARNING -- repo collisions (would-be silent data loss):")
+        for w in report.warnings:
+            print(
+                f"  ! repo={w['repo']} requested_project={w['requested_project']} "
+                f"-> assigned={w['assigned_project']} path={w.get('path')}"
             )
 
     if report.ambiguities:
@@ -83,6 +109,46 @@ def _render_human(report, *, dry_run: bool) -> None:
         for e in report.errors:
             print(f"  - repo={e['repo']} --workspace={e['W']}: {e['suggestion']}")
 
+    # SV2: cross-DB detection blocks (alerts only -- the human adjudicates).
+    if report.move_candidates:
+        print(f"{prefix}MOVE CANDIDATES (remote match, human adjudicates):")
+        for m in report.move_candidates:
+            src, dst = m["from"], m["to"]
+            print(
+                f"  ~ {src['workspace']}/{src['project']} ({src['path']}) -> "
+                f"{dst['workspace']}/{dst['project']} ({dst['path']}) "
+                f"remote={m['remote']} confidence={m['confidence']}"
+            )
+
+    if report.vanished:
+        print(f"{prefix}VANISHED:")
+        for v in report.vanished:
+            since = v["missing_since"] if v["missing_since"] else ("pending" if dry_run else None)
+            print(
+                f"  - {v['workspace']}/{v['project']} path={v['path']} "
+                f"remote={v['remote']} missing_since={since}"
+            )
+
+    if report.rename_candidates:
+        print(f"{prefix}RENAME CANDIDATES (folder basename != stored name):")
+        for r in report.rename_candidates:
+            print(
+                f"  ? {r['workspace']}/{r['project']} path={r['path']} "
+                f"expected_name={r['expected_name']}"
+            )
+
+    if report.orphaned_autored:
+        print(f"{prefix}ORPHANED CONTEXT (vanished project carried authored content):")
+        for o in report.orphaned_autored:
+            print(
+                f"  ! {o['workspace']}/{o['project']}: {o['description']!r} "
+                f"(workspace holds {o['memory_count']} memory note(s), "
+                f"{o['brief_count']} open brief(s))"
+            )
+
+    if report.diff:
+        print(f"{prefix}diff               : {report.diff}")
+
     if not dry_run:
         print(f"{prefix}marked_missing     : {report.marked_missing}")
 

package/bin/cli/uninstall.py

@@ -311,11 +311,15 @@ def _print_human(result: dict, *, preuninstall: bool, dry_run: bool) -> None:
     for rel in symlinks.get("removed", []):
         verb = "Would remove symlink" if dry_run else "Removed symlink"
         print(f"  {verb}: {rel}")
-    for action in retention:
-        verb = "Would prune" if dry_run else "Pruned"
-        path = action.get("path", "?")
-        label = action.get("label", "")
-        print(f"  {verb}: {path} ({label})")
+    if retention:
+        # These are routine log-hygiene prunes applied on the way out, NOT
+        # part of the uninstall teardown -- the header keeps that distinct.
+        print("\n  Retention policy (routine log hygiene, not part of uninstall):")
+        for action in retention:
+            verb = "Would prune" if dry_run else "Pruned"
+            path = action.get("path", "?")
+            label = action.get("label", "")
+            print(f"    {verb}: {path} ({label})")
 
     print()
     snapshot = result.get("snapshot") or {}

package/bin/pre-publish-validate.js

@@ -208,6 +208,11 @@ class PrePublishValidator {
   validateNodeModules() {
     this.log('Step 4: Validating node_modules installation...', 'info');
 
+    if (this.dryRun) {
+      this.log('[DRY RUN] skipping node_modules version validation', 'info');
+      return;
+    }
+
     if (!fs.existsSync(NODE_MODULES_INSTALL)) {
       this.log(`⚠️  ${PKG_NAME} not found in node_modules, installing...`, 'warning');
       this.reinstallNodeModules();
@@ -254,7 +259,7 @@ class PrePublishValidator {
 
     const criticalFiles = [
       'package.json',
-      'bin/gaia-scan',
+      'bin/cli/scan.py',
       'tools/context/context_provider.py',
       'hooks/pre_tool_use.py',
     ];
@@ -527,9 +532,7 @@ class PrePublishValidator {
     try {
       // Test 1: Validate JSON files
       this.log('Test 1: Validating JSON configuration files...', 'info');
-      const jsonFiles = [
-        'config/clarification_rules.json'
-      ];
+      const jsonFiles = [];
 
       jsonFiles.forEach(file => {
         const filePath = path.join(baseDir, file);

package/gaia/project.py

@@ -1,13 +1,20 @@
 """
 gaia.project -- Workspace identity model and consolidate operations.
 
-Workspace identity is derived from the git remote URL, normalized to the
-canonical form ``host/owner/repo`` (lowercase, no protocol, no .git suffix).
+Workspace identity (``current()``) is PATH-based (M2-T7, AC-9): it is derived
+from the repository's location on disk, not from the git remote, so it is
+stable regardless of remote state and converges across vantage points (root,
+subdirectory, linked worktree of the same repo all resolve identically).
 
-Three-level fallback:
-  1. Git remote URL normalized to canonical form (primary)
-  2. Directory name in lowercase (when no git remote)
-  3. Literal ``"global"`` (when neither git remote nor identifiable directory)
+Three-level resolution:
+  1. Git repo -> basename of the repository ROOT (via git-common-dir)
+  2. Directory name in lowercase (when not a git repo)
+  3. Literal ``"global"`` (when neither a git repo nor an identifiable name)
+
+The remote-derived canonical identity (``host/owner/repo``) is still produced
+by :func:`_normalize_remote`, but it is captured separately in the
+``workspaces.identity`` column by the store writer, which reads the remote
+directly -- it no longer flows through ``current()``.
 
 Patterns inspired by engram (https://github.com/koaning/engram), MIT License.
 No runtime dependency on engram.
@@ -142,12 +149,28 @@ def git_common_dir(cwd: Path | str | None = None) -> str | None:
 
 
 def current(cwd: Path | str | None = None) -> str:
-    """Return the workspace identity for the given directory.
-
-    Three-level fallback:
-      1. Git remote URL normalized to canonical form (``host/owner/repo``)
-      2. Directory basename in lowercase
-      3. Literal ``"global"`` (no git, no identifiable directory)
+    """Return the workspace identity for the given directory -- PATH-BASED.
+
+    Resolution is PATH-first (M2-T7, AC-9), NOT git-remote-first. The identity
+    is derived from the repository's own location on disk, so it is stable
+    regardless of remote state and converges across vantage points:
+
+      1. Git repo -> the basename of the REPOSITORY ROOT, resolved via
+         ``git rev-parse --git-common-dir`` (:func:`git_common_dir`). Because
+         the common dir is identical from the repo root, any nested
+         subdirectory, and any linked worktree, two different working-directory
+         paths of the SAME repo always resolve to the SAME identity -- and the
+         git remote never decides the identity ahead of the path.
+      2. Not a git repo -> the basename of ``cwd`` in lowercase.
+      3. Literal ``"global"`` (no git, no identifiable directory name).
+
+    The git remote URL is deliberately NOT consulted here. The remote-derived
+    canonical identity still exists, but it is captured separately in the
+    ``workspaces.identity`` column by the store writer
+    (``gaia/store/writer.py::_resolve_identity``), which reads the remote
+    directly -- so ``current()`` answering "which workspace am I in" stays
+    coherent with the path-anchored scan model (workspace -> proyecto -> repo)
+    while the remote identity is preserved where it belongs.
 
     Args:
         cwd: Directory to resolve identity for. Defaults to ``Path.cwd()``.
@@ -162,14 +185,20 @@ def current(cwd: Path | str | None = None) -> str:
         # If resolve fails (broken symlink, permission), fall back to global
         return "global"
 
-    # Level 1: git remote URL
-    remote = _git_remote_origin(target)
-    if remote:
-        normalized = _normalize_remote(remote)
-        if normalized:
-            return normalized
-
-    # Level 2: directory basename
+    # Level 1 (PATH-based): repository root basename, vantage-independent.
+    # git_common_dir collapses root / subdir / worktree of the same repo to
+    # one path, so the identity does not diverge across vantage points and
+    # does not depend on the remote.
+    common = git_common_dir(target)
+    if common:
+        # The common dir (e.g. ``/x/repo/.git``) sits inside the repo root;
+        # its parent is the repository root directory.
+        repo_root = Path(common).parent
+        name = repo_root.name.lower().strip()
+        if name:
+            return name
+
+    # Level 2: directory basename (not a git repo).
     name = target.name.lower().strip()
     if name:
         return name

package/gaia/store/reader.py

@@ -130,6 +130,12 @@ def _query_memory(
         where.append("type = ?")
         params.append(type_filter)
 
+    # scan-v2 SV3: tombstoned rows (deleted_at non-NULL) are soft-deleted and
+    # must never surface in a query. delete_memory() stamps deleted_at instead
+    # of physically removing the row, so this filter is what keeps a tombstone
+    # invisible to `gaia query` / cross_surface_query.
+    where.append("deleted_at IS NULL")
+
     sql = (
         "SELECT workspace, name, type, description, body, origin_session_id, "
         "updated_at "
@@ -164,6 +170,49 @@ def _query_memory(
     return out
 
 
+# Metric fields projected out of episodes.context_metrics when metrics=True.
+# The workflow recorder nests these under the "metrics" key of the JSON blob
+# (T4 episodic-workflow-to-db); a few older migrated rows store them at the
+# top level, so each extraction COALESCEs the nested path with the flat one.
+# json1 is compiled into SQLite by default -- no schema migration required.
+_METRIC_JSON_FIELDS = (
+    # (output column, json leaf path under $.metrics / $)
+    ("compliance_score", "compliance_score.total"),
+    ("compliance_grade", "compliance_score.grade"),
+    ("input_tokens", "input_tokens"),
+    ("cache_creation_tokens", "cache_creation_tokens"),
+    ("cache_read_tokens", "cache_read_tokens"),
+    ("output_tokens_real", "output_tokens_real"),
+    ("duration_ms", "duration_ms"),
+    ("tool_call_count", "tool_call_count"),
+    ("api_call_count", "api_call_count"),
+    ("model_used", "model_used"),
+)
+
+# Numeric metric fields summed by aggregate_metrics.
+_METRIC_SUM_FIELDS = (
+    "input_tokens",
+    "cache_creation_tokens",
+    "cache_read_tokens",
+    "output_tokens_real",
+    "tool_call_count",
+    "api_call_count",
+)
+
+
+def _metric_select_columns() -> str:
+    """Build the json_extract projection clause for --metrics queries."""
+    cols = []
+    for out_col, leaf in _METRIC_JSON_FIELDS:
+        cols.append(
+            f"COALESCE("
+            f"json_extract(context_metrics, '$.metrics.{leaf}'), "
+            f"json_extract(context_metrics, '$.{leaf}')"
+            f") AS {out_col}"
+        )
+    return ", ".join(cols)
+
+
 def _query_episodes(
     con: sqlite3.Connection,
     *,
@@ -174,6 +223,7 @@ def _query_episodes(
     agent_filter: str | None,
     failed: bool,
     limit: int,
+    metrics: bool = False,
 ) -> list[dict]:
     where = []
     params: list[Any] = []
@@ -198,12 +248,18 @@ def _query_episodes(
             "(plan_status IN ('BLOCKED', 'NEEDS_INPUT') "
             "OR (outcome IS NOT NULL AND outcome NOT IN ('success', '')))"
         )
+    if metrics:
+        # Only rows that actually carry a metrics blob can project fields.
+        where.append("context_metrics IS NOT NULL")
 
-    sql = (
-        "SELECT episode_id, workspace, timestamp, session_id, task_id, agent, "
-        "type, title, plan_status, outcome, exit_code, duration_seconds "
-        "FROM episodes"
+    base_cols = (
+        "episode_id, workspace, timestamp, session_id, task_id, agent, "
+        "type, title, plan_status, outcome, exit_code, duration_seconds"
     )
+    if metrics:
+        sql = f"SELECT {base_cols}, {_metric_select_columns()} FROM episodes"
+    else:
+        sql = f"SELECT {base_cols} FROM episodes"
     if where:
         sql += " WHERE " + " AND ".join(where)
     sql += " ORDER BY timestamp DESC LIMIT ?"
@@ -217,13 +273,30 @@ def _query_episodes(
         ps = d.get("plan_status") or ""
         oc = d.get("outcome") or ""
         bits = [title or d.get("episode_id", "")]
-        tail = []
-        if ps:
-            tail.append(f"plan_status={ps}")
-        if oc and oc != ps:
-            tail.append(f"outcome={oc}")
-        if tail:
-            bits.append("[" + ", ".join(tail) + "]")
+        if metrics:
+            # Metrics view: lead with the projected metric fields.
+            mtail = []
+            cs = d.get("compliance_score")
+            if cs is not None:
+                grade = d.get("compliance_grade") or ""
+                mtail.append(f"compliance={cs}{('/' + grade) if grade else ''}")
+            it = d.get("input_tokens")
+            ot = d.get("output_tokens_real")
+            if it is not None or ot is not None:
+                mtail.append(f"tok in={it if it is not None else '?'} out_real={ot if ot is not None else '?'}")
+            model = d.get("model_used")
+            if model:
+                mtail.append(f"model={model}")
+            if mtail:
+                bits.append("[" + ", ".join(mtail) + "]")
+        else:
+            tail = []
+            if ps:
+                tail.append(f"plan_status={ps}")
+            if oc and oc != ps:
+                tail.append(f"outcome={oc}")
+            if tail:
+                bits.append("[" + ", ".join(tail) + "]")
         out.append({
             "surface": "episodes",
             "timestamp": d.get("timestamp") or "",
@@ -435,6 +508,87 @@ def group_and_count(
     return out
 
 
+def aggregate_metrics(
+    rows: list[dict],
+    *,
+    group_by: str | None,
+) -> list[dict]:
+    """Roll up ``--metrics`` episode rows into per-group summaries.
+
+    Each output bucket carries ``count``, ``avg_compliance_score`` (over rows
+    that have one), ``avg_duration_ms``, and the sum of every field in
+    ``_METRIC_SUM_FIELDS``. When ``group_by`` is ``None`` a single ``(all)``
+    bucket is returned. Reuses the same ``VALID_GROUP_BY`` keys as
+    :func:`group_and_count`; metric values are read from each row's ``raw``.
+    Group order is descending count, ties broken alphabetically.
+    """
+    if group_by and group_by not in VALID_GROUP_BY:
+        raise ValueError(
+            f"invalid group_by '{group_by}'; must be one of {list(VALID_GROUP_BY)}"
+        )
+
+    buckets: dict[str, dict] = {}
+    for r in rows:
+        raw = r.get("raw") or {}
+        if group_by is None:
+            key = "(all)"
+        elif group_by == "day":
+            key = _truncate_day(r.get("timestamp"))
+        elif group_by == "surface":
+            key = r.get("surface") or ""
+        else:
+            key = r.get(group_by) or raw.get(group_by) or ""
+
+        b = buckets.get(key)
+        if b is None:
+            b = {
+                "count": 0,
+                "compliance_sum": 0.0,
+                "compliance_n": 0,
+                "duration_sum": 0.0,
+                "duration_n": 0,
+            }
+            for f in _METRIC_SUM_FIELDS:
+                b[f] = 0
+            buckets[key] = b
+
+        b["count"] += 1
+        cs = raw.get("compliance_score")
+        if isinstance(cs, (int, float)):
+            b["compliance_sum"] += cs
+            b["compliance_n"] += 1
+        dm = raw.get("duration_ms")
+        if isinstance(dm, (int, float)):
+            b["duration_sum"] += dm
+            b["duration_n"] += 1
+        for f in _METRIC_SUM_FIELDS:
+            v = raw.get(f)
+            if isinstance(v, (int, float)):
+                b[f] += v
+
+    out = []
+    for key, b in buckets.items():
+        row = {
+            "count": b["count"],
+            "avg_compliance_score": (
+                round(b["compliance_sum"] / b["compliance_n"], 1)
+                if b["compliance_n"] else None
+            ),
+            "avg_duration_ms": (
+                round(b["duration_sum"] / b["duration_n"])
+                if b["duration_n"] else None
+            ),
+        }
+        for f in _METRIC_SUM_FIELDS:
+            row[f] = b[f]
+        if group_by:
+            row[group_by] = key
+        out.append(row)
+
+    out.sort(key=lambda d: (-d["count"], str(d.get(group_by) if group_by else "")))
+    return out
+
+
 def cross_surface_query(
     *,
     surface: str = "all",
@@ -446,6 +600,7 @@ def cross_surface_query(
     agent: str | None = None,
     command_like: str | None = None,
     failed: bool = False,
+    metrics: bool = False,
     db_path: Path | None = None,
 ) -> list[dict]:
     """Run a cross-surface analytical query against the substrate.
@@ -475,6 +630,13 @@ def cross_surface_query(
                        outcome != success; harness_events: severity=error or
                        result starting with fail/error). Memory surface
                        has no notion of "failed" -- ignored there.
+        metrics:       When True, the episodes surface projects the per-turn
+                       telemetry stored in ``episodes.context_metrics``
+                       (compliance_score, token counts, duration_ms,
+                       tool/api call counts, model_used) via json_extract.
+                       Only affects the episodes surface. Pair with
+                       :func:`aggregate_metrics` for per-agent/-surface
+                       rollups.
         db_path:       Optional explicit substrate path (tests).
 
     Returns:
@@ -511,6 +673,7 @@ def cross_surface_query(
                 agent_filter=agent,
                 failed=failed,
                 limit=last,
+                metrics=metrics,
             ))
         if surface in ("harness_events", "all"):
             results.extend(_query_harness_events(
@@ -539,6 +702,7 @@ __all__ = [
     "parse_when",
     "cross_surface_query",
     "group_and_count",
+    "aggregate_metrics",
     "_highlight_snippet",
     "_extract_text_needle",
     "_row_text_for_snippet",