seedcode-cli 6.1.5__py3-none-any.whl

seedcode/computer/browser_selenium.py

@@ -0,0 +1,209 @@
+"""Optional Selenium fallback for deep, DOM-level browser automation.
+
+This is NOT the primary browser mechanism — :mod:`seedcode.computer.browser`
+drives the user's real default browser through the OS and the UI resolver, with
+no driver downloads and full offline support. Selenium is only used when a task
+genuinely needs DOM-level control (CSS/XPath selectors, ``execute_script``) and
+the user has installed the optional extra.
+
+Kept isolated here so importing the Computer Engine never pulls in Selenium, and
+so the default-browser path has zero dependency on WebDriver being present.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from selenium import webdriver
+
+_driver: "webdriver.Chrome | webdriver.Edge | None" = None
+_browser_type: str | None = None
+
+
+class BrowserError(Exception):
+    """Selenium-backed browser automation error."""
+
+
+def is_available() -> tuple[bool, str]:
+    """Whether the optional Selenium fallback can run."""
+    try:
+        import selenium  # noqa: F401
+
+        return True, ""
+    except ImportError:
+        return False, "selenium not installed (pip install seedcode-cli[browser])"
+
+
+def _get_driver() -> "webdriver.Chrome | webdriver.Edge":
+    """Get or create the WebDriver session."""
+    global _driver, _browser_type
+
+    if _driver is not None:
+        try:
+            _driver.current_url  # liveness probe
+            return _driver
+        except Exception:
+            _driver = None
+
+    if _driver is None:
+        _driver, _browser_type = _launch_browser()
+    return _driver
+
+
+def _launch_browser() -> tuple["webdriver.Chrome | webdriver.Edge", str]:
+    """Launch Chrome or Edge under WebDriver."""
+    from selenium import webdriver
+    from selenium.webdriver.chrome.options import Options as ChromeOptions
+    from selenium.webdriver.chrome.service import Service as ChromeService
+    from selenium.webdriver.edge.options import Options as EdgeOptions
+    from selenium.webdriver.edge.service import Service as EdgeService
+
+    try:
+        from webdriver_manager.chrome import ChromeDriverManager
+        from webdriver_manager.microsoft import EdgeChromiumDriverManager
+
+        try:
+            options = ChromeOptions()
+            options.add_argument("--start-maximized")
+            options.add_experimental_option("excludeSwitches", ["enable-logging"])
+            service = ChromeService(ChromeDriverManager().install())
+            return webdriver.Chrome(service=service, options=options), "chrome"
+        except Exception:
+            pass
+
+        try:
+            options = EdgeOptions()
+            options.add_argument("--start-maximized")
+            options.add_experimental_option("excludeSwitches", ["enable-logging"])
+            service = EdgeService(EdgeChromiumDriverManager().install())
+            return webdriver.Edge(service=service, options=options), "edge"
+        except Exception:
+            pass
+    except ImportError:
+        try:
+            options = ChromeOptions()
+            options.add_argument("--start-maximized")
+            return webdriver.Chrome(options=options), "chrome"
+        except Exception:
+            pass
+        try:
+            options = EdgeOptions()
+            options.add_argument("--start-maximized")
+            return webdriver.Edge(options=options), "edge"
+        except Exception:
+            pass
+
+    raise BrowserError(
+        "Could not launch a WebDriver browser. Install the optional extra: "
+        "pip install seedcode-cli[browser]"
+    )
+
+
+def navigate(url: str) -> str:
+    driver = _get_driver()
+    if not url.startswith(("http://", "https://", "file://", "about:")):
+        url = "https://" + url
+    driver.get(url)
+    time.sleep(1)
+    return f"Navigated to: {driver.current_url}\nTitle: {driver.title}"
+
+
+def click_element(selector: str, selector_type: str = "css") -> str:
+    from selenium.webdriver.common.by import By
+    from selenium.webdriver.support import expected_conditions as EC
+    from selenium.webdriver.support.ui import WebDriverWait
+
+    driver = _get_driver()
+    by_map = {
+        "css": By.CSS_SELECTOR, "xpath": By.XPATH, "id": By.ID, "name": By.NAME,
+        "class": By.CLASS_NAME, "tag": By.TAG_NAME, "link_text": By.LINK_TEXT,
+        "partial_link": By.PARTIAL_LINK_TEXT,
+    }
+    by = by_map.get(selector_type)
+    if by is None:
+        raise BrowserError(f"Unknown selector type: {selector_type}")
+    try:
+        element = WebDriverWait(driver, 10).until(EC.element_to_be_clickable((by, selector)))
+        element.click()
+        return f"Clicked element: {selector}"
+    except Exception as exc:
+        raise BrowserError(f"Could not click element '{selector}': {exc}")
+
+
+def type_in_element(selector: str, text: str, selector_type: str = "css", clear: bool = True) -> str:
+    from selenium.webdriver.common.by import By
+    from selenium.webdriver.support import expected_conditions as EC
+    from selenium.webdriver.support.ui import WebDriverWait
+
+    driver = _get_driver()
+    by_map = {"css": By.CSS_SELECTOR, "xpath": By.XPATH, "id": By.ID, "name": By.NAME}
+    by = by_map.get(selector_type)
+    if by is None:
+        raise BrowserError(f"Unknown selector type: {selector_type}")
+    try:
+        element = WebDriverWait(driver, 10).until(EC.presence_of_element_located((by, selector)))
+        if clear:
+            element.clear()
+        element.send_keys(text)
+        return f"Typed into {selector}: {text}"
+    except Exception as exc:
+        raise BrowserError(f"Could not type into '{selector}': {exc}")
+
+
+def get_page_info() -> str:
+    driver = _get_driver()
+    return f"URL: {driver.current_url}\nTitle: {driver.title}"
+
+
+def find_elements(selector: str, selector_type: str = "css") -> str:
+    from selenium.webdriver.common.by import By
+
+    driver = _get_driver()
+    by_map = {
+        "css": By.CSS_SELECTOR, "xpath": By.XPATH, "id": By.ID, "name": By.NAME,
+        "class": By.CLASS_NAME, "tag": By.TAG_NAME,
+    }
+    by = by_map.get(selector_type)
+    if by is None:
+        raise BrowserError(f"Unknown selector type: {selector_type}")
+    try:
+        elements = driver.find_elements(by, selector)
+        if not elements:
+            return f"No elements found matching: {selector}"
+        results = []
+        for i, elem in enumerate(elements[:20], 1):
+            text = elem.text.strip()[:100] or elem.get_attribute("value") or ""
+            results.append(f"{i}. {text}")
+        return f"Found {len(elements)} elements:\n" + "\n".join(results)
+    except Exception as exc:
+        raise BrowserError(f"Could not find elements '{selector}': {exc}")
+
+
+def execute_script(script: str) -> str:
+    driver = _get_driver()
+    try:
+        result = driver.execute_script(script)
+        return f"Script executed. Result: {result}"
+    except Exception as exc:
+        raise BrowserError(f"Script execution failed: {exc}")
+
+
+def close_browser() -> str:
+    global _driver, _browser_type
+    if _driver is not None:
+        try:
+            _driver.quit()
+        except Exception:
+            pass
+        _driver = None
+        _browser_type = None
+        return "Browser closed"
+    return "No browser open"
+
+
+def get_current_browser() -> str:
+    if _driver is None:
+        return "No browser open"
+    return _browser_type or "unknown"

seedcode/computer/browser_skills.py

@@ -0,0 +1,245 @@
+"""Browser skills: the complete AI-facing surface for web automation.
+
+Each skill here takes a *goal* ("play Love Me Thoda Aur on YouTube") and hands
+it to the deterministic :class:`~.browser_engine.BrowserEngine`, which performs
+every step — navigation, popup dismissal, result selection, playback, and
+verification — without returning to the AI in between. The AI issues exactly
+one call per goal and reads back one verified outcome.
+
+This is the boundary the refactor exists to enforce. There is deliberately no
+skill that clicks "a thing on a web page": if a workflow is worth automating it
+gets a named skill whose procedure lives here in code, where it is testable,
+repeatable, and identical on every run. ``ui_*`` actions are refused outright
+on browser windows (see :mod:`.dispatcher`) so the old click-by-click pattern
+cannot come back.
+
+Importing this module registers the skills; :mod:`.catalog` imports it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..tools.permissions import PermissionLevel
+from .browser_engine import BrowserEngine, BrowserWorkflowError, WorkflowResult
+from .skills import Outcome, SkillContext, SkillError, skill
+
+# One engine per controller. Skills are dispatched one at a time against the
+# session's single controller, so caching here keeps the DevTools connection
+# and popup state alive across calls instead of re-attaching every skill.
+_engines: "dict[int, BrowserEngine]" = {}
+
+
+def _engine(ctx: SkillContext) -> BrowserEngine:
+    """The BrowserEngine bound to this context's controller."""
+    key = id(ctx.controller)
+    engine = _engines.get(key)
+    if engine is None:
+        engine = BrowserEngine(controller=ctx.controller)
+        _engines[key] = engine
+    return engine
+
+
+def reset_engines() -> None:
+    """Drop cached engines (session teardown and tests)."""
+    _engines.clear()
+
+
+def bind_engine(controller: Any, engine: BrowserEngine) -> None:
+    """Pre-bind a BrowserEngine to a controller.
+
+    Lets a caller (notably the test suite) supply an engine with injected
+    drivers, so browser skills can be exercised without a live browser.
+    """
+    _engines[id(controller)] = engine
+
+
+def _run(ctx: SkillContext, action, description: str) -> Outcome:
+    """Execute a workflow and translate it into a verifiable Outcome.
+
+    Every browser skill funnels through here so failure handling, state
+    recording, and the expectation contract are identical across the catalog.
+    """
+    try:
+        result: WorkflowResult = action()
+    except BrowserWorkflowError as exc:
+        # A workflow failure is already human-readable and actionable; surface
+        # it as a SkillError so the dispatcher can log and replan on it.
+        raise SkillError(str(exc))
+    ctx.state.record_action(description)
+    if result.url:
+        ctx.state.set_browser_url(result.url)
+    return Outcome(result.detail, result.expected, app_target="browser")
+
+
+def _query(params: dict[str, Any]) -> str:
+    """The search phrase, accepting the names an AI naturally reaches for."""
+    for key in ("query", "q", "search", "text", "title", "song"):
+        value = str(params.get(key, "")).strip()
+        if value:
+            return value
+    raise SkillError("this skill requires a 'query' parameter")
+
+
+# --- search ------------------------------------------------------------------
+
+@skill(
+    "youtube_search",
+    "Search YouTube for a query. Opens the results page and clears any consent "
+    "or sign-in popups automatically.",
+    PermissionLevel.DESKTOP,
+    {"query": "what to search for on YouTube"},
+)
+def youtube_search(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    query = _query(params)
+    return _run(
+        ctx, lambda: _engine(ctx).youtube_search(query), f"searched YouTube for {query}"
+    )
+
+
+@skill(
+    "youtube_play",
+    "Play a song or video on YouTube by name — the complete workflow. Finds the "
+    "best match, opens it, dismisses popups, and starts playback. Use this "
+    "instead of searching and then clicking a result.",
+    PermissionLevel.DESKTOP,
+    {"query": "the song, video, or channel to play"},
+)
+def youtube_play(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    query = _query(params)
+    return _run(ctx, lambda: _engine(ctx).youtube_play(query), f"played {query} on YouTube")
+
+
+@skill(
+    "google_search",
+    "Search Google for a query in the default browser.",
+    PermissionLevel.DESKTOP,
+    {"query": "what to search for"},
+)
+def google_search(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    query = _query(params)
+    return _run(
+        ctx, lambda: _engine(ctx).google_search(query), f"searched Google for {query}"
+    )
+
+
+@skill(
+    "web_search",
+    "Search the web in the default browser (google, bing, duckduckgo, youtube).",
+    PermissionLevel.DESKTOP,
+    {"query": "search terms", "engine": "(optional) google|bing|duckduckgo|youtube"},
+)
+def web_search(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    query = _query(params)
+    engine_name = str(params.get("engine", "google")).strip().lower() or "google"
+    return _run(
+        ctx,
+        lambda: _engine(ctx).search(query, engine_name),
+        f"searched {engine_name} for {query}",
+    )
+
+
+# --- navigation --------------------------------------------------------------
+
+@skill(
+    "open_url",
+    "Open a web address in the default browser and confirm the page loaded.",
+    PermissionLevel.DESKTOP,
+    {"url": "the address to open", "new_tab": "(optional) true to use a new tab"},
+)
+def open_url(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    url = str(params.get("url") or params.get("address") or "").strip()
+    if not url:
+        raise SkillError("open_url requires a 'url' parameter")
+    new_tab = _flag(params, "new_tab")
+    return _run(
+        ctx, lambda: _engine(ctx).open_url(url, new_tab=new_tab), f"opened {url}"
+    )
+
+
+@skill(
+    "new_tab",
+    "Open a new browser tab, optionally at a URL.",
+    PermissionLevel.DESKTOP,
+    {"url": "(optional) address to open in the new tab"},
+)
+def new_tab(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    url = str(params.get("url", "")).strip() or "about:blank"
+    return _run(ctx, lambda: _engine(ctx).new_tab(url), "opened a new browser tab")
+
+
+@skill(
+    "close_tab",
+    "Close the active browser tab.",
+    PermissionLevel.DESKTOP,
+)
+def close_tab(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    return _run(ctx, lambda: _engine(ctx).close_tab(), "closed a browser tab")
+
+
+@skill(
+    "switch_tab",
+    "Switch to another browser tab, by part of its title or URL (or the next "
+    "tab when no target is given).",
+    PermissionLevel.DESKTOP,
+    {"target": "(optional) part of the tab's title or address"},
+)
+def switch_tab(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    target = str(params.get("target") or params.get("title") or params.get("url") or "").strip()
+    return _run(
+        ctx,
+        lambda: _engine(ctx).switch_tab(target),
+        f"switched to tab {target}" if target else "switched browser tab",
+    )
+
+
+@skill("back", "Go back one page in the browser's history.", PermissionLevel.DESKTOP)
+def back(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    return _run(ctx, lambda: _engine(ctx).back(), "went back in the browser")
+
+
+@skill("forward", "Go forward one page in the browser's history.", PermissionLevel.DESKTOP)
+def forward(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    return _run(ctx, lambda: _engine(ctx).forward(), "went forward in the browser")
+
+
+@skill("refresh", "Reload the current browser page.", PermissionLevel.DESKTOP)
+def refresh(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    return _run(ctx, lambda: _engine(ctx).refresh(), "refreshed the browser page")
+
+
+# --- information -------------------------------------------------------------
+
+@skill(
+    "browser_page",
+    "Report the title and address of the page currently open in the browser.",
+    PermissionLevel.DESKTOP,
+)
+def browser_page(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    return _run(ctx, lambda: _engine(ctx).page_info(), "read the current browser page")
+
+
+@skill(
+    "which_browser",
+    "Report which browser is the system default.",
+    PermissionLevel.DESKTOP,
+)
+def which_browser(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    return Outcome(f"default browser: {_engine(ctx).which_browser()}")
+
+
+@skill(
+    "launch_browser",
+    "Open the user's default browser, optionally at a URL.",
+    PermissionLevel.DESKTOP,
+    {"url": "(optional) URL to open"},
+)
+def launch_browser(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    url = str(params.get("url", "")).strip()
+    if not url or url == "about:blank":
+        return _run(ctx, lambda: _engine(ctx).new_tab("about:blank"), "opened the browser")
+    return _run(ctx, lambda: _engine(ctx).open_url(url), f"opened browser at {url}")
+
+
+def _flag(params: dict[str, Any], key: str) -> bool:
+    return str(params.get(key, "")).strip().lower() in ("true", "1", "yes", "on")

seedcode/computer/catalog.py

@@ -0,0 +1,200 @@
+"""The built-in skill catalog.
+
+Concrete, deterministic skills registered into ``skills.REGISTRY``. Each is a
+real procedure over the :class:`ComputerController` primitives — launching apps,
+creating projects, editor/clipboard/git actions — with a declared permission
+level and an ``expected`` outcome for the verifier. No placeholders, no AI
+calls.
+
+Browser work lives in its own module (:mod:`.browser_skills`) because it is a
+whole workflow engine rather than a handful of primitives; importing this
+module pulls those skills in too.
+
+Importing this module has the side effect of populating the registry; the
+Computer Engine imports it once at startup.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from ..tools.permissions import PermissionLevel, CATEGORY_SHELL
+from .skills import Outcome, SkillContext, SkillError, skill
+
+
+def _req(params: dict[str, Any], key: str) -> str:
+    val = str(params.get(key, "")).strip()
+    if not val:
+        raise SkillError(f"skill requires a '{key}' parameter")
+    return val
+
+
+# --- application launching --------------------------------------------------
+
+@skill("launch_app", "Open or focus a desktop application by name or path.",
+       PermissionLevel.DESKTOP, {"target": "app name, e.g. 'notepad' or a path"})
+def launch_app(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    target = _req(params, "target")
+    # Already open? Focus it instead of spawning a duplicate.
+    for w in ctx.controller.list_windows():
+        if target.lower() in w.title.lower():
+            ctx.controller.focus_window(w.title)
+            ctx.state.note_focus(w.title)
+            return Outcome(f"focused existing {w.title}", {"window": target},
+                           window_title=w.title, app_target=target)
+    ctx.controller.open_app(target)
+    ctx.state.record_action(f"launched {target}")
+    ctx.state.note_focus(target)
+    return Outcome(f"launched {target}", {"window": target},
+                   window_title=target, app_target=target)
+
+
+@skill("focus_app", "Bring an already-open application to the foreground.",
+       PermissionLevel.DESKTOP, {"target": "part of the window title"})
+def focus_app(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    target = _req(params, "target")
+    win = ctx.controller.focus_window(target)
+    title = getattr(win, "title", target)
+    ctx.state.note_focus(title)
+    return Outcome(f"focused {title}", {"window": target}, window_title=title)
+
+
+@skill("close_app", "Close an application window.",
+       PermissionLevel.DESKTOP, {"target": "part of the window title"})
+def close_app(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    target = _req(params, "target")
+    ctx.controller.close_app(target)
+    ctx.state.record_action(f"closed {target}")
+    return Outcome(f"closed {target}", {"window_gone": target})
+
+
+@skill("launch_vscode", "Open Visual Studio Code, optionally on a folder.",
+       PermissionLevel.DESKTOP, {"path": "(optional) folder to open"})
+def launch_vscode(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    path = str(params.get("path", "")).strip()
+    target = f'code "{path}"' if path else "code"
+    ctx.controller.open_app(target)
+    ctx.state.note_focus("Visual Studio Code")
+    return Outcome(f"opened VS Code{f' on {path}' if path else ''}",
+                   {"window": "Visual Studio Code"},
+                   window_title="Visual Studio Code", app_target="code")
+
+
+@skill("launch_terminal", "Open a terminal window.", PermissionLevel.DESKTOP)
+def launch_terminal(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    # Windows Terminal if present, else the classic console.
+    target = "wt" if os.name == "nt" else "x-terminal-emulator"
+    try:
+        ctx.controller.open_app(target)
+    except Exception:
+        ctx.controller.open_app("cmd" if os.name == "nt" else "xterm")
+    ctx.state.note_focus("Terminal")
+    return Outcome("opened a terminal", {"window": "Terminal"}, app_target=target)
+
+
+# --- browser ----------------------------------------------------------------
+# Every web workflow lives in :mod:`.browser_skills`, backed by the
+# deterministic BrowserEngine: importing it registers youtube_play,
+# youtube_search, google_search, open_url, new_tab/close_tab/switch_tab, and
+# back/forward/refresh. They are whole procedures — popup handling, result
+# selection, and verification included — so the AI issues one goal per task
+# and never assembles a browser workflow out of clicks.
+from . import browser_skills as _browser_skills  # noqa: E402,F401
+
+
+# --- operator skills (Phase 4+) ---------------------------------------------
+# Screen intelligence queries, semantic element-id actions, the application
+# controller (open/find/close/install), DOM web extraction, and local
+# memory. Same registry, same permission gates, same verification path.
+from . import operator_skills as _operator_skills  # noqa: E402,F401
+
+
+# --- editor / clipboard -----------------------------------------------------
+
+@skill("save_current_file", "Save the file in the focused editor (Ctrl+S).",
+       PermissionLevel.DESKTOP)
+def save_current_file(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    ctx.controller.hotkey(["ctrl", "s"])
+    ctx.state.record_action("saved current file")
+    return Outcome("sent save (Ctrl+S) to the focused window")
+
+
+@skill("copy_selection", "Copy the current selection to the clipboard.",
+       PermissionLevel.DESKTOP)
+def copy_selection(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    ctx.controller.hotkey(["ctrl", "c"])
+    ctx.state.record_action("copied selection")
+    return Outcome("copied selection to clipboard")
+
+
+@skill("paste_clipboard", "Paste the clipboard into the focused window.",
+       PermissionLevel.DESKTOP)
+def paste_clipboard(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    ctx.controller.hotkey(["ctrl", "v"])
+    ctx.state.record_action("pasted clipboard")
+    return Outcome("pasted clipboard into the focused window")
+
+
+# --- filesystem / projects (workspace level) --------------------------------
+
+@skill("create_python_project", "Scaffold a Python project folder with main.py and a venv-ready layout.",
+       PermissionLevel.WORKSPACE, {"name": "project folder name", "path": "(optional) parent dir"})
+def create_python_project(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    name = _req(params, "name")
+    parent = ctx.permissions.resolve(str(params.get("path", ".")))
+    root = parent / name
+    ctx.permissions.check_write(root)
+    (root / "src").mkdir(parents=True, exist_ok=True)
+    (root / "src" / "main.py").write_text(
+        'def main() -> None:\n    print("Hello from ' + name + '")\n\n\n'
+        'if __name__ == "__main__":\n    main()\n',
+        encoding="utf-8",
+    )
+    (root / "README.md").write_text(f"# {name}\n", encoding="utf-8")
+    (root / "requirements.txt").write_text("", encoding="utf-8")
+    ctx.state.record_action(f"created python project {name}")
+    return Outcome(f"created Python project at {root}", {"file_exists": str(root / "src" / "main.py")})
+
+
+# --- terminal / commands (require confirmation) -----------------------------
+
+@skill("run_python", "Run a Python script with the system interpreter.",
+       PermissionLevel.WORKSPACE, {"script": "path to the .py file"}, sensitive=True)
+def run_python(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    script = _req(params, "script")
+    path = ctx.permissions.resolve(script)
+    ctx.permissions.check_execute(f"python {path}")
+    ctx.permissions.confirm_action(CATEGORY_SHELL, f"python {path}")
+    out = _run_command(["python", str(path)], cwd=ctx.permissions.workspace, ctx=ctx)
+    return Outcome(f"ran {path}\n{out}")
+
+
+@skill("run_node", "Run a JavaScript file with Node.js.",
+       PermissionLevel.WORKSPACE, {"script": "path to the .js file"}, sensitive=True)
+def run_node(ctx: SkillContext, params: dict[str, Any]) -> Outcome:
+    script = _req(params, "script")
+    path = ctx.permissions.resolve(script)
+    ctx.permissions.check_execute(f"node {path}")
+    ctx.permissions.confirm_action(CATEGORY_SHELL, f"node {path}")
+    out = _run_command(["node", str(path)], cwd=ctx.permissions.workspace, ctx=ctx)
+    return Outcome(f"ran {path}\n{out}")
+
+
+def _run_command(argv: list[str], *, cwd: Path, ctx: SkillContext) -> str:
+    import subprocess
+
+    try:
+        proc = subprocess.run(
+            argv, cwd=str(cwd), capture_output=True, text=True, timeout=120
+        )
+    except FileNotFoundError:
+        raise SkillError(f"'{argv[0]}' is not installed or not on PATH")
+    except subprocess.TimeoutExpired:
+        raise SkillError(f"'{' '.join(argv)}' timed out after 120s")
+    output = (proc.stdout or "") + (proc.stderr or "")
+    if ctx.permissions.on_output and output:
+        for line in output.splitlines():
+            ctx.permissions.on_output(line)
+    return output.strip()[:4000] or f"(exit {proc.returncode}, no output)"