fix(cli): expose activity event source filter

.changeset/issue-1660-recovery-metadata-events.md

@@ -1,5 +1,6 @@
 ---
+"@aoagents/ao-cli": patch
 "@aoagents/ao-core": minor
 ---
 
-Wire activity events for the recovery subsystem, metadata-corruption detection, and agent-report apply path. New event kinds: `recovery.session_failed`, `recovery.action_failed`, `metadata.corrupt_detected`, `api.agent_report.session_not_found`, `api.agent_report.transition_rejected`. Adds `"recovery"` to the `ActivityEventSource` union. Lets RCA reconstruct `ao recover` invocations, find every silent metadata overwrite, and audit rejected agent transitions.
+Wire activity events for the recovery subsystem, metadata-corruption detection, and agent-report apply path. New event kinds: `recovery.session_failed`, `recovery.action_failed`, `metadata.corrupt_detected`, `api.agent_report.session_not_found`, `api.agent_report.transition_rejected`. Adds `"recovery"` to the `ActivityEventSource` union. Lets RCA reconstruct `ao recover` invocations, find every silent metadata overwrite, and audit rejected agent transitions. Adds `ao events list --source` and `--kind` so these forensic event queries are available from the CLI.

packages/cli/__tests__/commands/events.test.ts

@@ -0,0 +1,87 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Command } from "commander";
+
+const { mockQueryActivityEvents, mockSearchActivityEvents, mockGetActivityEventStats } = vi.hoisted(
+  () => ({
+    mockQueryActivityEvents: vi.fn(),
+    mockSearchActivityEvents: vi.fn(),
+    mockGetActivityEventStats: vi.fn(),
+  }),
+);
+
+vi.mock("@aoagents/ao-core", () => ({
+  queryActivityEvents: (...args: unknown[]) => mockQueryActivityEvents(...args),
+  searchActivityEvents: (...args: unknown[]) => mockSearchActivityEvents(...args),
+  getActivityEventStats: (...args: unknown[]) => mockGetActivityEventStats(...args),
+  droppedEventCount: () => 0,
+  isActivityEventsFtsEnabled: () => true,
+}));
+
+import { registerEvents } from "../../src/commands/events.js";
+
+describe("events command", () => {
+  let program: Command;
+  let consoleLogSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    program = new Command();
+    program.exitOverride();
+    registerEvents(program);
+
+    consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    mockQueryActivityEvents.mockReset();
+    mockSearchActivityEvents.mockReset();
+    mockGetActivityEventStats.mockReset();
+    mockQueryActivityEvents.mockReturnValue([]);
+  });
+
+  afterEach(() => {
+    consoleLogSpy.mockRestore();
+  });
+
+  it("filters list output by source and --kind alias", async () => {
+    await program.parseAsync([
+      "node",
+      "test",
+      "events",
+      "list",
+      "--source",
+      "recovery",
+      "--kind",
+      "metadata.corrupt_detected",
+      "--limit",
+      "1",
+      "--json",
+    ]);
+
+    expect(mockQueryActivityEvents).toHaveBeenCalledWith(
+      expect.objectContaining({
+        source: "recovery",
+        kind: "metadata.corrupt_detected",
+        limit: 1,
+      }),
+    );
+    expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('"source": "recovery"'));
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      expect.stringContaining('"kind": "metadata.corrupt_detected"'),
+    );
+  });
+
+  it("keeps --type as the existing event-kind filter", async () => {
+    await program.parseAsync([
+      "node",
+      "test",
+      "events",
+      "list",
+      "--type",
+      "recovery.session_failed",
+      "--json",
+    ]);
+
+    expect(mockQueryActivityEvents).toHaveBeenCalledWith(
+      expect.objectContaining({
+        kind: "recovery.session_failed",
+      }),
+    );
+  });
+});

packages/cli/src/commands/events.ts

@@ -9,6 +9,7 @@ import {
   type ActivityEvent,
   type ActivityEventLevel,
   type ActivityEventKind,
+  type ActivityEventSource,
 } from "@aoagents/ao-core";
 
 interface JsonEnvelope {
@@ -80,7 +81,12 @@ export function registerEvents(program: Command): void {
     .description("List recent activity events")
     .option("-p, --project <id>", "Filter by project ID")
     .option("-s, --session <id>", "Filter by session ID")
-    .option("-t, --type <kind>", "Filter by event kind (e.g. session.spawned, lifecycle.transition)")
+    .option(
+      "-t, --type <kind>",
+      "Filter by event kind (e.g. session.spawned, lifecycle.transition)",
+    )
+    .option("--kind <kind>", "Alias for --type")
+    .option("--source <source>", "Filter by event source (e.g. lifecycle, recovery, api)")
     .option("--log-level <level>", "Filter by log level (debug, info, warn, error)")
     .option("--since <duration>", "Show events from last N minutes/hours/days (e.g. 30m, 2h, 1d)")
     .option("-n, --limit <n>", "Max results", "50")
@@ -91,15 +97,21 @@ export function registerEvents(program: Command): void {
       if (sinceRaw) {
         since = parseSinceDuration(sinceRaw);
         if (!since) {
-          console.error(chalk.yellow(`Warning: unrecognised --since format "${sinceRaw}" (use e.g. 30m, 2h, 1d). No time filter applied.`));
+          console.error(
+            chalk.yellow(
+              `Warning: unrecognised --since format "${sinceRaw}" (use e.g. 30m, 2h, 1d). No time filter applied.`,
+            ),
+          );
         }
       }
       const limit = parseInt(opts["limit"] ?? "50", 10);
+      const kind = opts["type"] ?? opts["kind"];
 
       const results = queryActivityEvents({
         projectId: opts["project"],
         sessionId: opts["session"],
-        kind: opts["type"] as ActivityEventKind,
+        kind: kind as ActivityEventKind,
+        source: opts["source"] as ActivityEventSource,
         level: opts["logLevel"] as ActivityEventLevel,
         since,
         limit,
@@ -111,7 +123,8 @@ export function registerEvents(program: Command): void {
           query: {
             projectId: opts["project"] ?? null,
             sessionId: opts["session"] ?? null,
-            kind: opts["type"] ?? null,
+            kind: kind ?? null,
+            source: opts["source"] ?? null,
             level: opts["logLevel"] ?? null,
             since: sinceRaw ?? null,
             limit,