nstbrowser-ai-agent 0.0.4 → 0.0.6

package/README.md

@@ -46,6 +46,9 @@ export NST_API_KEY="YOUR_API_KEY"
 Test your configuration:
 
 ```bash
+# Check if NST agent is running
+nstbrowser-ai-agent nst status
+
 # Check CLI version
 nstbrowser-ai-agent --version
 
@@ -82,7 +85,6 @@ For projects that want to pin the version in `package.json`:
 
 ```bash
 npm install nstbrowser-ai-agent
-npx nstbrowser-ai-agent install
 ```
 
 Then use via `npx` or `package.json` scripts:
@@ -112,11 +114,6 @@ You can also download pre-built binaries directly from [GitHub Releases](https:/
    sudo mv nstbrowser-ai-agent-* /usr/local/bin/nstbrowser-ai-agent
    ```
 
-4. Download Chromium:
-   ```bash
-   nstbrowser-ai-agent install
-   ```
-
 ### From Source
 
 ```bash
@@ -126,18 +123,50 @@ pnpm install
 pnpm build
 pnpm build:native   # Requires Rust (https://rustup.rs)
 pnpm link --global  # Makes nstbrowser-ai-agent available globally
-nstbrowser-ai-agent install
 ```
 
-### Linux Dependencies
+## Updates
+
+### Automatic Update Checks
 
-On Linux, install system dependencies:
+The CLI automatically checks for updates once every 24 hours and notifies you when a new version is available.
 
+**Disable automatic checks:**
 ```bash
-nstbrowser-ai-agent install --with-deps
-# or manually: npx playwright install-deps chromium
+export NSTBROWSER_AI_AGENT_NO_UPDATE_CHECK=1
 ```
 
+### Manual Update Check
+
+Check for updates manually:
+
+```bash
+# Human-readable output
+nstbrowser-ai-agent update check
+
+# JSON output
+nstbrowser-ai-agent update check --json
+```
+
+### Updating
+
+When an update is available:
+
+```bash
+# If installed globally
+npm install -g nstbrowser-ai-agent@latest
+
+# If using npx
+npx nstbrowser-ai-agent@latest
+
+# If installed locally in project
+npm install nstbrowser-ai-agent@latest
+```
+
+### Linux Dependencies
+
+The tool uses Nstbrowser by default, which handles browser management automatically. No additional dependencies are required.
+
 ## Quick Start Examples
 
 ### Using Temporary Browser (Fastest)
@@ -210,42 +239,33 @@ When you specify a profile for a browser action, the system follows these rules:
    - Otherwise creates a new temporary browser
    - Temporary browsers don't persist session data
 
-#### Specifying Profiles
+#### UUID Format Auto-Detection
 
-You can specify profiles in three ways:
+**Important:** The system automatically detects UUID format in profile names and treats them as profile IDs.
 
-**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"
+# UUID format is automatically detected and treated as profile ID:
+nstbrowser-ai-agent open https://example.com --profile "ef2b083a-8f77-4a7f-8441-a8d56bbd832b"
 ```
 
-**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"
+This means:
+- You can use `--profile` with either names or IDs
+- UUID format (8-4-4-4-12 hex digits) is automatically recognized
+- Case-insensitive: both lowercase and uppercase UUIDs work
+- Prevents accidental profile creation when you meant to use an ID
 
-# 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"
-```
+#### Specifying Profiles
 
-**3. Mixed Approach**
-```bash
-# Set default profile
-export NST_PROFILE="default-profile"
+Use the `--profile` flag to specify which profile to use:
 
-# Most commands use the default
-nstbrowser-ai-agent open https://example.com
+```bash
+# By profile name
+nstbrowser-ai-agent open https://example.com --profile "my-profile"
+nstbrowser-ai-agent click "#button" --profile "my-profile"
 
-# Override for specific commands
-nstbrowser-ai-agent click "#button" --nst-profile "other-profile"
+# By profile ID (UUID format auto-detected)
+nstbrowser-ai-agent open https://example.com --profile "ef2b083a-8f77-4a7f-8441-a8d56bbd832b"
+nstbrowser-ai-agent fill "#email" "test@test.com" --profile "abc-123-def-456"
 ```
 
 #### Examples
@@ -253,8 +273,8 @@ nstbrowser-ai-agent click "#button" --nst-profile "other-profile"
 **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"
+nstbrowser-ai-agent open https://example.com --profile "test-profile"
+nstbrowser-ai-agent click "#login" --profile "test-profile"
 ```
 
 **Use existing profile by ID:**
@@ -262,17 +282,17 @@ nstbrowser-ai-agent click "#login" --nst-profile "test-profile"
 # 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"
+# Use specific profile ID (UUID format auto-detected)
+nstbrowser-ai-agent open https://example.com --profile "abc-123-def-456-789"
 ```
 
 **Reuse running browser:**
 ```bash
 # Start a browser with a profile
-nstbrowser-ai-agent open https://example.com --nst-profile "my-profile"
+nstbrowser-ai-agent open https://example.com --profile "my-profile"
 
 # Later commands automatically connect to the same running browser
-nstbrowser-ai-agent click "#button" --nst-profile "my-profile"
+nstbrowser-ai-agent click "#button" --profile "my-profile"
 # No restart needed - uses existing browser!
 ```
 
@@ -522,13 +542,6 @@ nstbrowser-ai-agent forward                 # Go forward
 nstbrowser-ai-agent reload                  # Reload page
 ```
 
-### Setup
-
-```bash
-nstbrowser-ai-agent install                 # Download Chromium browser
-nstbrowser-ai-agent install --with-deps     # Also install system deps (Linux)
-```
-
 ## Sessions
 
 Run multiple isolated browser instances:
@@ -586,6 +599,20 @@ Configuration is stored in `~/.nst-ai-agent/config.json` and takes priority over
 
 **Priority order:** Config file > Environment variables > Defaults
 
+### Check NST Agent Status
+
+Verify that NST agent is running and responsive:
+
+```bash
+# Check NST agent status
+nstbrowser-ai-agent nst status
+
+# JSON output
+nstbrowser-ai-agent nst status --json
+```
+
+This command uses the `/api/agent/agent/info` endpoint to verify the NST service is accessible.
+
 ## Persistent Profiles
 
 By default, browser state (cookies, localStorage, login sessions) is ephemeral and lost when the browser closes. Use `--profile` to persist state across browser restarts:
@@ -1244,7 +1271,7 @@ 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. Set profile: `export NST_PROFILE="my-profile"` or use `browser start-once` for temporary browser
+1. Use profile: `--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
@@ -1396,11 +1423,7 @@ nstbrowser-ai-agent nst browser stop-all
 <td>Nstbrowser API port</td>
 <td><code>8848</code></td>
 </tr>
-<tr>
-<td><code>NST_PROFILE</code></td>
-<td>Profile name for provider=nst launch</td>
-<td>(none)</td>
-</tr>
+
 </tbody>
 </table>
 

package/dist/actions.js

@@ -138,15 +138,11 @@ export async function executeCommand(command, browser) {
  */
 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;
+    // Check if command has profile specification
+    const hasProfileSpec = !!cmdWithProfile.profile;
     // 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)
+    // 2. 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) {
@@ -182,8 +178,7 @@ async function ensureBrowserWithProfile(command, browser) {
                 id: command.id,
                 action: 'launch',
                 provider: 'nst',
-                nstProfileId: resolved.profileId,
-                nstProfileName: resolved.profileName,
+                profile: cmdWithProfile.profile,
             });
         }
         catch (error) {
@@ -193,6 +188,11 @@ async function ensureBrowserWithProfile(command, browser) {
             throw error;
         }
     }
+    // CRITICAL FIX: After launching NST browser, ensure at least one page exists
+    // NST browsers may connect with 0 pages initially, so we need to create one
+    if (!browser.hasPages()) {
+        await browser.ensurePage();
+    }
 }
 /**
  * Dispatch a command to its handler after policy checks have passed.