pycodex-ws 0.4.7__tar.gz → 0.5.0__tar.gz

pycodex_ws-0.5.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.1
+Name: pycodex-ws
+Version: 0.5.0
+Summary: Browser workspace and optional Feishu integration for python-codex
+License-File: LICENSE
+Requires-Python: >=3.7
+Requires-Dist: pillow>=9.0.0
+Requires-Dist: python-codex==0.5.0
+Requires-Dist: websockets<16,>=11
+Description-Content-Type: text/markdown
+
+# pycodex-ws
+
+Browser conversations, a live HTML Canvas, read-only file/diff viewers and
+optional Feishu integration for
+[`python-codex`](https://pypi.org/project/python-codex/).
+Requires Python 3.7+ and installs the matching core version.
+
+## Quick start
+
+```bash
+python3 -m pip install pycodex-ws
+```
+
+Create `workspaces.json`:
+
+```json
+{
+  "workspaces": [
+    {"id": "demo", "work_dir": ".", "state_path": "demo", "enable_board": true}
+  ]
+}
+```
+
+```bash
+pycodex-ws --listen 127.0.0.1:6007 --workspace-config workspaces.json
+```
+
+Open `http://127.0.0.1:6007`. Use `python3 -m workspace_server` if the command
+is not on `PATH`. Keep stdin open while the server runs; EOF initiates shutdown.
+Model configuration comes from `~/.codex/config.toml`.
+
+## Conversations and views
+
+The session sidebar starts collapsed. Hover to preview it, click to keep it
+open, and click the toggle or empty space again to close it. Expansion narrows
+the conversation while keeping the board fixed. On phones, use the header
+buttons to switch between chat and board.
+
+Use the expanded sidebar to create, rename or close sessions. Status dots show
+running sessions and unread replies. `/cd <directory>` changes the current
+session's working directory while idle; `/model`, `/resume`, `/compact` and
+other core session commands are also available.
+
+Click Markdown links to open files and comparisons, for example
+`[source](app.py:42)` or `[changes](diff:HEAD:app.py)`. In a code or diff view,
+select text and choose **Insert into chat** to add editable context to the draft.
+Click a context block to edit or remove it before sending.
+See [view links and supported formats](../../docs/RUNTIME.md#workspace-content-views).
+
+When using a router, its directory groups workspaces by device and lists unread
+workspaces at the top. Device handles reorder the list; pencil buttons edit
+device names.
+
+The [VS Code extension](extensions/vscode/README.md) uses this backend and is
+distributed separately as a VSIX.
+
+## Customize the interface
+
+Click the gear button to start a customization conversation with the Agent.
+Custom files live in the server user's `~/.pycodex/frontend/`:
+
+- `custom.css` and `custom.js`: optional styles and an ES module, loaded automatically.
+- `workspace.html`: optional full-page override; otherwise the packaged page is used.
+- Other files: available at workspace-relative `frontend/<path>` URLs.
+
+Refresh to apply changes and keep the selected conversation. Open the workspace
+with `?builtin=1` to bypass all customizations; click “Re-enable customizations”
+to return. Changes apply to all workspaces for that OS user.
+See the [customization contract](../../docs/RUNTIME.md#frontend-customization).
+
+## Storage
+
+Paths in `workspaces.json` resolve from the configuration directory.
+`state_path` is a unique filename prefix: the example saves sessions in
+`demo.pycodex-ws.json`, file views in `demo.pycodex-views.json`, and Canvas in
+`demo.html`. Suffixes are appended to the complete prefix, including any dots.
+
+Set `enable_board` to `false` to disable Canvas while retaining conversations
+and file views. Session directories and history survive server restarts;
+changing a session's directory does not move Canvas or workspace state files.
+Configuration and restoration details are in the [runtime guide](../../docs/RUNTIME.md).
+
+## Feishu
+
+Install the optional SDK in the workspace's Python environment, then authorize:
+
+```bash
+python3 -m pip install lark-oapi
+python3 -m pycodex_ws.feishu_oauth
+```
+
+Authorization reads app credentials from `~/.codex/.env` and stores the refresh
+token in `~/.codex/.feishu_refresh_token`. In a workspace session, use
+`/link <feishu-email|open_id|chat_id>` to connect a card and `/unlink` to disconnect.
+Other workspace features work without the SDK.
+
+## Development
+
+From the repository root:
+
+```bash
+uv sync --dev
+uv run pycodex-ws --help
+uv run --dev pytest packages/pycodex-ws/tests
+uv build packages/pycodex-ws
+```
+
+Python integrations use `pycodex_ws.build_runtime(agent)` to include workspace
+commands. See [runtime contracts](../../docs/RUNTIME.md) and
+[test documentation](../../tests/TESTS.md).

pycodex_ws-0.5.0/README.md

@@ -0,0 +1,110 @@
+# pycodex-ws
+
+Browser conversations, a live HTML Canvas, read-only file/diff viewers and
+optional Feishu integration for
+[`python-codex`](https://pypi.org/project/python-codex/).
+Requires Python 3.7+ and installs the matching core version.
+
+## Quick start
+
+```bash
+python3 -m pip install pycodex-ws
+```
+
+Create `workspaces.json`:
+
+```json
+{
+  "workspaces": [
+    {"id": "demo", "work_dir": ".", "state_path": "demo", "enable_board": true}
+  ]
+}
+```
+
+```bash
+pycodex-ws --listen 127.0.0.1:6007 --workspace-config workspaces.json
+```
+
+Open `http://127.0.0.1:6007`. Use `python3 -m workspace_server` if the command
+is not on `PATH`. Keep stdin open while the server runs; EOF initiates shutdown.
+Model configuration comes from `~/.codex/config.toml`.
+
+## Conversations and views
+
+The session sidebar starts collapsed. Hover to preview it, click to keep it
+open, and click the toggle or empty space again to close it. Expansion narrows
+the conversation while keeping the board fixed. On phones, use the header
+buttons to switch between chat and board.
+
+Use the expanded sidebar to create, rename or close sessions. Status dots show
+running sessions and unread replies. `/cd <directory>` changes the current
+session's working directory while idle; `/model`, `/resume`, `/compact` and
+other core session commands are also available.
+
+Click Markdown links to open files and comparisons, for example
+`[source](app.py:42)` or `[changes](diff:HEAD:app.py)`. In a code or diff view,
+select text and choose **Insert into chat** to add editable context to the draft.
+Click a context block to edit or remove it before sending.
+See [view links and supported formats](../../docs/RUNTIME.md#workspace-content-views).
+
+When using a router, its directory groups workspaces by device and lists unread
+workspaces at the top. Device handles reorder the list; pencil buttons edit
+device names.
+
+The [VS Code extension](extensions/vscode/README.md) uses this backend and is
+distributed separately as a VSIX.
+
+## Customize the interface
+
+Click the gear button to start a customization conversation with the Agent.
+Custom files live in the server user's `~/.pycodex/frontend/`:
+
+- `custom.css` and `custom.js`: optional styles and an ES module, loaded automatically.
+- `workspace.html`: optional full-page override; otherwise the packaged page is used.
+- Other files: available at workspace-relative `frontend/<path>` URLs.
+
+Refresh to apply changes and keep the selected conversation. Open the workspace
+with `?builtin=1` to bypass all customizations; click “Re-enable customizations”
+to return. Changes apply to all workspaces for that OS user.
+See the [customization contract](../../docs/RUNTIME.md#frontend-customization).
+
+## Storage
+
+Paths in `workspaces.json` resolve from the configuration directory.
+`state_path` is a unique filename prefix: the example saves sessions in
+`demo.pycodex-ws.json`, file views in `demo.pycodex-views.json`, and Canvas in
+`demo.html`. Suffixes are appended to the complete prefix, including any dots.
+
+Set `enable_board` to `false` to disable Canvas while retaining conversations
+and file views. Session directories and history survive server restarts;
+changing a session's directory does not move Canvas or workspace state files.
+Configuration and restoration details are in the [runtime guide](../../docs/RUNTIME.md).
+
+## Feishu
+
+Install the optional SDK in the workspace's Python environment, then authorize:
+
+```bash
+python3 -m pip install lark-oapi
+python3 -m pycodex_ws.feishu_oauth
+```
+
+Authorization reads app credentials from `~/.codex/.env` and stores the refresh
+token in `~/.codex/.feishu_refresh_token`. In a workspace session, use
+`/link <feishu-email|open_id|chat_id>` to connect a card and `/unlink` to disconnect.
+Other workspace features work without the SDK.
+
+## Development
+
+From the repository root:
+
+```bash
+uv sync --dev
+uv run pycodex-ws --help
+uv run --dev pytest packages/pycodex-ws/tests
+uv build packages/pycodex-ws
+```
+
+Python integrations use `pycodex_ws.build_runtime(agent)` to include workspace
+commands. See [runtime contracts](../../docs/RUNTIME.md) and
+[test documentation](../../tests/TESTS.md).

{pycodex_ws-0.4.7 → pycodex_ws-0.5.0}/pycodex_router/browser.py

@@ -8,7 +8,7 @@ from starlette.exceptions import HTTPException
 from starlette.requests import HTTPConnection
 from starlette.responses import JSONResponse, RedirectResponse
 
-from .protocol import route_path
+from .protocol import agent_api_request, route_path
 
 
 def request_origin(connection):
@@ -77,6 +77,11 @@ class BrowserAccess:
                 raise HTTPException(
                     403, "Cross-origin router requests are not allowed."
                 )
+            device = (
+                self.router.authenticated_device(connection)
+                if agent_api_request(scope) else None
+            )
+            scope["pycodex.agent_access"] = device is not None
             await self.app(scope, receive, secured_send)
         except HTTPException as exc:
             if scope["type"] == "websocket":

{pycodex_ws-0.4.7 → pycodex_ws-0.5.0}/pycodex_router/client.py

@@ -7,7 +7,9 @@ from contextlib import asynccontextmanager
 from websockets.exceptions import ConnectionClosed, InvalidHandshake, InvalidStatusCode
 from websockets.legacy.client import connect
 
-from .protocol import decode, device_id, encode, parse_target, send_event, tunnel_url
+from .protocol import (
+    decode, device_id, encode, normalize_api_url, parse_target, send_event, tunnel_url,
+)
 
 
 class NodeIdInUse(Exception):
@@ -37,6 +39,7 @@ class RouterClient:
         self.refresh_seconds = refresh_seconds
         self.reconnect_seconds = reconnect_seconds
         self.connected = False
+        self.api_url = None
         self._task = None
         self._channels = set()
         self._requests = set()
@@ -89,6 +92,7 @@ class RouterClient:
                 failure = exc
             finally:
                 self.connected = False
+                self.api_url = None
 
             try:
                 await self._close_channels()
@@ -133,6 +137,8 @@ class RouterClient:
             raise NodeIdInUse("router node id is still registered")
         if reply.get("type") != "registered" or reply.get("id") != self.node_id:
             raise ValueError("unexpected router registration response")
+        api_url = reply.get("api_url")
+        self.api_url = normalize_api_url(api_url) if api_url is not None else None
 
     async def _session(self, channel):
         async def receive_requests():
@@ -187,6 +193,7 @@ class RouterClient:
                     scope = opening["scope"]
                     if scope["type"] not in {"http", "websocket"}:
                         raise ValueError("unsupported router request type")
+                    scope["pycodex.agent_access"] = opening.get("agent_access") is True
 
                     async def receive():
                         try:

{pycodex_ws-0.4.7 → pycodex_ws-0.5.0}/pycodex_router/index.html

@@ -19,6 +19,8 @@
       --danger: #b54739;
       --unread-bg: #fff7f4;
       --unread-line: #ead0c8;
+      --breathing-duration: 1.2s;
+      --breathing-ease: cubic-bezier(0.4, 0, 0.2, 1);
       font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
     }
     @media (prefers-color-scheme: dark) {
@@ -97,7 +99,7 @@
     .activity-badge[hidden] { display: none; }
     .workspace-group-name .device-working { margin-left: 8px; white-space: nowrap; }
     .activity-badge[data-state="working"] { color: var(--green); background: var(--green-soft); }
-    .activity-badge[data-state="working"]::before { content: ""; width: 5px; height: 5px; border-radius: 50%; background: currentColor; animation: spinner-pulse 1.2s cubic-bezier(0.4, 0, 0.2, 1) infinite; }
+    .activity-badge[data-state="working"]::before { content: ""; width: 5px; height: 5px; border-radius: 50%; background: currentColor; animation: spinner-pulse var(--breathing-duration) var(--breathing-ease) infinite; }
     @keyframes spinner-pulse {
       0%, 100% { opacity: .45; transform: scale(.82); }
       50% { opacity: 1; transform: scale(1.08); }
@@ -643,6 +645,14 @@
         document.getElementById("activity").textContent = running ? `${running} working` : "";
       }
 
+      document.addEventListener("animationstart", event => {
+        if (event.animationName !== "spinner-pulse") return;
+        // Include pseudo-elements and anchor new indicators to the page's breathing phase.
+        for (const animation of event.target.getAnimations({subtree: true})) {
+          if (animation.animationName === event.animationName) animation.startTime = 0;
+        }
+      });
+
       async function refresh() {
         if (refreshing) return;
         refreshing = true;

{pycodex_ws-0.4.7 → pycodex_ws-0.5.0}/pycodex_router/protocol.py

@@ -8,6 +8,29 @@ from http.cookies import SimpleCookie
 from urllib.parse import urlsplit, urlunsplit
 
 
+def normalize_api_url(value):
+    """A public HTTP base URL, without credentials or request parameters."""
+    try:
+        if not isinstance(value, str) or any(
+            char.isspace() or ord(char) < 32 or char in "\\?#" for char in value
+        ):
+            raise ValueError()
+        parsed = urlsplit(value)
+        if (
+            parsed.scheme not in {"http", "https"}
+            or not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+        ):
+            raise ValueError()
+        parsed.port
+    except ValueError:
+        raise ValueError(
+            "API URL must be an http(s) URL without credentials, query or fragment"
+        ) from None
+    return value.rstrip("/")
+
+
 def device_id(identity_key):
     if not isinstance(identity_key, str) or not re.fullmatch(
         "[0-9a-f]{64}", identity_key
@@ -23,6 +46,25 @@ def route_path(scope):
     return path[len(root) :] if root and path.startswith(root + "/") else path
 
 
+def agent_api_request(scope):
+    """The existing HTTP discovery, message and polling endpoints."""
+    if scope["type"] != "http":
+        return False
+    match = re.fullmatch(
+        r"(?:/n/[a-z2-7]{52})?(?:/w/[^/]+)?/api/(workspaces|sessions|session|session/message)",
+        route_path(scope),
+    )
+    return match is not None and scope["method"] == (
+        "POST" if match.group(1) == "session/message" else "GET"
+    )
+
+
+def trusted_agent_request(scope):
+    # This flag comes only from the private socket or an authenticated tunnel
+    # envelope, never from HTTP headers or the forwarded ASGI scope.
+    return scope.get("pycodex.agent_access") is True and agent_api_request(scope)
+
+
 def tunnel_url(target, endpoint):
     parsed = urlsplit(target if "://" in target else "ws://" + target)
     schemes = {"http": "ws", "https": "wss", "ws": "ws", "wss": "wss"}

{pycodex_ws-0.4.7 → pycodex_ws-0.5.0}/pycodex_router/server.py

@@ -30,9 +30,11 @@ from .protocol import (
     decode,
     device_id,
     encode,
+    normalize_api_url,
     request_scope,
     response_headers,
     send_event,
+    trusted_agent_request,
 )
 
 
@@ -154,7 +156,11 @@ class Router:
         max_connections=64,
         registration_key=None,
         aliases_path=None,
+        api_url=None,
+        api_port=None,
     ):
+        self.api_url = normalize_api_url(api_url) if api_url is not None else None
+        self.api_port = api_port
         self.registration_key = (
             _base58_encode(os.urandom(16))
             if registration_key is None
@@ -257,6 +263,18 @@ class Router:
         await websocket.accept()
         return True
 
+    def authenticated_device(self, connection):
+        if "origin" in connection.headers or "sec-fetch-site" in connection.headers:
+            return None
+        authorization = connection.headers.get("authorization", "")
+        if not authorization.startswith("Bearer "):
+            return None
+        try:
+            node_id = device_id(authorization[7:])
+        except ValueError:
+            return None
+        return self.nodes.get(node_id)
+
     async def control(self, websocket):
         if not await self.accept_tunnel(websocket):
             return
@@ -295,7 +313,17 @@ class Router:
                 aliases[node_id] = ""
                 self._save_aliases(aliases)
             self.nodes[node_id] = node
-            await websocket.send_text(encode({"type": "registered", "id": node_id}))
+            api_url = self.api_url
+            if api_url is None and self.api_port is not None:
+                host = websocket.url.hostname
+                if ":" in host:
+                    host = "[" + host + "]"
+                api_url = normalize_api_url(
+                    "http://{0}:{1}".format(host, self.api_port)
+                )
+            await websocket.send_text(encode({
+                "type": "registered", "id": node_id, "api_url": api_url,
+            }))
             while True:
                 message = await control_message(websocket)
                 if message.get("type") != "workspaces":
@@ -376,8 +404,12 @@ class Router:
     async def proxy(self, scope, receive, send):
         connection = HTTPConnection(scope)
         blocked = connection.client.host in self.blocked_ips
-        if blocked or not _auth_cookie_matches(
-            self.browser_token, connection.cookies.get("pycodex_router_auth")
+        agent_access = trusted_agent_request(scope)
+        if blocked or not (
+            agent_access
+            or _auth_cookie_matches(
+                self.browser_token, connection.cookies.get("pycodex_router_auth")
+            )
         ):
             await require_login(scope, receive, send)
             return
@@ -423,6 +455,7 @@ class Router:
                         {
                             "type": "open",
                             "scope": request_scope(scope),
+                            "agent_access": agent_access,
                         }
                     )
                 )
@@ -488,8 +521,12 @@ def create_app(
     max_connections=64,
     registration_key=None,
     aliases_path=None,
+    api_url=None,
+    api_port=None,
 ):
-    router = Router(connect_timeout, max_connections, registration_key, aliases_path)
+    router = Router(
+        connect_timeout, max_connections, registration_key, aliases_path, api_url, api_port
+    )
 
     async def index(request):
         return HTMLResponse(
@@ -568,6 +605,14 @@ def build_parser():
     parser.add_argument(
         "--tunnel-listen", default="0.0.0.0:6000", help="Device host:port."
     )
+    parser.add_argument(
+        "--api-url",
+        help=(
+            "Public browser/API base URL advertised to devices, including any proxy "
+            "path prefix. Defaults to the device connection hostname and browser "
+            "HTTP port; set this for HTTPS, reverse proxies or port forwarding."
+        ),
+    )
     parser.add_argument(
         "--password",
         required=True,
@@ -583,6 +628,11 @@ def main(argv=None):
     args = parser.parse_args(argv)
     if not args.password:
         parser.error("--password must not be empty")
+    if args.api_url is not None:
+        try:
+            args.api_url = normalize_api_url(args.api_url)
+        except ValueError as exc:
+            parser.error(str(exc))
     addresses = [parse_listen(args.listen), parse_listen(args.tunnel_listen)]
     if addresses[0][1] != 0 and addresses[0][1] == addresses[1][1]:
         parser.error("browser and device listeners must use different ports")
@@ -592,6 +642,7 @@ def main(argv=None):
         args.password,
         registration_key=load_registration_key(key_path),
         aliases_path=codex_home / "router-aliases.json",
+        api_url=args.api_url,
     )
     tunnel_app = create_tunnel_app(app.state.router)
     sockets = []
@@ -652,6 +703,7 @@ def main(argv=None):
                 config = listener
         if sockets[0].getsockname()[1] == sockets[1].getsockname()[1]:
             raise ValueError("browser and device listeners must use different ports")
+        app.state.router.api_port = sockets[0].getsockname()[1]
         RouterServer(config).run(sockets=sockets)
     finally:
         for listener_socket in sockets:

{pycodex_ws-0.4.7 → pycodex_ws-0.5.0}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycodex-ws"
-version = "0.4.7"
+version = "0.5.0"
 description = "Browser workspace and optional Feishu integration for python-codex"
 readme = "README.md"
 requires-python = ">=3.7"
 dependencies = [
-    "python-codex==0.4.7",
+    "python-codex==0.5.0",
     "pillow>=9.0.0",
     "websockets>=11,<16",
 ]

pycodex_ws-0.5.0/workspace_server/agent_access.py

@@ -0,0 +1,66 @@
+"""Same-user HTTP access to existing local and registered-device APIs."""
+
+from urllib.parse import unquote, urlsplit, urlunsplit
+
+import requests
+from starlette.concurrency import run_in_threadpool
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from pycodex_router.protocol import agent_api_request
+
+
+class AgentSocketAccess:
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        socket_path = getattr(self.app.state, "agent_socket_path", None)
+        # Uvicorn gets this address from the socket, independently of HTTP headers.
+        if (
+            scope["type"] != "http" or socket_path is None
+            or scope["server"] not in (None, (socket_path, None))
+        ):
+            await self.app(scope, receive, send)
+            return
+        scope = dict(scope)
+        scope["pycodex.agent_access"] = True
+        if not scope["path"].startswith("/router/"):
+            await self.app(scope, receive, send)
+            return
+        client = getattr(self.app.state, "router_client", None)
+        if client is None or not client.connected or client.api_url is None:
+            await JSONResponse({"error": "router API is unavailable"}, 503)(scope, receive, send)
+            return
+        remote = urlsplit(client.api_url)
+        scope["path"] = scope["path"][len("/router"):]
+        scope["root_path"] = unquote(remote.path)
+        if not scope["path"].startswith(scope["root_path"] + "/") or not agent_api_request(scope):
+            await JSONResponse({"error": "not a session API"}, 403)(scope, receive, send)
+            return
+        url = urlunsplit((
+            remote.scheme, remote.netloc,
+            scope["raw_path"][len(b"/router"):].decode("ascii"),
+            scope["query_string"].decode("ascii"), "",
+        ))
+        body = await Request(scope, receive).body()
+
+        def forward():
+            with requests.Session() as session:
+                session.trust_env = False
+                result = session.request(
+                    scope["method"], url, data=body,
+                    headers={"Authorization": "Bearer " + client._identity_key,
+                             "Content-Type": "application/json"},
+                    allow_redirects=False, timeout=(10, 30),
+                )
+                return Response(
+                    result.content, result.status_code,
+                    media_type=result.headers.get("content-type", "application/json"),
+                )
+
+        try:
+            response = await run_in_threadpool(forward)
+        except requests.RequestException:
+            response = JSONResponse({"error": "router API is unavailable"}, 503)
+        await response(scope, receive, send)