pycodex-ws 0.5.1__tar.gz → 0.6.0__tar.gz

{pycodex_ws-0.5.1 → pycodex_ws-0.6.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.1
 Name: pycodex-ws
-Version: 0.5.1
+Version: 0.6.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.1
+Requires-Dist: python-codex==0.6.0
 Requires-Dist: websockets<16,>=11
 Description-Content-Type: text/markdown
 
@@ -16,6 +16,9 @@ optional Feishu integration for
 [`python-codex`](https://pypi.org/project/python-codex/).
 Requires Python 3.7+ and installs the matching core version.
 
+See the [0.6.0 release notes](https://github.com/Randomizez/pycodex/blob/v0.6.0/docs/RELEASE_0.6.0.md) for changes and
+integration migration from 0.5.0.
+
 ## Quick start
 
 ```bash
@@ -52,6 +55,12 @@ 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.
 
+Consecutive model reconnection diagnostics share one collapsed `Model retries`
+row per sequence. The summary shows the number of recorded retries, the latest
+attempt and its HTTP status when available. Expand it to read the original errors
+in a scrollable log. New retries update the same row and preserve its open state;
+refreshing starts collapsed. Other model diagnostics and final errors stay visible.
+
 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.
@@ -62,12 +71,22 @@ 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 runtime information shared between Agents recommends plain messages, which
+steer active work at the next safe boundary. Use `/queue` explicitly for an
+independent follow-up task that should wait for current work to finish.
+
+The message API also accepts a string `name`, defaulting to `"user"`, for
+identifying the source of a user message. The history API returns it, and
+recorded sessions preserve it across resume. It is metadata only: the model request and frontend display do
+not include it. See the [message API contract](workspace_server/WORKSPACE_API.md#commands-and-results).
+
 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.
+Click the gear button and choose **Frontend customization** 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.
@@ -78,6 +97,43 @@ 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).
+For custom interfaces, the [resource API](../../docs/WORKSPACE_API.md) exposes
+state, model catalogs, asynchronous command results, paginated history, event
+replay and sub-agent/background-work inventories. A `mount(host)` export in
+`custom.js` can access the built-in page's session, draft and view controls.
+
+Backend module ownership and the preserved session interfaces are documented in
+the [runtime guide](../../docs/RUNTIME.md#workspace-session-api).
+File/Git source resolution and view storage retain their existing public classes;
+see [content views](../../docs/RUNTIME.md#workspace-content-views).
+
+Ask the Agent to show the [feature catalog](workspace_server/optional_features/README.md)
+in the view area, then choose features by name or ID in chat. The Agent adapts
+their source into your frontend. To share a local change, ask it to publish a
+feature PR on GitHub; the [contribution guide](workspace_server/optional_features/CONTRIBUTING.md)
+specifies the source, documentation, validation and PR format.
+
+## Share a workspace
+
+Start the workspace server with an administrator password (`--password`), then
+choose **Settings → Share** in a workspace. Set a different share password and
+send the displayed workspace link and password to the recipient.
+
+The existing login page accepts either the administrator password or the share
+password for the workspace being opened. Visitors can use all its conversations,
+Canvas, files, APIs and WebSocket connections, but cannot access workspace
+management, another workspace or sharing settings. The settings button and
+management navigation are hidden for visitors.
+
+Passwords, verification values and visitor tokens are kept only in process
+memory. Changing the password or stopping sharing invalidates existing visitor
+logins and disconnects their WebSockets. Restarting the process clears all
+shares. Already accepted Agent work continues.
+
+This restricts web access; Agent tools retain their existing file and execution
+permissions. An unprotected server must configure its administrator password
+before enabling sharing. Router authentication is unchanged: a link through a
+router still requires its normal login.
 
 ## Storage
 
@@ -105,6 +161,11 @@ 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.
 
+The adapter separates card rendering, refresh-token storage and SDK connections.
+`PycodexCard` and `PycodexRuntimeLink` keep their existing imports and interfaces;
+see [connection lifecycle](../../docs/RUNTIME.md#feishu-connection-lifecycle)
+and [event presentation](../../docs/RUNTIME.md#observation).
+
 ## Development
 
 From the repository root:
@@ -116,6 +177,9 @@ 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
+Python integrations construct a runtime through `AgentsManager.create_root_runtime()`
+and call `pycodex_ws.register_feishu_commands(runtime)` to include `/link` and
+`/unlink`. The context indicator shows tokens against the auto-compaction limit;
+its expandable Agent tree shows each task's status and latest assistant text.
+See [runtime contracts](../../docs/RUNTIME.md) and
 [test documentation](../../tests/TESTS.md).

pycodex_ws-0.6.0/README.md

@@ -0,0 +1,174 @@
+# 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.
+
+See the [0.6.0 release notes](https://github.com/Randomizez/pycodex/blob/v0.6.0/docs/RELEASE_0.6.0.md) for changes and
+integration migration from 0.5.0.
+
+## 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.
+
+Consecutive model reconnection diagnostics share one collapsed `Model retries`
+row per sequence. The summary shows the number of recorded retries, the latest
+attempt and its HTTP status when available. Expand it to read the original errors
+in a scrollable log. New retries update the same row and preserve its open state;
+refreshing starts collapsed. Other model diagnostics and final errors stay visible.
+
+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 runtime information shared between Agents recommends plain messages, which
+steer active work at the next safe boundary. Use `/queue` explicitly for an
+independent follow-up task that should wait for current work to finish.
+
+The message API also accepts a string `name`, defaulting to `"user"`, for
+identifying the source of a user message. The history API returns it, and
+recorded sessions preserve it across resume. It is metadata only: the model request and frontend display do
+not include it. See the [message API contract](workspace_server/WORKSPACE_API.md#commands-and-results).
+
+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 and choose **Frontend customization** 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).
+For custom interfaces, the [resource API](../../docs/WORKSPACE_API.md) exposes
+state, model catalogs, asynchronous command results, paginated history, event
+replay and sub-agent/background-work inventories. A `mount(host)` export in
+`custom.js` can access the built-in page's session, draft and view controls.
+
+Backend module ownership and the preserved session interfaces are documented in
+the [runtime guide](../../docs/RUNTIME.md#workspace-session-api).
+File/Git source resolution and view storage retain their existing public classes;
+see [content views](../../docs/RUNTIME.md#workspace-content-views).
+
+Ask the Agent to show the [feature catalog](workspace_server/optional_features/README.md)
+in the view area, then choose features by name or ID in chat. The Agent adapts
+their source into your frontend. To share a local change, ask it to publish a
+feature PR on GitHub; the [contribution guide](workspace_server/optional_features/CONTRIBUTING.md)
+specifies the source, documentation, validation and PR format.
+
+## Share a workspace
+
+Start the workspace server with an administrator password (`--password`), then
+choose **Settings → Share** in a workspace. Set a different share password and
+send the displayed workspace link and password to the recipient.
+
+The existing login page accepts either the administrator password or the share
+password for the workspace being opened. Visitors can use all its conversations,
+Canvas, files, APIs and WebSocket connections, but cannot access workspace
+management, another workspace or sharing settings. The settings button and
+management navigation are hidden for visitors.
+
+Passwords, verification values and visitor tokens are kept only in process
+memory. Changing the password or stopping sharing invalidates existing visitor
+logins and disconnects their WebSockets. Restarting the process clears all
+shares. Already accepted Agent work continues.
+
+This restricts web access; Agent tools retain their existing file and execution
+permissions. An unprotected server must configure its administrator password
+before enabling sharing. Router authentication is unchanged: a link through a
+router still requires its normal login.
+
+## 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.
+
+The adapter separates card rendering, refresh-token storage and SDK connections.
+`PycodexCard` and `PycodexRuntimeLink` keep their existing imports and interfaces;
+see [connection lifecycle](../../docs/RUNTIME.md#feishu-connection-lifecycle)
+and [event presentation](../../docs/RUNTIME.md#observation).
+
+## 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 construct a runtime through `AgentsManager.create_root_runtime()`
+and call `pycodex_ws.register_feishu_commands(runtime)` to include `/link` and
+`/unlink`. The context indicator shows tokens against the auto-compaction limit;
+its expandable Agent tree shows each task's status and latest assistant text.
+See [runtime contracts](../../docs/RUNTIME.md) and
+[test documentation](../../tests/TESTS.md).

{pycodex_ws-0.5.1 → pycodex_ws-0.6.0}/pycodex_router/server.py

@@ -15,15 +15,15 @@ from starlette.requests import HTTPConnection
 from starlette.responses import HTMLResponse, JSONResponse
 from starlette.routing import Mount, Route, WebSocketRoute
 from starlette.websockets import WebSocketDisconnect, WebSocketState
-from pycodex.portable.client import _base58_encode
+from pycodex.portable.protocol import base58_encode
 from pycodex.utils.session_persist import resolve_codex_home
-from workspace_server.app import (
-    _auth_cookie_matches,
-    _install_auth,
-    _json_object_body,
+from pycodex_ws.server_support import (
+    auth_cookie_matches,
+    install_auth,
+    json_object_body,
     parse_listen,
 )
-from workspace_server.workspaces import normalize_workspace_id
+from pycodex_ws.workspace_config import normalize_workspace_id
 
 from .browser import BrowserAccess, require_login
 from .protocol import (
@@ -52,7 +52,7 @@ def load_registration_key(path):
     except FileExistsError:
         value = path.read_bytes().strip()
     else:
-        value = _base58_encode(os.urandom(16)).encode("ascii")
+        value = base58_encode(os.urandom(16)).encode("ascii")
         with os.fdopen(descriptor, "wb") as handle:
             handle.write(value + b"\n")
     if not re.fullmatch(b"[1-9A-HJ-NP-Za-km-z]{1,22}", value):
@@ -162,7 +162,7 @@ class Router:
         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))
+            base58_encode(os.urandom(16))
             if registration_key is None
             else registration_key
         )
@@ -208,11 +208,11 @@ class Router:
         self.aliases = aliases
 
     async def reorder_devices(self, request):
-        if not self.browser_token or not _auth_cookie_matches(
+        if not self.browser_token or not auth_cookie_matches(
             self.browser_token, request.cookies.get("pycodex_router_auth")
         ):
             raise HTTPException(401, "Authentication required.")
-        payload = await _json_object_body(request, max_bytes=64 * 1024)
+        payload = await json_object_body(request, max_bytes=64 * 1024)
         order = payload.get("order")
         if (
             not isinstance(order, list)
@@ -235,14 +235,14 @@ class Router:
         return JSONResponse({"order": order})
 
     async def rename_device(self, request):
-        if not self.browser_token or not _auth_cookie_matches(
+        if not self.browser_token or not auth_cookie_matches(
             self.browser_token, request.cookies.get("pycodex_router_auth")
         ):
             raise HTTPException(401, "Authentication required.")
         node_id = request.path_params["node_id"]
         if node_id not in self.nodes:
             raise HTTPException(404, "Device is not connected.")
-        payload = await _json_object_body(request)
+        payload = await json_object_body(request)
         try:
             alias = normalize_alias(payload.get("alias"))
         except ValueError as exc:
@@ -407,7 +407,7 @@ class Router:
         agent_access = trusted_agent_request(scope)
         if blocked or not (
             agent_access
-            or _auth_cookie_matches(
+            or auth_cookie_matches(
                 self.browser_token, connection.cookies.get("pycodex_router_auth")
             )
         ):
@@ -535,7 +535,7 @@ def create_app(
         )
 
     async def registration_key_info(request):
-        if not router.browser_token or not _auth_cookie_matches(
+        if not router.browser_token or not auth_cookie_matches(
             router.browser_token, request.cookies.get("pycodex_router_auth")
         ):
             return JSONResponse({"error": "authentication required"}, status_code=401)
@@ -553,7 +553,7 @@ def create_app(
             Route("/api/nodes/{node_id}/alias", router.rename_device, methods=["POST"]),
         ]
     )
-    router.browser_token = _install_auth(
+    router.browser_token = install_auth(
         web,
         password,
         cookie_name="pycodex_router_auth",

{pycodex_ws-0.5.1 → pycodex_ws-0.6.0}/pycodex_ws/__init__.py

@@ -2,11 +2,9 @@
 
 from importlib import import_module
 
-from pycodex.bootstrap import build_runtime as build_core_runtime
 
-
-def build_runtime(agent):
-    runtime = build_core_runtime(agent)
+def register_feishu_commands(runtime):
+    """Attach Feishu commands and connection cleanup to an existing runtime."""
     link = None
 
     async def unlink(argument):
@@ -52,4 +50,3 @@ def build_runtime(agent):
     runtime.register_command("link", connect)
     runtime.register_command("unlink", unlink)
     runtime.add_close_handler(close_link)
-    return runtime

pycodex_ws-0.6.0/pycodex_ws/feishu_auth.py

@@ -0,0 +1,30 @@
+"""Shared Feishu endpoints and refresh-token storage."""
+
+import os
+import typing
+from pathlib import Path
+
+FEISHU_API_BASE = "https://open.feishu.cn/open-apis"
+FEISHU_DOMAIN = "https://open.feishu.cn"
+FEISHU_REFRESH_TOKEN_FILE = "~/.codex/.feishu_refresh_token"
+
+
+def refresh_token_path() -> Path:
+    return Path(FEISHU_REFRESH_TOKEN_FILE).expanduser()
+
+
+def read_refresh_token() -> "typing.Union[str, None]":
+    path = refresh_token_path()
+    if not path.exists():
+        return None
+    value = path.read_text(encoding="utf-8", errors="replace").strip()
+    return value or None
+
+
+def write_refresh_token(value: str) -> None:
+    path = refresh_token_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+        path.chmod(0o600)
+        stream.write("{0}\n".format(value))