Skip to content

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

feat(profiles): add CLI creation and explicit missing status (PIN-307)

Luigi Agosti7bc0689d5140
diff --git a/cmd/pinchtab/cmd_cli_management.go b/cmd/pinchtab/cmd_cli_management.go
index d3fd1404..7f91e7b0 100644
--- a/cmd/pinchtab/cmd_cli_management.go
+++ b/cmd/pinchtab/cmd_cli_management.go
@@ -68,6 +68,17 @@ var profilesPruneCmd = &cobra.Command{
},
}
+var profilesCreateCmd = &cobra.Command{
+ Use: "create <name>",
+ Short: "Create a browser profile for human setup and authentication",
+ Args: cobra.ExactArgs(1),
+ Run: func(cmd *cobra.Command, args []string) {
+ runCLI(func(rt cliRuntime) {
+ browseractions.ProfilesCreate(rt.client, rt.base, rt.token, args[0])
+ })
+ },
+}
+
var activityCmd = &cobra.Command{
Use: "activity",
Short: "List recorded activity events",
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index bdb6f251..0505dfae 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -56,7 +56,7 @@ func registerManagementCommands() {
instanceCmd.AddCommand(instanceListCmd, startInstanceCmd, instanceNavigateCmd, instanceStopCmd, instanceRestartCmd, instanceLogsCmd)
activityCmd.AddCommand(activityTabCmd)
- profilesCmd.AddCommand(profilesPruneCmd)
+ profilesCmd.AddCommand(profilesCreateCmd, profilesPruneCmd)
configureManagementFlags()
diff --git a/internal/cli/actions/actions_profiles_create_test.go b/internal/cli/actions/actions_profiles_create_test.go
new file mode 100644
index 00000000..dd706149
--- /dev/null
+++ b/internal/cli/actions/actions_profiles_create_test.go
@@ -0,0 +1,38 @@
+package actions
+
+import (
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+)
+
+func TestProfilesCreatePostsTheNameAndPrintsTheCreatedIdentity(t *testing.T) {
+ var sent struct {
+ Name string `json:"name"`
+ }
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodPost || r.URL.Path != "/profiles" {
+ t.Fatalf("request = %s %s, want POST /profiles", r.Method, r.URL.Path)
+ }
+ if err := json.NewDecoder(r.Body).Decode(&sent); err != nil {
+ t.Fatalf("decode request: %v", err)
+ }
+ _, _ = w.Write([]byte(`{"status":"created","id":"prof_1234","name":"work"}`))
+ }))
+ defer srv.Close()
+
+ out := captureStdout(t, func() {
+ ProfilesCreate(srv.Client(), srv.URL, "", "work")
+ })
+
+ if sent.Name != "work" {
+ t.Fatalf("created name = %q, want work", sent.Name)
+ }
+ for _, want := range []string{"prof_1234", "work"} {
+ if !strings.Contains(out, want) {
+ t.Fatalf("output %q does not contain %q", out, want)
+ }
+ }
+}
diff --git a/internal/cli/actions/actions_system.go b/internal/cli/actions/actions_system.go
index 0fc74a3f..d6030f09 100644
--- a/internal/cli/actions/actions_system.go
+++ b/internal/cli/actions/actions_system.go
@@ -111,6 +111,19 @@ func Profiles(client *http.Client, base, token string, cmd *cobra.Command) {
fmt.Print(formatProfileList(profiles))
}
+func ProfilesCreate(client *http.Client, base, token, name string) {
+ raw := apiclient.DoPostRaw(client, base, token, "/profiles", map[string]any{"name": name})
+ var created struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
+ }
+ if err := json.Unmarshal(raw, &created); err != nil || created.ID == "" || created.Name == "" {
+ fmt.Fprintf(os.Stderr, "Failed to parse created profile: %s\n", strings.TrimSpace(string(raw)))
+ return
+ }
+ fmt.Printf("%s\t%s\n", created.ID, created.Name)
+}
+
// ProfilesPrune reclaims quarantine backlog. Without --confirm it reports what would go
// and frees nothing, so the bare invocation is safe for an agent to run.
func ProfilesPrune(client *http.Client, base, token string, cmd *cobra.Command) {
diff --git a/internal/mcp/handlers_helpers.go b/internal/mcp/handlers_helpers.go
index 22034f84..b659cca9 100644
--- a/internal/mcp/handlers_helpers.go
+++ b/internal/mcp/handlers_helpers.go
@@ -315,11 +315,13 @@ func topLevelCount(top map[string]json.RawMessage, key string) (int, bool) {
type profileInstanceStatus struct {
Name string `json:"name"`
+ Exists bool `json:"exists"`
Running bool `json:"running"`
Status string `json:"status"`
Port string `json:"port"`
ID string `json:"id"`
Error string `json:"error"`
+ Message string `json:"message"`
}
func jsonResult(v any) (*mcp.CallToolResult, error) {
diff --git a/internal/mcp/handlers_tabs.go b/internal/mcp/handlers_tabs.go
index 9c6fecd9..04572701 100644
--- a/internal/mcp/handlers_tabs.go
+++ b/internal/mcp/handlers_tabs.go
@@ -162,6 +162,7 @@ func handleConnectProfile(c *Client) func(context.Context, mcp.CallToolRequest)
resp := map[string]any{
"profile": status.Name,
+ "exists": status.Exists,
"running": status.Running,
"status": status.Status,
"id": status.ID,
@@ -170,6 +171,14 @@ func handleConnectProfile(c *Client) func(context.Context, mcp.CallToolRequest)
if status.Error != "" {
resp["error"] = status.Error
}
+ if !status.Exists || status.Status == "missing" {
+ resp["status"] = "missing"
+ resp["message"] = status.Message
+ if status.Message == "" {
+ resp["message"] = fmt.Sprintf("Profile %q does not exist. Creating and authenticating a reusable profile is a human setup step.", status.Name)
+ }
+ return jsonResult(resp)
+ }
if status.Running && status.Port != "" {
resp["url"] = c.dashboardProfilesURL()
resp["message"] = fmt.Sprintf("Open the dashboard to access the running profile %q.", status.Name)
diff --git a/internal/mcp/handlers_tabs_test.go b/internal/mcp/handlers_tabs_test.go
index 16e609c9..2811174e 100644
--- a/internal/mcp/handlers_tabs_test.go
+++ b/internal/mcp/handlers_tabs_test.go
@@ -102,6 +102,7 @@ func TestHandleConnectProfileRunning(t *testing.T) {
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(map[string]any{
"name": "work",
+ "exists": true,
"running": true,
"status": "running",
"port": "9868",
@@ -128,6 +129,7 @@ func TestHandleConnectProfileNotRunning(t *testing.T) {
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(map[string]any{
"name": "work",
+ "exists": true,
"running": false,
"status": "stopped",
"port": "",
@@ -152,7 +154,7 @@ func TestHandleConnectProfileNotRunning(t *testing.T) {
}
}
-func TestHandleConnectProfileMissingProfile(t *testing.T) {
+func TestHandleConnectProfileRequiresAProfileArgument(t *testing.T) {
srv := mockPinchTab()
defer srv.Close()
@@ -162,6 +164,31 @@ func TestHandleConnectProfileMissingProfile(t *testing.T) {
}
}
+func TestHandleConnectProfileReportsMissingAsAHumanSetupStep(t *testing.T) {
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ _ = json.NewEncoder(w).Encode(map[string]any{
+ "name": "missing",
+ "exists": false,
+ "running": false,
+ "status": "missing",
+ "message": `Profile "missing" does not exist. Creating and authenticating a reusable profile is a human setup step.`,
+ })
+ }))
+ defer srv.Close()
+
+ r := callTool(t, "pinchtab_connect_profile", map[string]any{"profile": "missing"}, srv)
+ text := resultText(t, r)
+ for _, want := range []string{`"exists": false`, `"status": "missing"`, "does not exist", "human setup step"} {
+ if !strings.Contains(text, want) {
+ t.Fatalf("missing-profile result %q does not contain %q", text, want)
+ }
+ }
+ if strings.Contains(text, "start the profile") {
+ t.Fatalf("missing-profile result suggests an agent retry: %q", text)
+ }
+}
+
func TestHandleHTTPError(t *testing.T) {
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
w.WriteHeader(500)
diff --git a/internal/orchestrator/handlers_instances.go b/internal/orchestrator/handlers_instances.go
index 9f2aad94..9fde85ca 100644
--- a/internal/orchestrator/handlers_instances.go
+++ b/internal/orchestrator/handlers_instances.go
@@ -254,7 +254,10 @@ func (o *Orchestrator) startInstanceWithRequest(w http.ResponseWriter, r *http.R
if req.ProfileID != "" {
profileName, err = o.resolveProfileName(req.ProfileID)
if err != nil {
- httpx.Error(w, 404, fmt.Errorf("profile %q not found", req.ProfileID))
+ httpx.ErrorCode(w, http.StatusNotFound, "profile_not_found", fmt.Sprintf("profile %q not found", req.ProfileID), false, map[string]any{
+ "profile": req.ProfileID,
+ "remedy": "pinchtab profiles create <name>",
+ })
return
}
} else {
diff --git a/internal/orchestrator/handlers_instances_test.go b/internal/orchestrator/handlers_instances_test.go
index 7efb0388..85d03981 100644
--- a/internal/orchestrator/handlers_instances_test.go
+++ b/internal/orchestrator/handlers_instances_test.go
@@ -62,6 +62,28 @@ func TestInstanceStartEndpointsRejectUnknownProfileKeysWithoutLaunching(t *testi
}
}
+func TestHandleStartInstanceMissingProfileNamesTheCreateRemedy(t *testing.T) {
+ runner := &mockRunner{portAvail: true}
+ o := NewOrchestratorWithRunner(t.TempDir(), runner)
+ o.profiles = profiles.NewProfileManager(t.TempDir())
+ req := httptest.NewRequest(http.MethodPost, "/instances/start", strings.NewReader(`{"profileId":"missing"}`))
+ w := httptest.NewRecorder()
+
+ o.handleStartInstance(w, req)
+
+ if w.Code != http.StatusNotFound {
+ t.Fatalf("status = %d, want 404: %s", w.Code, w.Body.String())
+ }
+ for _, want := range []string{"profile_not_found", "pinchtab profiles create"} {
+ if !strings.Contains(w.Body.String(), want) {
+ t.Fatalf("body %q does not contain %q", w.Body.String(), want)
+ }
+ }
+ if runner.runCalled || len(o.List()) != 0 {
+ t.Fatal("a missing profile started an instance")
+ }
+}
+
func TestHandleLaunchByNameAliasesStartSemantics(t *testing.T) {
old := processAliveFunc
processAliveFunc = func(pid int) bool { return pid > 0 }
diff --git a/internal/orchestrator/handlers_profiles.go b/internal/orchestrator/handlers_profiles.go
index 206d2c3c..88d1fb20 100644
--- a/internal/orchestrator/handlers_profiles.go
+++ b/internal/orchestrator/handlers_profiles.go
@@ -81,9 +81,11 @@ func (o *Orchestrator) handleProfileInstance(w http.ResponseWriter, r *http.Requ
if err != nil {
httpx.JSON(w, 200, map[string]any{
"name": id,
+ "exists": false,
"running": false,
- "status": "stopped",
+ "status": "missing",
"port": "",
+ "message": fmt.Sprintf("Profile %q does not exist. Creating and authenticating a reusable profile is a human setup step.", id),
})
return
}
@@ -93,6 +95,7 @@ func (o *Orchestrator) handleProfileInstance(w http.ResponseWriter, r *http.Requ
if inst.ProfileName == name && (inst.Status == "running" || inst.Status == "starting") {
httpx.JSON(w, 200, map[string]any{
"name": name,
+ "exists": true,
"running": inst.Status == "running",
"status": inst.Status,
"port": inst.Port,
@@ -103,6 +106,7 @@ func (o *Orchestrator) handleProfileInstance(w http.ResponseWriter, r *http.Requ
}
httpx.JSON(w, 200, map[string]any{
"name": name,
+ "exists": true,
"running": false,
"status": "stopped",
"port": "",
diff --git a/internal/orchestrator/handlers_profiles_test.go b/internal/orchestrator/handlers_profiles_test.go
index e701c603..fd06fa95 100644
--- a/internal/orchestrator/handlers_profiles_test.go
+++ b/internal/orchestrator/handlers_profiles_test.go
@@ -88,3 +88,44 @@ func TestHandleStartByID_TargetsConfigBadBrowser_Rejects400(t *testing.T) {
t.Fatalf("status = %d, want 400 body=%s", w.Code, w.Body.String())
}
}
+
+func TestHandleProfileInstanceDistinguishesMissingFromStopped(t *testing.T) {
+ baseDir := t.TempDir()
+ o := NewOrchestratorWithRunner(baseDir, &mockRunner{portAvail: true})
+ pm := profiles.NewProfileManager(baseDir)
+ if err := pm.CreateWithMeta("work", profiles.ProfileMeta{}); err != nil {
+ t.Fatalf("CreateWithMeta: %v", err)
+ }
+ o.profiles = pm
+
+ for _, tc := range []struct {
+ name string
+ wantExists bool
+ wantStatus string
+ }{
+ {"work", true, "stopped"},
+ {"missing", false, "missing"},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ req := httptest.NewRequest(http.MethodGet, "/profiles/"+tc.name+"/instance", nil)
+ req.SetPathValue("id", tc.name)
+ w := httptest.NewRecorder()
+ o.handleProfileInstance(w, req)
+
+ var body struct {
+ Exists bool `json:"exists"`
+ Status string `json:"status"`
+ Message string `json:"message"`
+ }
+ if err := json.NewDecoder(w.Body).Decode(&body); err != nil {
+ t.Fatalf("decode: %v", err)
+ }
+ if body.Exists != tc.wantExists || body.Status != tc.wantStatus {
+ t.Fatalf("exists/status = %v/%q, want %v/%q", body.Exists, body.Status, tc.wantExists, tc.wantStatus)
+ }
+ if !tc.wantExists && (!strings.Contains(body.Message, "does not exist") || !strings.Contains(body.Message, "human setup step")) {
+ t.Fatalf("missing-profile message does not stop an agent retry loop: %q", body.Message)
+ }
+ })
+ }
+}
diff --git a/plugins/grok/skills/pinchtab/SKILL.md b/plugins/grok/skills/pinchtab/SKILL.md
index 66c2f1f0..ddd3e37d 100644
--- a/plugins/grok/skills/pinchtab/SKILL.md
+++ b/plugins/grok/skills/pinchtab/SKILL.md
@@ -87,7 +87,7 @@ If a site requires a CAPTCHA, anti-bot challenge, or other human verification, s
## Authentication and State
-Patterns: (1) one-off `pinchtab instance start`; (2) reuse profile `instance start --profile work --mode headed`, switch to headless after login; (3) HTTP `POST /profiles` then `POST /profiles/<name>/start`; (4) human-assisted headed login, agent reuses headless. Agent sessions: `pinchtab session create --agent-id <id>` or `POST /sessions` → set `PINCHTAB_SESSION=ses_...`.
+Patterns: (1) one-off `pinchtab instance start`; (2) reuse a profile with `instance start --profile work`; (3) HTTP `POST /profiles` then `POST /profiles/<name>/start`. Human setup: `pinchtab profiles create work`, authenticate headed; agents reuse headless. Agent sessions: `pinchtab session create --agent-id <id>` or `POST /sessions` → set `PINCHTAB_SESSION=ses_...`.
**Session reuse safety:** When reusing authenticated browser sessions established by a human, use a dedicated low-privilege profile — not the user's personal browsing profile. Confirm with the user before performing account-changing actions (password changes, payment, deletion, permissions) in a reused session. Restrict navigation to the sites needed for the task.
diff --git a/plugins/grok/skills/pinchtab/references/commands.md b/plugins/grok/skills/pinchtab/references/commands.md
index bb5dbd16..e6feb3e9 100644
--- a/plugins/grok/skills/pinchtab/references/commands.md
+++ b/plugins/grok/skills/pinchtab/references/commands.md
@@ -365,6 +365,7 @@ List available profiles.
```bash
pinchtab profiles
+pinchtab profiles create work
pinchtab instance start --profile work
```
diff --git a/plugins/grok/skills/pinchtab/references/mcp.md b/plugins/grok/skills/pinchtab/references/mcp.md
index 9c83bd9c..42f69cf1 100644
--- a/plugins/grok/skills/pinchtab/references/mcp.md
+++ b/plugins/grok/skills/pinchtab/references/mcp.md
@@ -137,7 +137,7 @@ The MCP surface is intentionally scoped to browser automation. The following are
| Capability | Status | Alternative |
|------------|--------|-------------|
-| Create/edit/delete profiles | ❌ Not available | Use `pinchtab profiles`, `pinchtab instance start --profile <name>`, or the HTTP API |
+| Create/edit/delete profiles | ❌ Not available | Human setup uses `pinchtab profiles create <name>`, authenticates it headed, then starts/reuses it with `pinchtab instance start --profile <name>` |
| Configure the scheduler | ❌ Not available | Use the HTTP API/configuration surface |
| CAPTCHA or human verification | ❌ Not available | Hand the step to the user |
| Modify stealth or fingerprint settings | ❌ Not available | Not part of an agent workflow |
diff --git a/plugins/grok/skills/pinchtab/references/profiles.md b/plugins/grok/skills/pinchtab/references/profiles.md
index 6d0c3e61..07d3ced7 100644
--- a/plugins/grok/skills/pinchtab/references/profiles.md
+++ b/plugins/grok/skills/pinchtab/references/profiles.md
@@ -58,6 +58,7 @@ CLI subcommands are available — use these instead of `curl` when possible:
```bash
pinchtab profiles # list profiles
+pinchtab profiles create <name> # human setup: create before authentication
pinchtab instance start --profile <name> # start (auto-allocates port)
pinchtab instance navigate <id> <url>
pinchtab instance stop <id>
@@ -65,6 +66,9 @@ pinchtab instance restart <id>
pinchtab instance logs <id>
```
+Creating a profile only creates an empty browser state. A human must start it headed and
+authenticate before an agent can reuse that session.
+
Once a profile instance is running, the CLI auto-routes to it; you can also target it explicitly:
```bash
diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.md
index 66c2f1f0..ddd3e37d 100644
--- a/skills/pinchtab/SKILL.md
+++ b/skills/pinchtab/SKILL.md
@@ -87,7 +87,7 @@ If a site requires a CAPTCHA, anti-bot challenge, or other human verification, s
## Authentication and State
-Patterns: (1) one-off `pinchtab instance start`; (2) reuse profile `instance start --profile work --mode headed`, switch to headless after login; (3) HTTP `POST /profiles` then `POST /profiles/<name>/start`; (4) human-assisted headed login, agent reuses headless. Agent sessions: `pinchtab session create --agent-id <id>` or `POST /sessions` → set `PINCHTAB_SESSION=ses_...`.
+Patterns: (1) one-off `pinchtab instance start`; (2) reuse a profile with `instance start --profile work`; (3) HTTP `POST /profiles` then `POST /profiles/<name>/start`. Human setup: `pinchtab profiles create work`, authenticate headed; agents reuse headless. Agent sessions: `pinchtab session create --agent-id <id>` or `POST /sessions` → set `PINCHTAB_SESSION=ses_...`.
**Session reuse safety:** When reusing authenticated browser sessions established by a human, use a dedicated low-privilege profile — not the user's personal browsing profile. Confirm with the user before performing account-changing actions (password changes, payment, deletion, permissions) in a reused session. Restrict navigation to the sites needed for the task.
diff --git a/skills/pinchtab/references/commands.md b/skills/pinchtab/references/commands.md
index bb5dbd16..e6feb3e9 100644
--- a/skills/pinchtab/references/commands.md
+++ b/skills/pinchtab/references/commands.md
@@ -365,6 +365,7 @@ List available profiles.
```bash
pinchtab profiles
+pinchtab profiles create work
pinchtab instance start --profile work
```
diff --git a/skills/pinchtab/references/mcp.md b/skills/pinchtab/references/mcp.md
index 9c83bd9c..42f69cf1 100644
--- a/skills/pinchtab/references/mcp.md
+++ b/skills/pinchtab/references/mcp.md
@@ -137,7 +137,7 @@ The MCP surface is intentionally scoped to browser automation. The following are
| Capability | Status | Alternative |
|------------|--------|-------------|
-| Create/edit/delete profiles | ❌ Not available | Use `pinchtab profiles`, `pinchtab instance start --profile <name>`, or the HTTP API |
+| Create/edit/delete profiles | ❌ Not available | Human setup uses `pinchtab profiles create <name>`, authenticates it headed, then starts/reuses it with `pinchtab instance start --profile <name>` |
| Configure the scheduler | ❌ Not available | Use the HTTP API/configuration surface |
| CAPTCHA or human verification | ❌ Not available | Hand the step to the user |
| Modify stealth or fingerprint settings | ❌ Not available | Not part of an agent workflow |
diff --git a/skills/pinchtab/references/profiles.md b/skills/pinchtab/references/profiles.md
index 6d0c3e61..07d3ced7 100644
--- a/skills/pinchtab/references/profiles.md
+++ b/skills/pinchtab/references/profiles.md
@@ -58,6 +58,7 @@ CLI subcommands are available — use these instead of `curl` when possible:
```bash
pinchtab profiles # list profiles
+pinchtab profiles create <name> # human setup: create before authentication
pinchtab instance start --profile <name> # start (auto-allocates port)
pinchtab instance navigate <id> <url>
pinchtab instance stop <id>
@@ -65,6 +66,9 @@ pinchtab instance restart <id>
pinchtab instance logs <id>
```
+Creating a profile only creates an empty browser state. A human must start it headed and
+authenticate before an agent can reuse that session.
+
Once a profile instance is running, the CLI auto-routes to it; you can also target it explicitly:
```bash