browser-workspace 0.4.2 → 0.4.5

package/src/browser_workspace_app/node/admin.mjs

@@ -0,0 +1,44 @@
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+
+function socketPath() {
+  if (process.env.BROWSER_WORKSPACE_TEST_MODE === "1" && process.env.BROWSER_WORKSPACE_SESSION_SOCKET) return process.env.BROWSER_WORKSPACE_SESSION_SOCKET;
+  return path.join(os.homedir(), ".config", "browser-workspace", "runtime", "session.sock");
+}
+
+function request(payload) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection({ path: socketPath() });
+    let buffer = "";
+    let settled = false;
+    const fail = (error) => { if (!settled) { settled = true; reject(error); } };
+    socket.setEncoding("utf8");
+    socket.on("connect", () => socket.write(`${JSON.stringify(payload)}\n`));
+    socket.on("data", chunk => {
+      buffer += chunk;
+      const newline = buffer.indexOf("\n");
+      if (newline < 0 || settled) return;
+      settled = true;
+      socket.end();
+      try {
+        const result = JSON.parse(buffer.slice(0, newline));
+        if (result && result.error) reject(new Error(result.error));
+        else resolve(result);
+      } catch (error) { reject(error); }
+    });
+    socket.on("error", fail);
+    socket.on("end", () => { if (!settled) fail(new Error("browser-workspace daemon closed without a response")); });
+  });
+}
+
+export async function ensureWorkspace(name, size = 5) {
+  if (typeof name !== "string" || !name.trim()) throw new TypeError("workspace name must be a non-empty string");
+  if (!Number.isInteger(size) || size < 1) throw new TypeError("workspace size must be a positive integer");
+  return request({ op: "workspace-create", name: name.trim(), pool_size: size });
+}
+
+export async function deleteWorkspace(name, { force = false } = {}) {
+  if (typeof name !== "string" || !name.trim()) throw new TypeError("workspace name must be a non-empty string");
+  return request({ op: "workspace-delete", name: name.trim(), force: Boolean(force) });
+}

package/src/browser_workspace_app/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "browser-workspace",
+  "version": "0.4.5",
+  "description": "Agent browser workspace with persistent sessions, tab leasing, snapshots, and platform workflows.",
+  "bin": {
+    "browser-workspace": "bin/browser-workspace"
+  },
+  "files": [
+    "bin/",
+    "node/",
+    "src/",
+    "agent-workspace/agent_helpers.py",
+    "interaction-skills/",
+    "platforms/",
+    "licenses/",
+    "platform_runner.py",
+    "session_client.py",
+    "session_daemon.py",
+    "pyproject.toml",
+    "README.md",
+    "SKILL.md",
+    "PRIVACY.md",
+    "managed_chrome.py",
+    "extension/"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "python3 -m pytest -q test && node --test test/workspace-manager.test.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lalalic/browser-workspace.git"
+  }
+}

package/src/browser_workspace_app/platform_runner.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import yaml
+
+from session_client import request
+
+ROOT = Path(__file__).resolve().parent
+PLATFORMS = ROOT / "platforms"
+
+
+def platform_manifest(platform: str) -> dict:
+    platform = platform.strip()
+    manifest = PLATFORMS / platform / "manifest.yaml"
+    if not manifest.is_file():
+        raise FileNotFoundError(f"unknown platform: {platform}")
+    data = yaml.safe_load(manifest.read_text())
+    if not isinstance(data, dict):
+        raise ValueError(f"invalid platform manifest: {platform}")
+    return data
+
+
+def platform_profile(platform: str) -> dict:
+    data = platform_manifest(platform)
+    keys = (
+        "platform", "display_name", "aliases", "implementation_status",
+        "media", "fields", "capabilities", "content_mapping", "notes",
+    )
+    return {key: data[key] for key in keys if key in data}
+
+
+def _validate_string(name: str, value, spec: dict) -> None:
+    if value is None:
+        return
+    text = str(value)
+    minimum = spec.get("min_chars")
+    maximum = spec.get("max_chars") or spec.get("max_chars_including_tags")
+    if minimum is not None and text and len(text) < int(minimum):
+        raise ValueError(f"{name} too short: {len(text)} chars (min {minimum})")
+    if maximum is not None and len(text) > int(maximum):
+        raise ValueError(f"{name} too long: {len(text)} chars (max {maximum})")
+
+
+def validate_platform_config(platform: str, action: str, config: dict) -> None:
+    if action != "post":
+        return
+    profile = platform_profile(platform)
+    fields = profile.get("fields") or {}
+    for name, spec in fields.items():
+        if not isinstance(spec, dict) or spec.get("type") == "operation":
+            continue
+        value = config.get(name)
+        if spec.get("required") and (value is None or value == "" or value == []):
+            raise ValueError(f"{platform}: missing required field {name}")
+        if value is None:
+            continue
+        kind = spec.get("type")
+        if kind == "string":
+            _validate_string(name, value, spec)
+        elif kind == "string_list":
+            values = value if isinstance(value, list) else [x.strip() for x in str(value).split(",") if x.strip()]
+            maximum = spec.get("max_count")
+            if maximum is not None and len(values) > int(maximum):
+                raise ValueError(f"{name} has {len(values)} items (max {maximum})")
+            each = spec.get("max_chars_each")
+            if each is not None:
+                for item in values:
+                    if len(str(item)) > int(each):
+                        raise ValueError(f"{name} item too long: {item!r} (max {each})")
+            total = spec.get("max_total_chars")
+            if total is not None and sum(len(str(x)) for x in values) > int(total):
+                raise ValueError(f"{name} total length exceeds {total}")
+        elif kind == "enum":
+            values = spec.get("values") or []
+            if value not in values:
+                raise ValueError(f"{name} must be one of: {', '.join(map(str, values))}")
+
+    images_spec = (profile.get("media") or {}).get("images") or {}
+    images = config.get("images") or []
+    maximum = images_spec.get("max_count")
+    if maximum is not None and len(images) > int(maximum):
+        raise ValueError(f"images has {len(images)} items (max {maximum})")
+
+
+def declared_actions(platform: str) -> dict[str, Path]:
+    platform = platform.strip()
+    manifest = PLATFORMS / platform / "manifest.yaml"
+    if not manifest.is_file():
+        raise FileNotFoundError(f"unknown platform: {platform}")
+
+    text = manifest.read_text()
+    match = re.search(
+        r"^actions:\s*\n(?P<body>(?:^[ \t]+.*\n?)*)",
+        text,
+        flags=re.MULTILINE,
+    )
+    if not match:
+        raise ValueError(f"{platform}/manifest.yaml has no actions block")
+
+    actions: dict[str, Path] = {}
+    for line in match.group("body").splitlines():
+        entry = re.match(r'^\s{2}([\w-]+):\s*(.+?)\s*$', line)
+        if not entry:
+            continue
+        name, relative = entry.groups()
+        if len(relative) >= 2 and relative[0] == relative[-1] and relative[0] in {"\"", "'"}:
+            relative = relative[1:-1]
+        # Actions are simple relative file paths; comments and nested mappings are not runnable actions.
+        if not relative or relative.startswith(("#", "{", "[")) or " #" in relative:
+            continue
+        path = PLATFORMS / platform / relative
+        if not path.is_file():
+            raise FileNotFoundError(f"declared platform action missing: {platform}/{name} -> {relative}")
+        actions[name] = path
+    if not actions:
+        raise ValueError(f"{platform}/manifest.yaml declares no runnable actions")
+    return actions
+
+
+def action_path(platform: str, action: str) -> Path:
+    platform = platform.strip()
+    action = action.strip().replace("_", "-")
+    actions = declared_actions(platform)
+    if action not in actions:
+        raise FileNotFoundError(
+            f"unknown platform action {platform}/{action}; "
+            f"available: {', '.join(sorted(actions)) or 'none'}"
+        )
+    return actions[action]
+
+
+def prepare_action(path: Path, config_path: Path | None = None) -> str:
+    source = path.read_text()
+    source = "import sys\nsys.path.insert(0, " + repr(str(path.parent.resolve())) + ")\n" + source
+    if "__CFG_PATH__" in source:
+        if config_path is None:
+            raise ValueError(f"{path.parent.parent.name}/{path.stem}: --config is required")
+        escaped = str(config_path.resolve()).replace("\\", "\\\\").replace('"', '\\"')
+        source = source.replace("__CFG_PATH__", escaped)
+    return source
+
+
+def run_platform_action(
+    platform: str,
+    action: str,
+    *,
+    config_path: str | None = None,
+    url: str | None = None,
+    session_id: str | None = None,
+    auto_session: bool = False,
+) -> dict:
+    path = action_path(platform, action)
+    config_file = Path(config_path) if config_path else None
+    if config_file is not None:
+        config = json.loads(config_file.read_text())
+        if not isinstance(config, dict):
+            raise ValueError("platform config must be a JSON object")
+        validate_platform_config(platform, action, config)
+    code = prepare_action(path, config_file)
+
+    if not session_id and not auto_session:
+        raise ValueError(
+            "platform run requires session_id; orchestrators should use: "
+            "session start -> platform run --session-id SESSION_ID -> self-heal in the same session -> session stop. "
+            "Use auto_session=True only for a one-shot run without orchestrator self-heal."
+        )
+    if session_id and auto_session:
+        raise ValueError("session_id and auto_session are mutually exclusive")
+
+    owned_session = bool(auto_session)
+    started = request({"op": "start", "workspace": None, "url": url}) if owned_session else {"session_id": session_id, "workspace_supported": None}
+    sid = started["session_id"]
+    result = None
+    cleanup = None
+    try:
+        raw_result = request({"op": "exec", "session_id": sid, "code": code})
+        result = {k: v for k, v in raw_result.items() if k not in {"session_id", "workspace", "target_id"}}
+        output = {
+            "platform": platform,
+            "action": action,
+            "workspace_supported": started.get("workspace_supported"),
+            "session_mode": "auto_session_no_self_heal" if owned_session else "caller_owned_self_heal_capable",
+            "self_heal_capable": not owned_session,
+            "result": result,
+        }
+        if started.get("warning"):
+            output["warning"] = started["warning"]
+            output["extension_url"] = started.get("extension_url")
+        return output
+    finally:
+        if owned_session:
+            try:
+                raw_cleanup = request({"op": "stop", "session_id": sid})
+                cleanup = {k: v for k, v in raw_cleanup.items() if k not in {"session_id", "workspace", "target_id"}}
+            except Exception as exc:
+                cleanup = {"release_error": f"{type(exc).__name__}: {exc}"}
+        else:
+            cleanup = {"caller_owned_session": True}
+        if result is not None:
+            result["cleanup"] = cleanup

package/src/browser_workspace_app/platforms/chatgpt/README.md

@@ -0,0 +1,60 @@
+# ChatGPT browser platform
+
+Canonical reusable browser mechanics for ChatGPT.
+
+This platform owns ChatGPT-specific page behavior. Callers own lifecycle:
+
+- Agents Relay: disposable worker lifecycle and event/barrier ownership.
+- NeoY Tutor Workspace: persistent learner/thread lifecycle.
+
+Use Browser Workspace as the only browser-control engine. Do not duplicate ChatGPT
+selectors or submit/result-completion logic in callers.
+
+`temporary-submit` owns the reusable Temporary Chat page mechanics and verified submit receipt. Callers that need delayed cleanup should render the action source into a caller-owned Browser Workspace session and stop that session at their lifecycle barrier.
+
+## Web ChatGPT MCP apps
+
+Use the `mcp-app` action for repeatable inspection of an installed custom MCP app and for a safe tool refresh. It deliberately uses semantic text/role discovery rather than transient snapshot refs such as `e31`.
+
+```bash
+cat > /tmp/chatgpt-mcp-app.json <<'JSON'
+{"app_name":"neo","operation":"status"}
+JSON
+browser-workspace platform run chatgpt mcp-app --config /tmp/chatgpt-mcp-app.json
+```
+
+A connected app is verified by its detail page exposing `Permissions`, `Disconnect`, and `Refresh tools`. The action returns these as structured booleans.
+
+### Configure a custom MCP app
+
+The proven Web ChatGPT flow is:
+
+1. Start/reuse a Browser Workspace session on `https://chatgpt.com` and take a fresh `snapshot()` before interacting. Never reuse `eNN` refs from an earlier snapshot.
+2. Open the visible profile menu by semantic label `Open profile menu`, choose `Settings`, then choose `Plugins`. The durable settings route observed in October 2026 is `/settings/plugins-settings`, but prefer semantic navigation because routes can drift.
+3. From Plugins, use the create/add-custom-app control. Enter the app display name and its public HTTPS MCP endpoint. Keep endpoint/client/OAuth values in caller configuration; never commit credentials to this platform.
+4. Ask ChatGPT to scan/discover the MCP tools. If OAuth is advertised by the MCP server, continue the OAuth authorization flow and return to ChatGPT.
+5. Finish creating/installing the app, then reopen Settings -> Plugins and select the app by exact display name.
+6. Verify the detail page exposes `Permissions`, `Disconnect`, and `Refresh tools`. `Disconnect` is the positive signal that the account/OAuth connection is established. Run `mcp-app` with `operation=status` to capture this verification programmatically.
+7. After an MCP server descriptor/tool change, use `operation=refresh-tools`, then inspect status again before testing tool calls.
+
+### Snapshot-first fallback for UI drift
+
+If a semantic selector no longer resolves, do not guess coordinates or hard-code old refs. In the same Browser Workspace session:
+
+```python
+print(snapshot(interactive_only=False))
+```
+
+Use the fresh accessibility/DOM output to rediscover the visible control by role, accessible label, or stable text. When a menu is lazy-loaded, trigger the visible semantic control, wait for hydration, then snapshot again. This is how the profile menu -> Settings -> Plugins path was recovered during the live MCP setup.
+
+Destructive controls (`Disconnect`, `Uninstall`, `Delete app`) are intentionally not exposed as `mcp-app` operations.
+
+
+## XChat lifecycle control transfer
+
+Browser Workspace owns the ChatGPT UI mechanics for orchestrator lifecycle handoff.
+
+- `new-turn`: given stable `project_id`, `thread_id`, and `message`, wait until the current assistant turn is no longer generating, submit the continuation as the next user turn in the same thread, verify acceptance, and return without waiting for the new assistant answer.
+- `new-thread`: given stable `project_id` and `message` (plus optional `source_thread_id` provenance), open the same Project, submit the continuation to create a fresh thread, and return the durable new `thread_id` once ChatGPT replaces any temporary local id.
+
+These actions are control-transfer primitives. The generic Browser Workspace runner owns session start/stop and cleanup. Product code should pass stable Project/Thread IDs rather than persist ChatGPT URLs or DOM identities.

package/src/browser_workspace_app/platforms/chatgpt/actions/_bootstrap_start.py

@@ -0,0 +1,58 @@
+import json
+import time
+from urllib.parse import urlsplit
+
+CFG=json.load(open("__CFG_PATH__",encoding="utf-8"))
+
+def wait(pred,label,timeout=30):
+    deadline=time.time()+timeout
+    while time.time()<deadline:
+        value=pred()
+        if value:return value
+        time.sleep(.2)
+    raise RuntimeError(f"{label} not observed")
+
+def composer():
+    return js("""(() => {
+      const sels=['#prompt-textarea','[contenteditable="true"][data-composer-markdown]','[contenteditable="true"][data-lexical-editor="true"]','textarea'];
+      for(const s of sels){const e=document.querySelector(s);if(!e)continue;const r=e.getBoundingClientRect();if(r.width&&r.height)return s;}
+      return null;
+    })()""")
+
+def set_value(selector,text):
+    ok=js(f"""(() => {{
+      const e=document.querySelector({json.dumps(selector)});
+      if(!e)return false;e.focus();
+      if(e instanceof HTMLTextAreaElement || e instanceof HTMLInputElement){{
+        const p=e instanceof HTMLTextAreaElement?HTMLTextAreaElement.prototype:HTMLInputElement.prototype;
+        Object.getOwnPropertyDescriptor(p,'value')?.set?.call(e,{json.dumps(text)});
+      }}else{{
+        const sel=window.getSelection(),r=document.createRange();r.selectNodeContents(e);sel.removeAllRanges();sel.addRange(r);
+        document.execCommand('delete',false,null);document.execCommand('insertText',false,{json.dumps(text)});sel.removeAllRanges();
+      }}
+      e.dispatchEvent(new InputEvent('input',{{bubbles:true,inputType:'insertText',data:{json.dumps(text)}}}));
+      return true;
+    }})()""")
+    if not ok: raise RuntimeError("bootstrap composer could not be filled")
+
+target_id=new_tab("https://chatgpt.com/")
+wait_for_load()
+selector=wait(composer,"ChatGPT bootstrap composer",45)
+set_value(selector,CFG["instructions"])
+button=wait(lambda: js("""(() => {
+  const b=document.querySelector('button[data-testid="send-button"],button[aria-label="Send prompt"],button[aria-label="Send"],form button[type="submit"]');
+  if(!b||b.disabled||b.getAttribute('aria-disabled')==='true')return null;
+  b.setAttribute('data-neoy-bootstrap-send','1');return '[data-neoy-bootstrap-send="1"]';
+})()"""),"ChatGPT bootstrap send button",20)
+if not js("""(() => {const b=document.querySelector('[data-neoy-bootstrap-send="1"]');if(!b)return false;b.click();return true;})()"""):
+    raise RuntimeError("bootstrap send failed")
+deadline=time.time()+90
+thread_url=None
+while time.time()<deadline:
+    current=page_info().get("url","")
+    if "/c/" in urlsplit(current).path and "local-chatgpt" not in current:
+        thread_url=current.split("?",1)[0]
+        break
+    time.sleep(.25)
+if not thread_url: raise RuntimeError("bootstrap thread durable URL not observed")
+print(json.dumps({"status":"started","thread_url":thread_url,"target_id":target_id},ensure_ascii=False),flush=True)

package/src/browser_workspace_app/platforms/chatgpt/actions/_lifecycle_common.py

@@ -0,0 +1,119 @@
+import json
+import time
+from _readiness import wait_until_stable, submission_receipt, prompt_text_matches
+
+
+def composer_selector():
+    return js("""(() => {
+      const selectors=['#prompt-textarea','[contenteditable="true"][data-composer-markdown]','[contenteditable="true"][data-lexical-editor="true"]','textarea'];
+      for (const selector of selectors) {
+        const e=document.querySelector(selector);
+        if (!e || e.disabled) continue;
+        const r=e.getBoundingClientRect();
+        if (r.width>0 && r.height>0) return selector;
+      }
+      return null;
+    })()""")
+
+
+def composer_text(selector=None):
+    selector=selector or composer_selector()
+    if not selector: return ""
+    return js(f"""(() => {{
+      const e=document.querySelector({json.dumps(selector)});
+      if (!e) return '';
+      return (e.innerText || e.value || e.textContent || '').trim();
+    }})()""") or ""
+
+
+def send_enabled():
+    return bool(js("""(() => {
+      const b=document.querySelector('button[data-testid="send-button"],button[aria-label="Send prompt"],button[aria-label="Send"],form button[type="submit"]');
+      return !!b && !b.disabled && b.getAttribute('aria-disabled') !== 'true';
+    })()"""))
+
+
+def is_generating():
+    return bool(js("""(() => !![...document.querySelectorAll('button')].find(b => {
+      const a=(b.getAttribute('aria-label')||'').toLowerCase();
+      const t=(b.textContent||'').trim().toLowerCase();
+      const id=(b.getAttribute('data-testid')||'').toLowerCase();
+      return a.includes('stop answering') || a.includes('stop generating') || t === 'stop' || id.includes('stop');
+    }))()"""))
+
+
+def user_turns():
+    return js("""(() => {
+      const legacy=[...document.querySelectorAll('[data-message-author-role="user"]')]
+        .map(e=>({text:(e.innerText||'').trim(),id:e.getAttribute('data-message-id')||''})).filter(x=>x.text);
+      if (legacy.length) return legacy;
+      return [...document.querySelectorAll('h4')]
+        .filter(e=>(e.innerText||'').trim()==='You said:')
+        .map((e,index)=>({text:(e.parentElement?.innerText||'').replace(/^You said:\\s*/,'').trim(),id:`dom-user-${index}`}))
+        .filter(x=>x.text);
+    })()""") or []
+
+
+def wait_for_idle(timeout=300):
+    return wait_until_stable(
+        lambda: {"composer": composer_selector(), "generating": is_generating()},
+        lambda state: bool(state["composer"]) and not state["generating"],
+        timeout=timeout,
+        interval=.25,
+        stable_samples=3,
+        phase="ChatGPT turn completion",
+    )
+
+
+def fill_prompt(prompt):
+    selector=wait_until_stable(
+        lambda: composer_selector(),
+        lambda value: bool(value),
+        timeout=30,
+        phase="ChatGPT composer readiness",
+    )
+    editable=bool(js(f"""(() => document.querySelector({json.dumps(selector)})?.getAttribute('contenteditable')==='true')()"""))
+    if editable:
+        chunks=[prompt[i:i+256] for i in range(0, len(prompt), 256)]
+        ok=js(f"""(() => {{
+          const e=document.querySelector({json.dumps(selector)});
+          if(!e)return false;
+          e.focus();
+          const sel=window.getSelection(), range=document.createRange();
+          range.selectNodeContents(e); sel.removeAllRanges(); sel.addRange(range);
+          document.execCommand('delete',false,null); sel.removeAllRanges();
+          for (const chunk of {json.dumps(chunks)}) {{
+            const current=window.getSelection(), r=document.createRange();
+            r.selectNodeContents(e); r.collapse(false); current.removeAllRanges(); current.addRange(r);
+            if(!document.execCommand('insertText',false,chunk)) return false;
+          }}
+          e.dispatchEvent(new InputEvent('input',{{bubbles:true,inputType:'insertText',data:{json.dumps(prompt)}}}));
+          return true;
+        }})()""")
+        if not ok: raise RuntimeError("ChatGPT composer rejected lifecycle continuation")
+    else:
+        fill_input(selector,prompt,clear_first=True)
+    wait_until_stable(
+        lambda: {"text":composer_text(selector),"send":send_enabled()},
+        lambda state: prompt_text_matches(state["text"],prompt) and state["send"],
+        timeout=20,
+        phase="ChatGPT lifecycle continuation readiness",
+    )
+    return selector
+
+
+def submit(prompt):
+    before=len(user_turns())
+    selector=fill_prompt(prompt)
+    clicked=js("""(() => {
+      const b=document.querySelector('button[data-testid="send-button"],button[aria-label="Send prompt"],button[aria-label="Send"],form button[type="submit"]');
+      if(!b||b.disabled||b.getAttribute('aria-disabled')==='true')return false;
+      b.click(); return true;
+    })()""")
+    if not clicked: raise RuntimeError("ChatGPT send button changed before lifecycle submit")
+    deadline=time.time()+30
+    while time.time()<deadline:
+        receipt=submission_receipt(user_turns(),before,prompt,composer_text(selector))
+        if receipt: return receipt
+        time.sleep(.2)
+    raise RuntimeError("ChatGPT lifecycle submission was not observed")

package/src/browser_workspace_app/platforms/chatgpt/actions/_mcp_app.py

@@ -0,0 +1,80 @@
+import json
+import time
+
+CFG = json.load(open("__CFG_PATH__", encoding="utf-8"))
+APP_NAME = str(CFG.get("app_name") or "").strip()
+OP = str(CFG.get("operation") or "status").strip()
+
+if not APP_NAME:
+    raise ValueError("app_name is required")
+if OP not in {"status", "open", "refresh-tools"}:
+    raise ValueError("operation must be status, open, or refresh-tools")
+
+
+def wait_until(pred, label, timeout=30):
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        value = pred()
+        if value:
+            return value
+        time.sleep(0.2)
+    raise RuntimeError(f"{label} not observed")
+
+
+def app_button_exists():
+    return js(f"""(() => {{
+      const name={json.dumps(APP_NAME)};
+      return Array.from(document.querySelectorAll('button,a')).some(el => {{
+        const text=(el.innerText||'').trim();
+        return text===name || text.startsWith(name+'\\n');
+      }});
+    }})()""")
+
+
+def open_app():
+    ok = js(f"""(() => {{
+      const name={json.dumps(APP_NAME)};
+      const el=Array.from(document.querySelectorAll('button,a')).find(el => {{
+        const text=(el.innerText||'').trim();
+        return text===name || text.startsWith(name+'\\n');
+      }});
+      if(!el)return false; el.click(); return true;
+    }})()""")
+    if not ok:
+        raise RuntimeError(f"installed ChatGPT plugin not found: {APP_NAME}")
+    wait_until(lambda: js("document.body?.innerText?.includes('Refresh tools') || document.body?.innerText?.includes('Disconnect')"), "plugin detail controls")
+
+
+def detail_state():
+    return js("""(() => {
+      const body=(document.body?.innerText||'');
+      const texts=Array.from(document.querySelectorAll('button,a')).map(el=>(el.innerText||el.getAttribute('aria-label')||'').trim()).filter(Boolean);
+      return {
+        connected:body.includes('Disconnect'),
+        permissions:body.includes('Permissions'),
+        refresh_tools:texts.includes('Refresh tools'),
+        editable:texts.includes('Edit'),
+        uninstallable:texts.includes('Uninstall'),
+        url:location.href
+      };
+    })()""")
+
+
+goto_url("https://chatgpt.com/settings/plugins-settings")
+wait_for_load()
+wait_until(lambda: js("document.body?.innerText?.includes('Plugins')"), "ChatGPT Plugins settings")
+wait_until(app_button_exists, f"installed plugin {APP_NAME}")
+open_app()
+
+if OP == "refresh-tools":
+    ok = js("""(() => {
+      const b=Array.from(document.querySelectorAll('button')).find(x=>(x.innerText||'').trim()==='Refresh tools');
+      if(!b||b.disabled)return false; b.click(); return true;
+    })()""")
+    if not ok:
+        raise RuntimeError("Refresh tools control is unavailable")
+    time.sleep(0.5)
+
+wait_until(lambda: js("document.body?.innerText?.includes('Refresh tools') || document.body?.innerText?.includes('Disconnect')"), "plugin detail hydration")
+state = detail_state()
+print(json.dumps({"app_name": APP_NAME, "operation": OP, **state}, ensure_ascii=False), flush=True)