nstbrowser-ai-agent 0.0.2 → 0.0.4

package/README.md

@@ -4,6 +4,58 @@ Headless browser automation CLI for AI agents. Fast Rust CLI with Node.js fallba
 
 ## Installation
 
+## Prerequisites
+
+Before using nstbrowser-ai-agent, ensure you have the following:
+
+### 1. Nstbrowser Client
+
+**Nstbrowser client must be installed and running.**
+
+- Download from: https://www.nstbrowser.io/
+- Install the client application
+- Launch the Nstbrowser client
+
+### 2. Nstbrowser Service
+
+The Nstbrowser API service must be accessible:
+
+- Default endpoint: `http://127.0.0.1:8848`
+- Verify service is running:
+  ```bash
+  curl http://127.0.0.1:8848/api/v2/profiles
+  ```
+- Expected response: JSON with profile data or empty list
+
+### 3. API Key
+
+Obtain your API key from the Nstbrowser dashboard and configure it:
+
+**Method 1: Config File (Recommended)**
+```bash
+nstbrowser-ai-agent config set key YOUR_API_KEY
+```
+
+**Method 2: Environment Variable**
+```bash
+export NST_API_KEY="YOUR_API_KEY"
+```
+
+### 4. Verify Setup
+
+Test your configuration:
+
+```bash
+# Check CLI version
+nstbrowser-ai-agent --version
+
+# List profiles (verifies API connection)
+nstbrowser-ai-agent profile list
+```
+
+If you see your profiles or an empty list, your environment is configured correctly.
+
+
 ### npm (Recommended)
 
 Install globally via npm to get the native Rust binary for maximum performance:
@@ -86,6 +138,144 @@ nstbrowser-ai-agent install --with-deps
 # or manually: npx playwright install-deps chromium
 ```
 
+## Quick Start Examples
+
+### Using Temporary Browser (Fastest)
+
+For quick tests or one-time tasks:
+
+```bash
+# Start temporary browser
+nstbrowser-ai-agent browser start-once
+
+# Open a website
+nstbrowser-ai-agent open https://example.com
+
+# Take a snapshot
+nstbrowser-ai-agent snapshot -i
+
+# Close browser (auto-cleanup)
+nstbrowser-ai-agent close
+```
+
+**Note:** Temporary browsers don't save session state.
+
+### Using Profile (Recommended)
+
+For tasks requiring persistent sessions:
+
+```bash
+# List available profiles
+nstbrowser-ai-agent profile list
+
+# Create a new profile (if needed)
+nstbrowser-ai-agent profile create my-profile
+
+# Set default profile
+export NST_PROFILE="my-profile"
+
+# Open browser (auto-starts with profile)
+nstbrowser-ai-agent open https://example.com
+
+# Interact with page
+nstbrowser-ai-agent snapshot -i
+nstbrowser-ai-agent click @e1
+
+# Close browser (session saved to profile)
+nstbrowser-ai-agent close
+```
+
+### Profile Specification for Browser Actions
+
+**All browser actions** (open, click, fill, type, etc.) support specifying a profile name or ID. The CLI will automatically handle profile resolution and browser startup.
+
+#### Profile Resolution Priority
+
+When you specify a profile for a browser action, the system follows these rules:
+
+1. **Check running browsers** - First, it looks for a browser already running with the specified name or ID
+   - If multiple browsers match a name, the earliest started browser is used
+   - Profile IDs always uniquely match a single browser
+
+2. **Start browser if not running** - If the profile exists but isn't running, the browser is automatically started
+
+3. **Create profile if name doesn't exist** - If you specify a profile **name** that doesn't exist, a new profile is automatically created
+   - This makes it easy to create profiles on-the-fly
+
+4. **Error if ID doesn't exist** - If you specify a profile **ID** that doesn't exist, an error is thrown
+   - Profile IDs are expected to be exact matches
+
+5. **Use once browser if no profile specified** - If no profile is specified:
+   - Uses an existing "once" (temporary) browser if one is running
+   - Otherwise creates a new temporary browser
+   - Temporary browsers don't persist session data
+
+#### Specifying Profiles
+
+You can specify profiles in three ways:
+
+**1. Environment Variables (Global Default)**
+```bash
+export NST_PROFILE="my-profile"        # Use profile name
+# OR
+export NST_PROFILE_ID="abc-123-def"    # Use profile ID
+
+# All browser actions will use this profile
+nstbrowser-ai-agent open https://example.com
+nstbrowser-ai-agent click "#button"
+```
+
+**2. Command-Line Flags (Per-Action)**
+```bash
+# By profile name
+nstbrowser-ai-agent open https://example.com --nst-profile "my-profile"
+nstbrowser-ai-agent click "#button" --nst-profile "my-profile"
+
+# By profile ID
+nstbrowser-ai-agent open https://example.com --nst-profile-id "abc-123-def"
+nstbrowser-ai-agent fill "#email" "test@test.com" --nst-profile-id "abc-123-def"
+```
+
+**3. Mixed Approach**
+```bash
+# Set default profile
+export NST_PROFILE="default-profile"
+
+# Most commands use the default
+nstbrowser-ai-agent open https://example.com
+
+# Override for specific commands
+nstbrowser-ai-agent click "#button" --nst-profile "other-profile"
+```
+
+#### Examples
+
+**Auto-create profile on first use:**
+```bash
+# This will create "test-profile" if it doesn't exist
+nstbrowser-ai-agent open https://example.com --nst-profile "test-profile"
+nstbrowser-ai-agent click "#login" --nst-profile "test-profile"
+```
+
+**Use existing profile by ID:**
+```bash
+# List profiles to find ID
+nstbrowser-ai-agent profile list
+
+# Use specific profile ID
+nstbrowser-ai-agent open https://example.com --nst-profile-id "abc-123-def"
+```
+
+**Reuse running browser:**
+```bash
+# Start a browser with a profile
+nstbrowser-ai-agent open https://example.com --nst-profile "my-profile"
+
+# Later commands automatically connect to the same running browser
+nstbrowser-ai-agent click "#button" --nst-profile "my-profile"
+# No restart needed - uses existing browser!
+```
+
 ## Default Provider
 
 By default, nstbrowser-ai-agent uses **Nstbrowser** as the browser provider. This means you don't need to specify `-p nst` every time - it's automatic.
@@ -112,29 +302,6 @@ nstbrowser-ai-agent browser list               # List running browsers
 nstbrowser-ai-agent browser start profile-id   # Start browser with profile
 ```
 
-### Using Local Browser Mode
-
-If you want to use a local browser instead of Nstbrowser, use the `--local` flag:
-
-```bash
-# Use local browser (no API key needed)
-nstbrowser-ai-agent --local open example.com
-nstbrowser-ai-agent --headed open example.com  # Visual browser (also uses local)
-```
-
-### Provider Selection Logic
-
-The provider is selected automatically based on the following priority (highest to lowest):
-
-1. Explicit `--provider` flag
-2. `--local` flag (uses local browser)
-3. `--headed` flag (implies local)
-4. `--cdp` flag (implies local)
-5. `--auto-connect` flag (implies local)
-6. `NST_API_KEY` environment variable (uses nst)
-7. **Default: nst (Nstbrowser)**
-
-This means if you have `NST_API_KEY` set, Nstbrowser will be used automatically. To override this, use `--local` or any other flag that implies local mode.
 
 ### Traditional Selectors (also supported)
 
@@ -173,7 +340,6 @@ nstbrowser-ai-agent screenshot --annotate   # Annotated screenshot with numbered
 nstbrowser-ai-agent pdf <path>              # Save as PDF
 nstbrowser-ai-agent snapshot                # Accessibility tree with refs (best for AI)
 nstbrowser-ai-agent eval <js>               # Run JavaScript (-b for base64, --stdin for piped input)
-nstbrowser-ai-agent connect <port>          # Connect to browser via CDP
 nstbrowser-ai-agent close                   # Close browser (aliases: quit, exit)
 ```
 
@@ -478,7 +644,6 @@ nstbrowser-ai-agent --session-name secure open example.com
 | `NSTBROWSER_AI_AGENT_ENCRYPTION_KEY` | 64-char hex key for AES-256-GCM encryption |
 | `NSTBROWSER_AI_AGENT_STATE_EXPIRE_DAYS` | Auto-delete states older than N days (default: 30) |
 | `NSTBROWSER_AI_AGENT_PROVIDER` | Browser provider (default: nst) |
-| `NSTBROWSER_AI_AGENT_LOCAL` | Use local browser instead of Nstbrowser |
 | `NST_API_KEY` | Nstbrowser API key (required for nst provider, default provider) |
 | `NST_HOST` | Nstbrowser API host (default: localhost) |
 | `NST_PORT` | Nstbrowser API port (default: 8848) |
@@ -503,7 +668,6 @@ nstbrowser-ai-agent includes security features for safe AI agent deployments. Al
 | `NSTBROWSER_AI_AGENT_CONFIRM_ACTIONS` | Action categories requiring confirmation |
 | `NSTBROWSER_AI_AGENT_CONFIRM_INTERACTIVE` | Enable interactive confirmation prompts |
 | `NSTBROWSER_AI_AGENT_PROVIDER` | Browser provider (default: nst) |
-| `NSTBROWSER_AI_AGENT_LOCAL` | Use local browser instead of Nstbrowser |
 | `NST_API_KEY` | Nstbrowser API key (required for nst provider, default provider) |
 | `NST_HOST` | Nstbrowser API host (default: localhost) |
 | `NST_PORT` | Nstbrowser API port (default: 8848) |
@@ -573,13 +737,9 @@ This is useful for multimodal AI models that can reason about visual layout, unl
 | `--ignore-https-errors` | Ignore HTTPS certificate errors (useful for self-signed certs)                                                   |
 | `--allow-file-access` | Allow file:// URLs to access local files (Chromium only)                                                         |
 | `-p, --provider <name>` | Browser provider: `nst` (default), `local` (or `NSTBROWSER_AI_AGENT_PROVIDER` env)   |
-| `--local` | Use local browser instead of Nstbrowser (or `NSTBROWSER_AI_AGENT_LOCAL` env)                                           |
 | `--json` | JSON output (for agents)                                                                                         |
 | `--full, -f` | Full page screenshot                                                                                             |
 | `--annotate` | Annotated screenshot with numbered element labels (or `NSTBROWSER_AI_AGENT_ANNOTATE` env)                              |
-| `--headed` | Show browser window (not headless, implies local mode)                                                           |
-| `--cdp <port\|url>` | Connect via Chrome DevTools Protocol (port or WebSocket URL, implies local mode)                                 |
-| `--auto-connect` | Auto-discover and connect to running Chrome (implies local mode) (or `NSTBROWSER_AI_AGENT_AUTO_CONNECT` env)          |
 | `--color-scheme <scheme>` | Color scheme: `dark`, `light`, `no-preference` (or `NSTBROWSER_AI_AGENT_COLOR_SCHEME` env)                             |
 | `--download-path <path>` | Default download directory (or `NSTBROWSER_AI_AGENT_DOWNLOAD_PATH` env)                                                |
 | `--content-boundaries` | Wrap page output in boundary markers for LLM safety (or `NSTBROWSER_AI_AGENT_CONTENT_BOUNDARIES` env)                  |
@@ -876,59 +1036,6 @@ The `--allow-file-access` flag adds Chromium flags (`--allow-file-access-from-fi
 
 **Note:** This flag only works with Chromium. For security, it's disabled by default.
 
-## CDP Mode
-
-Connect to an existing browser via Chrome DevTools Protocol:
-
-```bash
-# Start Chrome with: google-chrome --remote-debugging-port=9222
-
-# Connect once, then run commands without --cdp
-nstbrowser-ai-agent connect 9222
-nstbrowser-ai-agent snapshot
-nstbrowser-ai-agent tab
-nstbrowser-ai-agent close
-
-# Or pass --cdp on each command
-nstbrowser-ai-agent --cdp 9222 snapshot
-
-# Connect to remote browser via WebSocket URL
-nstbrowser-ai-agent --cdp "wss://your-browser-service.com/cdp?token=..." snapshot
-```
-
-The `--cdp` flag accepts either:
-- A port number (e.g., `9222`) for local connections via `http://localhost:{port}`
-- A full WebSocket URL (e.g., `wss://...` or `ws://...`) for remote browser services
-
-This enables control of:
-- Electron apps
-- Chrome/Chromium instances with remote debugging
-- WebView2 applications
-- Any browser exposing a CDP endpoint
-
-### Auto-Connect
-
-Use `--auto-connect` to automatically discover and connect to a running Chrome instance without specifying a port:
-
-```bash
-# Auto-discover running Chrome with remote debugging
-nstbrowser-ai-agent --auto-connect open example.com
-nstbrowser-ai-agent --auto-connect snapshot
-
-# Or via environment variable
-NSTBROWSER_AI_AGENT_AUTO_CONNECT=1 nstbrowser-ai-agent snapshot
-```
-
-Auto-connect discovers Chrome by:
-1. Reading Chrome's `DevToolsActivePort` file from the default user data directory
-2. Falling back to probing common debugging ports (9222, 9229)
-
-This is useful when:
-- Chrome 144+ has remote debugging enabled via `chrome://inspect/#remote-debugging` (which uses a dynamic port)
-- You want a zero-configuration connection to your existing browser
-- You don't want to track which port Chrome is using
-
-## Streaming (Browser Preview)
 
 Stream the browser viewport via WebSocket for live preview or "pair browsing" where a human can watch and interact alongside an AI agent.
 
@@ -1137,10 +1244,11 @@ For more consistent results, add to your project or global instructions file:
 Use `nstbrowser-ai-agent` for web automation. Run `nstbrowser-ai-agent --help` for all commands.
 
 Core workflow:
-1. `nstbrowser-ai-agent open <url>` - Navigate to page
-2. `nstbrowser-ai-agent snapshot -i` - Get interactive elements with refs (@e1, @e2)
-3. `nstbrowser-ai-agent click @e1` / `fill @e2 "text"` - Interact using refs
-4. Re-snapshot after page changes
+1. Set profile: `export NST_PROFILE="my-profile"` or use `browser start-once` for temporary browser
+2. `nstbrowser-ai-agent open <url>` - Navigate to page
+3. `nstbrowser-ai-agent snapshot -i` - Get interactive elements with refs (@e1, @e2)
+4. `nstbrowser-ai-agent click @e1` / `fill @e2 "text"` - Interact using refs
+5. Re-snapshot after page changes
 ```
 
 ## Nstbrowser Integration
@@ -1245,7 +1353,6 @@ You can still use `--profile-id` for explicit ID specification if preferred, but
 # With default NST provider (NST_API_KEY set), no 'nst' prefix needed:
 nstbrowser-ai-agent browser list                    # List running instances
 nstbrowser-ai-agent browser start profile-123       # Start browser for profile
-nstbrowser-ai-agent browser start-batch p1 p2 p3    # Start multiple browsers
 nstbrowser-ai-agent browser start-once              # Start temporary browser
 nstbrowser-ai-agent browser stop profile-123        # Stop browser instance
 nstbrowser-ai-agent browser stop-all                # Stop all instances
@@ -1259,7 +1366,6 @@ nstbrowser-ai-agent browser connect-once            # Connect to temp browser
 # Traditional explicit syntax still works:
 nstbrowser-ai-agent nst browser list
 nstbrowser-ai-agent nst browser start profile-123
-nstbrowser-ai-agent nst browser start-batch p1 p2 p3
 nstbrowser-ai-agent nst browser stop profile-123
 nstbrowser-ai-agent nst browser stop-all
 ```

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAqBpE,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAsIT,MAAM,YAAY,CAAC;AAQpB;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC,GAAG,IAAI,GAClD,IAAI,CAEN;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAqDzE;AAKD,wBAAgB,gBAAgB,IAAI,IAAI,CAuBvC;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CA6CjG"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAwBpE,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAsIT,MAAM,YAAY,CAAC;AAQpB;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC,GAAG,IAAI,GAClD,IAAI,CAEN;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAqDzE;AAKD,wBAAgB,gBAAgB,IAAI,IAAI,CAuBvC;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CA2DjG"}

package/dist/actions.js

@@ -2,6 +2,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { mkdirSync } from 'node:fs';
 import { getAppDir } from './daemon.js';
+import { resolveBrowserProfile, extractProfileOptions } from './browser-profile-resolver.js';
+import { NstbrowserClient } from './nstbrowser-client.js';
+import { loadNstConfig } from './config-loader.js';
 import { checkPolicy, describeAction, getActionCategory, loadPolicyFile, initPolicyReloader, reloadPolicyIfChanged, } from './action-policy.js';
 import { requestConfirmation, getAndRemovePending } from './confirmation.js';
 import { getAuthProfile, updateLastLogin } from './auth-vault.js';
@@ -111,6 +114,17 @@ export async function executeCommand(command, browser) {
                 confirmation_id: confirmationId,
             });
         }
+        // === Profile-Aware Browser Action Handling ===
+        // Check if this is a browser action command that needs profile resolution
+        // Skip launch command as it already handles its own profile resolution
+        if (command.action !== 'launch' &&
+            command.action !== 'state_list' &&
+            command.action !== 'state_show' &&
+            command.action !== 'state_clean' &&
+            command.action !== 'state_clear' &&
+            command.action !== 'state_rename') {
+            await ensureBrowserWithProfile(command, browser);
+        }
         return await dispatchAction(command, browser);
     }
     catch (error) {
@@ -118,6 +132,68 @@ export async function executeCommand(command, browser) {
         return errorResponse(command.id, message);
     }
 }
+/**
+ * Ensure browser is launched with the correct profile before executing an action
+ * Implements the unified profile resolution logic for all browser actions
+ */
+async function ensureBrowserWithProfile(command, browser) {
+    const cmdWithProfile = command;
+    // Check if command has profile specifications or environment variables are set
+    const hasProfileSpec = !!cmdWithProfile.nstProfileName ||
+        !!cmdWithProfile.nstProfileId ||
+        !!process.env.NST_PROFILE ||
+        !!process.env.NST_PROFILE_ID;
+    // Only proceed with profile resolution if:
+    // 1. Profile is explicitly specified in the command OR
+    // 2. Environment variables are set OR
+    // 3. We're using NST provider (default or explicit)
+    const provider = process.env.NSTBROWSER_AI_AGENT_PROVIDER;
+    const isNstProvider = !provider || provider === 'nst'; // Default is NST
+    if (!hasProfileSpec && !isNstProvider) {
+        // Not NST provider and no profile specified, skip profile resolution
+        return;
+    }
+    // If browser is not launched or needs reconnection, launch with profile
+    if (!browser.isLaunched()) {
+        const config = loadNstConfig();
+        if (!config) {
+            // NST not configured, skip profile resolution (will use local browser)
+            if (process.env.NSTBROWSER_AI_AGENT_DEBUG === '1') {
+                console.error('[DEBUG] NST not configured, skipping profile resolution');
+            }
+            return;
+        }
+        // Launch browser with profile resolution
+        const client = new NstbrowserClient(config.host, config.port, config.apiKey);
+        try {
+            const profileOptions = extractProfileOptions(cmdWithProfile, config.host, config.port, config.apiKey);
+            const resolved = await resolveBrowserProfile(client, profileOptions);
+            if (process.env.NSTBROWSER_AI_AGENT_DEBUG === '1') {
+                console.error('[DEBUG] Resolved profile for action:', {
+                    action: command.action,
+                    profileId: resolved.profileId,
+                    profileName: resolved.profileName,
+                    isOnce: resolved.isOnce,
+                    wasCreated: resolved.wasCreated,
+                });
+            }
+            // Launch browser with the resolved profile
+            await browser.launch({
+                id: command.id,
+                action: 'launch',
+                provider: 'nst',
+                nstProfileId: resolved.profileId,
+                nstProfileName: resolved.profileName,
+            });
+        }
+        catch (error) {
+            if (process.env.NSTBROWSER_AI_AGENT_DEBUG === '1') {
+                console.error('[DEBUG] Profile resolution failed:', error);
+            }
+            throw error;
+        }
+    }
+}
 /**
  * Dispatch a command to its handler after policy checks have passed.
  */