python-codex 0.3.3__tar.gz → 0.4.0__tar.gz

python_codex-0.3.3/README.md → python_codex-0.4.0/PKG-INFO

@@ -1,7 +1,29 @@
+Metadata-Version: 2.1
+Name: python-codex
+Version: 0.4.0
+Summary: A minimal Python extraction of Codex's main agent loop
+License-File: LICENSE
+Requires-Python: >=3.6.2
+Requires-Dist: dataclasses>=0.8; python_version < '3.7'
+Requires-Dist: importlib-metadata>=4.8.3; python_version < '3.8'
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: prompt-toolkit>=3.0.36
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.27.1
+Requires-Dist: starlette<0.20,>=0.19.1; python_version < '3.7'
+Requires-Dist: starlette>=0.19.1; python_version >= '3.7'
+Requires-Dist: tomli<2,>=1.2.3; python_version < '3.11'
+Requires-Dist: typing-extensions>=4.1.1; python_version < '3.8'
+Requires-Dist: uvicorn<0.17,>=0.16.0; python_version < '3.7'
+Requires-Dist: uvicorn>=0.16.0; python_version >= '3.7'
+Description-Content-Type: text/markdown
+
 # pycodex
 
 English README. Chinese version: `README_ZH.md`
 
+0.4.0 core/workspace package split and dependency cleanup: [release notes](docs/RELEASE_0.4.0.md).
+
 0.3.3 workspace viewers and reasoning stream fix: [release notes](docs/RELEASE_0.3.3.md).
 
 0.3.2 startup fixes: [release notes](docs/RELEASE_0.3.2.md).
@@ -10,15 +32,33 @@ English README. Chinese version: `README_ZH.md`
 
 PyPI distributions:
 
-- Primary package: `python-codex`
-- Workspace install alias: `pycodex-ws`
+- Core package: `python-codex`
+- Workspace and integrations: `pycodex-ws`
 
 The import path remains `pycodex`; the CLI commands are `pycodex` and
 `pycodex-ws`.
 
-`pycodex-ws` is a thin metapackage that depends on the exact matching
-`python-codex` version. The implementation and console script remain owned by
-`python-codex`, so the two distributions never install duplicate modules.
+`python-codex` contains the Agent, runtime, CLI, standard tools, Responses
+compatibility server and portable storage support. `pycodex-ws` depends on the
+exact matching core version and contains the browser workspace, viewer assets,
+Feishu and IPython integrations, including their dependencies. It owns the
+`workspace_server` and `pycodex_ws` modules and the `pycodex-ws` command.
+
+Core does not require Pillow. Without it, `view_image` sends the original image
+bytes with `detail="original"`, including when `high` is requested. With Pillow
+installed, the default path retains resizing to a maximum dimension of 2048.
+`pycodex-ws` installs Pillow for image preview validation.
+
+Portable encryption uses a bundled pure Python AES-GCM subset of pyaes and
+tlslite-ng, under MIT and BSD licenses. Core does not require a crypto package
+or compiler and ships a `py3-none-any` wheel. Existing `PCX1` bundles and call
+tokens remain compatible; large bundles take longer to encrypt and decrypt.
+See the [source notes](pycodex/utils/_aes_gcm/README.md).
+
+The Responses compatibility server and workspace HTTP server use Starlette
+and Uvicorn directly. Neither package requires FastAPI, Pydantic or
+`pydantic-core`. Python 3.6 uses Starlette 0.19.x; newer interpreters resolve
+a compatible Starlette release through its Python version metadata.
 
 This repository extracts the core Codex agent loop from upstream Codex
 (`https://github.com/openai/codex`) into a deliberately small Python version,
@@ -38,16 +78,17 @@ Relevant Rust reference points:
 
 ## Quick Start
 
-Install the full package or the workspace-oriented alias:
+Install the core CLI, or install the workspace package to include all integrations:
 
 ```bash
 python3 -m pip install python-codex
 python3 -m pip install pycodex-ws
 ```
 
-Use Python 3.6.2 or newer. Both console commands are installed into that
-interpreter's scripts directory. On a machine with multiple Python installations,
-you can select the same interpreter explicitly for startup:
+The core supports Python 3.6.2 or newer. The workspace package requires Python
+3.7 or newer because of its Feishu SDK dependency. Commands are installed into
+that interpreter's scripts directory. On a machine with multiple Python
+installations, select the same interpreter explicitly for startup:
 
 ```bash
 python3 -m pycodex
@@ -58,10 +99,14 @@ If `pycodex` is missing from `PATH` or resolves to an older installation, use th
 module entry points. `python3 -m pip --version` shows which Python environment
 received the installation.
 
+For an existing Web installation, use `python3 -m pip install --upgrade pycodex-ws`
+to upgrade the workspace and its matching core together. Installing only
+`python-codex` provides the CLI and core API.
+
 For development from this repository, install dependencies first:
 
 ```bash
-uv sync
+uv sync --dev
 ```
 
 Try the real entry points:
@@ -71,8 +116,22 @@ uv run pycodex "Reply with exactly OK."
 uv run pycodex
 ```
 
-A VS Code frontend is available in [`extensions/vscode`](extensions/vscode/README.md).
-It reuses an existing `python-codex>=0.3.1` installation. On first use, missing
+Tests are split by package. `uv run --dev pytest` runs both suites;
+`uv run --dev pytest packages/pycodex-ws/tests` runs workspace and integration
+tests. To check core without installing workspace or its SDKs, use a separate
+environment:
+
+```bash
+UV_PROJECT_ENVIRONMENT=.tmp/core-tests uv sync --group test
+UV_PROJECT_ENVIRONMENT=.tmp/core-tests uv run --group test pytest tests
+```
+
+See [test environments and coverage](tests/TESTS.md). Core tests support Python
+3.6.2+; workspace tests require Python 3.7+.
+
+A VS Code frontend is available in [`packages/pycodex-ws/extensions/vscode`](packages/pycodex-ws/extensions/vscode/README.md).
+It belongs to the workspace frontend and is packaged separately as a VSIX.
+It reuses an existing `pycodex-ws>=0.4.0` installation. On first use, missing
 or older backends are installed/upgraded with pip in the selected Python
 environment on the workspace host; compatible versions need no network check.
 It starts a dedicated `pycodex-ws` workspace on the project's host and opens a
@@ -120,19 +179,35 @@ nailing the core tool-augmented reasoning loop first.
 
 ## Layout
 
+The top level of `pycodex/` contains the core components and package entry points.
+Supporting services live in `tools/`, `portable/` and `utils/`.
+
+- `pycodex/agent.py`: inner turn loop
+- `pycodex/runtime.py`: session commands, submission queues and frontend event subscriptions
+- `pycodex/model.py`: model client protocol and Responses API adapter
+- `pycodex/context.py`: configuration, prompt assembly and instruction loading
 - `pycodex/protocol.py`: minimal conversation item / prompt protocol
 - `pycodex/events.py`: typed events, plain-text views and stateful presentation
-- `pycodex/utils/event_helpers.py`: stateless text, color, summary and result-formatting helpers
-- `pycodex/utils/image_utils.py`: image loading, resizing and data-URL preparation
-- `pycodex/model.py`: model client protocol and Responses API adapter
-- `pycodex/cli.py`: single-turn/interactive entry points, terminal I/O executor and input loop
 - `pycodex/bootstrap.py`: frontend-independent model, tools, Agent and session assembly
+- `pycodex/cli.py`: single-turn/interactive entry points, terminal I/O executor and input loop
 - `pycodex/tools/base_tool.py`: `BaseTool`, `ToolRegistry`, `ToolContext`
-- `pycodex/tools/`: concrete tool implementations
-- `pycodex/agent.py`: inner turn loop
-- `pycodex/runtime.py`: session commands, submission queues and frontend event subscriptions
-- `extensions/vscode/`: VS Code chat frontend using the workspace HTTP API
-- `tests/test_agent.py`: core behavior tests
+- `pycodex/tools/runtime_services.py`: plan, sub-agent, user-input and permissions services
+- `pycodex/tools/`: concrete tools and their execution managers
+- `pycodex/portable/`: Codex home storage client and server, both included in core
+- `pycodex/utils/compat.py`: supported-Python compatibility helpers
+- `pycodex/utils/doctor.py`: configuration and connectivity diagnostics
+- `pycodex/utils/model_metadata.py`: vendored model metadata lookup
+- `pycodex/utils/debug.py`: debug paths and the `pycodex.debug()` implementation
+- `pycodex/utils/event_helpers.py`: stateless text, color, summary and result-formatting helpers
+- `pycodex/utils/image_utils.py`: image loading, resizing and data-URL preparation
+- `pycodex/prompts/`: vendored prompts and model metadata
+- `packages/pycodex-ws/workspace_server/`: Web board, API and file/diff viewers
+- `packages/pycodex-ws/pycodex_ws/`: Feishu, IPython and workspace assembly
+- `packages/pycodex-ws/extensions/vscode/`: workspace's VS Code frontend, built separately as a VSIX
+- `tests/`: core tests
+- `packages/pycodex-ws/tests/`: workspace and cross-frontend integration tests
+
+See [package layout and import paths](docs/RUNTIME.md#package-layout).
 
 ## Current Alignment Status
 
@@ -243,7 +318,7 @@ Current behavior:
 - with an argv prompt or piped stdin, run a single turn
 - `pycodex-ws` starts the standalone browser workspace manager and serves each
   workspace with a board pane and a pycodex session pane
-- the left pane is the board, containing a live HTML Canvas tab and closable read-only file/diff tabs that
+- the left pane is the board, containing an optional live HTML Canvas tab and closable read-only file/diff tabs that
   scroll together in one toolbar; a mouse wheel scrolls overflowing tab strips
   horizontally.
   Click Markdown file links such as `[source](src/app.py:42)` or
@@ -262,6 +337,14 @@ Current behavior:
   hover titles retain the complete paths and revisions. Text,
   Markdown, HTML, common raster images and text diffs are supported. Monaco
   provides syntax highlighting, find, folding and character-level diffs.
+  Right-click code and choose **Insert into chat**, or select text and use the
+  toolbar button, to insert context at the current chat draft's cursor.
+  Context appears as a separate block among your words. Click it to edit or
+  remove it; Backspace and Delete also remove a block as one element.
+  Context identifies the full view label, including both revisions of a diff.
+  Selections include only the selected text and range; otherwise it records the
+  cursor location. Diff context also identifies the selected side.
+  The draft stays editable until you send it.
   Its code and styles load only when a code or diff view opens, so Canvas,
   Markdown and HTML previews do not load the editor. Viewer assets use gzip
   when supported and revalidate cached content with ETags.
@@ -330,28 +413,37 @@ Current behavior:
   non-persisted follow-up session and submits the file contents as the next
   user instruction; this is intended for side-effect follow-ups such as
   Feishu notifications
-- `/link <feishu-email|open_id|chat_id>` attaches the current interactive
-  session to a Feishu card; multiple sessions in the same pycodex process share
+- `/link <feishu-email|open_id|chat_id>` in a workspace session attaches it
+  to a Feishu card; multiple sessions in the same workspace process share
   one Feishu long-connection listener and route card actions by message id
 - Feishu user OAuth stores its refresh token only in
   `~/.codex/.feishu_refresh_token` (mode `0600`). Run
-  `env -u VIRTUAL_ENV uv run python tools/feishu_oauth.py` from this repository
-  to authorize; app credentials can stay in `~/.codex/.env`. Each refresh reads
+  `python3 -m pycodex_ws.feishu_oauth` after installing `pycodex-ws` to authorize.
+  From this repository, use `env -u VIRTUAL_ENV uv run --dev python -m pycodex_ws.feishu_oauth`.
+  App credentials can stay in `~/.codex/.env`. Each refresh reads
   the latest token from the dedicated file and saves its replacement there.
   `FEISHU_REFRESH_TOKEN` in `.env` or the environment is no longer used and
   can be removed. Refresh is triggered by API calls, with no idle keepalive.
 - `pycodex-ws --workspace-config workspaces.json` serves workspace boards from
   one process. The JSON file can be either a list or
-  `{"workspaces": [...]}`; each entry uses `board` and `work_dir`, with optional
-  display/URL `id`, and is exposed at `/w/<id>/`. Internally the resolved
-  `board` path is the workspace identity, so adding the same board path twice is
-  rejected even with a different name. Relative `board` and `work_dir` paths
+  `{"workspaces": [...]}`; each entry uses `state_path` and `work_dir`, with optional
+  display/URL `id` and `enable_board` (default `true`), and is exposed at `/w/<id>/`.
+  `state_path` is a filename prefix: `/data/demo` uses
+  `/data/demo.pycodex-ws.json` for the session index,
+  `/data/demo.pycodex-views.json` for file views and `/data/demo.html` for Canvas.
+  Suffixes are appended, so prefixes containing dots remain distinct.
+  The resolved `state_path` is the workspace identity; duplicates are rejected
+  regardless of name or Canvas setting. Relative `state_path` and `work_dir` paths
   resolve from the config file directory. The root path `/` shows a workspaces
-  management page with `add_workspace(name=None, dir="./", board=None)` and
-  `delete(name)` controls; omitted names become `workspace-1`, `workspace-2`,
-  etc. If `board` is omitted when adding a workspace, pycodex assigns a random
-  writable `/tmp/pcws-*.html` board path. Add/delete actions and later
-  session-state saves refresh the JSON file. Board HTML can reference local
+  management page with create/delete controls; omitted names become `workspace-1`,
+  `workspace-2`, etc. Omitted `state_path` when creating a workspace generates a
+  writable `/tmp/pcws-*` prefix. `enable_board: false` hides Canvas and disables its
+  routes, polling and context injection; sessions and file views still persist.
+  Existing `board: "demo.html"` and `board: false` configurations load with their
+  original state paths and are saved in the new format. See the
+  [workspace configuration example](packages/pycodex-ws/README.md).
+  Add/delete actions and later session-state saves refresh the JSON file.
+  Board HTML can reference local
   images beside the board (including nested paths) with relative URLs; only
   `image/*` files contained by the board directory are served.
   Assistant Markdown supports KaTeX formulas with `$...$`, `$$...$$`,
@@ -443,6 +535,13 @@ pycodex doctor --json
 `Portable Mode` is the quickest way to bring your usual `pycodex` setup into a
 fresh machine, container, or debug image.
 
+The storage client and server are both included in `python-codex`. To start a
+local storage service, run this in a separate terminal:
+
+```bash
+python -m pycodex.portable.server --root .tmp/pycodex_storage --host 127.0.0.1 --port 5577
+```
+
 Use it like this:
 
 ```bash
@@ -636,7 +735,9 @@ CLI, Web and Feishu all use `AgentRuntime.submit_input`: not just `/model`
 and `/resume`, but every session command, steer/queue admission, interactive
 questions and permissions, state notifications and shutdown. Frontends only
 adapt input and render events. Web no longer imports or runs the CLI shell.
-IPython is the deliberate exception: `ipython_agent()` still returns a bare Agent.
+IPython is the deliberate exception: `pycodex_ws.ipython.ipython_agent()` returns
+a bare Agent. Workspace assembly uses `pycodex_ws.build_runtime()` to add
+`/link` and `/unlink`; `pycodex.bootstrap.build_runtime()` provides core commands.
 
 ```python
 from pycodex.bootstrap import build_agent, build_model, build_runtime

python_codex-0.3.3/PKG-INFO → python_codex-0.4.0/README.md

@@ -1,30 +1,9 @@
-Metadata-Version: 2.1
-Name: python-codex
-Version: 0.3.3
-Summary: A minimal Python extraction of Codex's main agent loop
-License-File: LICENSE
-Requires-Python: >=3.6.2
-Requires-Dist: dataclasses>=0.8; python_version < '3.7'
-Requires-Dist: fastapi<0.84,>=0.83.0; python_version < '3.7'
-Requires-Dist: fastapi>=0.83.0; python_version >= '3.7'
-Requires-Dist: importlib-metadata>=4.8.3; python_version < '3.8'
-Requires-Dist: loguru>=0.7.3
-Requires-Dist: pillow>=8.4.0; python_version < '3.7'
-Requires-Dist: pillow>=9.0.0; python_version >= '3.7'
-Requires-Dist: prompt-toolkit>=3.0.36
-Requires-Dist: pycryptodomex>=3.20
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: requests>=2.27.1
-Requires-Dist: tomli<2,>=1.2.3; python_version < '3.11'
-Requires-Dist: typing-extensions>=4.1.1; python_version < '3.8'
-Requires-Dist: uvicorn<0.17,>=0.16.0; python_version < '3.7'
-Requires-Dist: uvicorn>=0.16.0; python_version >= '3.7'
-Description-Content-Type: text/markdown
-
 # pycodex
 
 English README. Chinese version: `README_ZH.md`
 
+0.4.0 core/workspace package split and dependency cleanup: [release notes](docs/RELEASE_0.4.0.md).
+
 0.3.3 workspace viewers and reasoning stream fix: [release notes](docs/RELEASE_0.3.3.md).
 
 0.3.2 startup fixes: [release notes](docs/RELEASE_0.3.2.md).
@@ -33,15 +12,33 @@ English README. Chinese version: `README_ZH.md`
 
 PyPI distributions:
 
-- Primary package: `python-codex`
-- Workspace install alias: `pycodex-ws`
+- Core package: `python-codex`
+- Workspace and integrations: `pycodex-ws`
 
 The import path remains `pycodex`; the CLI commands are `pycodex` and
 `pycodex-ws`.
 
-`pycodex-ws` is a thin metapackage that depends on the exact matching
-`python-codex` version. The implementation and console script remain owned by
-`python-codex`, so the two distributions never install duplicate modules.
+`python-codex` contains the Agent, runtime, CLI, standard tools, Responses
+compatibility server and portable storage support. `pycodex-ws` depends on the
+exact matching core version and contains the browser workspace, viewer assets,
+Feishu and IPython integrations, including their dependencies. It owns the
+`workspace_server` and `pycodex_ws` modules and the `pycodex-ws` command.
+
+Core does not require Pillow. Without it, `view_image` sends the original image
+bytes with `detail="original"`, including when `high` is requested. With Pillow
+installed, the default path retains resizing to a maximum dimension of 2048.
+`pycodex-ws` installs Pillow for image preview validation.
+
+Portable encryption uses a bundled pure Python AES-GCM subset of pyaes and
+tlslite-ng, under MIT and BSD licenses. Core does not require a crypto package
+or compiler and ships a `py3-none-any` wheel. Existing `PCX1` bundles and call
+tokens remain compatible; large bundles take longer to encrypt and decrypt.
+See the [source notes](pycodex/utils/_aes_gcm/README.md).
+
+The Responses compatibility server and workspace HTTP server use Starlette
+and Uvicorn directly. Neither package requires FastAPI, Pydantic or
+`pydantic-core`. Python 3.6 uses Starlette 0.19.x; newer interpreters resolve
+a compatible Starlette release through its Python version metadata.
 
 This repository extracts the core Codex agent loop from upstream Codex
 (`https://github.com/openai/codex`) into a deliberately small Python version,
@@ -61,16 +58,17 @@ Relevant Rust reference points:
 
 ## Quick Start
 
-Install the full package or the workspace-oriented alias:
+Install the core CLI, or install the workspace package to include all integrations:
 
 ```bash
 python3 -m pip install python-codex
 python3 -m pip install pycodex-ws
 ```
 
-Use Python 3.6.2 or newer. Both console commands are installed into that
-interpreter's scripts directory. On a machine with multiple Python installations,
-you can select the same interpreter explicitly for startup:
+The core supports Python 3.6.2 or newer. The workspace package requires Python
+3.7 or newer because of its Feishu SDK dependency. Commands are installed into
+that interpreter's scripts directory. On a machine with multiple Python
+installations, select the same interpreter explicitly for startup:
 
 ```bash
 python3 -m pycodex
@@ -81,10 +79,14 @@ If `pycodex` is missing from `PATH` or resolves to an older installation, use th
 module entry points. `python3 -m pip --version` shows which Python environment
 received the installation.
 
+For an existing Web installation, use `python3 -m pip install --upgrade pycodex-ws`
+to upgrade the workspace and its matching core together. Installing only
+`python-codex` provides the CLI and core API.
+
 For development from this repository, install dependencies first:
 
 ```bash
-uv sync
+uv sync --dev
 ```
 
 Try the real entry points:
@@ -94,8 +96,22 @@ uv run pycodex "Reply with exactly OK."
 uv run pycodex
 ```
 
-A VS Code frontend is available in [`extensions/vscode`](extensions/vscode/README.md).
-It reuses an existing `python-codex>=0.3.1` installation. On first use, missing
+Tests are split by package. `uv run --dev pytest` runs both suites;
+`uv run --dev pytest packages/pycodex-ws/tests` runs workspace and integration
+tests. To check core without installing workspace or its SDKs, use a separate
+environment:
+
+```bash
+UV_PROJECT_ENVIRONMENT=.tmp/core-tests uv sync --group test
+UV_PROJECT_ENVIRONMENT=.tmp/core-tests uv run --group test pytest tests
+```
+
+See [test environments and coverage](tests/TESTS.md). Core tests support Python
+3.6.2+; workspace tests require Python 3.7+.
+
+A VS Code frontend is available in [`packages/pycodex-ws/extensions/vscode`](packages/pycodex-ws/extensions/vscode/README.md).
+It belongs to the workspace frontend and is packaged separately as a VSIX.
+It reuses an existing `pycodex-ws>=0.4.0` installation. On first use, missing
 or older backends are installed/upgraded with pip in the selected Python
 environment on the workspace host; compatible versions need no network check.
 It starts a dedicated `pycodex-ws` workspace on the project's host and opens a
@@ -143,19 +159,35 @@ nailing the core tool-augmented reasoning loop first.
 
 ## Layout
 
+The top level of `pycodex/` contains the core components and package entry points.
+Supporting services live in `tools/`, `portable/` and `utils/`.
+
+- `pycodex/agent.py`: inner turn loop
+- `pycodex/runtime.py`: session commands, submission queues and frontend event subscriptions
+- `pycodex/model.py`: model client protocol and Responses API adapter
+- `pycodex/context.py`: configuration, prompt assembly and instruction loading
 - `pycodex/protocol.py`: minimal conversation item / prompt protocol
 - `pycodex/events.py`: typed events, plain-text views and stateful presentation
-- `pycodex/utils/event_helpers.py`: stateless text, color, summary and result-formatting helpers
-- `pycodex/utils/image_utils.py`: image loading, resizing and data-URL preparation
-- `pycodex/model.py`: model client protocol and Responses API adapter
-- `pycodex/cli.py`: single-turn/interactive entry points, terminal I/O executor and input loop
 - `pycodex/bootstrap.py`: frontend-independent model, tools, Agent and session assembly
+- `pycodex/cli.py`: single-turn/interactive entry points, terminal I/O executor and input loop
 - `pycodex/tools/base_tool.py`: `BaseTool`, `ToolRegistry`, `ToolContext`
-- `pycodex/tools/`: concrete tool implementations
-- `pycodex/agent.py`: inner turn loop
-- `pycodex/runtime.py`: session commands, submission queues and frontend event subscriptions
-- `extensions/vscode/`: VS Code chat frontend using the workspace HTTP API
-- `tests/test_agent.py`: core behavior tests
+- `pycodex/tools/runtime_services.py`: plan, sub-agent, user-input and permissions services
+- `pycodex/tools/`: concrete tools and their execution managers
+- `pycodex/portable/`: Codex home storage client and server, both included in core
+- `pycodex/utils/compat.py`: supported-Python compatibility helpers
+- `pycodex/utils/doctor.py`: configuration and connectivity diagnostics
+- `pycodex/utils/model_metadata.py`: vendored model metadata lookup
+- `pycodex/utils/debug.py`: debug paths and the `pycodex.debug()` implementation
+- `pycodex/utils/event_helpers.py`: stateless text, color, summary and result-formatting helpers
+- `pycodex/utils/image_utils.py`: image loading, resizing and data-URL preparation
+- `pycodex/prompts/`: vendored prompts and model metadata
+- `packages/pycodex-ws/workspace_server/`: Web board, API and file/diff viewers
+- `packages/pycodex-ws/pycodex_ws/`: Feishu, IPython and workspace assembly
+- `packages/pycodex-ws/extensions/vscode/`: workspace's VS Code frontend, built separately as a VSIX
+- `tests/`: core tests
+- `packages/pycodex-ws/tests/`: workspace and cross-frontend integration tests
+
+See [package layout and import paths](docs/RUNTIME.md#package-layout).
 
 ## Current Alignment Status
 
@@ -266,7 +298,7 @@ Current behavior:
 - with an argv prompt or piped stdin, run a single turn
 - `pycodex-ws` starts the standalone browser workspace manager and serves each
   workspace with a board pane and a pycodex session pane
-- the left pane is the board, containing a live HTML Canvas tab and closable read-only file/diff tabs that
+- the left pane is the board, containing an optional live HTML Canvas tab and closable read-only file/diff tabs that
   scroll together in one toolbar; a mouse wheel scrolls overflowing tab strips
   horizontally.
   Click Markdown file links such as `[source](src/app.py:42)` or
@@ -285,6 +317,14 @@ Current behavior:
   hover titles retain the complete paths and revisions. Text,
   Markdown, HTML, common raster images and text diffs are supported. Monaco
   provides syntax highlighting, find, folding and character-level diffs.
+  Right-click code and choose **Insert into chat**, or select text and use the
+  toolbar button, to insert context at the current chat draft's cursor.
+  Context appears as a separate block among your words. Click it to edit or
+  remove it; Backspace and Delete also remove a block as one element.
+  Context identifies the full view label, including both revisions of a diff.
+  Selections include only the selected text and range; otherwise it records the
+  cursor location. Diff context also identifies the selected side.
+  The draft stays editable until you send it.
   Its code and styles load only when a code or diff view opens, so Canvas,
   Markdown and HTML previews do not load the editor. Viewer assets use gzip
   when supported and revalidate cached content with ETags.
@@ -353,28 +393,37 @@ Current behavior:
   non-persisted follow-up session and submits the file contents as the next
   user instruction; this is intended for side-effect follow-ups such as
   Feishu notifications
-- `/link <feishu-email|open_id|chat_id>` attaches the current interactive
-  session to a Feishu card; multiple sessions in the same pycodex process share
+- `/link <feishu-email|open_id|chat_id>` in a workspace session attaches it
+  to a Feishu card; multiple sessions in the same workspace process share
   one Feishu long-connection listener and route card actions by message id
 - Feishu user OAuth stores its refresh token only in
   `~/.codex/.feishu_refresh_token` (mode `0600`). Run
-  `env -u VIRTUAL_ENV uv run python tools/feishu_oauth.py` from this repository
-  to authorize; app credentials can stay in `~/.codex/.env`. Each refresh reads
+  `python3 -m pycodex_ws.feishu_oauth` after installing `pycodex-ws` to authorize.
+  From this repository, use `env -u VIRTUAL_ENV uv run --dev python -m pycodex_ws.feishu_oauth`.
+  App credentials can stay in `~/.codex/.env`. Each refresh reads
   the latest token from the dedicated file and saves its replacement there.
   `FEISHU_REFRESH_TOKEN` in `.env` or the environment is no longer used and
   can be removed. Refresh is triggered by API calls, with no idle keepalive.
 - `pycodex-ws --workspace-config workspaces.json` serves workspace boards from
   one process. The JSON file can be either a list or
-  `{"workspaces": [...]}`; each entry uses `board` and `work_dir`, with optional
-  display/URL `id`, and is exposed at `/w/<id>/`. Internally the resolved
-  `board` path is the workspace identity, so adding the same board path twice is
-  rejected even with a different name. Relative `board` and `work_dir` paths
+  `{"workspaces": [...]}`; each entry uses `state_path` and `work_dir`, with optional
+  display/URL `id` and `enable_board` (default `true`), and is exposed at `/w/<id>/`.
+  `state_path` is a filename prefix: `/data/demo` uses
+  `/data/demo.pycodex-ws.json` for the session index,
+  `/data/demo.pycodex-views.json` for file views and `/data/demo.html` for Canvas.
+  Suffixes are appended, so prefixes containing dots remain distinct.
+  The resolved `state_path` is the workspace identity; duplicates are rejected
+  regardless of name or Canvas setting. Relative `state_path` and `work_dir` paths
   resolve from the config file directory. The root path `/` shows a workspaces
-  management page with `add_workspace(name=None, dir="./", board=None)` and
-  `delete(name)` controls; omitted names become `workspace-1`, `workspace-2`,
-  etc. If `board` is omitted when adding a workspace, pycodex assigns a random
-  writable `/tmp/pcws-*.html` board path. Add/delete actions and later
-  session-state saves refresh the JSON file. Board HTML can reference local
+  management page with create/delete controls; omitted names become `workspace-1`,
+  `workspace-2`, etc. Omitted `state_path` when creating a workspace generates a
+  writable `/tmp/pcws-*` prefix. `enable_board: false` hides Canvas and disables its
+  routes, polling and context injection; sessions and file views still persist.
+  Existing `board: "demo.html"` and `board: false` configurations load with their
+  original state paths and are saved in the new format. See the
+  [workspace configuration example](packages/pycodex-ws/README.md).
+  Add/delete actions and later session-state saves refresh the JSON file.
+  Board HTML can reference local
   images beside the board (including nested paths) with relative URLs; only
   `image/*` files contained by the board directory are served.
   Assistant Markdown supports KaTeX formulas with `$...$`, `$$...$$`,
@@ -466,6 +515,13 @@ pycodex doctor --json
 `Portable Mode` is the quickest way to bring your usual `pycodex` setup into a
 fresh machine, container, or debug image.
 
+The storage client and server are both included in `python-codex`. To start a
+local storage service, run this in a separate terminal:
+
+```bash
+python -m pycodex.portable.server --root .tmp/pycodex_storage --host 127.0.0.1 --port 5577
+```
+
 Use it like this:
 
 ```bash
@@ -659,7 +715,9 @@ CLI, Web and Feishu all use `AgentRuntime.submit_input`: not just `/model`
 and `/resume`, but every session command, steer/queue admission, interactive
 questions and permissions, state notifications and shutdown. Frontends only
 adapt input and render events. Web no longer imports or runs the CLI shell.
-IPython is the deliberate exception: `ipython_agent()` still returns a bare Agent.
+IPython is the deliberate exception: `pycodex_ws.ipython.ipython_agent()` returns
+a bare Agent. Workspace assembly uses `pycodex_ws.build_runtime()` to add
+`/link` and `/unlink`; `pycodex.bootstrap.build_runtime()` provides core commands.
 
 ```python
 from pycodex.bootstrap import build_agent, build_model, build_runtime