npm package: @principal-ai/agent-monitoring
Description: Agent event monitoring and processing system
Author: Principal AI
Latest version: 0.3.12

# @principal-ai/agent-monitoring

Agent event monitoring and processing system for AI coding assistants.

## Overview

This package provides a unified monitoring and event processing system for various AI coding assistants including Claude, Cline, and OpenCode. It offers:

- Normalized event types across different agents
- Path normalization and file operation detection
- Event processors for each supported agent
- Hook configuration utilities
- Type-safe event handling

## Installation

```bash
bun install @principal-ai/agent-monitoring
```

## Features

### Supported Agents

- Claude (Anthropic's CLI)
- Cline (VS Code extension)
- OpenCode (Open source CLI)
- Droid (Factory AI)

### Event Processing

- Unified event normalization across agents
- Tool usage tracking
- File operation detection
- Path context analysis

### Hook Configuration

- Agent-specific hook types
- Configurable matchers
- Event filtering

## Usage

```typescript
import {
  SupportedAgent,
  ClaudeEventProcessor,
  AgentEventPipeline,
  CLAUDE_HOOK_TYPES,
} from "@principal-ai/agent-monitoring";

// Process a raw Claude event
const processor = new ClaudeEventProcessor();
const universalEvent = processor.normalize(rawClaudeHookData);

// Or use the full pipeline with path normalization
const pipeline = new AgentEventPipeline(pathAdapter, {
  metrics: {
    onEventProcessed: (event, durationMs, agent) => {
      console.log(`Processed ${agent} event in ${durationMs}ms`);
    },
  },
});

const normalizedEvent = await pipeline.processRawEvent(
  SupportedAgent.CLAUDE,
  rawClaudeHookData
);

// Access normalized data
console.log(normalizedEvent.repository?.branch);
console.log(normalizedEvent.files?.map(f => f.displayPath));
```

## API Reference

### Types

- `SupportedAgent` - Enum of supported AI agents (claude, cline, opencode, droid)
- `UniversalAgentSessionEvent` - Agent-normalized event format (intermediate)
- `RepoNormalizedUniversalAgentSessionEvent` - Final event format with repository context
- `NormalizedPathInfo` - File path with repository metadata and context
- `PathContext` - File classification enum (REPO_FILE, SYSTEM_FILE, USER_FILE, TEMP_FILE, CONFIG_FILE)
- `FileOperation` - Operation type enum (READ, WRITE, CREATE, DELETE, EDIT, SEARCH, LIST)

### Event Processors

- `ClaudeEventProcessor` - Normalize Claude hook events
- `ClineEventProcessor` - Normalize Cline hook events
- `OpenCodeEventProcessor` - Normalize OpenCode hook events
- `DroidEventProcessor` - Normalize Droid hook events

### Pipeline

- `AgentEventPipeline` - Full processing pipeline with path normalization
- `PathNormalizationService` - Service for enriching paths with repository context

### Hook Types

- `CLAUDE_HOOK_TYPES` - Available Claude hook event types
- `CLINE_HOOK_TYPES` - Available Cline hook event types
- `OPENCODE_HOOK_TYPES` - Available OpenCode hook event types
- `DROID_HOOK_TYPES` - Available Droid hook event types

### Utility Functions

- `getAvailableHookTypes(agent)` - Get hook types for a specific agent
- `getHookTypeDisplayName(hookType)` - Get human-readable hook type name
- `getHookTypeDescription(hookType)` - Get hook type description
- `isToolEvent(event)` - Check if event is a tool use event
- `isStopEvent(event)` - Check if event is a stop event
- `getEventFilePaths(event)` - Extract file paths from an event
- `classifyPath(path)` - Classify a file path into a PathContext

## License

MIT