nstbrowser-ai-agent 0.0.3 → 0.0.5

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
 
@@ -129,6 +132,44 @@ pnpm link --global  # Makes nstbrowser-ai-agent available globally
 nstbrowser-ai-agent install
 ```
 
+## Updates
+
+### Automatic Update Checks
+
+The CLI automatically checks for updates once every 24 hours and notifies you when a new version is available.
+
+**Disable automatic checks:**
+```bash
+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
 
 On Linux, install system dependencies:
@@ -185,6 +226,119 @@ nstbrowser-ai-agent click @e1
 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
+
+#### UUID Format Auto-Detection
+
+**Important:** The system automatically detects UUID format in profile names and treats them as profile IDs.
+
+```bash
+# These are equivalent (UUID format detected):
+nstbrowser-ai-agent open https://example.com --nst-profile "ef2b083a-8f77-4a7f-8441-a8d56bbd832b"
+nstbrowser-ai-agent open https://example.com --nst-profile-id "ef2b083a-8f77-4a7f-8441-a8d56bbd832b"
+
+# Also works with environment variables:
+export NST_PROFILE="ef2b083a-8f77-4a7f-8441-a8d56bbd832b"  # Treated as ID
+```
+
+This means:
+- You can use `--nst-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
+
+#### 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"
+
+# UUID format auto-detected (treated as ID)
+nstbrowser-ai-agent open https://example.com --nst-profile "ef2b083a-8f77-4a7f-8441-a8d56bbd832b"
+```
+
+**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.
@@ -495,6 +649,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:

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.
  */