@dreki-gg/pi-datadog 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @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
+
+- Return a compact digest inline and write full log entries to a temp file.
+
+  `datadog_logs_search` no longer dumps truncated log entries inline. Instead it returns a token-light digest (result count, status breakdown, services, pagination) plus the path to a temp file containing the complete, untruncated results (full messages and attributes). The agent reads that file with the `read` tool when it needs actual log content — saving context tokens, removing the truncation blind spot, and avoiding extra rate-limited re-queries. Tool guidelines were updated to point at the file.
+
+## 0.2.3
+
+### Patch Changes
+
+- Write full untruncated log search results to a temp file the agent can read.
+
+  The inline `datadog_logs_search` output still truncates long messages and attributes for brevity, but the complete, untruncated results are now also written to a temp file and the path is included in the response. When the agent needs full message content (status codes, paths, stack traces), it can `read` that file instead of re-querying Datadog — avoiding both the truncation blind spot and extra rate-limited requests. Tool guidelines were updated to point at the file.
+
+## 0.2.2
+
+### Patch Changes
+
+- Handle Datadog rate limits gracefully instead of failing on 429s.
+
+  The log search client now enables the Datadog SDK's built-in retry (up to 4 attempts on 429/5xx), which honours the `x-ratelimit-reset` header and waits exactly the window Datadog asks for before retrying. When retries are exhausted, the tool returns a clear, actionable message (distinguishing rate-limit, auth, and other API errors) telling the agent to back off and keep queries narrow/batched rather than firing again immediately. Tool guidelines were updated to reinforce this batching behaviour.
+
+## 0.2.1
+
+### Patch Changes
+
+- Load project-root `.env` files so `DD_API_KEY` / `DD_APP_KEY` defined there are picked up.
+
+  Previously credentials were only read from the process environment, so keys placed in a project's `.env` (without exporting them in the shell) were never found and the extension reported missing credentials. The extension now loads `<cwd>/.env` via Node's built-in `process.loadEnvFile` at session start, before the tool runs, and in the `/datadog` status command. Shell-exported variables still take precedence over `.env` values.
+
 ## 0.2.0
 
 ### Minor 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

@@ -98,16 +98,108 @@ export function buildQuery(params: LogSearchParams, config: DatadogProjectConfig
   return parts.join(' ');
 }
 
-function createApiInstance(credentials: DatadogCredentials, site: string): v2.LogsApi {
+/** Max automatic retry attempts on 429 / 5xx responses. */
+const MAX_RETRIES = 4;
+
+/**
+ * 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,
     },
+    enableRetry: true,
+    maxRetries: MAX_RETRIES,
   });
   configuration.setServerVariables({ site });
+  return configuration;
+}
+
+function createApiInstance(credentials: DatadogCredentials, site: string): v2.LogsApi {
+  return new v2.LogsApi(createConfiguration(credentials, site));
+}
+
+export interface DatadogErrorInfo {
+  /** Human-readable, agent-facing message. */
+  message: string;
+  /** HTTP status code, when the error came from the Datadog API. */
+  code?: number;
+  /** True when the error is a rate-limit (429) after retries were exhausted. */
+  isRateLimit: boolean;
+}
+
+/**
+ * Classifies an error thrown by the Datadog SDK into a clear, actionable message.
+ *
+ * The SDK throws an `ApiException`-shaped object (`{ code, body }`) on non-2xx
+ * responses. A 429 here means retries were already exhausted, so the message
+ * tells the agent to back off and keep queries narrow/batched rather than
+ * firing more requests.
+ */
+export function describeDatadogError(err: unknown): DatadogErrorInfo {
+  const code = extractStatusCode(err);
+  const detail = extractApiMessage(err);
+
+  if (code === 429) {
+    return {
+      code,
+      isRateLimit: true,
+      message:
+        `Rate limited by Datadog (429) after ${MAX_RETRIES} retries${detail ? `: ${detail}` : ''}. ` +
+        'Wait before retrying, and keep queries narrow/batched instead of firing many in quick succession.',
+    };
+  }
 
-  return new v2.LogsApi(configuration);
+  if (code === 401 || code === 403) {
+    return {
+      code,
+      isRateLimit: false,
+      message: `Datadog auth error (${code})${detail ? `: ${detail}` : ''}. Check DD_API_KEY / DD_APP_KEY.`,
+    };
+  }
+
+  if (code !== undefined) {
+    return {
+      code,
+      isRateLimit: false,
+      message: `Datadog API error (${code})${detail ? `: ${detail}` : ''}.`,
+    };
+  }
+
+  return {
+    isRateLimit: false,
+    message: `Datadog API error: ${err instanceof Error ? err.message : String(err)}`,
+  };
+}
+
+function extractStatusCode(err: unknown): number | undefined {
+  if (typeof err === 'object' && err !== null && 'code' in err) {
+    const code = (err as { code: unknown }).code;
+    if (typeof code === 'number') return code;
+  }
+  return undefined;
+}
+
+function extractApiMessage(err: unknown): string | undefined {
+  if (typeof err !== 'object' || err === null || !('body' in err)) return undefined;
+  const body = (err as { body: unknown }).body;
+
+  if (typeof body === 'string') return body || undefined;
+  if (typeof body === 'object' && body !== null && 'errors' in body) {
+    const errors = (body as { errors: unknown }).errors;
+    if (Array.isArray(errors) && errors.length > 0) {
+      return errors.map((e) => String(e)).join('; ');
+    }
+  }
+  return undefined;
 }
 
 function normalizeLogEntry(log: v2.Log): LogEntry {

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/dotenv.ts

@@ -0,0 +1,85 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Loads a project-root `.env` file into `process.env`.
+ *
+ * Primary path uses Node's built-in `process.loadEnvFile` (Node >= 20.12).
+ * When that API is unavailable (older Node, or non-Node runtimes such as the
+ * Bun test runner) it falls back to a minimal inline parser with identical
+ * precedence semantics.
+ *
+ * Precedence follows the dotenv convention: variables already present in the
+ * environment (e.g. exported by the shell) take precedence over `.env` values;
+ * the file only fills in the gaps.
+ *
+ * Returns `true` if a `.env` file was found and loaded, `false` if none exists.
+ * A missing file or any read/parse error is swallowed so a malformed `.env`
+ * never breaks the extension.
+ */
+export function loadDotEnv(cwd: string): boolean {
+  const envPath = join(cwd, '.env');
+
+  if (typeof process.loadEnvFile === 'function') {
+    try {
+      process.loadEnvFile(envPath);
+      return true;
+    } catch (err: unknown) {
+      if (isENOENT(err)) return false;
+      return false;
+    }
+  }
+
+  return loadDotEnvFallback(envPath);
+}
+
+function loadDotEnvFallback(envPath: string): boolean {
+  let raw: string;
+  try {
+    raw = readFileSync(envPath, 'utf-8');
+  } catch (err: unknown) {
+    return isENOENT(err) ? false : false;
+  }
+
+  for (const parsed of parseDotEnv(raw)) {
+    // Existing env wins — only fill in unset keys.
+    if (process.env[parsed.key] === undefined) {
+      process.env[parsed.key] = parsed.value;
+    }
+  }
+  return true;
+}
+
+function parseDotEnv(raw: string): Array<{ key: string; value: string }> {
+  const result: Array<{ key: string; value: string }> = [];
+
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const withoutExport = trimmed.startsWith('export ') ? trimmed.slice('export '.length) : trimmed;
+
+    const eq = withoutExport.indexOf('=');
+    if (eq === -1) continue;
+
+    const key = withoutExport.slice(0, eq).trim();
+    if (!key) continue;
+
+    let value = withoutExport.slice(eq + 1).trim();
+    // Strip matching surrounding quotes.
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    result.push({ key, value });
+  }
+
+  return result;
+}
+
+function isENOENT(err: unknown): boolean {
+  return err instanceof Error && 'code' in err && (err as NodeJS.ErrnoException).code === 'ENOENT';
+}

package/extensions/datadog/format.ts

@@ -3,8 +3,16 @@ import type { LogEntry, LogSearchResult } from './client.js';
 const MAX_MESSAGE_LENGTH = 500;
 const MAX_ATTRIBUTES_LENGTH = 300;
 
+export interface FormatOptions {
+  /** Max message length before truncation. Use Infinity to disable. */
+  maxMessageLength?: number;
+  /** 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;
@@ -14,7 +22,7 @@ function truncate(text: string, maxLength: number): string {
 /**
  * Formats a single log entry as a compact markdown block.
  */
-function formatLogEntry(log: LogEntry, index: number): string {
+function formatLogEntry(log: LogEntry, index: number, opts: Required<FormatOptions>): string {
   const statusIcon = getStatusIcon(log.status);
   const header = `### ${index + 1}. ${statusIcon} \`${log.status}\` — ${log.timestamp}`;
 
@@ -24,12 +32,12 @@ function formatLogEntry(log: LogEntry, index: number): string {
   if (log.host !== 'unknown') lines.push(`**Host:** ${log.host}`);
 
   if (log.message) {
-    lines.push(`**Message:**\n\`\`\`\n${truncate(log.message, MAX_MESSAGE_LENGTH)}\n\`\`\``);
+    lines.push(`**Message:**\n\`\`\`\n${truncate(log.message, opts.maxMessageLength)}\n\`\`\``);
   }
 
   const attrKeys = Object.keys(log.attributes);
   if (attrKeys.length > 0) {
-    const attrStr = truncate(JSON.stringify(log.attributes, null, 2), MAX_ATTRIBUTES_LENGTH);
+    const attrStr = truncate(JSON.stringify(log.attributes, null, 2), opts.maxAttributesLength);
     lines.push(`**Attributes:**\n\`\`\`json\n${attrStr}\n\`\`\``);
   }
 
@@ -51,9 +59,17 @@ function getStatusIcon(status: string): string {
 }
 
 /**
- * Formats the full search result for LLM consumption.
+ * Formats the search result for LLM consumption.
+ *
+ * By default messages and attributes are truncated for a concise inline view.
+ * Pass `{ maxMessageLength: Infinity, maxAttributesLength: Infinity }` to render
+ * the complete, untruncated result (e.g. for writing to a temp file).
  */
-export function formatSearchResult(result: LogSearchResult): string {
+export function formatSearchResult(result: LogSearchResult, opts: FormatOptions = {}): string {
+  const resolved: Required<FormatOptions> = {
+    maxMessageLength: opts.maxMessageLength ?? MAX_MESSAGE_LENGTH,
+    maxAttributesLength: opts.maxAttributesLength ?? MAX_ATTRIBUTES_LENGTH,
+  };
   const lines: string[] = [];
 
   lines.push(`## Datadog Log Search Results`);
@@ -77,13 +93,50 @@ export function formatSearchResult(result: LogSearchResult): string {
   lines.push('');
 
   for (let i = 0; i < result.logs.length; i++) {
-    lines.push(formatLogEntry(result.logs[i], i));
+    lines.push(formatLogEntry(result.logs[i], i, resolved));
     if (i < result.logs.length - 1) lines.push('');
   }
 
   return lines.join('\n');
 }
 
+/**
+ * Builds a compact, token-light digest of a 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 formatResultDigest(result: LogSearchResult, resultsFile?: string): string {
+  const lines: string[] = [];
+  lines.push(
+    `## Datadog Log Search — ${result.totalCount} log${result.totalCount === 1 ? '' : 's'}`,
+  );
+  lines.push(`**Query:** \`${result.query}\``);
+  lines.push(`**Time range:** ${result.from} → ${result.to}`);
+
+  if (result.logs.length === 0) {
+    lines.push('');
+    lines.push('No logs found matching the query.');
+    return lines.join('\n');
+  }
+
+  const summary = formatSearchSummary(result);
+  const breakdown = Object.entries(summary.statusBreakdown)
+    .map(([status, count]) => `${status}: ${count}`)
+    .join(', ');
+  if (breakdown) lines.push(`**Status:** ${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 messages & attributes): \`${resultsFile}\`\nUse the \`read\` tool on this file to view every log entry.`,
+    );
+  }
+
+  return lines.join('\n');
+}
+
 /**
  * Formats a summary of the search result for tool details.
  */

package/extensions/datadog/index.ts

@@ -7,8 +7,16 @@ import {
   getCredentialStatus,
   loadProjectConfig,
 } from './config.js';
-import { searchLogs } from './client.js';
-import { formatSearchResult, formatSearchSummary } from './format.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;
 
@@ -16,13 +24,26 @@ const TOOL_GUIDELINES = [
   'Use `datadog_logs_search` to search production logs in Datadog. It uses Datadog query syntax (e.g. `status:error`, `@http.status_code:500`, `service:my-api`).',
   '`datadog_logs_search` auto-applies project defaults for service and environment from `.pi/datadog.json` — only override when the user explicitly asks for a different service or env.',
   'When `datadog_logs_search` returns many results, summarize the patterns (error types, frequency, affected services) instead of listing every log entry.',
+  'The inline `datadog_logs_search` output is a compact digest (counts, status breakdown, services). The complete log entries — full messages and attributes — are written to a temp file whose path is in the response. To inspect actual log content (status codes, paths, stack traces), use the `read` tool on that file instead of re-querying.',
   'Use appropriate time ranges with `datadog_logs_search`: "15m" for recent issues, "1h" for general debugging, "24h" or "7d" for trend analysis.',
+  "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;
 
   pi.on('session_start', async (_event, ctx) => {
+    // Load project-root .env so DD_API_KEY / DD_APP_KEY defined there are
+    // visible. Shell-exported vars still take precedence.
+    loadDotEnv(ctx.cwd);
     try {
       projectConfig = await loadProjectConfig(ctx.cwd);
     } catch (err) {
@@ -93,6 +114,9 @@ export default function datadogExtension(pi: ExtensionAPI) {
       _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();
@@ -127,23 +151,190 @@ export default function datadogExtension(pi: ExtensionAPI) {
 
       try {
         const result = await searchLogs(params, config, credentials);
-        const formatted = formatSearchResult(result);
         const summary = formatSearchSummary(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.logs.length > 0) {
+          try {
+            const fullContent = formatSearchResult(result, {
+              maxMessageLength: Infinity,
+              maxAttributesLength: Infinity,
+            });
+            resultsFile = await writeResultsFile(fullContent);
+          } catch {
+            // Non-fatal: digest still carries the summary.
+            resultsFile = undefined;
+          }
+        }
+
+        return {
+          content: [{ type: 'text' as const, text: formatResultDigest(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.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: formatted }],
-          details: summary as Record<string, unknown>,
+          content: [{ type: 'text' as const, text: formatRumResultDigest(result, resultsFile) }],
+          details: { ...summary, resultsFile } as Record<string, unknown>,
         };
       } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
+        const info = describeDatadogError(err);
         return {
           content: [
             {
               type: 'text' as const,
-              text: `❌ Datadog API error: ${message}`,
+              text: `❌ ${info.message}`,
             },
           ],
-          details: { error: 'api_error', message } as Record<string, unknown>,
+          details: {
+            error: info.isRateLimit ? 'rate_limited' : 'api_error',
+            code: info.code,
+            message: info.message,
+          } as Record<string, unknown>,
           isError: true,
         };
       }
@@ -160,6 +351,7 @@ export default function datadogExtension(pi: ExtensionAPI) {
         ui: { notify(message: string, level: 'info' | 'warning' | 'error'): void };
       },
     ) => {
+      loadDotEnv(ctx.cwd);
       const credStatus = getCredentialStatus();
       const config = projectConfig ?? (await loadProjectConfig(ctx.cwd).catch(() => null));
 
@@ -180,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

@@ -0,0 +1,20 @@
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Writes the full (untruncated) search results to a temp file the agent can
+ * 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, prefix = 'logs'): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'pi-datadog-'));
+  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.0",
+  "version": "0.3.0",
   "description": "Datadog log search tools for pi — query production logs with project-aware context",
   "keywords": [
     "pi-package",