@testdriverai/agent 7.8.0-canary.10

package/docs/v7/_drafts/progressive-disclosure.mdx

@@ -0,0 +1,230 @@
+# Progressive Disclosure APIs
+
+TestDriver v7 introduces **progressive disclosure** - three levels of API to match your experience and needs.
+
+## Choose Your Level
+
+### 🟢 Beginner: Provision API
+
+**Best for:** Getting started, testing common apps (Chrome, VS Code, Electron)
+
+```javascript
+import { provision } from 'testdriverai/presets';
+
+test('my test', async (context) => {
+  const { testdriver } = await provision('chrome', {
+    url: 'https://example.com'
+  }, context);
+  
+  await testdriver.find('Login').click();
+});
+```
+
+**Why use this:**
+- ✅ Zero configuration
+- ✅ One line setup
+- ✅ Automatic everything (launch, focus, cleanup, recording)
+- ✅ Perfect for beginners
+
+[Learn more →](./PROVISION.md)
+
+---
+
+### 🟡 Intermediate: Hooks API
+
+**Best for:** Power users, custom workflows, manual lifecycle control
+
+```javascript
+import { useTestDriver, useDashcam } from 'testdriverai/vitest/hooks';
+
+test('my test', async (context) => {
+  const client = useTestDriver(context, { os: 'linux' });
+  const dashcam = useDashcam(context, client, {
+    autoStart: true,
+    autoStop: true
+  });
+  
+  await client.find('button').click();
+});
+```
+
+**Why use this:**
+- ✅ Automatic cleanup
+- ✅ Flexible configuration
+- ✅ Control over lifecycle
+- ✅ Works with any application
+
+[Learn more →](./HOOKS.md)
+
+---
+
+### 🔴 Advanced: Core Classes
+
+**Best for:** Full control, non-Vitest frameworks, custom integrations
+
+```javascript
+import { TestDriver, Dashcam } from 'testdriverai/core';
+
+const client = new TestDriver(apiKey, { os: 'linux' });
+await client.auth();
+await client.connect();
+
+const dashcam = new Dashcam(client);
+await dashcam.start();
+
+// Your code
+
+await dashcam.stop();
+await client.disconnect();
+```
+
+**Why use this:**
+- ✅ Complete manual control
+- ✅ No framework dependencies
+- ✅ Works anywhere
+- ✅ Maximum flexibility
+
+[Learn more →](./CORE.md)
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│          🟢 Provision API (Easiest)         │
+│   provision('chrome', options, context)     │
+└─────────────────┬───────────────────────────┘
+                  │
+┌─────────────────▼───────────────────────────┐
+│        🟡 Hooks API (Flexible)              │
+│   useTestDriver(), useDashcam()             │
+└─────────────────┬───────────────────────────┘
+                  │
+┌─────────────────▼───────────────────────────┐
+│    🔴 Core Classes (Full Control)           │
+│   new TestDriver(), new Dashcam()           │
+└─────────────────────────────────────────────┘
+```
+
+Each level builds on the one below it. Choose the highest level that meets your needs.
+
+## Quick Comparison
+
+| Feature | Provision | Hooks | Core |
+|---------|-----------|-------|------|
+| Setup complexity | ⭐ 1 line | ⭐⭐ 2-3 lines | ⭐⭐⭐ 5+ lines |
+| Cleanup | ✅ Automatic | ✅ Automatic | ❌ Manual |
+| Framework requirement | Vitest | Vitest | None |
+| Application support | Chrome, VS Code, Electron | Any | Any |
+| Launch application | ✅ Automatic | ❌ Manual | ❌ Manual |
+| Dashcam recording | ✅ Automatic | ⚡ Optional automatic | ❌ Manual |
+| TypeScript support | ✅ Full | ✅ Full | ✅ Full |
+| Customization | ⚡ Limited | ✅ High | ✅ Complete |
+
+## When to Use Each
+
+### Use Provision API when:
+- ✅ Testing Chrome, VS Code, or Electron
+- ✅ You're a beginner
+- ✅ You want the simplest possible code
+- ✅ You're okay with defaults
+
+### Use Hooks API when:
+- ✅ You need custom application launch
+- ✅ You want automatic cleanup
+- ✅ You're using Vitest
+- ✅ You need fine-grained lifecycle control
+
+### Use Core Classes when:
+- ✅ Not using Vitest
+- ✅ Integrating with other frameworks
+- ✅ Building custom abstractions
+- ✅ Debugging lifecycle issues
+- ✅ Need complete manual control
+
+## Examples
+
+### Simple Chrome Test
+
+**Provision (1 line):**
+```javascript
+const { testdriver } = await provision('chrome', { url }, context);
+```
+
+**Hooks (3 lines):**
+```javascript
+const client = useTestDriver(context);
+await client.exec('sh', 'google-chrome "https://..." &', 30000);
+await client.focusApplication('Google Chrome');
+```
+
+**Core (6+ lines):**
+```javascript
+const client = new TestDriver(apiKey, { os: 'linux' });
+await client.auth();
+await client.connect();
+await client.exec('sh', 'google-chrome "https://..." &', 30000);
+await client.focusApplication('Google Chrome');
+// ... test code ...
+await client.disconnect();
+```
+
+### With Dashcam Recording
+
+**Provision (1 line):**
+```javascript
+const { testdriver, dashcam } = await provision('chrome', { url }, context);
+// Recording automatic!
+```
+
+**Hooks (2 lines):**
+```javascript
+const client = useTestDriver(context);
+const dashcam = useDashcam(context, client, { autoStart: true, autoStop: true });
+```
+
+**Core (7+ lines):**
+```javascript
+const client = new TestDriver(apiKey);
+await client.auth();
+await client.connect();
+const dashcam = new Dashcam(client);
+await dashcam.auth();
+await dashcam.start();
+// ... test code ...
+await dashcam.stop();
+await client.disconnect();
+```
+
+## Migration Path
+
+Start simple, grow as needed:
+
+1. **Start with Provision** - Get tests working quickly
+2. **Move to Hooks** - When you need custom app launch
+3. **Use Core** - Only if you need full control or non-Vitest
+
+You can mix and match in the same project!
+
+## Package Exports
+
+All three APIs are available from the same package:
+
+```javascript
+// Provision API
+import { provision, chrome, vscode, electron } from 'testdriverai/presets';
+
+// Hooks API
+import { useTestDriver, useDashcam } from 'testdriverai/vitest/hooks';
+
+// Core Classes
+import { TestDriver, Dashcam } from 'testdriverai/core';
+```
+
+## See Also
+
+- [Provision API Reference](./PROVISION.md)
+- [Hooks API Reference](./HOOKS.md)
+- [Core Classes Reference](./CORE.md)
+- [Migration Guide](../MIGRATION.md)

package/docs/v7/_drafts/prompt-cache.mdx

@@ -0,0 +1,200 @@
+# Prompt Cache System
+
+## Overview
+
+The TestDriver SDK includes automatic caching of `.ai()` responses. When you use the SDK to execute natural language prompts, the YAML commands generated by the AI are cached locally to improve performance and reduce API calls.
+
+**Caching is enabled by default** and can be controlled per-call using the `cache` parameter.
+
+## How It Works
+
+1. **First Call**: When you call `.ai('click the submit button')` for the first time:
+
+   - The SDK sends the prompt and screenshot to the API
+   - The API returns YAML commands in markdown format
+   - The response is cached to `.testdriver/.cache/{prompt-hash}.yaml`
+
+2. **Subsequent Calls**: When you call `.ai('click the submit button')` again:
+
+   - The SDK checks the cache first
+   - If found, it uses the cached YAML instead of calling the API
+   - You'll see `(using cached response)` in the output
+
+3. **Disable Caching**: Pass `false` as the second parameter:
+   - `.ai('click the submit button', false)` bypasses the cache
+   - Forces a fresh API call and updates the cache
+
+## Cache Location
+
+Cached responses are stored in:
+
+```
+.testdriver/.cache/
+```
+
+Files are named using a combination of:
+
+- Sanitized prompt (first 50 chars, alphanumeric only)
+- MD5 hash of the full prompt for uniqueness
+
+Example:
+
+```
+.testdriver/.cache/click-the-submit-button-a1b2c3d4e5f6.yaml
+```
+
+## Benefits
+
+- **Faster execution**: No API call needed for repeated prompts
+- **Cost savings**: Reduces API usage for repeated operations
+- **Offline testing**: Can rerun tests without network access
+- **Deterministic tests**: Same prompt always produces same commands
+
+## Disabling Cache
+
+To disable caching for a specific `.ai()` call, pass `false` as the second parameter:
+
+```javascript
+// Force fresh API call, bypass cache
+await client.ai("click the submit button", false);
+```
+
+Caching is **enabled by default** (equivalent to passing `true`):
+
+```javascript
+// These are equivalent
+await client.ai("click the submit button");
+await client.ai("click the submit button", true);
+```
+
+## Clearing Cache
+
+To clear all cached prompts:
+
+```bash
+rm -rf .testdriver/.cache/*.yaml
+```
+
+Or programmatically:
+
+```javascript
+const promptCache = require("testdriverai/agent/lib/cache.js");
+promptCache.clearCache();
+```
+
+## Usage Examples
+
+### Basic Usage (Automatic Caching)
+
+```javascript
+const TestDriver = require("testdriverai");
+
+const client = new TestDriver(process.env.TD_API_KEY);
+await client.connect();
+
+// First call - makes API request and caches
+await client.ai("click the login button");
+
+// Second call - uses cache (instant)
+await client.ai("click the login button");
+
+// Force fresh API call, bypass cache
+await client.ai("click the login button", false);
+```
+
+### Check Cache Status
+
+```javascript
+const promptCache = require("testdriverai/agent/lib/cache.js");
+
+// Check if a prompt is cached
+if (promptCache.hasCache("click the login button")) {
+  console.log("This prompt is cached");
+}
+
+// Get cache statistics
+const stats = promptCache.getCacheStats();
+console.log(`Cached prompts: ${stats.count}`);
+console.log(`Files: ${stats.files}`);
+```
+
+### Read Cached YAML
+
+```javascript
+const promptCache = require("testdriverai/agent/lib/cache.js");
+
+const yaml = promptCache.readCache("click the login button");
+if (yaml) {
+  console.log("Cached YAML:", yaml);
+}
+```
+
+### Manual Cache Control
+
+```javascript
+const promptCache = require("testdriverai/agent/lib/cache.js");
+
+// Write to cache manually
+promptCache.writeCache("custom prompt", yamlContent);
+
+// Clear entire cache
+promptCache.clearCache();
+
+// Get cache path for a prompt
+const path = promptCache.getCachePath("my prompt");
+console.log(`Cache file: ${path}`);
+```
+
+## Important Notes
+
+1. **Prompt Matching**: Cache keys are based on the exact prompt text (case-insensitive, trimmed)
+
+   - `'Click the button'` and `'click the button'` will match
+   - `'Click the button'` and `'Click the button '` will match (trailing space trimmed)
+   - `'Click button'` and `'Click the button'` will NOT match
+
+2. **No Screenshot Comparison**: The cache does NOT compare screenshots
+
+   - Cached responses assume the UI state is similar
+   - Use different prompts if the UI state has changed significantly
+
+3. **Manual Cache Management**: The cache never expires automatically
+
+   - Clear it periodically if needed
+   - Delete specific files if a prompt's behavior should change
+
+4. **Version Compatibility**: Cache files are plain YAML
+   - Compatible across TestDriver versions
+   - Safe to commit to version control (though not recommended)
+
+## Testing
+
+Run the test suite to verify caching:
+
+```bash
+node test-prompt-cache.js
+```
+
+This will:
+
+- Make an initial `.ai()` call that caches the response
+- Make a second `.ai()` call that uses the cache
+- Show cache statistics and file locations
+
+## Troubleshooting
+
+### Cache not being used
+
+- Check that prompts match exactly (case-insensitive)
+- Verify `TD_NO_PROMPT_CACHE` is not set
+- Check `.testdriver/.cache/` directory exists and is writable
+
+### Stale cache data
+
+- Clear the cache directory
+- Or delete specific cached prompt files
+
+### Permission errors
+
+- Ensure `.testdriver/.cache/` is writable
+- Check file system permissions