High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
fix: include mode in instance responses and update docs
Luigi Agostie36d944e9d3b
diff --git a/dashboard/src/activities/ActivityPage.test.tsx b/dashboard/src/activities/ActivityPage.test.tsxindex 9dd9c4ca..0855db7d 100644--- a/dashboard/src/activities/ActivityPage.test.tsx+++ b/dashboard/src/activities/ActivityPage.test.tsx@@ -48,6 +48,7 @@ describe("ActivityPage", () => {profileId: "prof_default",profileName: "default",port: "9988",+ mode: "headless",headless: true,status: "running",startTime: "2026-03-16T08:00:00Z",diff --git a/dashboard/src/components/molecules/NavBar.test.tsx b/dashboard/src/components/molecules/NavBar.test.tsxindex f50eafbf..22b84bc9 100644--- a/dashboard/src/components/molecules/NavBar.test.tsx+++ b/dashboard/src/components/molecules/NavBar.test.tsx@@ -28,6 +28,7 @@ describe("NavBar", () => {profileId: "prof_alpha",profileName: "alpha",port: "9988",+ mode: "headed",headless: false,status: "running",startTime: "2026-04-09T10:00:00Z",diff --git a/dashboard/src/components/molecules/ServerStatusBadge.test.tsx b/dashboard/src/components/molecules/ServerStatusBadge.test.tsxindex fe2262f8..70d38c77 100644--- a/dashboard/src/components/molecules/ServerStatusBadge.test.tsx+++ b/dashboard/src/components/molecules/ServerStatusBadge.test.tsx@@ -9,6 +9,7 @@ const runningInstance: Instance = {profileId: "prof_alpha",profileName: "alpha",port: "9988",+ mode: "headed",headless: false,status: "running",startTime: "2026-04-09T10:00:00Z",diff --git a/dashboard/src/components/molecules/StartInstanceModal.test.tsx b/dashboard/src/components/molecules/StartInstanceModal.test.tsxindex 85392a97..4e4652b0 100644--- a/dashboard/src/components/molecules/StartInstanceModal.test.tsx+++ b/dashboard/src/components/molecules/StartInstanceModal.test.tsx@@ -58,6 +58,7 @@ describe("StartInstanceModal", () => {profileId: "prof_alpha",profileName: "alpha",port: "9988",+ mode: "headed",headless: false,status: "running",startTime: "2026-03-06T10:00:00Z",diff --git a/dashboard/src/generated/types.ts b/dashboard/src/generated/types.tsindex a1fc89dd..57086afe 100644--- a/dashboard/src/generated/types.ts+++ b/dashboard/src/generated/types.ts@@ -43,6 +43,7 @@ export interface Instance {profileName: string;port: string; // Note: string not inturl?: string;+ mode: string;headless: boolean;status: string; // starting/running/stopping/stopped/errorstartTime: string;diff --git a/dashboard/src/pages/MonitoringPage.test.tsx b/dashboard/src/pages/MonitoringPage.test.tsxindex 5d514160..0cc1a620 100644--- a/dashboard/src/pages/MonitoringPage.test.tsx+++ b/dashboard/src/pages/MonitoringPage.test.tsx@@ -15,6 +15,7 @@ vi.mock("../services/api", () => ({profileId: "default",profileName: "default",port: "9868",+ mode: "headed",headless: false,status: "starting",startTime: "2026-03-06T10:00:00Z",@@ -37,6 +38,7 @@ const instances: Instance[] = [profileId: "prof_beta",profileName: "beta",port: "9988",+ mode: "headed",headless: false,status: "running",startTime: "2026-03-06T10:00:00Z",diff --git a/dashboard/src/pages/ProfilesPage.test.tsx b/dashboard/src/pages/ProfilesPage.test.tsxindex 9873ac45..0a3a3aa1 100644--- a/dashboard/src/pages/ProfilesPage.test.tsx+++ b/dashboard/src/pages/ProfilesPage.test.tsx@@ -49,6 +49,7 @@ const instances: Instance[] = [profileId: "prof_beta",profileName: "beta",port: "9988",+ mode: "headed",headless: false,status: "running",startTime: "2026-03-06T10:00:00Z",diff --git a/dashboard/src/profiles/ProfileCard.test.tsx b/dashboard/src/profiles/ProfileCard.test.tsxindex 6c11004d..12bebf3f 100644--- a/dashboard/src/profiles/ProfileCard.test.tsx+++ b/dashboard/src/profiles/ProfileCard.test.tsx@@ -19,6 +19,7 @@ const mockRunningInstance: Instance = {profileId: "prof_123",profileName: "test-profile",port: "9868",+ mode: "headed",headless: false,status: "running",startTime: new Date().toISOString(),diff --git a/dashboard/src/services/api.ts b/dashboard/src/services/api.tsindex d31e7c4a..084ea451 100644--- a/dashboard/src/services/api.ts+++ b/dashboard/src/services/api.ts@@ -166,6 +166,13 @@ function withDashboardSource(options?: RequestInit): RequestInit {};}+function normalizeInstance(instance: Instance): Instance {+ return {+ ...instance,+ mode: instance.mode ?? (instance.headless ? "headless" : "headed"),+ };+}+// Profiles — endpoint is /profiles (no /api prefix)export async function fetchProfiles(): Promise<Profile[]> {return request<Profile[]>("/profiles");@@ -212,18 +219,20 @@ export async function updateProfile(// Instances — endpoint is /instances (no /api prefix)export async function fetchInstances(): Promise<Instance[]> {- return request<Instance[]>("/instances");+ return (await request<Instance[]>("/instances")).map(normalizeInstance);}export async function launchInstance(data: LaunchInstanceRequest,): Promise<Instance> {// Use the canonical start endpoint to avoid legacy launch alias validation edge cases.- return request<Instance>("/instances/start", {- method: "POST",- headers: { "Content-Type": "application/json" },- body: JSON.stringify(data),- });+ return normalizeInstance(+ await request<Instance>("/instances/start", {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify(data),+ }),+ );}export async function stopInstance(id: string): Promise<void> {diff --git a/dashboard/src/types/index.ts b/dashboard/src/types/index.tsindex 652fd027..7607883e 100644--- a/dashboard/src/types/index.ts+++ b/dashboard/src/types/index.ts@@ -428,7 +428,10 @@ export function normalizeMonitoringSnapshot(): MonitoringSnapshot {return {timestamp: input.timestamp ?? Date.now(),- instances: input.instances ?? [],+ instances: (input.instances ?? []).map((instance) => ({+ ...instance,+ mode: instance.mode ?? (instance.headless ? "headless" : "headed"),+ })),tabs: input.tabs ?? [],metrics: input.metrics ?? [],serverMetrics: {diff --git a/docs/core-concepts.md b/docs/core-concepts.mdindex 2bf39e2c..9357a284 100644--- a/docs/core-concepts.md+++ b/docs/core-concepts.md@@ -139,6 +139,7 @@ pinchtab instance start --profile prof_278be873 --mode headed"profileId": "prof_278be873","profileName": "work","port": "9868",+ "mode": "headed","headless": false,"status": "starting"}diff --git a/docs/dashboard.md b/docs/dashboard.mdindex 3445d199..9adb4c29 100644--- a/docs/dashboard.md+++ b/docs/dashboard.md@@ -106,6 +106,7 @@ pinchtab instance start --profile prof_278be873 --mode headed"profileId": "prof_278be873","profileName": "work","port": "9868",+ "mode": "headed","headless": false,"status": "starting"}diff --git a/docs/endpoints.md b/docs/endpoints.mdindex e4317747..5c724be7 100644--- a/docs/endpoints.md+++ b/docs/endpoints.md@@ -491,6 +491,7 @@ Notes:- `/instances/start` and `/instances/launch` use `mode`, not `headless`- `/instances/launch` is a compatibility alias over `/instances/start`+- instance responses include both `mode` and `headless`- instance start surfaces accept `securityPolicy.allowedDomains` for additive instance-scoped IDPI/domain allowlist overrides- create profiles explicitly with `POST /profiles`; `name` is no longer supported on `/instances/launch`- `/profiles/{id}/start` uses `headless`diff --git a/docs/get-started.md b/docs/get-started.mdindex da370b89..900b3d8c 100644--- a/docs/get-started.md+++ b/docs/get-started.md@@ -112,6 +112,7 @@ pinchtab instance start"profileId": "prof_278be873","profileName": "instance-1741400000000000000","port": "9868",+ "mode": "headless","headless": true,"status": "starting"}diff --git a/docs/guides/attach-chrome.md b/docs/guides/attach-chrome.mdindex 6d8603cc..a7d49b31 100644--- a/docs/guides/attach-chrome.md+++ b/docs/guides/attach-chrome.md@@ -130,6 +130,7 @@ curl -X POST http://localhost:9867/instances/attach \"profileId": "prof_278be873","profileName": "shared-chrome","port": "",+ "mode": "headed","headless": false,"status": "running","attached": true,diff --git a/docs/guides/multi-instance.md b/docs/guides/multi-instance.mdindex 4f4f3e5b..f94bbc9e 100644--- a/docs/guides/multi-instance.md+++ b/docs/guides/multi-instance.md@@ -33,6 +33,7 @@ pinchtab instance start --mode headed --port 9999"profileId": "prof_278be873","profileName": "instance-1741410000000","port": "9999",+ "mode": "headed","headless": false,"status": "starting"}@@ -101,6 +102,7 @@ Useful fields:- `id`: stable instance identifier- `profileId` and `profileName`: the profile backing that instance- `port`: the instance's HTTP port+- `mode`: explicit `"headless"` or `"headed"` string for request/response symmetry- `headless`: whether Chrome was launched headless- `status`: usually `starting`, `running`, `stopping`, or `stopped`diff --git a/docs/guides/remote-bridge-orchestrator.md b/docs/guides/remote-bridge-orchestrator.mdindex 7282c907..ac8dd38f 100644--- a/docs/guides/remote-bridge-orchestrator.md+++ b/docs/guides/remote-bridge-orchestrator.md@@ -175,6 +175,7 @@ Response shape:"profileName": "bridge-eu-west-1","port": "","url": "http://10.0.12.24:9868",+ "mode": "headed","headless": false,"status": "running","attached": true,diff --git a/docs/headless-vs-headed.md b/docs/headless-vs-headed.mdindex f6962330..d56ca396 100644--- a/docs/headless-vs-headed.md+++ b/docs/headless-vs-headed.md@@ -25,6 +25,7 @@ pinchtab instance start"profileId": "prof_278be873","profileName": "instance-1741400000000000000","port": "9868",+ "mode": "headless","headless": true,"status": "starting"}@@ -60,6 +61,7 @@ pinchtab instance start --mode headed"profileId": "prof_278be873","profileName": "instance-1741400000000000001","port": "9869",+ "mode": "headed","headless": false,"status": "starting"}@@ -135,6 +137,7 @@ pinchtab instance start --profile prof_278be873 --mode headed"profileId": "prof_278be873","profileName": "dev","port": "9868",+ "mode": "headed","headless": false,"status": "starting"}diff --git a/docs/pinchtab.md b/docs/pinchtab.mdindex 36bcb75a..65dd446f 100644--- a/docs/pinchtab.md+++ b/docs/pinchtab.md@@ -52,6 +52,7 @@ pinchtab instance start"profileId": "prof_278be873","profileName": "instance-1741400000000000000","port": "9868",+ "mode": "headless","headless": true,"status": "starting"}diff --git a/docs/reference/instances.md b/docs/reference/instances.mdindex 8727ae9d..59996a05 100644--- a/docs/reference/instances.md+++ b/docs/reference/instances.md@@ -29,6 +29,7 @@ Response shape:"profileId": "prof_278be873","profileName": "instance-1741410000000","port": "9999",+ "mode": "headed","headless": false,"status": "running","securityPolicy": {@@ -38,7 +39,7 @@ Response shape:]```-`GET /instances` returns a bare JSON array, not an envelope like `{"instances":[...]}`.+`GET /instances` returns a bare JSON array, not an envelope like `{"instances":[...]}`. Each instance response includes both `mode` (`"headless"` or `"headed"`) and the legacy-compatible `headless` boolean.## Start An Instance@@ -107,6 +108,11 @@ Common status values:- `stopped`- `error`+Instance responses include:++- `mode`: `"headless"` or `"headed"`+- `headless`: boolean kept for compatibility+## Get Instance Logs```bashdiff --git a/docs/reference/profiles.md b/docs/reference/profiles.mdindex c73742e5..3419612b 100644--- a/docs/reference/profiles.md+++ b/docs/reference/profiles.md@@ -136,6 +136,7 @@ curl -X POST http://localhost:9867/profiles/prof_278be873/start \"profileId": "prof_278be873","profileName": "work","port": "9868",+ "mode": "headless","headless": true,"status": "starting"}@@ -153,7 +154,7 @@ curl -X POST http://localhost:9867/profiles/prof_278be873/stop}```-For these orchestrator routes, the path can be a profile ID or profile name.+For these orchestrator routes, the path can be a profile ID or profile name. The returned instance object now includes both `mode` and `headless`.## Check Whether A Profile Has A Running Instancediff --git a/docs/showcase.md b/docs/showcase.mdindex 65616f0a..b6a039bd 100644--- a/docs/showcase.md+++ b/docs/showcase.md@@ -24,6 +24,7 @@ pinchtab instance start"profileId": "prof_278be873","profileName": "instance-1741400000000000000","port": "9868",+ "mode": "headless","headless": true,"status": "starting"}diff --git a/internal/api/types/types.go b/internal/api/types/types.goindex ae2b45c5..45e94c40 100644--- a/internal/api/types/types.go+++ b/internal/api/types/types.go@@ -38,6 +38,7 @@ type Instance struct {ProfileName string `json:"profileName"`Port string `json:"port"` // Note: string not intURL string `json:"url,omitempty"`+ Mode string `json:"mode"`Headless bool `json:"headless"`Status string `json:"status"` // starting/running/stopping/stopped/errorStartTime time.Time `json:"startTime"`diff --git a/internal/bridge/api.go b/internal/bridge/api.goindex 94210f1b..5c0a1fe3 100644--- a/internal/bridge/api.go+++ b/internal/bridge/api.go@@ -2,6 +2,7 @@ package bridgeimport ("context"+ "encoding/json""errors""net/http""time"@@ -141,12 +142,29 @@ type SecurityPolicy struct {AllowedDomains []string `json:"allowedDomains,omitempty"`}+func ModeFromHeadless(headless bool) string {+ if headless {+ return "headless"+ }+ return "headed"+}++func normalizeInstanceMode(mode string, headless bool) string {+ switch mode {+ case "headless", "headed":+ return mode+ default:+ return ModeFromHeadless(headless)+ }+}+type Instance struct {ID string `json:"id"` // Hash-based ID: inst_XXXXXXXXProfileID string `json:"profileId"` // Hash-based profile ID: prof_XXXXXXXXProfileName string `json:"profileName"` // Human-readable profile name (for display only)Port string `json:"port"` // Internal: instance portURL string `json:"url,omitempty"` // Canonical base URL for bridge-backed instances+ Mode string `json:"mode"` // API mode: "headless" or "headed"Headless bool `json:"headless"` // Mode: headless vs headedStatus string `json:"status"` // Status: starting/running/stopping/stopped/errorStartTime time.Time `json:"startTime"` // When instance was created@@ -157,6 +175,13 @@ type Instance struct {SecurityPolicy *SecurityPolicy `json:"securityPolicy,omitempty"`}+func (i Instance) MarshalJSON() ([]byte, error) {+ type alias Instance+ copy := alias(i)+ copy.Mode = normalizeInstanceMode(copy.Mode, copy.Headless)+ return json.Marshal(copy)+}+type InstanceTab struct {ID string `json:"id"` // Runtime tab ID (raw CDP target ID on this branch)InstanceID string `json:"instanceId"` // Hash-based instance ID: inst_XXXXXXXXdiff --git a/internal/bridge/api_test.go b/internal/bridge/api_test.gonew file mode 100644index 00000000..e324a8a5--- /dev/null+++ b/internal/bridge/api_test.go@@ -0,0 +1,42 @@+package bridge++import (+ "encoding/json"+ "testing"+)++func TestInstanceMarshalJSONDerivesModeFromHeadless(t *testing.T) {+ data, err := json.Marshal(Instance{Headless: true})+ if err != nil {+ t.Fatalf("Marshal() error = %v", err)+ }++ var decoded map[string]any+ if err := json.Unmarshal(data, &decoded); err != nil {+ t.Fatalf("Unmarshal() error = %v", err)+ }+ if got := decoded["mode"]; got != "headless" {+ t.Fatalf("mode = %v, want headless", got)+ }+ if got := decoded["headless"]; got != true {+ t.Fatalf("headless = %v, want true", got)+ }+}++func TestInstanceMarshalJSONPreservesExplicitMode(t *testing.T) {+ data, err := json.Marshal(Instance{Mode: "headed", Headless: false})+ if err != nil {+ t.Fatalf("Marshal() error = %v", err)+ }++ var decoded map[string]any+ if err := json.Unmarshal(data, &decoded); err != nil {+ t.Fatalf("Unmarshal() error = %v", err)+ }+ if got := decoded["mode"]; got != "headed" {+ t.Fatalf("mode = %v, want headed", got)+ }+ if got := decoded["headless"]; got != false {+ t.Fatalf("headless = %v, want false", got)+ }+}diff --git a/internal/orchestrator/handlers_instances_test.go b/internal/orchestrator/handlers_instances_test.goindex c08b69f9..900f63fe 100644--- a/internal/orchestrator/handlers_instances_test.go+++ b/internal/orchestrator/handlers_instances_test.go@@ -63,6 +63,9 @@ func TestHandleLaunchByNameAliasesStartSemantics(t *testing.T) {if inst.ProfileName != "work" {t.Fatalf("ProfileName = %q, want %q", inst.ProfileName, "work")}+ if inst.Mode != "headed" {+ t.Fatalf("Mode = %q, want %q", inst.Mode, "headed")+ }if inst.Headless {t.Fatal("Headless = true, want false for mode=headed")}@@ -128,6 +131,9 @@ func TestHandleStartInstance_AppliesSecurityPolicyOverride(t *testing.T) {if err := json.NewDecoder(w.Body).Decode(&inst); err != nil {t.Fatalf("decode response: %v", err)}+ if inst.Mode != "headed" {+ t.Fatalf("Mode = %q, want %q", inst.Mode, "headed")+ }if inst.SecurityPolicy == nil {t.Fatal("expected securityPolicy on instance response")}diff --git a/internal/orchestrator/orchestrator.go b/internal/orchestrator/orchestrator.goindex 2954d739..f61020a6 100644--- a/internal/orchestrator/orchestrator.go+++ b/internal/orchestrator/orchestrator.go@@ -373,6 +373,7 @@ func (o *Orchestrator) LaunchWithOptions(name, port string, headless bool, optsProfileName: name,Port: port,URL: o.childInstanceBaseURL(port),+ Mode: bridge.ModeFromHeadless(headless),Headless: headless,Status: "starting",StartTime: time.Now(),@@ -577,6 +578,7 @@ func (o *Orchestrator) Attach(name, cdpURL string) (*bridge.Instance, error) {AttachType: "cdp",CdpURL: cdpURL,URL: cdpURL,+ Mode: bridge.ModeFromHeadless(false),}, "")if err != nil {return nil, err@@ -602,6 +604,7 @@ func (o *Orchestrator) AttachBridge(name, baseURL, token string) (*bridge.InstanAttached: true,AttachType: "bridge",URL: normalizedBaseURL,+ Mode: bridge.ModeFromHeadless(false),}, token)if err != nil {return nil, false, errdiff --git a/internal/orchestrator/orchestrator_test.go b/internal/orchestrator/orchestrator_test.goindex 88a89445..2196dc60 100644--- a/internal/orchestrator/orchestrator_test.go+++ b/internal/orchestrator/orchestrator_test.go@@ -49,6 +49,9 @@ func TestOrchestrator_Launch_Lifecycle(t *testing.T) {if err != nil {t.Fatalf("First launch failed: %v", err)}+ if inst.Mode != "headless" {+ t.Fatalf("Mode = %q, want %q", inst.Mode, "headless")+ }if inst.Status != "starting" {t.Errorf("expected status starting, got %s", inst.Status)}diff --git a/tests/e2e/scenarios/infra/orchestrator-extended.sh b/tests/e2e/scenarios/infra/orchestrator-extended.shindex 1021053a..2b88af17 100644--- a/tests/e2e/scenarios/infra/orchestrator-extended.sh+++ b/tests/e2e/scenarios/infra/orchestrator-extended.sh@@ -81,6 +81,8 @@ start_test "orchestrator: launch new instance"pt_post /instances/start '{"mode":"headless"}'assert_ok "launch instance"+assert_json_eq "$RESULT" '.mode' 'headless' "launch response includes mode"+assert_json_eq "$RESULT" '.headless' 'true' "launch response keeps headless boolean"INST_ID=$(echo "$RESULT" | jq -r '.id')assert_json_exists "$RESULT" '.id' "has instance id"@@ -100,6 +102,8 @@ start_test "orchestrator: get instance by id"pt_get "/instances/${INST_ID}"assert_ok "get instance"assert_json_eq "$RESULT" '.id' "$INST_ID"+assert_json_eq "$RESULT" '.mode' 'headless' "instance response includes mode"+assert_json_eq "$RESULT" '.headless' 'true' "instance response keeps headless boolean"end_test