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.goindex 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.goindex 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.gonew file mode 100644index 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.goindex 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.goindex 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.goindex 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.goindex 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.goindex 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.Rif 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.goindex 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 := processAliveFuncprocessAliveFunc = func(pid int) bool { return pid > 0 }diff --git a/internal/orchestrator/handlers_profiles.go b/internal/orchestrator/handlers_profiles.goindex 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.Requif 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.Requif 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.goindex 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.mdindex 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.mdindex 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.```bashpinchtab profiles+pinchtab profiles create workpinchtab instance start --profile work```diff --git a/plugins/grok/skills/pinchtab/references/mcp.md b/plugins/grok/skills/pinchtab/references/mcp.mdindex 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.mdindex 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:```bashpinchtab profiles # list profiles+pinchtab profiles create <name> # human setup: create before authenticationpinchtab 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:```bashdiff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.mdindex 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.mdindex bb5dbd16..e6feb3e9 100644--- a/skills/pinchtab/references/commands.md+++ b/skills/pinchtab/references/commands.md@@ -365,6 +365,7 @@ List available profiles.```bashpinchtab profiles+pinchtab profiles create workpinchtab instance start --profile work```diff --git a/skills/pinchtab/references/mcp.md b/skills/pinchtab/references/mcp.mdindex 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.mdindex 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:```bashpinchtab profiles # list profiles+pinchtab profiles create <name> # human setup: create before authenticationpinchtab 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