@dreki-gg/pi-datadog 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @dreki-gg/pi-datadog
 
+## 0.3.0
+
+### Minor Changes
+
+- Add `datadog_rum_search` tool for searching Datadog RUM events (sessions, views, actions, front-end errors). Defaults to session events and, like the logs tool, returns a compact inline digest while writing the full untruncated events to a temp file the agent can read. Adds optional `rumApplicationId` / `rumService` fields to `.pi/datadog.json` (with per-call overrides), and surfaces them in the `/datadog` status command.
+
 ## 0.2.4
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,6 @@
 # @dreki-gg/pi-datadog
 
-Datadog log search tools for [pi](https://github.com/earendil-works/pi) — query production logs with project-aware context.
+Datadog log and RUM search tools for [pi](https://github.com/earendil-works/pi) — query production logs and Real User Monitoring sessions with project-aware context.
 
 ## Setup
 
@@ -33,7 +33,9 @@ Create `.pi/datadog.json` in your project root to set defaults:
   "env": "production",
   "site": "datadoghq.com",
   "defaultTags": ["team:backend"],
-  "defaultTimeRange": "1h"
+  "defaultTimeRange": "1h",
+  "rumApplicationId": "abcd-1234",
+  "rumService": "web-frontend"
 }
 ```
 
@@ -44,6 +46,8 @@ Create `.pi/datadog.json` in your project root to set defaults:
 | `site` | Datadog site | `datadoghq.com` |
 | `defaultTags` | Tags auto-appended to every query | `[]` |
 | `defaultTimeRange` | Default lookback window | `1h` |
+| `rumApplicationId` | Default RUM application id (`@application.id`) for RUM searches | _(none)_ |
+| `rumService` | Default service for RUM searches (falls back to `service`) | _(none)_ |
 
 **Supported sites:** `datadoghq.com` (US1), `us3.datadoghq.com`, `us5.datadoghq.com`, `datadoghq.eu` (EU).
 
@@ -61,6 +65,14 @@ Just ask pi to search your logs:
 
 The agent uses your `.pi/datadog.json` defaults automatically — you don't need to specify service or environment unless you want to override them.
 
+You can also ask about front-end / RUM sessions:
+
+```
+> Show me RUM sessions from the last hour
+> Find RUM errors on the checkout view in production
+> What views did users hit in the last 30 minutes?
+```
+
 ### Tool: `datadog_logs_search`
 
 The agent calls this tool with [Datadog query syntax](https://docs.datadoghq.com/logs/explorer/search_syntax/):
@@ -75,6 +87,25 @@ The agent calls this tool with [Datadog query syntax](https://docs.datadoghq.com
 | `service` | `string` | Override project default service |
 | `env` | `string` | Override project default environment |
 
+The agent receives a compact inline digest (counts, status breakdown, services). The full, untruncated log entries are written to a temp file whose path is in the response — the agent reads that file with the `read` tool to inspect actual content.
+
+### Tool: `datadog_rum_search`
+
+Searches Datadog RUM events (sessions, views, actions, front-end errors) with [RUM query syntax](https://docs.datadoghq.com/real_user_monitoring/explorer/search_syntax/). Defaults to **session** events (`@type:session`) when the query omits `@type`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | `string` | **Required.** RUM query (e.g. `@type:session`, `@type:error`, `@view.url_path:/checkout`). Leave empty to list recent sessions |
+| `from` | `string` | Start time — relative (`15m`, `1h`, `7d`) or ISO 8601 |
+| `to` | `string` | End time — relative, ISO 8601, or `now` |
+| `limit` | `number` | Max results (1–100, default 25) |
+| `sort` | `string` | `newest` or `oldest` |
+| `service` | `string` | Override project default RUM service |
+| `env` | `string` | Override project default environment |
+| `applicationId` | `string` | Override project default RUM application id (`@application.id`) |
+
+Like the logs tool, it returns a compact digest inline (counts, event-type breakdown, services) and writes the full events to a `rum-*.md` temp file the agent can `read`.
+
 ### Command: `/datadog`
 
 Check your configuration and connection status:
@@ -83,7 +114,7 @@ Check your configuration and connection status:
 /datadog
 ```
 
-Shows: credential status (set/missing), project config (service, env, site, tags).
+Shows: credential status (set/missing), project config (service, env, site, tags, RUM application, RUM service).
 
 ## Query Syntax Examples
 
@@ -97,6 +128,18 @@ service:my-api env:production @duration:>5000  # Slow requests
 
 See the [Datadog Log Search Syntax docs](https://docs.datadoghq.com/logs/explorer/search_syntax/) for the full reference.
 
+### RUM query examples
+
+```
+@type:session                          # User sessions (the default)
+@type:error                            # Front-end errors
+@type:view @view.url_path:/checkout    # Views on the checkout page
+@type:session @session.type:user       # Real user sessions (exclude synthetics)
+@application.id:abcd-1234 @type:action # Actions in a specific RUM application
+```
+
+See the [RUM Search Syntax docs](https://docs.datadoghq.com/real_user_monitoring/explorer/search_syntax/) for the full reference.
+
 ## How It Works
 
 1. The extension loads `.pi/datadog.json` from your project on session start

package/extensions/datadog/client.ts

@@ -101,22 +101,30 @@ export function buildQuery(params: LogSearchParams, config: DatadogProjectConfig
 /** Max automatic retry attempts on 429 / 5xx responses. */
 const MAX_RETRIES = 4;
 
-function createApiInstance(credentials: DatadogCredentials, site: string): v2.LogsApi {
+/**
+ * Builds a Datadog SDK configuration with credentials, the target site, and
+ * transparent retry on 429 / 5xx. The SDK honours the `x-ratelimit-reset`
+ * header, so it waits exactly the window Datadog asks for before retrying
+ * (falling back to exponential backoff otherwise). This is what keeps the
+ * tools from "crying" about rate limits on bursty usage.
+ *
+ * Shared by the logs and RUM clients so both inherit identical retry behaviour.
+ */
+export function createConfiguration(credentials: DatadogCredentials, site: string) {
   const configuration = client.createConfiguration({
     authMethods: {
       apiKeyAuth: credentials.apiKey,
       appKeyAuth: credentials.appKey,
     },
-    // Transparently retry on 429 / 5xx. The SDK honours the `x-ratelimit-reset`
-    // header, so it waits exactly the window Datadog asks for before retrying
-    // (falling back to exponential backoff otherwise). This is what keeps the
-    // tool from "crying" about rate limits on bursty usage.
     enableRetry: true,
     maxRetries: MAX_RETRIES,
   });
   configuration.setServerVariables({ site });
+  return configuration;
+}
 
-  return new v2.LogsApi(configuration);
+function createApiInstance(credentials: DatadogCredentials, site: string): v2.LogsApi {
+  return new v2.LogsApi(createConfiguration(credentials, site));
 }
 
 export interface DatadogErrorInfo {

package/extensions/datadog/config.ts

@@ -7,6 +7,10 @@ export interface DatadogProjectConfig {
   site: string;
   defaultTags?: string[];
   defaultTimeRange: string;
+  /** Default RUM application id (@application.id) for RUM event searches. */
+  rumApplicationId?: string;
+  /** Default service name for RUM event searches (falls back to `service`). */
+  rumService?: string;
 }
 
 interface RawConfig {
@@ -15,6 +19,8 @@ interface RawConfig {
   site?: unknown;
   defaultTags?: unknown;
   defaultTimeRange?: unknown;
+  rumApplicationId?: unknown;
+  rumService?: unknown;
 }
 
 const DEFAULT_CONFIG: DatadogProjectConfig = {
@@ -120,5 +126,19 @@ function validateConfig(raw: RawConfig, configPath: string): DatadogProjectConfi
     config.defaultTimeRange = raw.defaultTimeRange;
   }
 
+  if (raw.rumApplicationId !== undefined) {
+    if (typeof raw.rumApplicationId !== 'string') {
+      throw new Error(`${configPath}: "rumApplicationId" must be a string`);
+    }
+    config.rumApplicationId = raw.rumApplicationId;
+  }
+
+  if (raw.rumService !== undefined) {
+    if (typeof raw.rumService !== 'string') {
+      throw new Error(`${configPath}: "rumService" must be a string`);
+    }
+    config.rumService = raw.rumService;
+  }
+
   return config;
 }

package/extensions/datadog/index.ts

@@ -8,8 +8,14 @@ import {
   loadProjectConfig,
 } from './config.js';
 import { searchLogs, describeDatadogError } from './client.js';
+import { searchRumEvents } from './rum-client.js';
 import { loadDotEnv } from './dotenv.js';
 import { formatSearchResult, formatSearchSummary, formatResultDigest } from './format.js';
+import {
+  formatRumSearchResult,
+  formatRumSearchSummary,
+  formatRumResultDigest,
+} from './rum-format.js';
 import { writeResultsFile } from './output.js';
 
 const SORT_ENUM = ['newest', 'oldest'] as const;
@@ -23,6 +29,14 @@ const TOOL_GUIDELINES = [
   "Datadog is rate-limit sensitive: prefer a single narrow, well-scoped `datadog_logs_search` over many broad calls in quick succession. The tool already auto-retries on 429 (honouring Datadog's reset window) — if it still reports a rate limit, wait before retrying rather than firing again immediately.",
 ];
 
+const RUM_TOOL_GUIDELINES = [
+  'Use `datadog_rum_search` to search Datadog RUM (Real User Monitoring) events — user sessions, views, actions, and front-end errors. It uses Datadog RUM query syntax (e.g. `@type:session`, `@type:error`, `@view.url_path:/checkout`, `@session.type:user`).',
+  '`datadog_rum_search` defaults to session events (`@type:session`) when your query does not specify `@type`. To inspect other event kinds, include `@type:view`, `@type:action`, or `@type:error` in the query.',
+  '`datadog_rum_search` auto-applies project defaults for RUM application, service, and environment from `.pi/datadog.json` — only override when the user explicitly asks for a different application, service, or env.',
+  'The inline `datadog_rum_search` output is a compact digest (counts, event-type breakdown, services). The complete events — full attributes, session ids, view URLs — are written to a temp file whose path is in the response. To inspect actual event content, use the `read` tool on that file instead of re-querying.',
+  'Use appropriate time ranges with `datadog_rum_search`: "15m" for recent issues, "1h" for general debugging, "24h" or "7d" for trend analysis.',
+];
+
 export default function datadogExtension(pi: ExtensionAPI) {
   let projectConfig: DatadogProjectConfig | null = null;
 
@@ -179,6 +193,154 @@ export default function datadogExtension(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerTool({
+    name: 'datadog_rum_search',
+    label: 'Datadog RUM Search',
+    description:
+      'Search Datadog RUM events (sessions, views, actions, errors) with RUM query syntax. Defaults to session events and uses project defaults from .pi/datadog.json for RUM application, service, environment, and time range.',
+    promptSnippet:
+      'Search Datadog RUM events (sessions/views/actions/errors) with project-aware defaults',
+    promptGuidelines: RUM_TOOL_GUIDELINES,
+    parameters: Type.Object({
+      query: Type.String({
+        description:
+          'Datadog RUM query syntax (e.g. "@type:session", "@type:error", "@view.url_path:/checkout"). Leave empty to list recent sessions.',
+      }),
+      from: Type.Optional(
+        Type.String({
+          description:
+            'Start time — relative (15m, 1h, 7d) or ISO 8601. Defaults to project config or 1h.',
+        }),
+      ),
+      to: Type.Optional(
+        Type.String({
+          description: 'End time — relative, ISO 8601, or "now". Defaults to "now".',
+        }),
+      ),
+      limit: Type.Optional(
+        Type.Number({
+          description: 'Max events to return (1-100). Default 25.',
+          minimum: 1,
+          maximum: 100,
+        }),
+      ),
+      sort: Type.Optional(
+        StringEnum(SORT_ENUM, {
+          description: 'Sort order by timestamp. Default "newest".',
+        }),
+      ),
+      service: Type.Optional(
+        Type.String({
+          description:
+            'Service name — overrides project rumService/service default from .pi/datadog.json.',
+        }),
+      ),
+      env: Type.Optional(
+        Type.String({
+          description: 'Environment — overrides project default from .pi/datadog.json.',
+        }),
+      ),
+      applicationId: Type.Optional(
+        Type.String({
+          description:
+            'RUM application id (@application.id) — overrides project rumApplicationId default.',
+        }),
+      ),
+    }),
+
+    async execute(
+      _toolCallId: string,
+      params: {
+        query: string;
+        from?: string;
+        to?: string;
+        limit?: number;
+        sort?: (typeof SORT_ENUM)[number];
+        service?: string;
+        env?: string;
+        applicationId?: string;
+      },
+      _signal?: AbortSignal,
+      _onUpdate?: unknown,
+      ctx?: { cwd: string },
+    ) {
+      // Ensure .env is loaded in case the tool runs before session_start.
+      if (ctx?.cwd) loadDotEnv(ctx.cwd);
+
+      const credentials = getCredentials();
+      if (!credentials) {
+        const status = getCredentialStatus();
+        const missing = [
+          !status.hasApiKey && 'DD_API_KEY',
+          !status.hasAppKey && 'DD_APP_KEY',
+        ].filter(Boolean);
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `❌ Missing Datadog credentials: ${missing.join(', ')}.\n\nSet these environment variables to enable Datadog RUM search.`,
+            },
+          ],
+          details: { error: 'missing_credentials', missing } as Record<string, unknown>,
+          isError: true,
+        };
+      }
+
+      // Reload config if not loaded yet (e.g. tool called before session_start)
+      if (!projectConfig && ctx?.cwd) {
+        try {
+          projectConfig = await loadProjectConfig(ctx.cwd);
+        } catch {
+          projectConfig = { site: 'datadoghq.com', defaultTimeRange: '1h' };
+        }
+      }
+
+      const config = projectConfig ?? { site: 'datadoghq.com', defaultTimeRange: '1h' };
+
+      try {
+        const result = await searchRumEvents(params, config, credentials);
+        const summary = formatRumSearchSummary(result);
+
+        // Write the full, untruncated results to a temp file the agent can read,
+        // and return only a compact digest inline to save tokens.
+        let resultsFile: string | undefined;
+        if (result.events.length > 0) {
+          try {
+            const fullContent = formatRumSearchResult(result, {
+              maxAttributesLength: Infinity,
+            });
+            resultsFile = await writeResultsFile(fullContent, 'rum');
+          } catch {
+            // Non-fatal: digest still carries the summary.
+            resultsFile = undefined;
+          }
+        }
+
+        return {
+          content: [{ type: 'text' as const, text: formatRumResultDigest(result, resultsFile) }],
+          details: { ...summary, resultsFile } as Record<string, unknown>,
+        };
+      } catch (err) {
+        const info = describeDatadogError(err);
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `❌ ${info.message}`,
+            },
+          ],
+          details: {
+            error: info.isRateLimit ? 'rate_limited' : 'api_error',
+            code: info.code,
+            message: info.message,
+          } as Record<string, unknown>,
+          isError: true,
+        };
+      }
+    },
+  });
+
   pi.registerCommand('datadog', {
     description: 'Show Datadog configuration and connection status',
     handler: async (
@@ -210,6 +372,8 @@ export default function datadogExtension(pi: ExtensionAPI) {
         if (config.defaultTags?.length) {
           lines.push(`  Default tags: ${config.defaultTags.join(', ')}`);
         }
+        lines.push(`  RUM application: ${config.rumApplicationId ?? '(not set)'}`);
+        lines.push(`  RUM service: ${config.rumService ?? '(not set)'}`);
       } else {
         lines.push('No .pi/datadog.json found — using defaults.');
       }

package/extensions/datadog/output.ts

@@ -7,11 +7,14 @@ import { join } from 'node:path';
  * read freely with the `read` tool, sidestepping the inline truncation that
  * hides long log messages and attributes.
  *
+ * The `prefix` controls the filename stem (e.g. "logs" → `logs-<ts>.md`,
+ * "rum" → `rum-<ts>.md`) so logs and RUM results stay distinguishable on disk.
+ *
  * Returns the absolute path to the written file.
  */
-export async function writeResultsFile(content: string): Promise<string> {
+export async function writeResultsFile(content: string, prefix = 'logs'): Promise<string> {
   const dir = await mkdtemp(join(tmpdir(), 'pi-datadog-'));
-  const path = join(dir, `logs-${Date.now()}.md`);
+  const path = join(dir, `${prefix}-${Date.now()}.md`);
   await writeFile(path, content, 'utf-8');
   return path;
 }

package/extensions/datadog/rum-client.ts

@@ -0,0 +1,130 @@
+import { v2 } from '@datadog/datadog-api-client';
+import type { DatadogCredentials, DatadogProjectConfig } from './config.js';
+import { createConfiguration, resolveTime } from './client.js';
+
+export interface RumSearchParams {
+  query: string;
+  from?: string;
+  to?: string;
+  limit?: number;
+  sort?: 'newest' | 'oldest';
+  service?: string;
+  env?: string;
+  applicationId?: string;
+}
+
+export interface RumEvent {
+  id: string;
+  /** RUM event type (session, view, action, error, …) from the event attributes. */
+  eventType: string;
+  timestamp: string;
+  service: string;
+  tags: string[];
+  attributes: Record<string, unknown>;
+}
+
+export interface RumSearchResult {
+  events: RumEvent[];
+  totalCount: number;
+  query: string;
+  from: string;
+  to: string;
+  cursor?: string;
+}
+
+/**
+ * Builds the full RUM query by merging the user query with config defaults.
+ *
+ * Defaults to session events (`@type:session`) unless the query already scopes
+ * `@type`, so views/actions/errors stay reachable. Application, service, env,
+ * and tag defaults are merged the same way as the logs client, skipping any
+ * dimension the user already constrained.
+ */
+export function buildRumQuery(params: RumSearchParams, config: DatadogProjectConfig): string {
+  const parts: string[] = [];
+  if (params.query.trim().length > 0) parts.push(params.query);
+
+  if (!params.query.includes('@type:')) {
+    parts.push('@type:session');
+  }
+
+  const applicationId = params.applicationId ?? config.rumApplicationId;
+  if (applicationId && !params.query.includes('@application.id:')) {
+    parts.push(`@application.id:${applicationId}`);
+  }
+
+  const service = params.service ?? config.rumService ?? config.service;
+  if (service && !params.query.includes('service:')) {
+    parts.push(`service:${service}`);
+  }
+
+  const env = params.env ?? config.env;
+  if (env && !params.query.includes('env:')) {
+    parts.push(`env:${env}`);
+  }
+
+  if (config.defaultTags) {
+    for (const tag of config.defaultTags) {
+      const tagKey = tag.split(':')[0];
+      if (!params.query.includes(`${tagKey}:`)) {
+        parts.push(tag);
+      }
+    }
+  }
+
+  return parts.join(' ');
+}
+
+/**
+ * Normalizes a raw RUM event from the SDK into a flat, agent-friendly shape.
+ */
+export function normalizeRumEvent(event: v2.RUMEvent): RumEvent {
+  const attrs = event.attributes;
+  const nested = (attrs?.attributes as Record<string, unknown> | undefined) ?? {};
+  const eventType = typeof nested.type === 'string' ? nested.type : 'unknown';
+
+  return {
+    id: event.id ?? 'unknown',
+    eventType,
+    timestamp: attrs?.timestamp?.toISOString() ?? 'unknown',
+    service: attrs?.service ?? 'unknown',
+    tags: attrs?.tags ?? [],
+    attributes: nested,
+  };
+}
+
+/**
+ * Searches Datadog RUM events using the v2 API.
+ */
+export async function searchRumEvents(
+  params: RumSearchParams,
+  config: DatadogProjectConfig,
+  credentials: DatadogCredentials,
+): Promise<RumSearchResult> {
+  const fullQuery = buildRumQuery(params, config);
+  const fromTime = resolveTime(params.from ?? config.defaultTimeRange);
+  const toTime = resolveTime(params.to ?? 'now');
+  const limit = Math.min(params.limit ?? 25, 100);
+  const sortOrder = params.sort === 'oldest' ? 'timestamp' : '-timestamp';
+
+  const api = new v2.RUMApi(createConfiguration(credentials, config.site));
+
+  const response = await api.listRUMEvents({
+    filterQuery: fullQuery,
+    filterFrom: fromTime,
+    filterTo: toTime,
+    pageLimit: limit,
+    sort: sortOrder as v2.RUMSort,
+  });
+
+  const events = (response.data ?? []).map(normalizeRumEvent);
+
+  return {
+    events,
+    totalCount: events.length,
+    query: fullQuery,
+    from: fromTime.toISOString(),
+    to: toTime.toISOString(),
+    cursor: response.meta?.page?.after,
+  };
+}

package/extensions/datadog/rum-format.ts

@@ -0,0 +1,188 @@
+import type { RumEvent, RumSearchResult } from './rum-client.js';
+
+const MAX_ATTRIBUTES_LENGTH = 300;
+
+export interface RumFormatOptions {
+  /** Max attributes JSON length before truncation. Use Infinity to disable. */
+  maxAttributesLength?: number;
+}
+
+/**
+ * Truncates a string to the given max length, appending "…" if truncated.
+ * A maxLength of Infinity disables truncation.
+ */
+function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength - 1)}…`;
+}
+
+function getTypeIcon(eventType: string): string {
+  switch (eventType.toLowerCase()) {
+    case 'error':
+      return '🔴';
+    case 'session':
+      return '👤';
+    case 'view':
+      return '📄';
+    case 'action':
+      return '🖱️';
+    case 'long_task':
+    case 'resource':
+      return '📦';
+    default:
+      return '⚪';
+  }
+}
+
+/** Reads a dotted-ish nested value (e.g. session.id) from the attribute bag. */
+function readNested(
+  attributes: Record<string, unknown>,
+  group: string,
+  key: string,
+): string | undefined {
+  const obj = attributes[group];
+  if (typeof obj === 'object' && obj !== null && key in obj) {
+    const value = (obj as Record<string, unknown>)[key];
+    if (value !== undefined && value !== null) return String(value);
+  }
+  return undefined;
+}
+
+function formatRumEvent(event: RumEvent, index: number, opts: Required<RumFormatOptions>): string {
+  const icon = getTypeIcon(event.eventType);
+  const header = `### ${index + 1}. ${icon} \`${event.eventType}\` — ${event.timestamp}`;
+
+  const lines: string[] = [header];
+
+  if (event.service !== 'unknown') lines.push(`**Service:** ${event.service}`);
+
+  const sessionId = readNested(event.attributes, 'session', 'id');
+  if (sessionId) lines.push(`**Session:** ${sessionId}`);
+
+  const viewUrl =
+    readNested(event.attributes, 'view', 'url') ?? readNested(event.attributes, 'view', 'url_path');
+  if (viewUrl) lines.push(`**View:** ${viewUrl}`);
+
+  const attrKeys = Object.keys(event.attributes);
+  if (attrKeys.length > 0) {
+    const attrStr = truncate(JSON.stringify(event.attributes, null, 2), opts.maxAttributesLength);
+    lines.push(`**Attributes:**\n\`\`\`json\n${attrStr}\n\`\`\``);
+  }
+
+  if (event.tags.length > 0) {
+    lines.push(`**Tags:** ${event.tags.map((t) => `\`${t}\``).join(', ')}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Formats the RUM search result for LLM consumption.
+ *
+ * By default attributes are truncated for a concise inline view. Pass
+ * `{ maxAttributesLength: Infinity }` to render the complete, untruncated
+ * result (e.g. for writing to a temp file).
+ */
+export function formatRumSearchResult(
+  result: RumSearchResult,
+  opts: RumFormatOptions = {},
+): string {
+  const resolved: Required<RumFormatOptions> = {
+    maxAttributesLength: opts.maxAttributesLength ?? MAX_ATTRIBUTES_LENGTH,
+  };
+  const lines: string[] = [];
+
+  lines.push(`## Datadog RUM Event Search Results`);
+  lines.push('');
+  lines.push(`**Query:** \`${result.query}\``);
+  lines.push(`**Time range:** ${result.from} → ${result.to}`);
+  lines.push(`**Results:** ${result.totalCount} events returned`);
+
+  if (result.cursor) {
+    lines.push(`**Pagination:** More results available (cursor present)`);
+  }
+
+  lines.push('');
+
+  if (result.events.length === 0) {
+    lines.push('No RUM events found matching the query.');
+    return lines.join('\n');
+  }
+
+  lines.push('---');
+  lines.push('');
+
+  for (let i = 0; i < result.events.length; i++) {
+    lines.push(formatRumEvent(result.events[i], i, resolved));
+    if (i < result.events.length - 1) lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Builds a compact, token-light digest of a RUM search result for inline tool
+ * output. The full per-entry detail lives in the temp file referenced by
+ * `resultsFile`; this just gives the agent enough to decide whether to read it.
+ */
+export function formatRumResultDigest(result: RumSearchResult, resultsFile?: string): string {
+  const lines: string[] = [];
+  lines.push(
+    `## Datadog RUM Search — ${result.totalCount} RUM event${result.totalCount === 1 ? '' : 's'}`,
+  );
+  lines.push(`**Query:** \`${result.query}\``);
+  lines.push(`**Time range:** ${result.from} → ${result.to}`);
+
+  if (result.events.length === 0) {
+    lines.push('');
+    lines.push('No RUM events found matching the query.');
+    return lines.join('\n');
+  }
+
+  const summary = formatRumSearchSummary(result);
+  const breakdown = Object.entries(summary.typeBreakdown)
+    .map(([type, count]) => `${type}: ${count}`)
+    .join(', ');
+  if (breakdown) lines.push(`**Types:** ${breakdown}`);
+  if (summary.services.length > 0) lines.push(`**Services:** ${summary.services.join(', ')}`);
+  if (result.cursor) lines.push(`**Pagination:** more results available (cursor present)`);
+
+  if (resultsFile) {
+    lines.push('');
+    lines.push(
+      `📄 **Full results** (complete event attributes): \`${resultsFile}\`\nUse the \`read\` tool on this file to view every RUM event.`,
+    );
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Formats a summary of the RUM search result for tool details.
+ */
+export function formatRumSearchSummary(result: RumSearchResult): {
+  totalCount: number;
+  query: string;
+  timeRange: { from: string; to: string };
+  typeBreakdown: Record<string, number>;
+  services: string[];
+  hasCursor: boolean;
+} {
+  const typeBreakdown: Record<string, number> = {};
+  const services = new Set<string>();
+
+  for (const event of result.events) {
+    const type = event.eventType.toLowerCase();
+    typeBreakdown[type] = (typeBreakdown[type] ?? 0) + 1;
+    if (event.service !== 'unknown') services.add(event.service);
+  }
+
+  return {
+    totalCount: result.totalCount,
+    query: result.query,
+    timeRange: { from: result.from, to: result.to },
+    typeBreakdown,
+    services: [...services],
+    hasCursor: Boolean(result.cursor),
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-datadog",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Datadog log search tools for pi — query production logs with project-aware context",
   "keywords": [
     "pi-package",