@lov3kaizen/agentsea-debugger 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 lovekaizen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,364 @@
+# @lov3kaizen/agentsea-debugger
+
+AI Agent debugger with step-through execution, decision tree visualization, checkpoint replay, and what-if scenario testing.
+
+## Features
+
+- **Step-through Debugging**: Pause execution at breakpoints and step through agent actions
+- **Execution Recording**: Record complete agent sessions for later analysis
+- **Checkpoint System**: Create and restore checkpoints at any point in execution
+- **Replay Engine**: Replay recordings with modifications to explore alternatives
+- **Failure Analysis**: Automatic root cause analysis with recommendations
+- **What-If Scenarios**: Test alternative paths without re-running the agent
+- **Decision Tree Visualization**: Visualize agent decision points as trees
+- **Flow Graph Visualization**: See execution flow as a graph
+- **Storage Adapters**: File-based and in-memory storage options
+
+## Installation
+
+```bash
+pnpm add @lov3kaizen/agentsea-debugger
+```
+
+## Quick Start
+
+```typescript
+import {
+  Debugger,
+  BreakpointHelpers,
+} from '@lov3kaizen/agentsea-debugger';
+
+// Create debugger
+const debugger = new Debugger();
+
+// Attach to agent
+debugger.attach(agent);
+
+// Set breakpoints
+debugger.setBreakpoint(BreakpointHelpers.onTool('search'));
+debugger.setBreakpoint(BreakpointHelpers.onError());
+
+// Start session
+const session = await debugger.startSession();
+
+// Execute agent...
+await agent.execute('Hello');
+
+// Get recording
+const recording = await debugger.endSession();
+```
+
+## Core Concepts
+
+### Debugger
+
+The main entry point for debugging agents:
+
+```typescript
+import { Debugger } from '@lov3kaizen/agentsea-debugger';
+
+const debugger = new Debugger({
+  maxSteps: 1000,
+  recording: {
+    enabled: true,
+    includePrompts: true,
+    includeResponses: true,
+  },
+});
+
+// Attach to agent
+debugger.attach({
+  id: 'my-agent',
+  name: 'My Agent',
+  model: 'gpt-4',
+});
+
+// Start debugging
+const session = await debugger.startSession();
+```
+
+### Breakpoints
+
+Set breakpoints to pause execution at specific points:
+
+```typescript
+import { BreakpointHelpers } from '@lov3kaizen/agentsea-debugger';
+
+// Break on specific tool
+debugger.setBreakpoint(BreakpointHelpers.onTool('search'));
+
+// Break on any error
+debugger.setBreakpoint(BreakpointHelpers.onError());
+
+// Break on decisions
+debugger.setBreakpoint(BreakpointHelpers.onDecision());
+
+// Break on low confidence
+debugger.setBreakpoint(BreakpointHelpers.onLowConfidence(0.5));
+
+// Custom breakpoint
+debugger.setBreakpoint(BreakpointHelpers.custom(
+  (ctx) => ctx.step.type === 'tool-call' && ctx.step.toolCall?.name === 'delete',
+  'Break on delete operations'
+));
+```
+
+### Recording
+
+Record agent execution for later analysis:
+
+```typescript
+import { Recorder } from '@lov3kaizen/agentsea-debugger';
+
+const recorder = new Recorder({
+  includePrompts: true,
+  includeResponses: true,
+  autoSnapshot: true,
+  snapshotInterval: 10,
+});
+
+// Start recording
+recorder.start('my-agent', initialState);
+
+// Record steps
+recorder.recordStep(step, state);
+
+// Create checkpoint
+recorder.createCheckpoint('Before API call');
+
+// Stop and get recording
+const recording = recorder.stop();
+```
+
+### Replay
+
+Replay recordings with modifications:
+
+```typescript
+import { ReplayEngine } from '@lov3kaizen/agentsea-debugger';
+
+const replay = new ReplayEngine();
+
+// Start replay
+const session = await replay.start(recording, {
+  speed: 'normal',
+  modifications: [
+    { stepIndex: 5, type: 'modify', data: { output: 'alternative result' } },
+  ],
+});
+
+// Listen to events
+replay.on('step:replayed', (step, state) => {
+  console.log(`Replayed step ${step.index}`);
+});
+
+// Control playback
+replay.pause();
+replay.resume();
+replay.setSpeed('fast');
+```
+
+### Failure Analysis
+
+Automatically analyze failed executions:
+
+```typescript
+import { FailureAnalyzer } from '@lov3kaizen/agentsea-debugger';
+
+const analyzer = new FailureAnalyzer();
+
+// Analyze a failed recording
+const analysis = analyzer.analyze(recording);
+
+console.log('Root Cause:', analysis.rootCause);
+console.log('Severity:', analysis.severity);
+console.log('Recommendations:', analysis.recommendations);
+```
+
+### What-If Scenarios
+
+Explore alternative execution paths:
+
+```typescript
+import { WhatIfEngine } from '@lov3kaizen/agentsea-debugger';
+
+const whatIf = new WhatIfEngine();
+
+// Create scenario
+const scenario = whatIf.createScenario({
+  name: 'What if search succeeded?',
+  recordingId: recording.id,
+  modifications: [
+    {
+      stepIndex: 3,
+      type: 'modify',
+      data: {
+        toolCall: {
+          id: 'tool_1',
+          name: 'search',
+          result: 'Success!',
+          success: true,
+        },
+      },
+    },
+  ],
+});
+
+// Run scenario
+const result = await whatIf.runScenario(scenario.id, recording);
+
+// Compare with original
+const comparison = whatIf.compare(recording, result);
+```
+
+### Visualization
+
+Generate decision trees and flow graphs:
+
+```typescript
+import {
+  DecisionTreeBuilder,
+  FlowGraphBuilder,
+} from '@lov3kaizen/agentsea-debugger';
+
+// Build decision tree
+const treeBuilder = new DecisionTreeBuilder();
+const tree = treeBuilder.build(recording);
+
+// Export as Mermaid
+console.log(treeBuilder.toMermaid());
+
+// Build flow graph
+const graphBuilder = new FlowGraphBuilder();
+const graph = graphBuilder.build(recording);
+
+// Export as DOT (Graphviz)
+console.log(graphBuilder.toDOT());
+```
+
+### Storage
+
+Store and retrieve recordings:
+
+```typescript
+import { FileStorage, MemoryStorage } from '@lov3kaizen/agentsea-debugger';
+
+// File-based storage
+const fileStorage = new FileStorage({
+  basePath: './debug-sessions',
+  fs: nodeFs, // Node.js fs/promises wrapper
+});
+
+// In-memory storage
+const memoryStorage = new MemoryStorage({
+  maxRecordings: 100,
+  maxSizeBytes: 50 * 1024 * 1024, // 50MB
+});
+
+// Save recording
+await storage.save(recording);
+
+// Load recording
+const loaded = await storage.load(recording.id);
+
+// List recordings
+const recordings = await storage.list();
+```
+
+## AgentSea Integration
+
+Use the high-level `AgentDebugger` for seamless integration:
+
+```typescript
+import { AgentDebugger, MemoryStorage } from '@lov3kaizen/agentsea-debugger';
+
+const debugger = new AgentDebugger({
+  storage: new MemoryStorage(),
+  autoSave: true,
+});
+
+// Set breakpoints
+debugger.breakOnTool('search');
+debugger.breakOnError();
+
+// Start session
+await debugger.startSession({
+  agentId: 'my-agent',
+  agentName: 'My Agent',
+  model: 'gpt-4',
+  messages: [],
+  tools: ['search'],
+});
+
+// Get middleware for step tracking
+const middleware = debugger.getMiddleware();
+
+// Track steps
+middleware.onInput('User question');
+middleware.onToolCall({ name: 'search', arguments: { query: 'test' } });
+middleware.onToolResult({ id: 'tool_1', name: 'search', result: 'Found!', success: true });
+middleware.onResponse('Here is the answer');
+
+// End session
+const recording = await debugger.endSession();
+
+// Analyze if failed
+if (recording.status === 'failed') {
+  const analysis = debugger.analyzeFailure(recording);
+  console.log(analysis.recommendations);
+}
+```
+
+## API Reference
+
+### Core
+
+- `Debugger` - Main debugger class
+- `DebugSessionManager` - Session management
+- `BreakpointManager` - Breakpoint management
+- `Inspector` - State inspection
+
+### Recording
+
+- `Recorder` - Execution recording
+- `SnapshotManager` - State snapshots
+- `CheckpointManager` - Checkpoint management
+- `Timeline` - Event timeline
+
+### Replay
+
+- `ReplayEngine` - Replay execution
+- `ReplayController` - Playback control
+- `StateRestorer` - State restoration
+
+### Visualization
+
+- `DecisionTreeBuilder` - Decision tree generation
+- `FlowGraphBuilder` - Flow graph generation
+
+### Analysis
+
+- `FailureAnalyzer` - Failure root cause analysis
+- `WhatIfEngine` - What-if scenario testing
+
+### Storage
+
+- `FileStorage` - File-based storage
+- `MemoryStorage` - In-memory storage
+
+### Integration
+
+- `AgentDebugger` - High-level debugger wrapper
+- `DebugMiddleware` - Middleware for agents
+
+## Examples
+
+See the `examples/` directory for complete examples:
+
+- `basic-debugging.ts` - Core debugging functionality
+- `replay-and-analysis.ts` - Replay and failure analysis
+- `agentsea-integration.ts` - AgentSea integration
+
+## License
+
+MIT

package/dist/Recorder-Dc9qR2V2.d.ts

@@ -0,0 +1,138 @@
+import { EventEmitter } from 'eventemitter3';
+import { q as TimelineEvent, m as Recording, E as ExecutionStep, p as Snapshot, C as Checkpoint, s as RecorderConfig, t as RecordingStorageAdapter, A as AgentState } from './recording.types-Ck7pbikw.js';
+
+interface TimelineEventOptions {
+    id?: string;
+    type: string;
+    timestamp?: number;
+    stepIndex: number;
+    description: string;
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+}
+interface TimelineMarker {
+    id: string;
+    name: string;
+    timestamp: number;
+    stepIndex: number;
+    color?: string;
+    description?: string;
+}
+interface TimelineSegment {
+    id: string;
+    startStep: number;
+    endStep: number;
+    startTime: number;
+    endTime: number;
+    name: string;
+    type: string;
+}
+interface TimelineFilterOptions {
+    types?: string[];
+    stepRange?: {
+        min?: number;
+        max?: number;
+    };
+    timeRange?: {
+        after?: number;
+        before?: number;
+    };
+    search?: string;
+}
+interface TimelineStats {
+    totalEvents: number;
+    eventsByType: Record<string, number>;
+    totalDurationMs: number;
+    avgEventDurationMs: number;
+    firstEventTime?: number;
+    lastEventTime?: number;
+}
+declare class Timeline {
+    private events;
+    private eventOrder;
+    private markers;
+    private segments;
+    addEvent(options: TimelineEventOptions): TimelineEvent;
+    getEvent(id: string): TimelineEvent | undefined;
+    getEvents(): TimelineEvent[];
+    filterEvents(options: TimelineFilterOptions): TimelineEvent[];
+    getEventsInRange(startStep: number, endStep: number): TimelineEvent[];
+    getEventsByType(type: string): TimelineEvent[];
+    getEventAtStep(stepIndex: number): TimelineEvent | undefined;
+    addMarker(options: Omit<TimelineMarker, 'id' | 'timestamp'> & {
+        timestamp?: number;
+    }): TimelineMarker;
+    getMarkers(): TimelineMarker[];
+    getMarkerAtStep(stepIndex: number): TimelineMarker | undefined;
+    removeMarker(id: string): boolean;
+    addSegment(options: Omit<TimelineSegment, 'id'>): TimelineSegment;
+    getSegments(): TimelineSegment[];
+    getSegmentForStep(stepIndex: number): TimelineSegment | undefined;
+    removeSegment(id: string): boolean;
+    getStats(): TimelineStats;
+    getDurationBetween(startStep: number, endStep: number): number;
+    format(): string;
+    clear(): void;
+    get count(): number;
+    export(): {
+        events: TimelineEvent[];
+        markers: TimelineMarker[];
+        segments: TimelineSegment[];
+    };
+    import(data: {
+        events?: TimelineEvent[];
+        markers?: TimelineMarker[];
+        segments?: TimelineSegment[];
+    }): void;
+}
+declare function createTimeline(): Timeline;
+
+interface RecorderEvents {
+    'recording:started': (recordingId: string) => void;
+    'recording:stopped': (recording: Recording) => void;
+    'recording:paused': () => void;
+    'recording:resumed': () => void;
+    'step:recorded': (step: ExecutionStep) => void;
+    'snapshot:created': (snapshot: Snapshot) => void;
+    'checkpoint:created': (checkpoint: Checkpoint) => void;
+    error: (error: Error) => void;
+}
+type RecordingState = 'idle' | 'recording' | 'paused' | 'stopped';
+declare class Recorder extends EventEmitter<RecorderEvents> {
+    private config;
+    private state;
+    private recordingId?;
+    private agentId?;
+    private agentName?;
+    private steps;
+    private startedAt;
+    private initialState?;
+    private currentState?;
+    private snapshots;
+    private checkpoints;
+    private timeline;
+    private storage?;
+    private estimatedSize;
+    constructor(config?: Partial<RecorderConfig>, storage?: RecordingStorageAdapter);
+    start(agentId: string, initialState: AgentState, agentName?: string): string;
+    stop(): Recording;
+    pause(): void;
+    resume(): void;
+    recordStep(step: ExecutionStep, state: AgentState): boolean;
+    createCheckpoint(name: string, description?: string): Checkpoint | undefined;
+    getState(): RecordingState;
+    getRecordingId(): string | undefined;
+    getStepsCount(): number;
+    getEstimatedSize(): number;
+    getTimeline(): Timeline;
+    getSnapshots(): Snapshot[];
+    getCheckpoints(): Checkpoint[];
+    save(): Promise<void>;
+    private filterStep;
+    private getStepDescription;
+    private buildRecording;
+    private buildMetadata;
+}
+declare function createRecorder(config?: Partial<RecorderConfig>, storage?: RecordingStorageAdapter): Recorder;
+
+export { Recorder as R, Timeline as T, type RecorderEvents as a, createTimeline as b, createRecorder as c, type TimelineEventOptions as d, type TimelineMarker as e, type TimelineSegment as f, type TimelineFilterOptions as g, type TimelineStats as h };

package/dist/ReplayEngine-Dyyqy5bw.d.ts

@@ -0,0 +1,54 @@
+import { EventEmitter } from 'eventemitter3';
+import { E as ExecutionStep, A as AgentState, m as Recording } from './recording.types-Ck7pbikw.js';
+import { b as ReplaySession, f as ReplayResult, g as ReplayDifference, c as ReplayConfig, a as ReplaySpeed, d as ReplayModification } from './replay.types-C9hJizI-.js';
+
+interface ReplayEngineEvents {
+    'replay:started': (session: ReplaySession) => void;
+    'replay:paused': (session: ReplaySession) => void;
+    'replay:resumed': (session: ReplaySession) => void;
+    'replay:stopped': (session: ReplaySession) => void;
+    'replay:completed': (result: ReplayResult) => void;
+    'step:replayed': (step: ExecutionStep, state: AgentState) => void;
+    'step:modified': (original: ExecutionStep, modified: ExecutionStep) => void;
+    'divergence:detected': (differences: ReplayDifference[]) => void;
+    error: (error: Error) => void;
+}
+interface ReplayOptions {
+    speed?: ReplaySpeed;
+    startStep?: number;
+    endStep?: number;
+    modifications?: ReplayModification[];
+    executeTools?: boolean;
+    executeLLM?: boolean;
+    onToolCall?: (step: ExecutionStep) => Promise<unknown>;
+    onLLMCall?: (step: ExecutionStep) => Promise<string>;
+}
+declare class ReplayEngine extends EventEmitter<ReplayEngineEvents> {
+    private config;
+    private sessions;
+    private currentSession?;
+    private stateRestorer;
+    private controller?;
+    private isRunning;
+    constructor(config?: Partial<ReplayConfig>);
+    start(recording: Recording, options?: ReplayOptions): ReplaySession;
+    private runReplay;
+    private executeStep;
+    private updateState;
+    private applyModification;
+    private compareResults;
+    private shouldPause;
+    private getSpeedMultiplier;
+    private getStepDelay;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    setSpeed(speed: ReplaySpeed): void;
+    jumpToStep(stepIndex: number): void;
+    getSession(): ReplaySession | undefined;
+    getSessionById(id: string): ReplaySession | undefined;
+    getSessions(): ReplaySession[];
+}
+declare function createReplayEngine(config?: Partial<ReplayConfig>): ReplayEngine;
+
+export { ReplayEngine as R, type ReplayEngineEvents as a, type ReplayOptions as b, createReplayEngine as c };

package/dist/analysis/index.d.ts

@@ -0,0 +1,4 @@
+export { A as AnalysisOptions, B as BatchScenarioOptions, F as FailureAnalyzer, d as FailurePattern, S as ScenarioOptions, e as StepAnalysis, W as WhatIfEngine, a as WhatIfEngineEvents, b as createFailureAnalyzer, c as createWhatIfEngine } from '../index-DRrKPSo9.js';
+import 'eventemitter3';
+import '../recording.types-Ck7pbikw.js';
+import '../replay.types-C9hJizI-.js';