Add file level filtering

README.md

@@ -444,13 +444,15 @@ providerOptions: {
 conversationsPerScenario: 3,  // run 3 independent conversations per scenario
 maxTurns: 8,                  // max user↔agent exchanges per conversation
 concurrency: 20,              // max parallel LLM calls across all scenarios
+debounceMs: 0,                // optional delay (ms) between scenario starts
 ```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `conversationsPerScenario` | `number` | `3` | How many independent conversations to run per scenario. More conversations = more statistical confidence, but more LLM cost |
 | `maxTurns` | `number` | `8` | Upper bound on user↔agent exchanges. The simulated user can stop earlier if the goal is met |
 | `concurrency` | `number` | `20` | Max parallel LLM calls. Controls both simulation and evaluation parallelism. Lower this if you're hitting rate limits |
+| `debounceMs` | `number` | `0` | Minimum delay in milliseconds between scenario starts. Useful for avoiding rate limits when running many scenarios |
 
 Both `conversationsPerScenario` and `maxTurns` can be overridden per-scenario.
 
@@ -960,6 +962,9 @@ npx agentest run --cwd ./packages/my-agent
 npx agentest run --scenario "booking"
 npx agentest run --scenario "cancel"
 
+# Filter by file path (case-insensitive substring match)
+npx agentest run --file "auth.sim.ts"
+
 # Print full conversation transcripts
 npx agentest run --verbose
 

docs/guide/configuration.md

@@ -281,13 +281,15 @@ Control how many conversations to run and how they're executed:
 conversationsPerScenario: 3,  // run 3 independent conversations per scenario
 maxTurns: 8,                  // max user↔agent exchanges per conversation
 concurrency: 20,              // max parallel LLM calls across all scenarios
+debounceMs: 0,                // optional delay (ms) between scenario starts
 ```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `conversationsPerScenario` | `number` | `3` | How many independent conversations to run per scenario. More conversations = more statistical confidence, but more LLM cost. |
 | `maxTurns` | `number` | `8` | Upper bound on user↔agent exchanges. The simulated user can stop earlier if the goal is met. |
 | `concurrency` | `number` | `20` | Max parallel LLM calls. Controls both simulation and evaluation parallelism. Lower this if you're hitting rate limits. |
+| `debounceMs` | `number` | `0` | Minimum delay in milliseconds between scenario starts. Useful for avoiding rate limits when running many scenarios. |
 
 Both `conversationsPerScenario` and `maxTurns` can be overridden per-scenario:
 

docs/reference/cli.md

@@ -19,6 +19,7 @@ npx agentest run [options]
 | `--config <path>` | `-c` | Path to config file (default: auto-detect) |
 | `--cwd <path>` | | Working directory (default: current directory) |
 | `--scenario <name>` | `-s` | Filter scenarios by name (case-insensitive substring match) |
+| `--file <path>` | | Filter scenarios by file path (case-insensitive substring match) |
 | `--verbose` | `-v` | Print full conversation transcripts |
 | `--watch` | `-w` | Watch mode — re-run on file changes |
 
@@ -39,6 +40,10 @@ npx agentest run --cwd ./packages/my-agent
 npx agentest run --scenario "booking"
 npx agentest run --scenario "cancel"
 
+# Filter by file path
+npx agentest run --file "auth.sim.ts"
+npx agentest run --file "booking"
+
 # Print full conversation transcripts
 npx agentest run --verbose
 
@@ -48,6 +53,9 @@ npx agentest run -w
 
 # Combine flags
 npx agentest run --watch --verbose --scenario "booking"
+
+# Combine file and scenario filters
+npx agentest run --file "auth" --scenario "login"
 ```
 
 ### `agentest show-prompts`

docs/reference/config-api.md

@@ -110,6 +110,14 @@ Maximum turns per conversation.
 
 Max parallel LLM calls.
 
+### `debounceMs`
+
+**Type:** `number`
+
+**Default:** `0`
+
+Minimum delay in milliseconds between scenario starts. Set this to avoid rate limits when running many scenarios (e.g., `debounceMs: 2000` for a 2-second gap).
+
 ## Evaluation
 
 ### `metrics`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentesting/agentest",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "Embedded agent simulation & evaluation framework for Node.js/TypeScript",
   "type": "module",
   "main": "./dist/index.cjs",

src/cli.ts

@@ -33,21 +33,29 @@ program
   .option('-c, --config <path>', 'Path to config file')
   .option('--cwd <dir>', 'Working directory', process.cwd())
   .option('--scenario <name>', 'Run only scenarios matching this name')
+  .option('--file <path>', 'Run only scenarios from files matching this path')
   .option('--verbose', 'Print full conversation transcripts')
   .option('-w, --watch', 'Watch for file changes and re-run')
   .action(
     async (opts: {
       config?: string
       cwd: string
       scenario?: string
+      file?: string
       verbose?: boolean
       watch?: boolean
     }) => {
       const configPath = await resolveConfigPath(opts.cwd, opts.config)
 
       const executeRun = async () => {
         const config = await loadConfig(configPath, opts.cwd)
-        const discoveries = await discoverAndLoad(config, opts.cwd)
+        let discoveries = await discoverAndLoad(config, opts.cwd)
+
+        // Filter by file path if specified
+        if (opts.file) {
+          const fileFilter = opts.file.toLowerCase()
+          discoveries = discoveries.filter((d) => d.file.toLowerCase().includes(fileFilter))
+        }
 
         // Filter by scenario name if specified
         if (opts.scenario) {