agent-relay 2.0.18 → 2.0.20

package/packages/cli-tester/README.md

@@ -0,0 +1,277 @@
+# @agent-relay/cli-tester
+
+Manual interactive testing environment for CLI authentication flows.
+
+## Purpose
+
+This package provides a Docker-based environment for testing CLI authentication with real OAuth providers. It's designed for:
+
+- **Debugging auth issues** - Isolate problems with specific CLIs (e.g., "Cursor doesn't work")
+- **Testing auth flows** - Verify OAuth flows work end-to-end
+- **Message injection** - Test relay-pty message delivery
+- **Credential verification** - Check that credentials are saved correctly
+
+## Quick Start
+
+From the relay repo root:
+
+```bash
+# Start the test environment (drops into container shell)
+npm run cli-tester:start
+
+# Start with clean credentials (removes any cached auth)
+npm run cli-tester:start:clean
+
+# Start with daemon for full integration testing
+npm run cli-tester:start:daemon
+```
+
+## Inside the Container
+
+### Test a CLI
+
+```bash
+# Test Claude CLI with relay-pty
+./scripts/test-cli.sh claude
+
+# Test Codex with device auth
+./scripts/test-cli.sh codex --device-auth
+
+# Test with debug output
+DEBUG=1 ./scripts/test-cli.sh cursor
+```
+
+### Verify Credentials
+
+```bash
+# Check if credentials exist (after authenticating)
+./scripts/verify-auth.sh claude
+./scripts/verify-auth.sh codex
+./scripts/verify-auth.sh gemini
+```
+
+### Inject Messages
+
+In a second terminal (while CLI is running):
+
+```bash
+# Send a message via relay-pty socket
+./scripts/inject-message.sh test-claude "What is 2+2?"
+```
+
+### Clear Credentials
+
+```bash
+# Clear credentials for fresh testing
+./scripts/clear-auth.sh claude
+./scripts/clear-auth.sh all  # Clear all CLIs
+```
+
+## Advanced: Testing Spawn Flow
+
+The simple `test-cli.sh` tests the CLI in isolation. For debugging issues where the CLI works in isolation but fails when spawned via the application (e.g., registration timeout), use these advanced tests:
+
+### Test Spawn Behavior
+
+Simulates what `AgentSpawner.spawn()` does, including CLI-specific flags:
+
+```bash
+# Test with same flags as spawner (--force for cursor, --dangerously-skip-permissions for claude)
+./scripts/test-spawn.sh cursor
+
+# Test in interactive mode (without auto-accept flags)
+./scripts/test-spawn.sh cursor --interactive
+
+# With verbose debug output
+DEBUG_SPAWN=1 ./scripts/test-spawn.sh cursor
+```
+
+### Test Registration Flow
+
+Monitors the registration files that the spawner polls. This is the step that times out:
+
+```bash
+# Watch registration with 60 second timeout
+./scripts/test-registration.sh cursor 60
+
+# With debug output
+DEBUG_SPAWN=1 ./scripts/test-registration.sh cursor
+```
+
+### Full Daemon Integration Test
+
+Starts a real daemon and tests the complete flow:
+
+```bash
+# Full end-to-end test with daemon
+./scripts/test-with-daemon.sh cursor
+
+# With debug output
+DEBUG=1 ./scripts/test-with-daemon.sh cursor
+```
+
+**Note:** Requires the daemon to be built: `cd packages/daemon && npm run build`
+
+## Debugging a Broken CLI
+
+When a CLI isn't working, use this workflow:
+
+```bash
+# 1. Start fresh
+npm run cli-tester:start:clean
+
+# 2. Test the problematic CLI
+./scripts/test-cli.sh cursor
+
+# 3. Observe the output for:
+#    - Auth URLs being printed
+#    - Error messages
+#    - Prompt patterns
+
+# 4. Check credentials
+./scripts/verify-auth.sh cursor
+ls -la ~/.cursor/
+
+# 5. Compare with a working CLI
+./scripts/test-cli.sh claude
+```
+
+## Debugging Registration Timeout
+
+If a CLI works in isolation but times out when spawned ("Agent registration timeout"), the issue is in the daemon registration flow.
+
+### Quick Test (Run This First)
+
+```bash
+# Test the EXACT setup flow - this is what TerminalProviderSetup.tsx does
+DEBUG=1 ./scripts/test-full-spawn.sh cursor true
+```
+
+This simulates:
+- `interactive: true` (no --force flag, like setup terminal)
+- 30 second registration timeout
+- Verbose logging of what's happening
+
+### Understanding the Flow
+
+**Normal spawn (non-interactive):**
+```bash
+./scripts/test-full-spawn.sh cursor       # Has --force flag
+```
+
+**Setup terminal (interactive):**
+```bash
+./scripts/test-full-spawn.sh cursor true  # NO --force flag
+```
+
+The key difference is `interactive: true` **skips auto-accept flags**. Setup terminals expect the user to respond to prompts in the browser terminal.
+
+### What the Tests Show
+
+1. **test-full-spawn.sh** - Simulates spawner's 30s registration timeout
+   - Shows poll count (like spawner logs)
+   - Shows socket status
+   - Captures CLI output to log file
+   - Tells you exactly where things fail
+
+2. **test-setup-flow.sh** - Identical to what TerminalProviderSetup.tsx does
+   - Uses `__setup__cursor-xxx` naming
+   - No CLI flags (interactive mode)
+
+### Debugging Steps
+
+```bash
+# 1. Test in isolation (verify CLI starts)
+./scripts/test-cli.sh cursor
+
+# 2. Test NON-INTERACTIVE spawn (with --force)
+DEBUG=1 ./scripts/test-full-spawn.sh cursor
+
+# 3. Test INTERACTIVE spawn (setup terminal flow)
+DEBUG=1 ./scripts/test-full-spawn.sh cursor true
+
+# 4. Watch the log file in another terminal
+tail -f /tmp/relay-spawn-*.log
+```
+
+### Common Causes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| CLI exits immediately | Not installed or crash | Check `which agent` |
+| Socket never created | CLI stuck on early prompt | Check log for prompts |
+| 30s timeout | CLI waiting for user input | Respond to prompts (trust, etc.) |
+| 30s timeout | No daemon to register with | Run with daemon profile |
+
+### The Registration Flow
+
+The spawner waits for TWO conditions:
+1. Agent in `connected-agents.json` (daemon updates this when CLI connects)
+2. Agent in `agents.json` (relay-pty hook updates this)
+
+Without a running daemon, both files are empty → timeout.
+
+## Available CLIs
+
+The container includes these pre-installed CLIs:
+
+| CLI | Command | Auth Command | Credential Path |
+|-----|---------|--------------|-----------------|
+| Claude | `claude` | (auto) | `~/.claude/.credentials.json` |
+| Codex | `codex` | `login` | `~/.codex/auth.json` |
+| Gemini | `gemini` | (auto) | `~/.gemini/credentials.json` |
+| Cursor | `agent` | (auto) | `~/.cursor/auth.json` |
+| OpenCode | `opencode` | `auth login` | `~/.local/share/opencode/auth.json` |
+| Droid | `droid` | `--login` | `~/.droid/auth.json` |
+| Copilot | `copilot` | `auth login` | `~/.config/gh/hosts.yml` |
+
+**Note:** Cursor CLI installs as `agent`, not `cursor`. The test scripts handle this mapping automatically.
+
+## How It Works
+
+1. **relay-pty** wraps the CLI and provides:
+   - Unix socket for message injection
+   - Output parsing for relay commands
+   - Idle detection for message timing
+
+2. **Docker volumes** persist credentials between runs so you don't have to re-authenticate each time.
+
+3. **Shell scripts** provide simple commands for common operations.
+
+## TypeScript API
+
+For programmatic use:
+
+```typescript
+import { RelayPtyClient, checkCredentials } from '@agent-relay/cli-tester';
+
+// Check credentials
+const result = checkCredentials('claude');
+console.log(result.exists, result.valid, result.hasAccessToken);
+
+// Inject messages via socket
+const client = new RelayPtyClient('/tmp/relay-pty-test-claude.sock');
+await client.connect();
+await client.inject({ from: 'Test', body: 'Hello' });
+```
+
+## File Structure
+
+```
+packages/cli-tester/
+├── docker/
+│   ├── Dockerfile           # Test environment image
+│   └── docker-compose.yml   # Container configuration
+├── scripts/
+│   ├── start.sh             # Start container
+│   ├── test-cli.sh          # Test a CLI with relay-pty
+│   ├── verify-auth.sh       # Check credentials
+│   ├── inject-message.sh    # Send message via socket
+│   └── clear-auth.sh        # Clear credentials
+├── src/
+│   └── utils/
+│       ├── socket-client.ts     # relay-pty socket communication
+│       └── credential-check.ts  # Credential file utilities
+└── tests/
+    └── credential-check.test.ts
+```

package/packages/cli-tester/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * CLI Auth Tester - Manual interactive testing for CLI authentication flows
+ *
+ * This package provides utilities for testing CLI authentication in a Docker container.
+ * Primary use case is debugging auth issues with various CLI tools (Claude, Codex, Gemini, etc.)
+ *
+ * @example
+ * ```bash
+ * # Start the test environment
+ * npm run cli-tester:start
+ *
+ * # Inside container, test a CLI
+ * ./scripts/test-cli.sh claude
+ *
+ * # Verify credentials
+ * ./scripts/verify-auth.sh claude
+ * ```
+ */
+export { RelayPtyClient, createClient, getSocketPath, type InjectRequest, type InjectResponse, type StatusRequest, type StatusResponse, type RelayPtyResponse, } from './utils/socket-client.js';
+export { checkCredentials, clearCredentials, checkAllCredentials, clearAllCredentials, getCredentialPath, getConfigPaths, type CLIType, type CredentialCheck, } from './utils/credential-check.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/cli-tester/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * CLI Auth Tester - Manual interactive testing for CLI authentication flows
+ *
+ * This package provides utilities for testing CLI authentication in a Docker container.
+ * Primary use case is debugging auth issues with various CLI tools (Claude, Codex, Gemini, etc.)
+ *
+ * @example
+ * ```bash
+ * # Start the test environment
+ * npm run cli-tester:start
+ *
+ * # Inside container, test a CLI
+ * ./scripts/test-cli.sh claude
+ *
+ * # Verify credentials
+ * ./scripts/verify-auth.sh claude
+ * ```
+ */
+export { RelayPtyClient, createClient, getSocketPath, } from './utils/socket-client.js';
+export { checkCredentials, clearCredentials, checkAllCredentials, clearAllCredentials, getCredentialPath, getConfigPaths, } from './utils/credential-check.js';
+//# sourceMappingURL=index.js.map

package/packages/cli-tester/dist/utils/credential-check.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Credential checking utilities for CLI authentication testing
+ * Verifies and parses credential files for various CLI tools
+ */
+export type CLIType = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'droid';
+export interface CredentialCheck {
+    /** CLI type being checked */
+    cli: CLIType;
+    /** Whether the credential file exists */
+    exists: boolean;
+    /** Whether the credentials appear valid (have required fields) */
+    valid: boolean;
+    /** Whether an access token is present */
+    hasAccessToken: boolean;
+    /** Whether a refresh token is present */
+    hasRefreshToken: boolean;
+    /** Token expiration date if available */
+    expiresAt?: Date;
+    /** Path to the credential file */
+    filePath: string;
+    /** Raw credential data (tokens redacted) */
+    data?: Record<string, unknown>;
+    /** Error message if check failed */
+    error?: string;
+}
+/**
+ * Get the credential file path for a CLI
+ */
+export declare function getCredentialPath(cli: CLIType): string;
+/**
+ * Get all config paths for a CLI (for clearing)
+ */
+export declare function getConfigPaths(cli: CLIType): string[];
+/**
+ * Check credentials for a specific CLI
+ */
+export declare function checkCredentials(cli: CLIType): CredentialCheck;
+/**
+ * Clear credentials for a specific CLI
+ */
+export declare function clearCredentials(cli: CLIType): {
+    cleared: string[];
+    errors: string[];
+};
+/**
+ * Clear all CLI credentials
+ */
+export declare function clearAllCredentials(): Record<CLIType, {
+    cleared: string[];
+    errors: string[];
+}>;
+/**
+ * Check all CLI credentials
+ */
+export declare function checkAllCredentials(): Record<CLIType, CredentialCheck>;
+//# sourceMappingURL=credential-check.d.ts.map

package/packages/cli-tester/dist/utils/credential-check.js

@@ -0,0 +1,230 @@
+/**
+ * Credential checking utilities for CLI authentication testing
+ * Verifies and parses credential files for various CLI tools
+ */
+import { readFileSync, existsSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Get the credential file path for a CLI
+ */
+export function getCredentialPath(cli) {
+    const home = homedir();
+    switch (cli) {
+        case 'claude':
+            return join(home, '.claude', '.credentials.json');
+        case 'codex':
+            return join(home, '.codex', 'auth.json');
+        case 'gemini':
+            return join(home, '.config', 'gcloud', 'application_default_credentials.json');
+        case 'cursor':
+            return join(home, '.cursor', 'auth.json');
+        case 'opencode':
+            return join(home, '.local', 'share', 'opencode', 'auth.json');
+        case 'droid':
+            return join(home, '.droid', 'auth.json');
+        default:
+            throw new Error(`Unknown CLI type: ${cli}`);
+    }
+}
+/**
+ * Get all config paths for a CLI (for clearing)
+ */
+export function getConfigPaths(cli) {
+    const home = homedir();
+    switch (cli) {
+        case 'claude':
+            return [
+                join(home, '.claude', '.credentials.json'),
+                join(home, '.claude', 'settings.json'),
+                join(home, '.claude', 'settings.local.json'),
+            ];
+        case 'codex':
+            return [
+                join(home, '.codex', 'auth.json'),
+                join(home, '.codex', 'config.json'),
+                join(home, '.codex', 'config.toml'),
+            ];
+        case 'gemini':
+            return [
+                join(home, '.config', 'gcloud', 'application_default_credentials.json'),
+                join(home, '.gemini', 'credentials.json'),
+                join(home, '.gemini', 'settings.json'),
+            ];
+        case 'cursor':
+            return [
+                join(home, '.cursor', 'auth.json'),
+                join(home, '.cursor', 'settings.json'),
+            ];
+        case 'opencode':
+            return [join(home, '.local', 'share', 'opencode', 'auth.json')];
+        case 'droid':
+            return [join(home, '.droid', 'auth.json')];
+        default:
+            throw new Error(`Unknown CLI type: ${cli}`);
+    }
+}
+/**
+ * Extract token info from credential data based on CLI type
+ */
+function extractTokenInfo(cli, data) {
+    let hasAccessToken = false;
+    let hasRefreshToken = false;
+    let expiresAt;
+    switch (cli) {
+        case 'claude': {
+            // Claude format: { claudeAiOauth: { accessToken, refreshToken, expiresAt } }
+            const oauth = data.claudeAiOauth;
+            if (oauth) {
+                hasAccessToken = typeof oauth.accessToken === 'string' && oauth.accessToken.length > 0;
+                hasRefreshToken = typeof oauth.refreshToken === 'string' && oauth.refreshToken.length > 0;
+                if (typeof oauth.expiresAt === 'number') {
+                    expiresAt = new Date(oauth.expiresAt);
+                }
+            }
+            break;
+        }
+        case 'codex': {
+            // Codex format: { tokens: { access_token, refresh_token, expires_at } }
+            const tokens = data.tokens;
+            if (tokens) {
+                hasAccessToken =
+                    typeof tokens.access_token === 'string' && tokens.access_token.length > 0;
+                hasRefreshToken =
+                    typeof tokens.refresh_token === 'string' && tokens.refresh_token.length > 0;
+                if (typeof tokens.expires_at === 'number') {
+                    expiresAt = new Date(tokens.expires_at * 1000); // Unix timestamp
+                }
+            }
+            break;
+        }
+        case 'gemini': {
+            // Google OAuth format: { access_token, refresh_token, expiry_date }
+            hasAccessToken =
+                typeof data.access_token === 'string' && data.access_token.length > 0;
+            hasRefreshToken =
+                typeof data.refresh_token === 'string' && data.refresh_token.length > 0;
+            if (typeof data.expiry_date === 'number') {
+                expiresAt = new Date(data.expiry_date);
+            }
+            break;
+        }
+        case 'cursor':
+        case 'opencode':
+        case 'droid': {
+            // Generic format: { accessToken, refreshToken } or { access_token, refresh_token }
+            hasAccessToken =
+                (typeof data.accessToken === 'string' && data.accessToken.length > 0) ||
+                    (typeof data.access_token === 'string' && data.access_token.length > 0);
+            hasRefreshToken =
+                (typeof data.refreshToken === 'string' && data.refreshToken.length > 0) ||
+                    (typeof data.refresh_token === 'string' && data.refresh_token.length > 0);
+            break;
+        }
+    }
+    return { hasAccessToken, hasRefreshToken, expiresAt };
+}
+/**
+ * Redact sensitive values in credential data
+ */
+function redactData(data) {
+    const redacted = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (typeof value === 'string') {
+            // Redact anything that looks like a token
+            if (key.toLowerCase().includes('token') ||
+                key.toLowerCase().includes('secret') ||
+                key.toLowerCase().includes('key') ||
+                value.length > 40) {
+                redacted[key] = '[REDACTED]';
+            }
+            else {
+                redacted[key] = value;
+            }
+        }
+        else if (typeof value === 'object' && value !== null) {
+            redacted[key] = redactData(value);
+        }
+        else {
+            redacted[key] = value;
+        }
+    }
+    return redacted;
+}
+/**
+ * Check credentials for a specific CLI
+ */
+export function checkCredentials(cli) {
+    const filePath = getCredentialPath(cli);
+    const result = {
+        cli,
+        exists: false,
+        valid: false,
+        hasAccessToken: false,
+        hasRefreshToken: false,
+        filePath,
+    };
+    if (!existsSync(filePath)) {
+        return result;
+    }
+    result.exists = true;
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(content);
+        const tokenInfo = extractTokenInfo(cli, data);
+        result.hasAccessToken = tokenInfo.hasAccessToken;
+        result.hasRefreshToken = tokenInfo.hasRefreshToken;
+        result.expiresAt = tokenInfo.expiresAt;
+        // Valid if at least access token is present
+        result.valid = result.hasAccessToken;
+        // Include redacted data for debugging
+        result.data = redactData(data);
+    }
+    catch (err) {
+        result.error = err instanceof Error ? err.message : 'Unknown error';
+    }
+    return result;
+}
+/**
+ * Clear credentials for a specific CLI
+ */
+export function clearCredentials(cli) {
+    const paths = getConfigPaths(cli);
+    const cleared = [];
+    const errors = [];
+    for (const path of paths) {
+        if (existsSync(path)) {
+            try {
+                unlinkSync(path);
+                cleared.push(path);
+            }
+            catch (err) {
+                errors.push(`Failed to remove ${path}: ${err instanceof Error ? err.message : 'Unknown error'}`);
+            }
+        }
+    }
+    return { cleared, errors };
+}
+/**
+ * Clear all CLI credentials
+ */
+export function clearAllCredentials() {
+    const clis = ['claude', 'codex', 'gemini', 'cursor', 'opencode', 'droid'];
+    const results = {};
+    for (const cli of clis) {
+        results[cli] = clearCredentials(cli);
+    }
+    return results;
+}
+/**
+ * Check all CLI credentials
+ */
+export function checkAllCredentials() {
+    const clis = ['claude', 'codex', 'gemini', 'cursor', 'opencode', 'droid'];
+    const results = {};
+    for (const cli of clis) {
+        results[cli] = checkCredentials(cli);
+    }
+    return results;
+}
+//# sourceMappingURL=credential-check.js.map

package/packages/cli-tester/dist/utils/socket-client.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Socket client for communicating with relay-pty Unix socket
+ * Used for programmatic message injection and status queries
+ */
+export interface InjectRequest {
+    type: 'inject';
+    id: string;
+    from: string;
+    body: string;
+    priority?: number;
+}
+export interface StatusRequest {
+    type: 'status';
+}
+export interface InjectResponse {
+    type: 'inject_result';
+    id: string;
+    status: 'queued' | 'injecting' | 'delivered' | 'failed';
+    timestamp: number;
+    error?: string;
+}
+export interface StatusResponse {
+    type: 'status';
+    agent_idle: boolean;
+    queue_length: number;
+    cursor_position: {
+        row: number;
+        col: number;
+    } | null;
+    last_output_ms: number;
+}
+export type RelayPtyResponse = InjectResponse | StatusResponse;
+export declare class RelayPtyClient {
+    private socket;
+    private socketPath;
+    private responseBuffer;
+    constructor(socketPath: string);
+    /**
+     * Connect to the relay-pty socket
+     */
+    connect(): Promise<void>;
+    /**
+     * Send a request and wait for response
+     */
+    private sendRequest;
+    /**
+     * Inject a message into the CLI
+     */
+    inject(message: {
+        from: string;
+        body: string;
+        priority?: number;
+    }): Promise<InjectResponse>;
+    /**
+     * Get current status of the CLI session
+     */
+    getStatus(): Promise<StatusResponse>;
+    /**
+     * Wait for a specific message to be delivered
+     * Returns when the message reaches 'delivered' or 'failed' status
+     */
+    waitForDelivered(messageId: string, timeoutMs?: number): Promise<InjectResponse>;
+    /**
+     * Close the connection
+     */
+    close(): void;
+}
+/**
+ * Helper to create a connected client
+ */
+export declare function createClient(socketPath: string): Promise<RelayPtyClient>;
+/**
+ * Get socket path for a named session
+ */
+export declare function getSocketPath(sessionName: string): string;
+//# sourceMappingURL=socket-client.d.ts.map