High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat: exposing humanize for some action, default to false
Luigi Agostiaed8be8d7250
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.goindex 88e74ffa..1aba5a64 100644--- a/cmd/pinchtab/cmd_cli_register.go+++ b/cmd/pinchtab/cmd_cli_register.go@@ -147,26 +147,35 @@ func configureBrowserFlags() {clickCmd.Flags().Bool("text", false, "Output page text after action (for verification)")clickCmd.Flags().String("dialog-action", "", "Auto-handle a JS dialog opened by the click: accept | dismiss")clickCmd.Flags().String("dialog-text", "", "Prompt response text (with --dialog-action accept on prompt())")+ clickCmd.Flags().Bool("humanize", false, "Use humanized bezier+jitter input path (overrides instance config)")dblclickCmd.Flags().String("css", "", "CSS selector instead of ref")addPointFlags(dblclickCmd, "dblclick")+ dblclickCmd.Flags().Bool("humanize", false, "Use humanized bezier+jitter input path (overrides instance config)")hoverCmd.Flags().String("css", "", "CSS selector instead of ref")addPointFlags(hoverCmd, "hover")+ hoverCmd.Flags().Bool("humanize", false, "Use humanized bezier+jitter input path (overrides instance config)")mouseMoveCmd.Flags().String("css", "", "CSS selector instead of ref")addPointFlags(mouseMoveCmd, bridge.ActionMouseMove)+ mouseMoveCmd.Flags().Bool("humanize", false, "Use humanized bezier+jitter input path (overrides instance config)")mouseDownCmd.Flags().String("css", "", "CSS selector instead of ref")addPointFlags(mouseDownCmd, bridge.ActionMouseDown)mouseDownCmd.Flags().String("button", "left", "Mouse button: left, right, middle")+ mouseDownCmd.Flags().Bool("humanize", false, "Use humanized bezier+jitter input path (overrides instance config)")mouseUpCmd.Flags().String("css", "", "CSS selector instead of ref")addPointFlags(mouseUpCmd, bridge.ActionMouseUp)mouseUpCmd.Flags().String("button", "left", "Mouse button: left, right, middle")+ mouseUpCmd.Flags().Bool("humanize", false, "Use humanized bezier+jitter input path (overrides instance config)")mouseWheelCmd.Flags().String("css", "", "CSS selector instead of ref")addPointFlags(mouseWheelCmd, bridge.ActionMouseWheel)+ mouseWheelCmd.Flags().Bool("humanize", false, "Use humanized bezier+jitter input path (overrides instance config)")++ typeCmd.Flags().Bool("humanize", false, "Use humanized per-character keypress timing (overrides instance config)")mouseWheelCmd.Flags().Int("dx", 0, "Wheel delta X")mouseWheelCmd.Flags().Int("dy", 0, "Wheel delta Y")diff --git a/internal/bridge/action_pointer.go b/internal/bridge/action_pointer.goindex c4c4d55e..8eed8547 100644--- a/internal/bridge/action_pointer.go+++ b/internal/bridge/action_pointer.go@@ -16,6 +16,28 @@ var mouseMoveByCoordinateAction = MouseMoveByCoordinatevar mouseDownByCoordinateAction = MouseDownByCoordinatevar mouseUpByCoordinateAction = MouseUpByCoordinate+// effectiveHumanize resolves whether an action should use the humanized+// (bezier + per-event jitter + pre-press sleeps) input path. Precedence:+//+// 1. Per-request override: ActionRequest.Humanize (if non-nil)+// 2. Per-instance default: bridge Config.Humanize+// 3. Built-in default: false+//+// The action kind is intentionally NOT consulted — both click/type and+// humanClick/humanType honour the same resolution. This means+// `kind: humanClick` defaults to raw input unless config.humanize=true+// or the request explicitly sets humanize:true; callers who relied on+// the legacy auto-humanizing behaviour need to opt in.+func (b *Bridge) effectiveHumanize(req ActionRequest) bool {+ if req.Humanize != nil {+ return *req.Humanize+ }+ if b != nil && b.Config != nil {+ return b.Config.Humanize+ }+ return false+}+const (dialogAutoHandlePollInterval = 10 * time.MilliseconddialogAutoHandleSettleDelay = 40 * time.Millisecond@@ -85,6 +107,13 @@ func submitFormIfButton(ctx context.Context, selector string) (bool, error) {}func (b *Bridge) actionClick(ctx context.Context, req ActionRequest) (map[string]any, error) {+ // Promote to the humanized click path when the caller (or instance+ // config) opted in via humanize=true. The guard on req.Kind avoids+ // ping-ponging when actionHumanClick has already delegated here.+ if req.Kind != ActionHumanClick && b.effectiveHumanize(req) {+ return b.actionHumanClick(ctx, req)+ }+// Arm a one-shot dialog auto-handler if the caller expects the click// to open a native JS dialog. Without this, the click would hang// waiting for the dialog to be handled from a separate request.@@ -435,6 +464,14 @@ func (b *Bridge) actionDrag(ctx context.Context, req ActionRequest) (map[string]}func (b *Bridge) actionHumanClick(ctx context.Context, req ActionRequest) (map[string]any, error) {+ // Fall through to the raw click path when humanization is disabled.+ // `kind: humanClick` is preserved as an action name for back-compat,+ // but its bezier+sleeps semantics now require humanize=true (either+ // per-request or via instance config).+ if !b.effectiveHumanize(req) {+ return b.actionClick(ctx, req)+ }+var backendNodeID cdp.BackendNodeIDswitch {case req.NodeID > 0:diff --git a/internal/bridge/action_request.go b/internal/bridge/action_request.goindex e500e102..55933709 100644--- a/internal/bridge/action_request.go+++ b/internal/bridge/action_request.go@@ -61,6 +61,12 @@ type ActionRequest struct {Fast bool `json:"fast"`Owner string `json:"owner"`+ // Humanize, when set, overrides the per-instance `humanize` default for+ // this action only. nil = use the configured default. true forces the+ // bezier/jitter/pre-press-sleep code path; false forces the raw+ // straight-to-target dispatch.+ Humanize *bool `json:"humanize,omitempty"`+// DialogAction arms a one-shot dialog auto-handler before the action// executes. Used when clicking a button/link that opens a JS dialog// (alert/confirm/prompt). Values: "accept" or "dismiss". When set, thediff --git a/internal/bridge/action_text.go b/internal/bridge/action_text.goindex 7d044f5f..aee37970 100644--- a/internal/bridge/action_text.go+++ b/internal/bridge/action_text.go@@ -52,6 +52,12 @@ func (b *Bridge) actionHumanType(ctx context.Context, req ActionRequest) (map[streturn nil, fmt.Errorf("text required for humanType")}+ // Fall through to the raw keyboard path when humanization is disabled.+ // Mirrors the actionHumanClick → actionClick fallback.+ if !b.effectiveHumanize(req) {+ return b.actionKeyboardType(ctx, req)+ }+if req.Selector != "" {if err := chromedp.Run(ctx, chromedp.Focus(req.Selector, chromedp.ByQuery)); err != nil {return nil, err@@ -86,6 +92,13 @@ func (b *Bridge) actionKeyboardType(ctx context.Context, req ActionRequest) (mapreturn nil, fmt.Errorf("text required for keyboard-type")}+ // Promote to the humanized typing path when humanize=true was opted+ // into. Guard on req.Kind so actionHumanType's delegation doesn't+ // bounce back here.+ if req.Kind != ActionHumanType && b.effectiveHumanize(req) {+ return b.actionHumanType(ctx, req)+ }+// For long strings, use insertText to avoid timeout (issue #413).// We still fire a keydown at the start and keyup at the end to trigger// any key-event listeners that apps might depend on.diff --git a/internal/cli/actions/actions_element.go b/internal/cli/actions/actions_element.goindex c8ebc266..dbdcd10c 100644--- a/internal/cli/actions/actions_element.go+++ b/internal/cli/actions/actions_element.go@@ -57,6 +57,16 @@ func Action(client *http.Client, base, token, kind, selectorArg string, cmd *cob}}+ // --humanize lets the caller opt into the bezier+jitter input path on+ // any pointer/typing action. Honours the same precedence as the API+ // flag (per-request override > instance config > built-in default).+ // Only set the body field when the flag was explicitly provided so+ // nil/null is preserved when omitted.+ if cmd.Flags().Changed("humanize") {+ v, _ := cmd.Flags().GetBool("humanize")+ body["humanize"] = v+ }+postAction(client, base, token, cmd, body)}@@ -278,6 +288,11 @@ func MouseAction(client *http.Client, base, token, kind string, args []string, ccli.Fatal("unsupported mouse action: %s", kind)}+ if cmd.Flags().Changed("humanize") {+ v, _ := cmd.Flags().GetBool("humanize")+ body["humanize"] = v+ }+postAction(client, base, token, cmd, body)}@@ -416,5 +431,10 @@ func ActionSimple(client *http.Client, base, token, kind string, args []string,body["key"] = args[0]}+ if cmd.Flags().Changed("humanize") {+ v, _ := cmd.Flags().GetBool("humanize")+ body["humanize"] = v+ }+postAction(client, base, token, cmd, body)}diff --git a/internal/config/config_file_json.go b/internal/config/config_file_json.goindex 4a27435b..a2642e94 100644--- a/internal/config/config_file_json.go+++ b/internal/config/config_file_json.go@@ -45,6 +45,7 @@ type instanceDefaultsConfigJSON struct {MaxParallelTabs *int `json:"maxParallelTabs"`UserAgent string `json:"userAgent"`NoAnimations *bool `json:"noAnimations"`+ Humanize *bool `json:"humanize"`StealthLevel string `json:"stealthLevel"`TabEvictionPolicy string `json:"tabEvictionPolicy"`TabPolicy *TabPolicyDefaults `json:"tabPolicy,omitempty"`diff --git a/internal/config/config_file_marshal.go b/internal/config/config_file_marshal.goindex 2baac6c5..db626512 100644--- a/internal/config/config_file_marshal.go+++ b/internal/config/config_file_marshal.go@@ -83,6 +83,7 @@ func (fc FileConfig) MarshalJSON() ([]byte, error) {MaxParallelTabs: fc.InstanceDefaults.MaxParallelTabs,UserAgent: fc.InstanceDefaults.UserAgent,NoAnimations: fc.InstanceDefaults.NoAnimations,+ Humanize: fc.InstanceDefaults.Humanize,StealthLevel: fc.InstanceDefaults.StealthLevel,TabEvictionPolicy: fc.InstanceDefaults.TabEvictionPolicy,TabPolicy: fc.InstanceDefaults.TabPolicy,@@ -242,6 +243,7 @@ func FileConfigFromRuntime(cfg *RuntimeConfig) FileConfig {maxTabs := cfg.MaxTabsmaxParallelTabs := cfg.MaxParallelTabsnoAnimations := cfg.NoAnimations+ humanize := cfg.HumanizeallowEvaluate := cfg.AllowEvaluateallowMacro := cfg.AllowMacroallowScreencast := cfg.AllowScreencast@@ -330,6 +332,7 @@ func FileConfigFromRuntime(cfg *RuntimeConfig) FileConfig {MaxParallelTabs: &maxParallelTabs,UserAgent: cfg.UserAgent,NoAnimations: &noAnimations,+ Humanize: &humanize,StealthLevel: cfg.StealthLevel,TabEvictionPolicy: cfg.TabEvictionPolicy,TabPolicy: tabPolicyDefaultsFromRuntime(cfg),diff --git a/internal/config/config_load.go b/internal/config/config_load.goindex 4572b0c8..6cd85e81 100644--- a/internal/config/config_load.go+++ b/internal/config/config_load.go@@ -57,6 +57,7 @@ func Load() *RuntimeConfig {ExtensionPaths: []string{defaultExtensionsDir(userConfigDir())},UserAgent: "",NoAnimations: false,+ Humanize: false,StealthLevel: "light",TabEvictionPolicy: "close_lru",TabLifecyclePolicy: "close_idle",@@ -400,6 +401,9 @@ func applyFileConfig(cfg *RuntimeConfig, fc *FileConfig) {if fc.InstanceDefaults.NoAnimations != nil {cfg.NoAnimations = *fc.InstanceDefaults.NoAnimations}+ if fc.InstanceDefaults.Humanize != nil {+ cfg.Humanize = *fc.InstanceDefaults.Humanize+ }if fc.InstanceDefaults.StealthLevel != "" {cfg.StealthLevel = fc.InstanceDefaults.StealthLevel}diff --git a/internal/config/config_types.go b/internal/config/config_types.goindex 731b1837..5d8a6921 100644--- a/internal/config/config_types.go+++ b/internal/config/config_types.go@@ -60,6 +60,7 @@ type RuntimeConfig struct {ExtensionPaths []stringUserAgent stringNoAnimations bool+ Humanize bool // when true, mouse moves and clicks use a humanized bezier path with per-step jitter and pre-press delays; default false (raw, fast input)StealthLevel stringTabEvictionPolicy string // "close_lru" (default), "reject", "close_oldest" — fires on MaxTabs pressureTabLifecyclePolicy string // "close_idle" (default), "keep" — fires on idle after read/action@@ -291,6 +292,7 @@ type InstanceDefaultsConfig struct {MaxParallelTabs *int `json:"maxParallelTabs,omitempty"`UserAgent string `json:"userAgent,omitempty"`NoAnimations *bool `json:"noAnimations,omitempty"`+ Humanize *bool `json:"humanize,omitempty"`StealthLevel string `json:"stealthLevel,omitempty"`TabEvictionPolicy string `json:"tabEvictionPolicy,omitempty"` // Deprecated: use TabPolicy.EvictionTabPolicy *TabPolicyDefaults `json:"tabPolicy,omitempty"`diff --git a/internal/config/editor_get.go b/internal/config/editor_get.goindex e81e3fd4..dd8a85d0 100644--- a/internal/config/editor_get.go+++ b/internal/config/editor_get.go@@ -170,6 +170,8 @@ func getInstanceDefaultsField(c *InstanceDefaultsConfig, field string) (string,return c.UserAgent, nilcase "noAnimations":return formatBoolPtr(c.NoAnimations), nil+ case "humanize":+ return formatBoolPtr(c.Humanize), nilcase "stealthLevel":return c.StealthLevel, nilcase "tabEvictionPolicy":diff --git a/internal/config/editor_set.go b/internal/config/editor_set.goindex 1a46d1f4..7c268ae7 100644--- a/internal/config/editor_set.go+++ b/internal/config/editor_set.go@@ -260,6 +260,12 @@ func setInstanceDefaultsField(c *InstanceDefaultsConfig, field, value string) erreturn fmt.Errorf("instanceDefaults.noAnimations: %w", err)}c.NoAnimations = &b+ case "humanize":+ b, err := parseBool(value)+ if err != nil {+ return fmt.Errorf("instanceDefaults.humanize: %w", err)+ }+ c.Humanize = &bcase "stealthLevel":c.StealthLevel = valuecase "tabEvictionPolicy":diff --git a/tests/e2e/helpers/api-actions.sh b/tests/e2e/helpers/api-actions.shindex f78b94df..7c7a4728 100644--- a/tests/e2e/helpers/api-actions.sh+++ b/tests/e2e/helpers/api-actions.sh@@ -29,10 +29,13 @@ action_type() {}# Human-like click by ref (uses mouse events).+# Sets humanize=true explicitly: with the new opt-in default, kind=humanClick+# alone falls through to a raw click. These helpers exist specifically to+# exercise the bezier+jitter+pre-press-sleep path, so we always opt in.# Usage: action_human_click "$ref"action_human_click() {local ref="$1"- pt_post /action -d "{\"kind\":\"humanClick\",\"ref\":\"$ref\"}" > /dev/null+ pt_post /action -d "{\"kind\":\"humanClick\",\"ref\":\"$ref\",\"humanize\":true}" > /dev/nullassert_ok "humanClick ref=$ref"}@@ -41,7 +44,7 @@ action_human_click() {action_human_type() {local ref="$1"local text="$2"- pt_post /action -d "{\"kind\":\"humanType\",\"ref\":\"$ref\",\"text\":\"$text\"}" > /dev/null+ pt_post /action -d "{\"kind\":\"humanType\",\"ref\":\"$ref\",\"text\":\"$text\",\"humanize\":true}" > /dev/nullassert_ok "humanType '$text' into ref=$ref"}@@ -50,7 +53,7 @@ action_human_type() {action_human_type_selector() {local selector="$1"local text="$2"- pt_post /action -d "{\"kind\":\"humanType\",\"selector\":\"$selector\",\"text\":\"$text\"}" > /dev/null+ pt_post /action -d "{\"kind\":\"humanType\",\"selector\":\"$selector\",\"text\":\"$text\",\"humanize\":true}" > /dev/nullassert_ok "humanType '$text' into $selector"}diff --git a/tests/e2e/scenarios/infra/network-extended.sh b/tests/e2e/scenarios/infra/network-extended.shindex e99363c4..19f2d1b0 100755--- a/tests/e2e/scenarios/infra/network-extended.sh+++ b/tests/e2e/scenarios/infra/network-extended.sh@@ -266,19 +266,30 @@ end_test# ─────────────────────────────────────────────────────────────────start_test "GET /network/export/stream: SSE events on navigation"-# Start a streaming export in background, navigate, then check output.-# We use a short timeout curl to capture initial SSE events.-STREAM_OUTPUT=$(e2e_curl -s -N \- --max-time 5 \+# The previous version of this test ran curl as foreground command+# substitution, which blocked for the whole --max-time before the+# navigate fired — so no SSE events ever overlapped the stream and+# the assertion silently fell through to the "no events captured"+# pass branch. Background the curl so it actually overlaps the+# navigate, drop the foreground budget from 5s to ~2s.+STREAM_TMP=$(mktemp)+e2e_curl -s -N --max-time 2 \-H "Content-Type: application/json" \"${E2E_SERVER}/network/export/stream?tabId=${TAB_ID}&format=har&path=e2e-stream.har" \- 2>/dev/null || true)+ > "$STREAM_TMP" 2>/dev/null &+SSE_PID=$!-# Trigger traffic while the stream might still be running+# Brief delay to let the stream open before generating traffic.+sleep 0.2++# Trigger traffic while the stream is still running.pt_post /navigate "{\"url\":\"${FIXTURES_URL}/form.html\"}"-sleep 2-# The curl with --max-time will have timed out by now. Check output.+# Wait for the SSE curl to hit --max-time and return.+wait "$SSE_PID" 2>/dev/null || true+STREAM_OUTPUT=$(cat "$STREAM_TMP")+rm -f "$STREAM_TMP"+if echo "$STREAM_OUTPUT" | grep -q "event:"; thenecho -e " ${GREEN}✓${NC} received SSE events from stream"((ASSERTIONS_PASSED++)) || truediff --git a/tests/e2e/scenarios/infra/orchestrator-extended.sh b/tests/e2e/scenarios/infra/orchestrator-extended.shindex 1e8541b2..ca48afa7 100644--- a/tests/e2e/scenarios/infra/orchestrator-extended.sh+++ b/tests/e2e/scenarios/infra/orchestrator-extended.sh@@ -156,6 +156,16 @@ assert_ok "instance tabs"end_test+# ─────────────────────────────────────────────────────────────────+# Run the ID-format check before the stop test so it can reuse the+# still-running INST_ID from "launch new instance" instead of paying+# another full launch+stop cycle (~6s) just to inspect the prefix.+start_test "orchestrator: ID format (inst_ prefix)"++assert_instance_id_prefix "$INST_ID"++end_test+# ─────────────────────────────────────────────────────────────────start_test "orchestrator: stop instance"@@ -168,19 +178,6 @@ assert_instance_list_absent "$INST_ID" "instance removed after stop" "instance send_test-# ─────────────────────────────────────────────────────────────────-start_test "orchestrator: ID format (inst_ prefix)"--pt_post /instances/start '{"mode":"headless"}'-assert_ok "launch"-ID_CHECK_INST=$(echo "$RESULT" | jq -r '.id')--assert_instance_id_prefix "$ID_CHECK_INST"--pt_post "/instances/${ID_CHECK_INST}/stop" '{}'--end_test-# ─────────────────────────────────────────────────────────────────start_test "orchestrator: ports, isolation, and cleanup"diff --git a/tests/e2e/scenarios/infra/system-extended.sh b/tests/e2e/scenarios/infra/system-extended.shindex 5e650dc8..00bc6bd2 100644--- a/tests/e2e/scenarios/infra/system-extended.sh+++ b/tests/e2e/scenarios/infra/system-extended.sh@@ -289,8 +289,10 @@ end_test# ─────────────────────────────────────────────────────────────────start_test "idpi: same-tab domain pivot warns in warn mode"+# idpi_setup already does navigate + sleep 1, which covers the fixture's+# 250ms setTimeout pivot and the follow-up navigation settle. The extra+# sleep 2 here was redundant.TAB_ID=$(idpi_setup "$E2E_SERVER" "${FIXTURES_URL}/idpi-domain-pivot.html")-sleep 2idpi_request GET "$E2E_SERVER" "/tabs/${TAB_ID}/text" "" "X-IDPI-Warning"assert_ok "text allowed after domain pivot in warn mode"assert_header_present "X-IDPI-Warning present after domain pivot"@@ -300,8 +302,9 @@ end_test# ─────────────────────────────────────────────────────────────────start_test "idpi: same-tab domain pivot blocks in strict mode"+# See note on the warn-mode pivot test above — idpi_setup's internal+# sleep 1 already covers the pivot timer.TAB_ID=$(idpi_setup "$E2E_SECURE_SERVER" "${FIXTURES_URL}/idpi-domain-pivot.html")-sleep 2idpi_request GET "$E2E_SECURE_SERVER" "/tabs/${TAB_ID}/text" "" "X-IDPI-Warning"assert_http_status 403 "text blocked after domain pivot in strict mode"assert_header_present "X-IDPI-Warning present on strict block"