coding-agent-adapters 0.2.13 → 0.2.15

package/README.md

@@ -2,6 +2,8 @@
 
 CLI adapters for AI coding agents. Works with [pty-manager](https://www.npmjs.com/package/pty-manager) to spawn and manage coding agents like Claude Code, Gemini CLI, OpenAI Codex, and Aider.
 
+Each adapter provides source-derived detection patterns for the full session lifecycle: login/auth, blocking prompts, ready state, exit conditions, and auto-response rules — all based on deep analysis of each CLI's open-source codebase.
+
 ## Installation
 
 ```bash
@@ -42,12 +44,122 @@ session.send('Help me refactor this function to use async/await');
 
 ## Available Adapters
 
-| Adapter | CLI | Type | Install Command |
-|---------|-----|------|-----------------|
-| `ClaudeAdapter` | Claude Code | `claude` | `npm install -g @anthropic-ai/claude-code` |
-| `GeminiAdapter` | Gemini CLI | `gemini` | `npm install -g @anthropics/gemini-cli` |
-| `CodexAdapter` | OpenAI Codex | `codex` | `npm install -g @openai/codex` |
-| `AiderAdapter` | Aider | `aider` | `pip install aider-chat` |
+| Adapter | CLI | Type | Input Style | Auto-Response Rules |
+|---------|-----|------|-------------|---------------------|
+| `ClaudeAdapter` | Claude Code | `claude` | TUI menus | 5 rules |
+| `GeminiAdapter` | Gemini CLI | `gemini` | TUI menus | 3 rules |
+| `CodexAdapter` | OpenAI Codex | `codex` | TUI menus | 6 rules |
+| `AiderAdapter` | Aider | `aider` | Text `(Y)es/(N)o` | 17 rules |
+
+## Session Lifecycle Detection
+
+Each adapter implements detection for every stage of a CLI session:
+
+### Login / Auth Detection
+
+Adapters detect various auth states and methods:
+
+```typescript
+const adapter = new GeminiAdapter();
+const login = adapter.detectLogin(output);
+// { required: true, type: 'browser', url: 'https://...', instructions: '...' }
+```
+
+| Adapter | Auth Types | Source Files |
+|---------|-----------|-------------|
+| Claude | API key, OAuth browser | CLI runtime |
+| Gemini | Google OAuth, API key entry, auth in-progress | `AuthDialog.tsx`, `ApiAuthDialog.tsx`, `AuthInProgress.tsx` |
+| Codex | Device code flow, onboarding auth menu | `auth.rs`, `headless_chatgpt_login.rs` |
+| Aider | API key missing/invalid, OpenRouter OAuth | `onboarding.py`, `models.py` |
+
+### Ready State Detection
+
+Each adapter knows exactly what "ready for input" looks like:
+
+| Adapter | Ready Indicators | Source |
+|---------|-----------------|--------|
+| Claude | `$` prompt | CLI runtime |
+| Gemini | Prompt glyphs (`>`, `!`, `*`, `(r:)`), composer placeholder | `InputPrompt.tsx`, `Composer.tsx` |
+| Codex | `>` glyph, placeholder suggestions | `chat_composer.rs` |
+| Aider | `ask>`, `code>`, `architect>`, `help>`, `multi>`, startup banner | `io.py`, `base_coder.py` |
+
+### Blocking Prompt Detection
+
+Adapters detect prompts that block the session and require user action:
+
+| Adapter | Detected Prompts |
+|---------|-----------------|
+| Claude | Permission requests, update notices |
+| Gemini | Folder trust, tool execution, validation dialogs, privacy consent |
+| Codex | Directory trust, tool approval, update available, model migration, CWD selection |
+| Aider | File operations, shell commands, git init, pip install, destructive operations |
+
+### Exit Detection
+
+Adapters detect when a CLI session has ended:
+
+| Adapter | Exit Conditions |
+|---------|----------------|
+| Claude | Base exit detection |
+| Gemini | Folder trust rejection, logout confirmation |
+| Codex | Session end, update completion |
+| Aider | Ctrl+C / KeyboardInterrupt, version update requiring restart |
+
+## Auto-Response Rules
+
+Adapters include pre-configured rules to automatically handle known prompts. Rules use two response modes depending on the CLI's input style.
+
+### TUI Menu CLIs (Gemini, Codex, Claude)
+
+These CLIs use arrow-key menus rendered with Ink/Ratatui. Rules send key sequences:
+
+```typescript
+const codex = new CodexAdapter();
+codex.autoResponseRules;
+// [
+//   { pattern: /update.?available/i, responseType: 'keys', keys: ['down', 'enter'], once: true, ... },
+//   { pattern: /trust.?this.?directory/i, responseType: 'keys', keys: ['enter'], once: true, ... },
+//   { pattern: /model.?migration/i, responseType: 'keys', keys: ['enter'], once: true, ... },
+//   ...
+// ]
+```
+
+### Text Prompt CLIs (Aider)
+
+Aider uses plain text `(Y)es/(N)o` prompts via `io.py`. Rules send typed text:
+
+```typescript
+const aider = new AiderAdapter();
+aider.autoResponseRules;
+// [
+//   { pattern: /allow collection of anonymous analytics/i, response: 'n', responseType: 'text', once: true, ... },
+//   { pattern: /add .+ to the chat\?/i, response: 'y', responseType: 'text', ... },
+//   { pattern: /create new file\?/i, response: 'y', responseType: 'text', ... },
+//   { pattern: /run shell commands?\?/i, response: 'y', responseType: 'text', ... },
+//   ...17 rules total
+// ]
+```
+
+### The `usesTuiMenus` Flag
+
+Adapters declare their input style via `usesTuiMenus`. This affects how auto-response rules with no explicit `responseType` are delivered:
+
+- `usesTuiMenus: true` (Gemini, Codex, Claude) — defaults to `sendKeys('enter')`
+- `usesTuiMenus: false` (Aider) — defaults to `writeRaw(response + '\r')`
+
+## Model Recommendations
+
+Each adapter provides model recommendations based on available credentials:
+
+```typescript
+const aider = new AiderAdapter();
+
+aider.getRecommendedModels({ anthropicKey: 'sk-ant-...' });
+// { powerful: 'anthropic/claude-sonnet-4-20250514', fast: 'anthropic/claude-haiku-4-5-20251001' }
+
+aider.getRecommendedModels({ googleKey: 'AIza...' });
+// { powerful: 'gemini/gemini-3-pro', fast: 'gemini/gemini-3-flash' }
+```
 
 ## Preflight Check
 
@@ -60,9 +172,9 @@ import { checkAdapters, checkAllAdapters, printMissingAdapters } from 'coding-ag
 const results = await checkAdapters(['claude', 'aider']);
 for (const result of results) {
   if (result.installed) {
-    console.log(`✓ ${result.adapter} v${result.version}`);
+    console.log(`${result.adapter} v${result.version}`);
   } else {
-    console.log(`✗ ${result.adapter} - Install: ${result.installCommand}`);
+    console.log(`${result.adapter} - Install: ${result.installCommand}`);
   }
 }
 
@@ -73,24 +185,6 @@ const allResults = await checkAllAdapters();
 await printMissingAdapters(['claude', 'gemini']);
 ```
 
-Each adapter also provides installation info:
-
-```typescript
-import { ClaudeAdapter } from 'coding-agent-adapters';
-
-const claude = new ClaudeAdapter();
-console.log(claude.installation);
-// {
-//   command: 'npm install -g @anthropic-ai/claude-code',
-//   alternatives: ['npx @anthropic-ai/claude-code', 'brew install claude-code'],
-//   docsUrl: 'https://docs.anthropic.com/en/docs/claude-code',
-//   minVersion: '1.0.0'
-// }
-
-// Get formatted instructions
-console.log(claude.getInstallInstructions());
-```
-
 ## Passing Credentials
 
 You can pass API keys either via environment variables or through `adapterConfig`:
@@ -112,93 +206,51 @@ const session = await manager.spawn({
   workdir: '/project',
   adapterConfig: {
     anthropicKey: 'sk-ant-...',
+    openaiKey: 'sk-...',
+    googleKey: 'AIza...',
   },
 });
 ```
 
-## Adapter Features
-
-### Auto-Response Rules
-
-Each adapter includes auto-response rules for common prompts (updates, telemetry, etc.):
-
-```typescript
-const claude = new ClaudeAdapter();
-console.log(claude.autoResponseRules);
-// [
-//   { pattern: /update available.*\[y\/n\]/i, response: 'n', ... },
-//   { pattern: /telemetry.*\[y\/n\]/i, response: 'n', ... },
-//   ...
-// ]
-```
-
-### Blocking Prompt Detection
-
-Adapters detect blocking prompts that require user intervention:
-
-```typescript
-session.on('blocking_prompt', (promptInfo, autoResponded) => {
-  if (!autoResponded) {
-    console.log(`User action required: ${promptInfo.type}`);
-    console.log(promptInfo.instructions);
-  }
-});
-```
-
-### Login Detection
-
-Adapters detect when authentication is required:
-
-```typescript
-session.on('login_required', (instructions, url) => {
-  console.log('Authentication required:', instructions);
-  if (url) {
-    console.log('Open:', url);
-  }
-});
-```
-
 ## Creating Custom Adapters
 
 Extend `BaseCodingAdapter` to create adapters for other coding CLIs:
 
 ```typescript
 import { BaseCodingAdapter } from 'coding-agent-adapters';
-import type { SpawnConfig, ParsedOutput, LoginDetection } from 'pty-manager';
+import type { SpawnConfig, ParsedOutput, LoginDetection, AutoResponseRule } from 'pty-manager';
 
 export class CursorAdapter extends BaseCodingAdapter {
   readonly adapterType = 'cursor';
   readonly displayName = 'Cursor';
 
-  getCommand(): string {
-    return 'cursor';
-  }
+  // Set to false if the CLI uses text prompts instead of TUI menus
+  override readonly usesTuiMenus = false;
 
-  getArgs(config: SpawnConfig): string[] {
-    return ['--cli'];
-  }
+  readonly autoResponseRules: AutoResponseRule[] = [
+    { pattern: /accept terms/i, type: 'tos', response: 'y', responseType: 'text', description: 'Accept TOS', safe: true, once: true },
+  ];
 
-  getEnv(config: SpawnConfig): Record<string, string> {
-    return {};
-  }
+  getCommand(): string { return 'cursor'; }
+  getArgs(config: SpawnConfig): string[] { return ['--cli']; }
+  getEnv(config: SpawnConfig): Record<string, string> { return {}; }
 
   detectLogin(output: string): LoginDetection {
-    // Implement login detection
+    if (/login required/i.test(output)) {
+      return { required: true, type: 'browser' };
+    }
     return { required: false };
   }
 
   detectReady(output: string): boolean {
-    return output.includes('Cursor ready');
+    return /cursor>\s*$/m.test(output);
   }
 
   parseOutput(output: string): ParsedOutput | null {
-    // Implement output parsing
-    return null;
+    return { type: 'response', content: output.trim(), isComplete: true, isQuestion: output.includes('?') };
   }
 
-  getPromptPattern(): RegExp {
-    return /cursor>\s*$/;
-  }
+  getPromptPattern(): RegExp { return /cursor>\s*$/; }
 }
 ```