@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/__main__.py

@@ -0,0 +1,226 @@
+"""Daemon entry point: python -m xactor --dispatcher-id <id> [--backend browser|stdlib]"""
+
+import argparse
+import asyncio
+import os
+
+# The host puts this package on PYTHONPATH rather than starting us inside it
+# (a working folder inside a worktree keeps Windows from ever deleting the
+# tree). `sys.path` was settled when the interpreter started, so the variable
+# has done its job; put back what the user had, so agent commands spawned from
+# here see their own environment rather than ours.
+_PYTHONPATH_BEFORE = os.environ.pop("WIDGEX_PYTHONPATH_BEFORE", None)
+if _PYTHONPATH_BEFORE is not None:
+    if _PYTHONPATH_BEFORE:
+        os.environ["PYTHONPATH"] = _PYTHONPATH_BEFORE
+    else:
+        os.environ.pop("PYTHONPATH", None)
+
+from . import bridge, plan_mode  # noqa: E402
+
+
+def _start_browser_backend(dispatcher_id: str) -> None:
+    """Original browser automation backend — requires a CDP dispatcher."""
+    from .api import ElementaryAPI
+    from .dom import DOMSnapshot, HybridNode, HybridDiff
+    from .states import PageState, LoadingState, Observation, Transition, Step, StateRegistry
+
+    api = ElementaryAPI()
+
+    bridge.set_exec_scope({
+        "api": api,
+        "asyncio": asyncio,
+        # The host composes exec code for `run_transition`, and needs one safe
+        # way to hand structured parameters across that boundary. JSON is that
+        # way: `json.loads` of a string literal cannot be talked into
+        # evaluating anything, whereas a Python dict literal assembled by
+        # string concatenation is one `true` away from a NameError and one
+        # quote away from being an injection.
+        "json": __import__("json"),
+        "DOMSnapshot": DOMSnapshot,
+        "HybridNode": HybridNode,
+        "HybridDiff": HybridDiff,
+        # Layer 2
+        "PageState": PageState,
+        "LoadingState": LoadingState,
+        "Observation": Observation,
+        "Transition": Transition,
+        "Step": Step,
+        "registry": StateRegistry,
+    })
+
+
+def _graft_browser_l1(api: object) -> None:
+    """Put the Layer 1 browser verbs on the stdlib `api`, as bound methods.
+
+    The browser backend used to be a *second* Python process whose only real
+    job was holding this namespace: the terminal already reached every browser
+    command through `api.browser_*`, so the extra interpreter existed so that
+    `api.click(...)` and `registry` would resolve somewhere. That made
+    `browser_exec` a courier — the terminal shipped a string of Python to
+    another process to run — and cost an interpreter spawn on every browser
+    open.
+
+    Grafting rather than nesting under `api.browser` keeps every man page and
+    every habit intact: the verbs read the same here as they did there.
+
+    Grafting bound methods, rather than delegating via `__getattr__`, is what
+    keeps `dir(api)` honest and tracebacks pointing at `ElementaryAPI`. The
+    queue state lives on the instance the methods are bound to, so `click()`
+    and the `drain()` that collects it stay on the same object.
+    """
+    from .api import ElementaryAPI
+
+    browser = ElementaryAPI()
+    # So a verb that hands `self` onward — `here()` building a PageState — gives
+    # it the whole api rather than this half of it. See `ElementaryAPI._surface`.
+    browser._merged = api
+    for name in dir(browser):
+        if name.startswith("_"):
+            continue
+        # The two surfaces are disjoint today (28 verbs against 58, no overlap).
+        # Nothing enforces that, and a later `StdlibAPI.select` would silently
+        # shadow the browser's — or be shadowed, depending on which way the
+        # loop ran. Refusing to start is the only failure mode here that cannot
+        # be mistaken for the verb simply misbehaving.
+        if hasattr(api, name):
+            raise RuntimeError(
+                f"Cannot merge browser Layer 1 into the shell: `api.{name}` "
+                f"already exists on StdlibAPI. Rename one of them."
+            )
+        # Wrapped, because this `setattr` is the reason these verbs have never
+        # been gated: `_gate_api_methods` decorates what is in the class body,
+        # and these arrive afterwards. `guard` returns the function untouched
+        # when Plan mode permits it, so the read verbs cost nothing.
+        setattr(api, name, plan_mode.guard(name, getattr(browser, name)))
+
+
+def _start_stdlib_backend(cwd: str, sandbox_mode: str, fallback_cwd: str | None = None,
+                          fence: str | None = None, allow: list[str] | None = None) -> None:
+    """Stdlib coding backend — file I/O, subprocess, search, sessions, xylon, browser."""
+    from .stdlib_api import StdlibAPI
+    from . import sandbox
+
+    # Install the sandbox BEFORE any user code can run
+    sandbox.configure(
+        cwd=cwd,
+        mode=sandbox_mode,
+        allow_subprocess=(sandbox_mode in ("permissive", "open")),
+        allow_network=(sandbox_mode == "open"),
+        # The task's other working copies (its slots on other boards): one
+        # task's folders, read and written without asking.
+        read_allow=list(allow or []),
+        write_allow=list(allow or []),
+    )
+    if fence is not None:
+        # A drive-channel task: strict paths rooted at its folder, so a read
+        # outside it is refused (and asked about) rather than allowed the way
+        # permissive allows it. Subprocesses stay on — `api.bash` is how the
+        # agent works, and the host asks about each command it runs — which
+        # strict alone would turn off. An empty fence is one the host could
+        # not name; it admits no folder, so every path is asked about.
+        sandbox.configure(cwd=fence or cwd, mode="strict", fence=fence, allow_subprocess=True)
+    sandbox.install()
+
+    from .dom import DOMSnapshot, HybridNode, HybridDiff
+    from .states import PageState, LoadingState, Observation, Transition, Step, StateRegistry
+
+    api = StdlibAPI(cwd=cwd, bridge=bridge, fallback_cwd=fallback_cwd)
+    _graft_browser_l1(api)
+
+    # os/Path/json stay bound for path and data manipulation; the operations
+    # they expose (open, os.remove, ...) are denied by the audit hook unless
+    # they happen inside an api.* call.
+    bridge.set_exec_scope({
+        "api": api,
+        "asyncio": asyncio,
+        # Re-export stdlib modules for convenience in exec scope.
+        #
+        # `os` is the sandboxed one. Every other way into the OS raises an
+        # audit event the hook above can deny; reading `os.environ` raises
+        # none, so it was the one part of the outside world agent code could
+        # reach directly, in every permission mode. See sandbox._GuardedOS —
+        # path manipulation, which is why `os` is bound at all, is untouched.
+        "os": sandbox.guarded_os(),
+        "Path": __import__("pathlib").Path,
+        "json": __import__("json"),
+        # Layer 2, formerly the browser process's whole reason to exist. Widget
+        # files are read by the host and arrive here as exec'd source, so they
+        # need these bound — they import nothing, by design, and could not
+        # import under `restrict_builtins` anyway.
+        "DOMSnapshot": DOMSnapshot,
+        "HybridNode": HybridNode,
+        "HybridDiff": HybridDiff,
+        "PageState": PageState,
+        "LoadingState": LoadingState,
+        "Observation": Observation,
+        "Transition": Transition,
+        "Step": Step,
+        "registry": StateRegistry,
+    }, restrict_builtins=True)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dispatcher-id", default="stdlib")
+    parser.add_argument("--backend", choices=["browser", "stdlib"], default="browser")
+    parser.add_argument("--cwd", default=None, help="Working directory for stdlib backend")
+    parser.add_argument("--requested-cwd", default=None,
+                        help="What the host originally asked for, for disclosure")
+    parser.add_argument("--fallback-cwd", default=None,
+                        help="Directory to use when --cwd no longer exists")
+    parser.add_argument("--sandbox", default="permissive",
+                        choices=["strict", "permissive", "open"],
+                        help="Sandbox permission mode")
+    parser.add_argument("--fence", default=None,
+                        help="The only folder file calls may use without asking")
+    parser.add_argument("--allow", action="append", default=[],
+                        help="A folder of the same task, read and written without asking")
+    args = parser.parse_args()
+
+    # Before the sandbox goes on, which refuses some of what watching needs.
+    # See `parent_watch` for why EOF alone did not end these daemons.
+    from . import parent_watch
+    parent_watch.watch(parent_watch.leave)
+
+    if args.backend == "stdlib":
+        import os
+        cwd = args.cwd or os.getcwd()
+        # The host checked this a moment ago, but the directory can be gone by
+        # the time we start — and a daemon that dies here reports ENOENT against
+        # the interpreter, naming neither the session nor the missing path.
+        if not os.path.isdir(cwd):
+            for candidate in (args.fallback_cwd, os.path.expanduser("~")):
+                if candidate and os.path.isdir(candidate):
+                    bridge._emit({
+                        "event": "cwd_fallback",
+                        "requested": args.requested_cwd or cwd,
+                        "effective": candidate,
+                    })
+                    cwd = candidate
+                    break
+        _start_stdlib_backend(cwd, args.sandbox, fallback_cwd=args.fallback_cwd, fence=args.fence, allow=args.allow)
+    else:
+        _start_browser_backend(args.dispatcher_id)
+
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+
+    # The read loop is the only thing servicing stdin. If it ever stops, every
+    # bridge call still waiting is unresolvable and every later one is too — the
+    # session looks alive and answers nothing. It used to die silently; now its
+    # death is announced and the pending calls are failed rather than orphaned.
+    _read_task = loop.create_task(bridge._read_loop())
+    _read_task.add_done_callback(bridge._read_loop_stopped)
+
+    bridge._emit({
+        "event": "ready",
+        "dispatcher_id": args.dispatcher_id,
+        "backend": args.backend,
+    })
+
+    loop.run_forever()
+
+
+if __name__ == "__main__":
+    main()