Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

refactor: unify profile routes around ID, add /profiles/{id}/start|stop|instance

Mario1258fa4c0069
diff --git a/internal/dashboard/dashboard/profiles.js b/internal/dashboard/dashboard/profiles.js
index 7b179c6c..9aff4c63 100644
--- a/internal/dashboard/dashboard/profiles.js
+++ b/internal/dashboard/dashboard/profiles.js
@@ -148,7 +148,7 @@ function renderProfileCard(profile, inst) {
let actions = '';
if (isRunning) {
actions = '<button onclick="viewProfileDetails(\'' + esc(name) + '\', \'' + esc(inst.id) + '\')">Details</button>'
- + '<button class="danger" onclick="stopProfile(\'' + esc(name) + '\')">Stop</button>';
+ + '<button class="danger" onclick="stopProfile(\'' + esc(profile.id) + '\', \'' + esc(name) + '\')">Stop</button>';
} else {
actions = '<button onclick="viewProfileDetails(\'' + esc(name) + '\', \'' + esc(inst ? inst.id : '') + '\')">Details</button>'
+ '<button class="btn-launch" onclick="openLaunchModal(\'' + esc(name) + '\')">Launch</button>';
@@ -348,9 +348,9 @@ async function stopInstance(id) {
setTimeout(loadProfiles, 1000);
}
-async function stopProfile(name) {
+async function stopProfile(profileId, name) {
if (!await appConfirm('Stop profile "' + name + '" gracefully?', '⏹ Stop Profile')) return;
- const res = await fetch('/profiles/' + encodeURIComponent(name) + '/stop', { method: 'POST' });
+ const res = await fetch('/profiles/' + encodeURIComponent(profileId) + '/stop', { method: 'POST' });
if (!res.ok) {
const data = await res.json().catch(() => ({}));
await appAlert('Stop failed: ' + (data.error || res.statusText), 'Error');
diff --git a/internal/orchestrator/handlers.go b/internal/orchestrator/handlers.go
index 4bd98254..fb356396 100644
--- a/internal/orchestrator/handlers.go
+++ b/internal/orchestrator/handlers.go
@@ -9,19 +9,23 @@ import (
)
func (o *Orchestrator) RegisterHandlers(mux *http.ServeMux) {
+ // Core routes
mux.HandleFunc("GET /instances", o.handleList)
+ mux.HandleFunc("GET /instances/tabs", o.handleAllTabs)
+
+ // Profile lifecycle by ID (canonical)
+ mux.HandleFunc("POST /profiles/{id}/start", o.handleStartByID)
+ mux.HandleFunc("POST /profiles/{id}/stop", o.handleStopByID)
+ mux.HandleFunc("GET /profiles/{id}/instance", o.handleProfileInstance)
- // Agent-friendly routes: start/stop by profile ID
+ // Short aliases for agents
mux.HandleFunc("POST /start/{id}", o.handleStartByID)
mux.HandleFunc("POST /stop/{id}", o.handleStopByID)
- // Dashboard-compatible aliases
- mux.HandleFunc("POST /instances/launch", o.handleLaunchCompat)
+ // Dashboard / backward compat
+ mux.HandleFunc("POST /instances/launch", o.handleLaunchByName)
mux.HandleFunc("POST /instances/{id}/stop", o.handleStopByInstanceID)
mux.HandleFunc("GET /instances/{id}/logs", o.handleLogsByID)
- mux.HandleFunc("GET /instances/tabs", o.handleAllTabs)
- mux.HandleFunc("POST /profiles/{name}/stop", o.handleStopProfileByPath)
- mux.HandleFunc("GET /profiles/{name}/instance", o.handleProfileInstance)
mux.HandleFunc("GET /instances/{id}/proxy/screencast", o.handleProxyScreencast)
}
@@ -29,13 +33,26 @@ func (o *Orchestrator) handleList(w http.ResponseWriter, r *http.Request) {
web.JSON(w, 200, o.List())
}
-func (o *Orchestrator) handleStartByID(w http.ResponseWriter, r *http.Request) {
- id := r.PathValue("id")
+// resolveProfileID resolves a path value to a profile name.
+// Accepts both a 12-char hex profile ID or a profile name directly.
+func (o *Orchestrator) resolveProfileName(idOrName string) (string, error) {
if o.profiles == nil {
- web.Error(w, 500, fmt.Errorf("profile manager not configured"))
- return
+ return "", fmt.Errorf("profile manager not configured")
}
- name, err := o.profiles.FindByID(id)
+ // Try as ID first
+ if name, err := o.profiles.FindByID(idOrName); err == nil {
+ return name, nil
+ }
+ // Try as name (for backward compat routes like /profiles/{name}/stop)
+ if o.profiles.Exists(idOrName) {
+ return idOrName, nil
+ }
+ return "", fmt.Errorf("profile %q not found", idOrName)
+}
+
+func (o *Orchestrator) handleStartByID(w http.ResponseWriter, r *http.Request) {
+ id := r.PathValue("id")
+ name, err := o.resolveProfileName(id)
if err != nil {
web.Error(w, 404, err)
return
@@ -60,11 +77,7 @@ func (o *Orchestrator) handleStartByID(w http.ResponseWriter, r *http.Request) {
func (o *Orchestrator) handleStopByID(w http.ResponseWriter, r *http.Request) {
id := r.PathValue("id")
- if o.profiles == nil {
- web.Error(w, 500, fmt.Errorf("profile manager not configured"))
- return
- }
- name, err := o.profiles.FindByID(id)
+ name, err := o.resolveProfileName(id)
if err != nil {
web.Error(w, 404, err)
return
@@ -76,7 +89,7 @@ func (o *Orchestrator) handleStopByID(w http.ResponseWriter, r *http.Request) {
web.JSON(w, 200, map[string]string{"status": "stopped", "id": id, "name": name})
}
-func (o *Orchestrator) handleLaunchCompat(w http.ResponseWriter, r *http.Request) {
+func (o *Orchestrator) handleLaunchByName(w http.ResponseWriter, r *http.Request) {
var req struct {
Name string `json:"name"`
Port string `json:"port"`
@@ -123,17 +136,19 @@ func (o *Orchestrator) handleAllTabs(w http.ResponseWriter, r *http.Request) {
web.JSON(w, 200, o.AllTabs())
}
-func (o *Orchestrator) handleStopProfileByPath(w http.ResponseWriter, r *http.Request) {
- name := r.PathValue("name")
- if err := o.StopProfile(name); err != nil {
- web.Error(w, 404, err)
+func (o *Orchestrator) handleProfileInstance(w http.ResponseWriter, r *http.Request) {
+ id := r.PathValue("id")
+ name, err := o.resolveProfileName(id)
+ if err != nil {
+ web.JSON(w, 200, map[string]any{
+ "name": id,
+ "running": false,
+ "status": "stopped",
+ "port": "",
+ })
return
}
- web.JSON(w, 200, map[string]string{"status": "stopped", "name": name})
-}
-func (o *Orchestrator) handleProfileInstance(w http.ResponseWriter, r *http.Request) {
- name := r.PathValue("name")
instances := o.List()
for _, inst := range instances {
if inst.Name == name && (inst.Status == "running" || inst.Status == "starting") {
@@ -170,5 +185,3 @@ func (o *Orchestrator) handleProxyScreencast(w http.ResponseWriter, r *http.Requ
targetURL := fmt.Sprintf("ws://localhost:%s/screencast?tabId=%s", inst.Port, tabID)
web.JSON(w, 200, map[string]string{"wsUrl": targetURL})
}
-
-// handleLogs removed — use handleLogsByID (path-param) instead
diff --git a/internal/profiles/profiles.go b/internal/profiles/profiles.go
index f06b79a4..3a7d72c5 100644
--- a/internal/profiles/profiles.go
+++ b/internal/profiles/profiles.go
@@ -56,6 +56,12 @@ func NewProfileManager(baseDir string) *ProfileManager {
}
}
+func (pm *ProfileManager) Exists(name string) bool {
+ dir := filepath.Join(pm.baseDir, name)
+ info, err := os.Stat(dir)
+ return err == nil && info.IsDir()
+}
+
func (pm *ProfileManager) List() ([]bridge.ProfileInfo, error) {
pm.mu.RLock()
defer pm.mu.RUnlock()
diff --git a/skill/pinchtab/SKILL.md b/skill/pinchtab/SKILL.md
index fdae757f..f2f869cd 100644
--- a/skill/pinchtab/SKILL.md
+++ b/skill/pinchtab/SKILL.md
@@ -165,12 +165,15 @@ Returns array of profiles with `id`, `name`, `accountEmail`, `useWhen`, etc.
```bash
# Auto-allocate port (recommended)
-curl -X POST http://localhost:9867/start/278be873adeb
+curl -X POST http://localhost:9867/profiles/278be873adeb/start
# With specific port and headless mode
-curl -X POST http://localhost:9867/start/278be873adeb \
+curl -X POST http://localhost:9867/profiles/278be873adeb/start \
-H 'Content-Type: application/json' \
-d '{"port": "9868", "headless": true}'
+
+# Short alias (same behavior)
+curl -X POST http://localhost:9867/start/278be873adeb
```
Returns the instance info including the allocated `port`. Use that port for all subsequent API calls (navigate, snapshot, action, etc.).
@@ -178,24 +181,25 @@ Returns the instance info including the allocated `port`. Use that port for all
### Stop a profile by ID
```bash
+curl -X POST http://localhost:9867/profiles/278be873adeb/stop
+
+# Short alias
curl -X POST http://localhost:9867/stop/278be873adeb
```
### Check profile instance status
```bash
+# By profile ID (recommended)
+curl http://localhost:9867/profiles/278be873adeb/instance
+
+# By profile name (also works)
curl http://localhost:9867/profiles/Pinchtab%20org/instance
```
-### Launch by name (alternative)
+### Launch by name (dashboard style)
```bash
-# Via /launch endpoint (name-based)
-curl -X POST http://localhost:9867/launch \
- -H 'Content-Type: application/json' \
- -d '{"profile": "work", "port": "9868", "headless": true}'
-
-# Via /instances/launch (dashboard compat)
curl -X POST http://localhost:9867/instances/launch \
-H 'Content-Type: application/json' \
-d '{"name": "work", "port": "9868"}'
@@ -206,10 +210,10 @@ curl -X POST http://localhost:9867/instances/launch \
```bash
# 1. List profiles to find the right one
PROFILES=$(curl -s http://localhost:9867/profiles)
-# Pick the profile ID you need
+# Pick the profile ID you need (12-char hex, e.g. "278be873adeb")
-# 2. Start the profile
-INSTANCE=$(curl -s -X POST http://localhost:9867/start/$PROFILE_ID)
+# 2. Start the profile (auto-allocates port)
+INSTANCE=$(curl -s -X POST http://localhost:9867/profiles/$PROFILE_ID/start)
PORT=$(echo $INSTANCE | jq -r .port)
# 3. Use the instance (all API calls go to the instance port)
@@ -217,8 +221,11 @@ curl -X POST http://localhost:$PORT/navigate -H 'Content-Type: application/json'
-d '{"url": "https://mail.google.com"}'
curl http://localhost:$PORT/snapshot?maxTokens=4000
-# 4. Stop when done
-curl -s -X POST http://localhost:9867/stop/$PROFILE_ID
+# 4. Check instance status
+curl http://localhost:9867/profiles/$PROFILE_ID/instance
+
+# 5. Stop when done
+curl -s -X POST http://localhost:9867/profiles/$PROFILE_ID/stop
```
### Profile IDs
diff --git a/tests/TEST-PLAN-dashboard.md b/tests/TEST-PLAN-dashboard.md
index ea3f8bbd..4e11c741 100644
--- a/tests/TEST-PLAN-dashboard.md
+++ b/tests/TEST-PLAN-dashboard.md
@@ -164,12 +164,21 @@ Verify every registered route returns a non-404 status (may return 400/503 for m
| RE21 | `/instances/nonexistent/logs` | GET | 404 | ✅ |
| RE22 | `/instances/nonexistent/proxy/screencast?tabId=x` | GET | 404 | ✅ |
-### Agent-friendly routes
+### Profile lifecycle (by ID — canonical for agents)
| # | Route | Method | Expected | Auto |
|---|-------|--------|----------|------|
-| RE23 | `/start/000000000000` | POST | 404 (unknown profile ID) | ✅ |
-| RE24 | `/stop/000000000000` | POST | 404 (unknown profile ID) | ✅ |
+| RE23 | `/profiles/{id}/start` | POST | 201 (launches instance) | ✅ |
+| RE24 | `/profiles/{id}/stop` | POST | 200 (stops instance) | ✅ |
+| RE25a | `/profiles/{id}/instance` | GET | 200 (instance status) | ✅ |
+| RE25b | `/profiles/{unknownId}/start` | POST | 404 | ✅ |
+
+### Short aliases (agent convenience)
+
+| # | Route | Method | Expected | Auto |
+|---|-------|--------|----------|------|
+| RE25c | `/start/{id}` | POST | 201 (same as /profiles/{id}/start) | ✅ |
+| RE25d | `/stop/{id}` | POST | 200 (same as /profiles/{id}/stop) | ✅ |
### Proxy endpoints (503 when no instance running)