failproofai 1.0.1 → 1.0.2-beta.0

package/.next/standalone/fp-cloud-cli/fp_cli/commands/errors_cmds.py

@@ -0,0 +1,190 @@
+"""errors — list errored events, or --aggregate them into a summary card.
+
+Read-only; talks to the dashboard `/api/events/summary` (the light, payload-free errored
+rows) and `/api/events/error_summary` (the aggregate). The list view renders the server's
+precomputed `summary` column — the CLI never returns the fat payload for an errors read.
+Free-text `--search` remains the exception at the database layer: it scans payload to match.
+Emits the server payload verbatim under `--json`.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+import typer
+
+from .. import client as api
+from .. import dates, output
+from .._context import (
+    GLOBALS_EPILOG,
+    AppState,
+    require_auth,
+    resolve_dates,
+    resolve_fields,
+    validate_choice,
+    validate_limit,
+)
+from ..models import AgentEvent
+
+
+def errors(
+    ctx: typer.Context,
+    aggregate: bool = typer.Option(False, "--aggregate", help="Summarise the matching errors into a card (count + sessions/agents/last seen) instead of listing them."),
+    limit: int = typer.Option(50, "--limit", "-n", help="Max rows in total (list mode). Use --all to auto-paginate beyond the server's single-request cap."),
+    since: Optional[str] = typer.Option(None, "--since", help=f"Relative window from now (dashboard presets): {', '.join(dates.SINCE_CHOICES)}."),
+    ts_from: Optional[str] = typer.Option(None, "--from", help="Custom-range start, ISO-8601 UTC (e.g. 2026-05-01T00:00:00Z). Overrides --since."),
+    ts_to: Optional[str] = typer.Option(None, "--to", help="Custom-range end, ISO-8601 UTC. Overrides --since."),
+    environment: Optional[str] = typer.Option(None, "--env", help="Filter to one environment (exact match). e.g. `prod`."),
+    error_type: Optional[str] = typer.Option(None, "--error-type", help="Filter to one error type (exact match). e.g. `TimeoutError`."),
+    event_type: Optional[str] = typer.Option(None, "--event-type", help="Filter to one event type (exact match). e.g. `error`."),
+    agent_id: Optional[str] = typer.Option(None, "--agent-id", help="Filter to one agent id (exact match)."),
+    session_id: Optional[str] = typer.Option(None, "--session-id", help="Filter to one session id (exact match)."),
+    search: Optional[List[str]] = typer.Option(None, "--search", help="Free-text term to match in the payload (repeatable; an event matches if it contains ANY of the terms)."),
+    order: Optional[str] = typer.Option(None, "--order", help="Sort order by time: `asc` or `desc` (default newest-first; list mode)."),
+    fetch_all: bool = typer.Option(False, "--all", help="Auto-paginate through all pages, up to --limit (list mode)."),
+    cursor: Optional[str] = typer.Option(None, "--cursor", help="Resume after this cursor (a prior next_cursor; opaque token; list mode)."),
+    page_size: Optional[int] = typer.Option(None, "--page-size", help="Rows per request when --all (max 200; list mode)."),
+    fields: Optional[str] = typer.Option(None, "--fields", help="Comma-separated subset of fields to output (list mode). e.g. `ts,event_type,session_id`."),
+    full_ids: bool = typer.Option(False, "--full-ids", help="Show full session ids in the table instead of truncating them (list mode; --json always has the full id)."),
+) -> None:
+    """List **errored events**, newest first — or roll them up with **`--aggregate`**.
+
+    Errored events are the failures across your agents' runs (the dashboard's `/errors` view).
+    Two modes, same filters:
+
+    * **list** (default) — one row per errored event: `time · event · env · agent · session ·
+      summary` (the summary is derived from the event payload).
+    * **`--aggregate`** — a summary card: the total error count plus how many sessions and agents
+      are affected and how recent the last error is.
+
+    Each filter — `--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id` — takes a
+    **single** value; combine them to narrow to one slice (they AND together). `--search` matches
+    a free-text term in the event payload (repeatable — an event matches ANY of the terms). Scope
+    time with `--since` or `--from`/`--to`. Every filter applies to both modes.
+
+    Needs `events:read`. List `--json`: `{"errors": [...], "next_cursor": …}` — each row is a
+    light, payload-free event (`id, session_id, agent_id, event_type, ts, environment,
+    summary, is_error, error_type, output_tokens`, also the valid `--fields` names). The
+    rendered `summary` is the server-computed `summary` field (no client-side payload
+    parsing). Aggregate `--json`: `{total, sessions, agents, last_ts, bins}`. For the raw
+    payload of an errored run, use `fp events --full --session-id <id>`.
+
+    Examples:
+
+    * `fp errors --env prod --since 24h` — recent production errors
+    * `fp errors --error-type TimeoutError --agent-id agent-orderbot` — one agent's timeouts
+    * `fp errors --aggregate --env prod --since 7d` — how many prod errors this week, and where
+    * `fp --json errors --session-id sess-001 --all | jq '.errors[].summary'` — one session's error summaries as JSON
+    """
+    state: AppState = ctx.obj
+    cctx = require_auth(state)
+    validate_limit(limit)
+    order = validate_choice(order, ("asc", "desc"), flag="--order")
+    frm, to = resolve_dates(since, ts_from, ts_to)
+
+    # Which narrowing filters did the user set? Used to word the empty message and to nudge them
+    # to re-check those values when nothing matches (a value matching nothing returns empty, not
+    # an error — so a typo reads as "no errors"). Applies to both modes.
+    active_filters = [
+        flag for flag, val in (
+            ("--env", environment),
+            ("--event-type", event_type),
+            ("--error-type", error_type),
+            ("--agent-id", agent_id),
+            ("--session-id", session_id),
+            ("--search", search),
+            ("--since/--from/--to", since or ts_from or ts_to),
+        ) if val
+    ]
+
+    # ── aggregate mode: one summary payload, no pagination ──
+    if aggregate:
+        data = api.event_error_summary(
+            cctx,
+            session_id=session_id,
+            agent_id=agent_id,
+            event_type=event_type,
+            error_type=error_type,
+            environment=environment,
+            search=search,
+            ts_from=frm,
+            ts_to=to,
+        )
+        if state.json:
+            output.emit_json(data)
+        else:
+            output.render_error_aggregate(data)
+            if not int(data.get("total", 0) or 0):
+                output.recheck_filters_hint(active_filters)
+        return
+
+    # ── list mode: errored events (errored=true, like the dashboard /errors view) ──
+    # `errors` ALWAYS reads the light, payload-free `/api/events/summary` feed —
+    # there is no `--full` here and no feed switch. So validating `--fields`
+    # against the whole `AgentEvent` dataclass accepted `payload`, whose
+    # dataclass default is `{}`, and the projection emitted that empty dict as if
+    # it were data: `fp --json errors --fields payload` exited 0 printing
+    # `{"payload": {}}` per row, and a caller piping it into `jq` reasonably
+    # concluded the errored events carried no payload. `events` gets this right
+    # by switching feeds; here the honest answer is a usage error naming the
+    # command that can serve it. The docstring above already lists the valid
+    # names and `payload` is deliberately not among them.
+    if fields and "payload" in {f.strip() for f in fields.split(",")}:
+        raise typer.BadParameter(
+            "`payload` is not available on `fp errors` — it reads the light, "
+            "payload-free feed. Use `fp events --full --session-id <id>` (or "
+            "`fp events --fields payload`) to get event payloads."
+        )
+    cols = resolve_fields(fields, AgentEvent)
+    common = dict(
+        session_id=session_id,
+        agent_id=agent_id,
+        event_type=event_type,
+        error_type=error_type,
+        environment=environment,
+        errored=True,
+        order=order,
+        search=search,
+        ts_from=frm,
+        ts_to=to,
+    )
+
+    if fetch_all:
+        walk = api.Walk()
+        items = list(
+            api.paginate(
+                lambda cursor, limit: api.list_event_summaries(cctx, cursor=cursor, limit=limit, **common),
+                limit=limit,
+                page_size=page_size,
+                start_cursor=cursor,
+                walk=walk,
+            )
+        )
+        # NOT `None`. `--limit` defaults to 50, so `--all` without an explicit
+        # limit stops at 50 rows — and hard-coding the cursor to null told the
+        # caller the feed was exhausted, on the one output a script or an agent
+        # reads. `walk` carries the cursor the walk actually stopped on.
+        next_cursor = walk.next_cursor
+    else:
+        page = api.list_event_summaries(cctx, cursor=cursor, limit=limit, **common)
+        items = page.items
+        next_cursor = page.next_cursor
+
+    if state.json:
+        payload = output.project_dicts(items, cols) if cols else items
+        output.emit_json({"errors": payload, "next_cursor": next_cursor})
+        return
+
+    if cols:
+        # `--fields` asks for specific raw columns → the generic table (no bespoke styling).
+        output.print_table(list(cols), output.project_rows(items, cols), title=f"Errors ({len(items)})")
+    else:
+        empty_message = "no errors match these filters" if active_filters else "no errors"
+        output.render_errors(items, order=order, full_ids=full_ids, empty_message=empty_message)
+    output.errors_footer(len(items), more=next_cursor is not None)
+    if not items:
+        output.recheck_filters_hint(active_filters)
+
+
+def register(app: typer.Typer) -> None:
+    app.command("errors", epilog=GLOBALS_EPILOG)(errors)

package/.next/standalone/fp-cloud-cli/fp_cli/commands/evals_cmds.py

@@ -0,0 +1,161 @@
+"""evals — list evaluation results (with scores), or roll them up with --aggregate."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+import typer
+
+from .. import client as api
+from .. import dates, output
+from .._context import (
+    GLOBALS_EPILOG,
+    AppState,
+    require_auth,
+    resolve_dates,
+    resolve_fields,
+    validate_choice,
+    validate_limit,
+    validate_score_filters,
+)
+from ..models import Evaluation
+
+
+def evals(
+    ctx: typer.Context,
+    aggregate: bool = typer.Option(False, "--aggregate", help="Roll the matching evaluations up into a totals card + per-metric score stats, instead of listing rows."),
+    limit: int = typer.Option(50, "--limit", "-n", help="Max rows in total (list mode). Use --all to auto-paginate beyond the server's single-request cap."),
+    since: Optional[str] = typer.Option(None, "--since", help=f"Relative window from now (dashboard presets): {', '.join(dates.SINCE_CHOICES)}."),
+    ts_from: Optional[str] = typer.Option(None, "--from", help="Custom-range start, ISO-8601 UTC (e.g. 2026-05-01T00:00:00Z). Overrides --since."),
+    ts_to: Optional[str] = typer.Option(None, "--to", help="Custom-range end, ISO-8601 UTC. Overrides --since."),
+    environment: Optional[str] = typer.Option(None, "--env", help="Filter to one environment (exact match). e.g. `prod`."),
+    status: Optional[str] = typer.Option(None, "--status", help="Filter to one evaluation status: `done`, `error`, or `timeout`."),
+    agent_id: Optional[str] = typer.Option(None, "--agent-id", help="Filter to one agent id (exact match)."),
+    session_id: Optional[str] = typer.Option(None, "--session-id", help="Filter to one session id (exact match)."),
+    score: Optional[List[str]] = typer.Option(None, "--score", help="Score range filter `KEY:MIN..MAX` (either bound optional). Repeatable; all must match. e.g. `helpfulness:0.5..0.8`."),
+    fetch_all: bool = typer.Option(False, "--all", help="Auto-paginate through all pages, up to --limit (list mode)."),
+    cursor: Optional[str] = typer.Option(None, "--cursor", help="Resume after this cursor (a prior next_cursor; opaque token; list mode)."),
+    page_size: Optional[int] = typer.Option(None, "--page-size", help="Rows per request when --all (max 200; list mode)."),
+    fields: Optional[str] = typer.Option(None, "--fields", help="Comma-separated subset of fields to output (list mode). e.g. `session_id,status,scores`."),
+    full_ids: bool = typer.Option(False, "--full-ids", help="Show full session ids in the table instead of truncating them (list mode; --json always has the full id)."),
+    scores_full: bool = typer.Option(False, "--scores-full", help="Show every score pair in the table instead of the first few + `+N` (list mode; may wrap)."),
+) -> None:
+    """List **evaluation results** with their scores, newest first — or roll them up with
+    **`--aggregate`**. An evaluation is one scored judgement of an agent run.
+
+    Two modes, same filters:
+
+    * **list** (default) — one row per evaluation: `time · env · agent · session · status · scores`.
+    * **`--aggregate`** — a totals card (run-health mix + success rate) and a per-metric
+      score-stats table (count, average + bar, min/max/p50) over the whole matching set, worst
+      average first. Point it at one slice — an agent, env, session, or status — to read that
+      slice's score performance.
+
+    The filters `--env`, `--status`, `--agent-id`, and `--session-id` each take a **single**
+    value; combine them to narrow a slice (they AND together). `--score KEY:MIN..MAX` filters by
+    score range — either bound optional (`helpfulness:0.5..0.8`, `tool_efficiency:..0.3`,
+    `factuality:0.9..`) — and is **repeatable**, with **all** ranges required (AND). Scope time
+    with `--since` or `--from`/`--to`. Every filter applies to both modes.
+
+    Needs `evaluations:read`. List `--json`: `{"evaluations": [...], "next_cursor": …}`.
+    Aggregate `--json`: `{total, status_counts, score_stats[], timeline}`.
+
+    Examples:
+
+    * `fp evals --agent-id agent-orderbot --aggregate` — one agent's score performance, rolled up
+    * `fp evals --aggregate --env prod --status error` — score stats for prod runs that failed
+    * `fp evals --score helpfulness:0.8.. --since 7d` — recent evaluations scoring ≥0.8 on helpfulness
+    * `fp --json evals --aggregate --session-id sess-001 | jq '.score_stats'` — one session's metric stats as JSON
+    """
+    state: AppState = ctx.obj
+    cctx = require_auth(state)
+    validate_score_filters(score)
+    validate_limit(limit)
+    status = validate_choice(status, ("done", "error", "timeout"), flag="--status")
+    frm, to = resolve_dates(since, ts_from, ts_to)
+    score_filters = ",".join(score) if score else None
+
+    # Which narrowing filters did the user set? Used to word the empty message and to nudge
+    # them to re-check those values when nothing matches (a value matching nothing returns an
+    # empty set, not an error — so a typo looks like "no evals"). Applies to both modes.
+    active_filters = [
+        flag for flag, val in (
+            ("--env", environment),
+            ("--status", status),
+            ("--agent-id", agent_id),
+            ("--session-id", session_id),
+            ("--score", score),
+            ("--since/--from/--to", since or ts_from or ts_to),
+        ) if val
+    ]
+
+    # ── aggregate mode: one rolled-up payload, no pagination ──
+    if aggregate:
+        data = api.evaluation_aggregate(
+            cctx,
+            session_id=session_id,
+            agent_id=agent_id,
+            environment=environment,
+            status=status,
+            score_filters=score_filters,
+            ts_from=frm,
+            ts_to=to,
+        )
+        if state.json:
+            output.emit_json(data)
+        else:
+            output.render_eval_aggregate(data)
+            if not int(data.get("total", 0) or 0):
+                output.recheck_filters_hint(active_filters)
+        return
+
+    # ── list mode ──
+    cols = resolve_fields(fields, Evaluation)
+
+    def fetch(cursor: Optional[int], limit: Optional[int]):
+        return api.list_evaluations(
+            cctx,
+            session_id=session_id,
+            agent_id=agent_id,
+            environment=environment,
+            status=status,
+            score_filters=score_filters,
+            ts_from=frm,
+            ts_to=to,
+            cursor=cursor,
+            limit=limit,
+        )
+
+    if fetch_all:
+        walk = api.Walk()
+        items = list(
+            api.paginate(fetch, limit=limit, page_size=page_size, start_cursor=cursor, walk=walk)
+        )
+        # NOT `None`. `--limit` defaults to 50, so `--all` without an explicit
+        # limit stops at 50 rows — and hard-coding the cursor to null told the
+        # caller the feed was exhausted, on the one output a script or an agent
+        # reads. `walk` carries the cursor the walk actually stopped on.
+        next_cursor = walk.next_cursor
+    else:
+        page = fetch(cursor, limit)
+        items = page.items
+        next_cursor = page.next_cursor
+
+    if state.json:
+        payload = output.project_dicts(items, cols) if cols else items
+        output.emit_json({"evaluations": payload, "next_cursor": next_cursor})
+        return
+
+    if cols:
+        # `--fields` asks for specific columns → the generic table (no bespoke styling).
+        output.print_table(list(cols), output.project_rows(items, cols), title=f"Evaluations ({len(items)})")
+    else:
+        empty_message = "no evals match these filters" if active_filters else "no evals"
+        output.render_evals(items, full_ids=full_ids, scores_full=scores_full, empty_message=empty_message)
+    output.evals_footer(len(items), more=next_cursor is not None)
+    if not items:
+        output.recheck_filters_hint(active_filters)
+
+
+def register(app: typer.Typer) -> None:
+    app.command("evals", epilog=GLOBALS_EPILOG)(evals)

package/.next/standalone/fp-cloud-cli/fp_cli/commands/events_cmds.py

@@ -0,0 +1,159 @@
+"""events — list raw agent events."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+import typer
+
+from .. import client as api
+from .. import dates, output
+from .._context import (
+    GLOBALS_EPILOG,
+    AppState,
+    collect_multi,
+    require_auth,
+    resolve_dates,
+    resolve_fields,
+    validate_limit,
+)
+from ..models import AgentEvent
+
+
+def events(
+    ctx: typer.Context,
+    limit: int = typer.Option(50, "--limit", "-n", help="Max rows in total. Use --all to auto-paginate beyond the server's single-request cap."),
+    since: Optional[str] = typer.Option(None, "--since", help=f"Relative window from now (dashboard presets): {', '.join(dates.SINCE_CHOICES)}."),
+    ts_from: Optional[str] = typer.Option(None, "--from", help="Custom-range start, ISO-8601 UTC (e.g. 2026-05-01T00:00:00Z). Overrides --since."),
+    ts_to: Optional[str] = typer.Option(None, "--to", help="Custom-range end, ISO-8601 UTC. Overrides --since."),
+    environment: Optional[List[str]] = typer.Option(None, "--env", help="Filter by environment. Accepts multiple — repeat the flag or comma-separate: `--env prod --env staging` or `--env prod,staging` (matches any)."),
+    event_type: Optional[List[str]] = typer.Option(None, "--event-type", help="Filter by event type. Accepts multiple — repeat the flag or comma-separate: `--event-type tool_use,tool_result` (matches any). Discover values with `fp list event_types`."),
+    agent_id: Optional[List[str]] = typer.Option(None, "--agent-id", help="Filter by agent id. Accepts multiple — repeat the flag or comma-separate: `--agent-id a,b` (matches any). Discover values with `fp list agents`."),
+    session_id: Optional[List[str]] = typer.Option(None, "--session-id", help="Filter by session id. Accepts multiple — repeat the flag or comma-separate: `--session-id a,b` (matches any)."),
+    search: Optional[List[str]] = typer.Option(None, "--search", help="Free-text term to match in the payload (repeatable; an event matches if it contains ANY of the terms)."),
+    order: Optional[str] = typer.Option(None, "--order", help="Sort order by time: `asc` or `desc` (default newest-first)."),
+    fetch_all: bool = typer.Option(False, "--all", help="Auto-paginate through all pages, up to --limit."),
+    cursor: Optional[str] = typer.Option(None, "--cursor", help="Resume after this cursor (a prior next_cursor; opaque token)."),
+    page_size: Optional[int] = typer.Option(None, "--page-size", help="Rows per request when --all (max 200)."),
+    full: bool = typer.Option(False, "--full", help="Fetch the FULL event rows incl. the raw `payload` (the heavy feed). Off by default — the light payload-free feed is used unless you pass this or request `--fields payload`. The full feed is slow at scale, so keep it bounded (e.g. to one `--session-id`)."),
+    fields: Optional[str] = typer.Option(None, "--fields", help="Comma-separated subset of fields to output (applies to --json and the table). e.g. `ts,event_type,summary`. Requesting `payload` auto-switches to the full feed."),
+) -> None:
+    """List **event logs** — the raw, per-step trail your agents emit (tool calls, model
+    requests/responses, hooks, results), newest first.
+
+    Narrow the feed with the filters below. `--env`, `--event-type`, `--agent-id`, and
+    `--session-id` each accept **multiple values** — repeat the flag or comma-separate
+    (`--env prod,staging` is the same as `--env prod --env staging`). Values within one
+    filter match **any** of them; different filters are combined (an event must satisfy all
+    of them). Scope by time with `--since` (a preset window) or `--from`/`--to` (a custom
+    UTC range), and walk large result sets with `--all` (or resume with `--cursor`).
+
+    Discover valid filter values with `fp list` — e.g. `fp list event_types`,
+    `fp list agents`, `fp list envs`.
+
+    Needs `events:read`. With `--json`: `{"events": [...], "next_cursor": <cursor or null>}`.
+
+    By **default** this reads the light, payload-free feed — each event has `id, session_id,
+    agent_id, event_type, ts, environment, summary, is_error, error_type, output_tokens,
+    context_window, context_fill` (a server-computed one-line `summary`, never the raw
+    payload). This is the fast path for structured filters, `--session-id`, and `--all`.
+    `--search` keeps the response payload-free but still scans payload server-side, so broad
+    searches may be expensive. To get
+    the raw `payload`, opt into the **full feed** with `--full` (or `--fields payload`), which
+    hits the heavy `/events` endpoint — slow at scale, so keep it bounded (pair `--full` with a
+    single `--session-id`). All listed keys are valid `--fields` names (`payload` too, in full
+    mode).
+
+    Examples:
+
+    * `fp events --env prod,staging --event-type tool_use,error --limit 100` — recent prod/staging events (light)
+    * `fp --json events --session-id run-001 --all` — a run's full timeline: event types + summaries (light, fast)
+    * `fp --json events --full --session-id run-001 --all | jq '.events[].payload'` — that run's raw payloads (full feed, bounded to one run)
+    """
+    state: AppState = ctx.obj
+    cctx = require_auth(state)
+    frm, to = resolve_dates(since, ts_from, ts_to)
+    cols = resolve_fields(fields, AgentEvent)
+    if order is not None and order not in ("asc", "desc"):
+        raise typer.BadParameter("--order must be 'asc' or 'desc'.")
+    validate_limit(limit)
+
+    # Multi-value filters: merge repeated flags + comma-separated values into one flat,
+    # de-duplicated list each (the server UNIONs within a filter via `IN`, ANDs across them).
+    session_id = collect_multi(session_id)
+    agent_id = collect_multi(agent_id)
+    event_type = collect_multi(event_type)
+    environment = collect_multi(environment)
+
+    # Default to the light, payload-free feed (/api/events/summary). Only reach for the heavy
+    # full feed (/api/events, with `payload`) when the caller EXPLICITLY asks for the raw
+    # payload: --full, or --fields payload. Everything else — including --session-id — stays
+    # on the light feed: the full feed is slow/timeout-prone at scale, a single-session read
+    # wants the summaries/timeline (not the fat payload), and payload is a deliberate opt-in.
+    use_full = full or (cols is not None and "payload" in cols)
+    fetch = api.list_events if use_full else api.list_event_summaries
+
+    common = dict(
+        session_id=session_id,
+        agent_id=agent_id,
+        event_type=event_type,
+        environment=environment,
+        order=order,
+        search=search,
+        ts_from=frm,
+        ts_to=to,
+    )
+
+    if fetch_all:
+        walk = api.Walk()
+        items = list(
+            api.paginate(
+                lambda cursor, limit: fetch(cctx, cursor=cursor, limit=limit, **common),
+                limit=limit,
+                page_size=page_size,
+                start_cursor=cursor,
+                walk=walk,
+            )
+        )
+        # NOT `None`. `--limit` defaults to 50, so `--all` without an explicit
+        # limit stops at 50 rows — and hard-coding the cursor to null told the
+        # caller the feed was exhausted, on the one output a script or an agent
+        # reads. `walk` carries the cursor the walk actually stopped on.
+        next_cursor = walk.next_cursor
+    else:
+        page = fetch(cctx, cursor=cursor, limit=limit, **common)
+        items = page.items
+        next_cursor = page.next_cursor
+
+    if state.json:
+        payload = output.project_dicts(items, cols) if cols else items
+        output.emit_json({"events": payload, "next_cursor": next_cursor})
+        return
+
+    # Which narrowing filters did the user actually set? Used to (a) word the empty-box
+    # message and (b) nudge them to re-check those values when 0 rows come back — the server
+    # returns an empty set for any value that matches nothing, so a typo looks like "no data".
+    active_filters = [
+        flag for flag, val in (
+            ("--env", environment),
+            ("--event-type", event_type),
+            ("--agent-id", agent_id),
+            ("--session-id", session_id),
+            ("--search", search),
+            ("--since/--from/--to", since or ts_from or ts_to),
+        ) if val
+    ]
+
+    if cols:
+        # `--fields` asks for specific columns → the generic table (no bespoke styling).
+        output.print_table(list(cols), output.project_rows(items, cols), title=f"Events ({len(items)})")
+    else:
+        empty_message = "no events match these filters" if active_filters else "no events in this window"
+        output.render_events(items, order=order, empty_message=empty_message)
+    output.events_footer(len(items), more=next_cursor is not None)
+    if not items:
+        output.recheck_filters_hint(active_filters)
+
+
+def register(app: typer.Typer) -> None:
+    app.command("events", epilog=GLOBALS_EPILOG)(events)