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

{python_codex-0.3.2 → python_codex-0.4.0}/PKG-INFO

@@ -1,20 +1,17 @@
 Metadata-Version: 2.1
 Name: python-codex
-Version: 0.3.2
+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: 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: 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'
@@ -25,21 +22,43 @@ Description-Content-Type: text/markdown
 
 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).
 
 0.3.0 release preparation and Python API migration: `docs/RELEASE_0.3.0.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,
@@ -59,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
@@ -79,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:
@@ -92,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
@@ -141,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
 
@@ -264,6 +318,53 @@ 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 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
+  `[source](/data/project/app.py#L42)` to open a view. Git-style diff links use
+  `[changes](diff:HEAD:src/app.py)` for working changes,
+  `[versions](diff:HEAD~1..HEAD:src/app.py)` for two revisions, and
+  `[files](diff:old.py..new.py)` for two local files. Append `#L42` or `#R42`
+  to a diff link to select a 1-based line on the left or right.
+  Views open when the user clicks; model replies alone do not create tabs.
+  Reopening the same file or comparison selects its existing tab in that
+  browser, including when the line changes. Other pages keep their selection.
+  Tabs show filenames first, adding a short directory suffix
+  for duplicate names. Git versions use short commit IDs in a secondary label.
+  Long labels use the same width limit as session tabs, shortening the secondary
+  information before the filename;
+  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.
+  Narrow content panes automatically use a unified diff; targeting the left
+  side keeps both sides visible. Markdown and HTML links default to previews;
+  line targets open their source. Clicking a link without a line returns that
+  same tab to preview. Manual tab switches preserve the chosen mode and reading state.
+  All views remain
+  read-only, with text selection and copying available. Local files update
+  automatically, including both sides of file diffs and the working side of
+  Git diffs; Git revisions stay fixed. Updates keep the active editor and
+  reading state without replaying an earlier line request.
+  Canvas is for explanations and custom visuals; source and diffs use links.
+  `[Canvas](workspace://canvas)` returns to the live page; an HTML file link opens
+  a preview tab, and `page.html:1` opens its source. File links work even with an empty `--toolset`.
+  Canvas and HTML previews share the same origin and script permissions;
+  the browser loads their resources with the workspace login cookie.
+  Open views survive reloads and server restarts. See
+  [workspace content views](docs/RUNTIME.md#workspace-content-views) for the
+  complete syntax and limits.
 - interactive mode exits through `/exit`, `/quit`, Ctrl+D on an empty prompt,
   or a single Ctrl+C; accepted work finishes before cleanup and normal exit.
   A `[closing]` message explains the wait. Press Ctrl+C again while closing
@@ -312,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 `$...$`, `$$...$$`,
@@ -366,7 +476,7 @@ Current behavior:
   time when it expires.
 - while a background command or clock is pending, the idle status is
   `idle: sleeping`
-- only the active workspace tab shows its close button; closing it restores
+- only the active workspace session tab shows its close button; closing it restores
   the selected tab's conversation, draft, and scroll position immediately
   after its snapshot loads
 - `--vllm-endpoint http://host:port` automatically launches a local
@@ -387,6 +497,10 @@ Current behavior:
   reasoning, retries the same downstream request once, and only then emits
   `response.failed` with `type = "model_output_invalid"` if the retry is still
   reasoning-only
+- compat reasoning fragments are forwarded immediately as
+  `response.reasoning_text.delta`, including thinking from `/v1/messages`.
+  Continuous reasoning keeps the client's read idle timeout from expiring
+  while it waits for assistant text; only finalized reasoning items enter history
 - malformed JSON in ordinary downstream function-call arguments is detected by
   `responses_server` and returned as `response.failed` with `type = "server_error"`;
   the client's existing `stream_max_retries` policy retries the current request
@@ -421,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
@@ -614,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.2 → python_codex-0.4.0}/README.md

@@ -2,21 +2,43 @@
 
 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).
 
 0.3.0 release preparation and Python API migration: `docs/RELEASE_0.3.0.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,
@@ -36,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
@@ -56,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:
@@ -69,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
@@ -118,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
 
@@ -241,6 +298,53 @@ 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 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
+  `[source](/data/project/app.py#L42)` to open a view. Git-style diff links use
+  `[changes](diff:HEAD:src/app.py)` for working changes,
+  `[versions](diff:HEAD~1..HEAD:src/app.py)` for two revisions, and
+  `[files](diff:old.py..new.py)` for two local files. Append `#L42` or `#R42`
+  to a diff link to select a 1-based line on the left or right.
+  Views open when the user clicks; model replies alone do not create tabs.
+  Reopening the same file or comparison selects its existing tab in that
+  browser, including when the line changes. Other pages keep their selection.
+  Tabs show filenames first, adding a short directory suffix
+  for duplicate names. Git versions use short commit IDs in a secondary label.
+  Long labels use the same width limit as session tabs, shortening the secondary
+  information before the filename;
+  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.
+  Narrow content panes automatically use a unified diff; targeting the left
+  side keeps both sides visible. Markdown and HTML links default to previews;
+  line targets open their source. Clicking a link without a line returns that
+  same tab to preview. Manual tab switches preserve the chosen mode and reading state.
+  All views remain
+  read-only, with text selection and copying available. Local files update
+  automatically, including both sides of file diffs and the working side of
+  Git diffs; Git revisions stay fixed. Updates keep the active editor and
+  reading state without replaying an earlier line request.
+  Canvas is for explanations and custom visuals; source and diffs use links.
+  `[Canvas](workspace://canvas)` returns to the live page; an HTML file link opens
+  a preview tab, and `page.html:1` opens its source. File links work even with an empty `--toolset`.
+  Canvas and HTML previews share the same origin and script permissions;
+  the browser loads their resources with the workspace login cookie.
+  Open views survive reloads and server restarts. See
+  [workspace content views](docs/RUNTIME.md#workspace-content-views) for the
+  complete syntax and limits.
 - interactive mode exits through `/exit`, `/quit`, Ctrl+D on an empty prompt,
   or a single Ctrl+C; accepted work finishes before cleanup and normal exit.
   A `[closing]` message explains the wait. Press Ctrl+C again while closing
@@ -289,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 `$...$`, `$$...$$`,
@@ -343,7 +456,7 @@ Current behavior:
   time when it expires.
 - while a background command or clock is pending, the idle status is
   `idle: sleeping`
-- only the active workspace tab shows its close button; closing it restores
+- only the active workspace session tab shows its close button; closing it restores
   the selected tab's conversation, draft, and scroll position immediately
   after its snapshot loads
 - `--vllm-endpoint http://host:port` automatically launches a local
@@ -364,6 +477,10 @@ Current behavior:
   reasoning, retries the same downstream request once, and only then emits
   `response.failed` with `type = "model_output_invalid"` if the retry is still
   reasoning-only
+- compat reasoning fragments are forwarded immediately as
+  `response.reasoning_text.delta`, including thinking from `/v1/messages`.
+  Continuous reasoning keeps the client's read idle timeout from expiring
+  while it waits for assistant text; only finalized reasoning items enter history
 - malformed JSON in ordinary downstream function-call arguments is detected by
   `responses_server` and returned as `response.failed` with `type = "server_error"`;
   the client's existing `stream_max_retries` policy retries the current request
@@ -398,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
@@ -591,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