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

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.1
 Name: pycodex-ws
-Version: 0.5.2
+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.2
+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
@@ -68,6 +71,15 @@ 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.
 
@@ -90,6 +102,11 @@ 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
@@ -144,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:
@@ -155,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.5.2 → pycodex_ws-0.6.0}/README.md

@@ -5,6 +5,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
@@ -57,6 +60,15 @@ 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.
 
@@ -79,6 +91,11 @@ 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
@@ -133,6 +150,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:
@@ -144,6 +166,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.5.2 → 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.2 → 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))

{pycodex_ws-0.5.2 → pycodex_ws-0.6.0}/pycodex_ws/feishu_card.py

@@ -2,7 +2,6 @@ import json
 import os
 import time
 import typing
-from pathlib import Path
 
 import requests
 
@@ -22,12 +21,21 @@ from pycodex.events import (
 )
 from pycodex.utils.event_helpers import completed_history
 
-FEISHU_API_BASE = "https://open.feishu.cn/open-apis"
-FEISHU_DOMAIN = "https://open.feishu.cn"
-FEISHU_REFRESH_TOKEN_FILE = "~/.codex/.feishu_refresh_token"
-CARD_OUTPUT_LIMIT = 6500
-CARD_OUTPUT_MODE_MARKDOWN = "markdown"
-CARD_OUTPUT_MODE_CODE = "code"
+from .feishu_auth import (
+    FEISHU_API_BASE,
+    FEISHU_DOMAIN,
+    FEISHU_REFRESH_TOKEN_FILE,
+    read_refresh_token as _read_refresh_token,
+    refresh_token_path as _refresh_token_path,
+    write_refresh_token as _write_refresh_token,
+)
+from .feishu_render import (
+    CARD_OUTPUT_LIMIT,
+    CARD_OUTPUT_MODE_CODE,
+    CARD_OUTPUT_MODE_MARKDOWN,
+    render_card,
+)
+
 CARD_CONTENT_ERROR_MARKER = "Failed to create card content"
 
 
@@ -240,97 +248,7 @@ class PycodexCard:
     def render(
         self, output_mode: str = CARD_OUTPUT_MODE_MARKDOWN
     ) -> "typing.Dict[str, object]":
-        status = "Closed" if self.display.closed else self.status
-        input_disabled = not self.accepts_input or self.detached or self.display.closed
-        output = _truncate(self.output_text, CARD_OUTPUT_LIMIT) or "Ready."
-        working_output = _truncate(self.working_output, CARD_OUTPUT_LIMIT)
-        color = _status_color("Detached" if self.detached else status or "Idle")
-        body_elements = [
-            _output_box(
-                "answer_box",
-                "answer_md",
-                _render_output_content(output, output_mode),
-                "grey-50",
-            ),
-        ]
-        if working_output:
-            body_elements.append(
-                _output_box(
-                    "working_output_box",
-                    "working_output_md",
-                    _render_output_content(working_output, output_mode),
-                    "green-50",
-                )
-            )
-        if self.activity_text:
-            body_elements.append(
-                {
-                    "tag": "markdown",
-                    "element_id": "activity_md",
-                    "content": _render_output_content(
-                        _truncate(self.activity_text, CARD_OUTPUT_LIMIT), output_mode
-                    ),
-                }
-            )
-        if self.user_prompt:
-            body_elements.insert(
-                0,
-                {
-                    "tag": "markdown",
-                    "element_id": "user_prompt_md",
-                    "content": _render_output_content(
-                        "user> " + _truncate(self.user_prompt, CARD_OUTPUT_LIMIT),
-                        output_mode,
-                    ),
-                },
-            )
-        history = self.earlier_turns()
-        if history:
-            index = (
-                len(history) - 1 if self.history_index is None else self.history_index
-            )
-            body_elements.insert(
-                0,
-                _history_panel(
-                    history,
-                    index,
-                    self.history_index is not None,
-                    output_mode,
-                    not self.detached,
-                ),
-            )
-        card = {
-            "schema": "2.0",
-            "config": {"update_multi": True},
-            "header": {
-                "title": {
-                    "tag": "plain_text",
-                    "content": self.display.title or "pycodex",
-                },
-                "template": color,
-            },
-            "body": {
-                "elements": body_elements,
-            },
-        }
-        if not self.detached:
-            card["body"]["elements"].append(
-                {
-                    "tag": "input",
-                    "element_id": "prompt_input",
-                    "name": "prompt",
-                    "input_type": "text",
-                    "width": "fill",
-                    "disabled": input_disabled,
-                    "placeholder": {
-                        "tag": "plain_text",
-                        "content": self.prompt_text + (status or self.model_name),
-                    },
-                    "behaviors": [{"type": "callback", "value": {"action": "send"}}],
-                    "value": {"action": "send"},
-                },
-            )
-        return card
+        return render_card(self, output_mode)
 
     def earlier_turns(self):
         if self._active_turn_id is not None:
@@ -389,9 +307,7 @@ class PycodexCard:
         aliases = _user_id_aliases()
         if normalized in aliases:
             return aliases[normalized]
-        if normalized.startswith("ou_"):
-            return normalized
-        if normalized.startswith("oc_"):
+        if normalized.startswith(("ou_", "oc_")):
             return normalized
         if normalized.isnumeric():
             return self._lookup_user({"mobiles": [normalized]})
@@ -477,7 +393,7 @@ class PycodexCard:
                 use_user_token=use_user_token,
             )
         except Exception as exc:
-            if not _is_card_content_error(exc):
+            if CARD_CONTENT_ERROR_MARKER not in str(exc):
                 raise
             return self._request(
                 method,
@@ -616,126 +532,6 @@ def _display_user_name(user: "typing.Any") -> "typing.Union[str, None]":
     return None
 
 
-def _status_color(status: str) -> str:
-    normalized = status.lower()
-    if normalized in {"detached", "closed"}:
-        return "grey"
-    if normalized in {"idle", "idle: sleeping"}:
-        return "green"
-    return "blue"
-
-
-def _truncate(text: str, limit: int) -> str:
-    value = str(text or "")
-    if len(value) <= limit:
-        return value
-    return value[: max(0, limit - 32)] + "\n...[truncated]"
-
-
-def _escape_code_block(text: str) -> str:
-    return str(text or "").replace("```", "'''")
-
-
-def _render_output_content(output: str, output_mode: str) -> str:
-    if output_mode == CARD_OUTPUT_MODE_CODE:
-        return "```text\n{0}\n```".format(_escape_code_block(output))
-    return output
-
-
-def _history_panel(history, index, expanded, output_mode, interactive):
-    prompt, response = history[index]
-    content = _truncate(
-        "user> {0}\n\nassistant> {1}".format(prompt, response), CARD_OUTPUT_LIMIT
-    )
-    columns = []
-    for label, target, disabled in (
-        ("Previous", index - 1, index == 0),
-        ("Next", index + 1, index == len(history) - 1),
-    ):
-        columns.append(
-            {
-                "tag": "column",
-                "width": "auto",
-                "elements": [
-                    {
-                        "tag": "button",
-                        "text": {"tag": "plain_text", "content": label},
-                        "type": "default",
-                        "disabled": disabled or not interactive,
-                        "behaviors": [
-                            {
-                                "type": "callback",
-                                "value": {
-                                    "action": "history",
-                                    "history_index": target,
-                                },
-                            }
-                        ],
-                    }
-                ],
-            }
-        )
-    return {
-        "tag": "collapsible_panel",
-        "element_id": "history_panel",
-        "expanded": expanded,
-        "header": {
-            "icon": {
-                "tag": "standard_icon",
-                "token": "down-small-ccm_outlined",
-                "size": "16px 16px",
-            },
-            "title": {
-                "tag": "plain_text",
-                "content": "History · {0} / {1}".format(index + 1, len(history)),
-            },
-        },
-        "elements": [
-            {
-                "tag": "markdown",
-                "element_id": "history_md",
-                "content": _render_output_content(content, output_mode),
-            },
-            {"tag": "column_set", "columns": columns},
-        ],
-    }
-
-
-def _output_box(
-    box_id: str,
-    markdown_id: str,
-    content: str,
-    background_style: str,
-) -> "typing.Dict[str, object]":
-    return {
-        "tag": "column_set",
-        "element_id": box_id,
-        "background_style": background_style,
-        "horizontal_spacing": "8px",
-        "horizontal_align": "left",
-        "columns": [
-            {
-                "tag": "column",
-                "width": "auto",
-                "elements": [
-                    {
-                        "tag": "markdown",
-                        "element_id": markdown_id,
-                        "content": content,
-                    },
-                ],
-                "vertical_spacing": "8px",
-                "horizontal_align": "left",
-                "vertical_align": "top",
-            }
-        ],
-    }
-
-
-def _is_card_content_error(exc: "BaseException") -> bool:
-    return CARD_CONTENT_ERROR_MARKER in str(exc)
-
-
 def _dig(value: "typing.Any", *path: str) -> "typing.Any":
     current = value
     for key in path:
@@ -753,27 +549,6 @@ def _env(*names: str) -> "typing.Union[str, None]":
     return None
 
 
-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))
-
-
 def _api_base_to_domain(api_base: str) -> str:
     base = str(api_base or FEISHU_API_BASE).rstrip("/")
     marker = "/open-apis"