python-codex 0.3.3__py3-none-any.whl → 0.4.0__py3-none-any.whl

pycodex/utils/_aes_gcm/aes.py

@@ -0,0 +1,175 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2014 Richard Moore
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+"""AES encryption subset of pyaes 1.6.1; see README.md for changes."""
+
+
+class AES256:
+    """AES-256 block encryption, used for both directions of GCM."""
+
+    S = (
+        0x63, 0x7c, 0x77, 0x7b, 0xf2, 0x6b, 0x6f, 0xc5,
+        0x30, 0x01, 0x67, 0x2b, 0xfe, 0xd7, 0xab, 0x76,
+        0xca, 0x82, 0xc9, 0x7d, 0xfa, 0x59, 0x47, 0xf0,
+        0xad, 0xd4, 0xa2, 0xaf, 0x9c, 0xa4, 0x72, 0xc0,
+        0xb7, 0xfd, 0x93, 0x26, 0x36, 0x3f, 0xf7, 0xcc,
+        0x34, 0xa5, 0xe5, 0xf1, 0x71, 0xd8, 0x31, 0x15,
+        0x04, 0xc7, 0x23, 0xc3, 0x18, 0x96, 0x05, 0x9a,
+        0x07, 0x12, 0x80, 0xe2, 0xeb, 0x27, 0xb2, 0x75,
+        0x09, 0x83, 0x2c, 0x1a, 0x1b, 0x6e, 0x5a, 0xa0,
+        0x52, 0x3b, 0xd6, 0xb3, 0x29, 0xe3, 0x2f, 0x84,
+        0x53, 0xd1, 0x00, 0xed, 0x20, 0xfc, 0xb1, 0x5b,
+        0x6a, 0xcb, 0xbe, 0x39, 0x4a, 0x4c, 0x58, 0xcf,
+        0xd0, 0xef, 0xaa, 0xfb, 0x43, 0x4d, 0x33, 0x85,
+        0x45, 0xf9, 0x02, 0x7f, 0x50, 0x3c, 0x9f, 0xa8,
+        0x51, 0xa3, 0x40, 0x8f, 0x92, 0x9d, 0x38, 0xf5,
+        0xbc, 0xb6, 0xda, 0x21, 0x10, 0xff, 0xf3, 0xd2,
+        0xcd, 0x0c, 0x13, 0xec, 0x5f, 0x97, 0x44, 0x17,
+        0xc4, 0xa7, 0x7e, 0x3d, 0x64, 0x5d, 0x19, 0x73,
+        0x60, 0x81, 0x4f, 0xdc, 0x22, 0x2a, 0x90, 0x88,
+        0x46, 0xee, 0xb8, 0x14, 0xde, 0x5e, 0x0b, 0xdb,
+        0xe0, 0x32, 0x3a, 0x0a, 0x49, 0x06, 0x24, 0x5c,
+        0xc2, 0xd3, 0xac, 0x62, 0x91, 0x95, 0xe4, 0x79,
+        0xe7, 0xc8, 0x37, 0x6d, 0x8d, 0xd5, 0x4e, 0xa9,
+        0x6c, 0x56, 0xf4, 0xea, 0x65, 0x7a, 0xae, 0x08,
+        0xba, 0x78, 0x25, 0x2e, 0x1c, 0xa6, 0xb4, 0xc6,
+        0xe8, 0xdd, 0x74, 0x1f, 0x4b, 0xbd, 0x8b, 0x8a,
+        0x70, 0x3e, 0xb5, 0x66, 0x48, 0x03, 0xf6, 0x0e,
+        0x61, 0x35, 0x57, 0xb9, 0x86, 0xc1, 0x1d, 0x9e,
+        0xe1, 0xf8, 0x98, 0x11, 0x69, 0xd9, 0x8e, 0x94,
+        0x9b, 0x1e, 0x87, 0xe9, 0xce, 0x55, 0x28, 0xdf,
+        0x8c, 0xa1, 0x89, 0x0d, 0xbf, 0xe6, 0x42, 0x68,
+        0x41, 0x99, 0x2d, 0x0f, 0xb0, 0x54, 0xbb, 0x16,
+    )
+
+    T1 = (
+        0xc66363a5, 0xf87c7c84, 0xee777799, 0xf67b7b8d, 0xfff2f20d, 0xd66b6bbd, 0xde6f6fb1, 0x91c5c554,
+        0x60303050, 0x02010103, 0xce6767a9, 0x562b2b7d, 0xe7fefe19, 0xb5d7d762, 0x4dababe6, 0xec76769a,
+        0x8fcaca45, 0x1f82829d, 0x89c9c940, 0xfa7d7d87, 0xeffafa15, 0xb25959eb, 0x8e4747c9, 0xfbf0f00b,
+        0x41adadec, 0xb3d4d467, 0x5fa2a2fd, 0x45afafea, 0x239c9cbf, 0x53a4a4f7, 0xe4727296, 0x9bc0c05b,
+        0x75b7b7c2, 0xe1fdfd1c, 0x3d9393ae, 0x4c26266a, 0x6c36365a, 0x7e3f3f41, 0xf5f7f702, 0x83cccc4f,
+        0x6834345c, 0x51a5a5f4, 0xd1e5e534, 0xf9f1f108, 0xe2717193, 0xabd8d873, 0x62313153, 0x2a15153f,
+        0x0804040c, 0x95c7c752, 0x46232365, 0x9dc3c35e, 0x30181828, 0x379696a1, 0x0a05050f, 0x2f9a9ab5,
+        0x0e070709, 0x24121236, 0x1b80809b, 0xdfe2e23d, 0xcdebeb26, 0x4e272769, 0x7fb2b2cd, 0xea75759f,
+        0x1209091b, 0x1d83839e, 0x582c2c74, 0x341a1a2e, 0x361b1b2d, 0xdc6e6eb2, 0xb45a5aee, 0x5ba0a0fb,
+        0xa45252f6, 0x763b3b4d, 0xb7d6d661, 0x7db3b3ce, 0x5229297b, 0xdde3e33e, 0x5e2f2f71, 0x13848497,
+        0xa65353f5, 0xb9d1d168, 0x00000000, 0xc1eded2c, 0x40202060, 0xe3fcfc1f, 0x79b1b1c8, 0xb65b5bed,
+        0xd46a6abe, 0x8dcbcb46, 0x67bebed9, 0x7239394b, 0x944a4ade, 0x984c4cd4, 0xb05858e8, 0x85cfcf4a,
+        0xbbd0d06b, 0xc5efef2a, 0x4faaaae5, 0xedfbfb16, 0x864343c5, 0x9a4d4dd7, 0x66333355, 0x11858594,
+        0x8a4545cf, 0xe9f9f910, 0x04020206, 0xfe7f7f81, 0xa05050f0, 0x783c3c44, 0x259f9fba, 0x4ba8a8e3,
+        0xa25151f3, 0x5da3a3fe, 0x804040c0, 0x058f8f8a, 0x3f9292ad, 0x219d9dbc, 0x70383848, 0xf1f5f504,
+        0x63bcbcdf, 0x77b6b6c1, 0xafdada75, 0x42212163, 0x20101030, 0xe5ffff1a, 0xfdf3f30e, 0xbfd2d26d,
+        0x81cdcd4c, 0x180c0c14, 0x26131335, 0xc3ecec2f, 0xbe5f5fe1, 0x359797a2, 0x884444cc, 0x2e171739,
+        0x93c4c457, 0x55a7a7f2, 0xfc7e7e82, 0x7a3d3d47, 0xc86464ac, 0xba5d5de7, 0x3219192b, 0xe6737395,
+        0xc06060a0, 0x19818198, 0x9e4f4fd1, 0xa3dcdc7f, 0x44222266, 0x542a2a7e, 0x3b9090ab, 0x0b888883,
+        0x8c4646ca, 0xc7eeee29, 0x6bb8b8d3, 0x2814143c, 0xa7dede79, 0xbc5e5ee2, 0x160b0b1d, 0xaddbdb76,
+        0xdbe0e03b, 0x64323256, 0x743a3a4e, 0x140a0a1e, 0x924949db, 0x0c06060a, 0x4824246c, 0xb85c5ce4,
+        0x9fc2c25d, 0xbdd3d36e, 0x43acacef, 0xc46262a6, 0x399191a8, 0x319595a4, 0xd3e4e437, 0xf279798b,
+        0xd5e7e732, 0x8bc8c843, 0x6e373759, 0xda6d6db7, 0x018d8d8c, 0xb1d5d564, 0x9c4e4ed2, 0x49a9a9e0,
+        0xd86c6cb4, 0xac5656fa, 0xf3f4f407, 0xcfeaea25, 0xca6565af, 0xf47a7a8e, 0x47aeaee9, 0x10080818,
+        0x6fbabad5, 0xf0787888, 0x4a25256f, 0x5c2e2e72, 0x381c1c24, 0x57a6a6f1, 0x73b4b4c7, 0x97c6c651,
+        0xcbe8e823, 0xa1dddd7c, 0xe874749c, 0x3e1f1f21, 0x964b4bdd, 0x61bdbddc, 0x0d8b8b86, 0x0f8a8a85,
+        0xe0707090, 0x7c3e3e42, 0x71b5b5c4, 0xcc6666aa, 0x904848d8, 0x06030305, 0xf7f6f601, 0x1c0e0e12,
+        0xc26161a3, 0x6a35355f, 0xae5757f9, 0x69b9b9d0, 0x17868691, 0x99c1c158, 0x3a1d1d27, 0x279e9eb9,
+        0xd9e1e138, 0xebf8f813, 0x2b9898b3, 0x22111133, 0xd26969bb, 0xa9d9d970, 0x078e8e89, 0x339494a7,
+        0x2d9b9bb6, 0x3c1e1e22, 0x15878792, 0xc9e9e920, 0x87cece49, 0xaa5555ff, 0x50282878, 0xa5dfdf7a,
+        0x038c8c8f, 0x59a1a1f8, 0x09898980, 0x1a0d0d17, 0x65bfbfda, 0xd7e6e631, 0x844242c6, 0xd06868b8,
+        0x824141c3, 0x299999b0, 0x5a2d2d77, 0x1e0f0f11, 0x7bb0b0cb, 0xa85454fc, 0x6dbbbbd6, 0x2c16163a,
+    )
+
+    # The other encryption tables are byte rotations of T1.
+    T2 = tuple((value >> 8) | ((value & 0xff) << 24) for value in T1)
+    T3 = tuple((value >> 16) | ((value & 0xffff) << 16) for value in T1)
+    T4 = tuple((value >> 24) | ((value & 0xffffff) << 8) for value in T1)
+    rcon = (0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40)
+
+    def __init__(self, key):
+        if len(key) != 32:
+            raise ValueError("AES-256 requires a 32-byte key")
+
+        self._Ke = [[0] * 4 for _ in range(15)]
+        tk = [int.from_bytes(key[i:i + 4], "big") for i in range(0, 32, 4)]
+        for i in range(8):
+            self._Ke[i // 4][i % 4] = tk[i]
+
+        # AES-256 key expansion, FIPS 197 section 5.2.
+        rconpointer = 0
+        t = 8
+        while t < 60:
+            tt = tk[7]
+            tk[0] ^= (
+                (self.S[(tt >> 16) & 0xff] << 24)
+                ^ (self.S[(tt >> 8) & 0xff] << 16)
+                ^ (self.S[tt & 0xff] << 8)
+                ^ self.S[(tt >> 24) & 0xff]
+                ^ (self.rcon[rconpointer] << 24)
+            )
+            rconpointer += 1
+            for i in range(1, 4):
+                tk[i] ^= tk[i - 1]
+            tt = tk[3]
+            tk[4] ^= (
+                self.S[tt & 0xff]
+                ^ (self.S[(tt >> 8) & 0xff] << 8)
+                ^ (self.S[(tt >> 16) & 0xff] << 16)
+                ^ (self.S[(tt >> 24) & 0xff] << 24)
+            )
+            for i in range(5, 8):
+                tk[i] ^= tk[i - 1]
+
+            j = 0
+            while j < 8 and t < 60:
+                self._Ke[t // 4][t % 4] = tk[j]
+                j += 1
+                t += 1
+
+    def encrypt(self, plaintext):
+        """Encrypt one 16-byte block without padding."""
+        if len(plaintext) != 16:
+            raise ValueError("AES requires a 16-byte block")
+
+        keys = self._Ke
+        sbox, t1, t2, t3, t4 = self.S, self.T1, self.T2, self.T3, self.T4
+        t = [
+            int.from_bytes(plaintext[4 * i:4 * i + 4], "big") ^ keys[0][i]
+            for i in range(4)
+        ]
+        a = [0] * 4
+        for r in range(1, 14):
+            for i in range(4):
+                a[i] = (
+                    t1[(t[i] >> 24) & 0xff]
+                    ^ t2[(t[(i + 1) % 4] >> 16) & 0xff]
+                    ^ t3[(t[(i + 2) % 4] >> 8) & 0xff]
+                    ^ t4[t[(i + 3) % 4] & 0xff]
+                    ^ keys[r][i]
+                )
+            t = a[:]
+
+        result = []
+        for i in range(4):
+            tt = keys[14][i]
+            result.append((sbox[(t[i] >> 24) & 0xff] ^ (tt >> 24)) & 0xff)
+            result.append((sbox[(t[(i + 1) % 4] >> 16) & 0xff] ^ (tt >> 16)) & 0xff)
+            result.append((sbox[(t[(i + 2) % 4] >> 8) & 0xff] ^ (tt >> 8)) & 0xff)
+            result.append((sbox[t[(i + 3) % 4] & 0xff] ^ tt) & 0xff)
+        return bytes(result)

pycodex/utils/_aes_gcm/gcm.py

@@ -0,0 +1,73 @@
+# Copyright (c) 2008, The Chromium Authors. All rights reserved.
+# Adapted from tlslite-ng 0.8.2, tlslite/utils/aesgcm.py (author: Google).
+# GCM derived there from Go's crypto/cipher implementation.
+# See LICENSE for the BSD license and README.md for local changes.
+
+"""GCM for 12-byte nonces, 16-byte tags and empty associated data."""
+
+from .aes import AES256
+
+
+class AESGCM:
+    # Reduction by 1+x+x^2+x^7 for each four-bit polynomial.
+    _reduction = (
+        0x0000, 0x1c20, 0x3840, 0x2460, 0x7080, 0x6ca0, 0x48c0, 0x54e0,
+        0xe100, 0xfd20, 0xd940, 0xc560, 0x9180, 0x8da0, 0xa9c0, 0xb5e0,
+    )
+
+    def __init__(self, key):
+        self._aes = AES256(key)
+        h = int.from_bytes(self._aes.encrypt(b"\0" * 16), "big")
+        self._product_table = [0] * 16
+        self._product_table[8] = h
+        for i in range(2, 16, 2):
+            self._product_table[self._reverse_bits(i)] = self._shift(
+                self._product_table[self._reverse_bits(i // 2)]
+            )
+            self._product_table[self._reverse_bits(i + 1)] = (
+                self._product_table[self._reverse_bits(i)] ^ h
+            )
+
+    def crypt(self, nonce, data):
+        """Apply GCM's counter stream to plaintext or authenticated ciphertext."""
+        output = bytearray(len(data))
+        for offset in range(0, len(data), 16):
+            counter = nonce + (2 + offset // 16).to_bytes(4, "big")
+            mask = self._aes.encrypt(counter)
+            for i, value in enumerate(data[offset:offset + 16]):
+                output[offset + i] = value ^ mask[i]
+        return bytes(output)
+
+    def tag(self, nonce, ciphertext):
+        """Authenticate ciphertext with empty associated data."""
+        y = 0
+        for offset in range(0, len(ciphertext), 16):
+            block = ciphertext[offset:offset + 16].ljust(16, b"\0")
+            y = self._multiply(y ^ int.from_bytes(block, "big"))
+        y = self._multiply(y ^ (len(ciphertext) << 3))
+        mask = self._aes.encrypt(nonce + b"\0\0\0\1")
+        return (y ^ int.from_bytes(mask, "big")).to_bytes(16, "big")
+
+    def _multiply(self, y):
+        """Multiply by the GCM key in GF(2^128), four bits at a time."""
+        result = 0
+        for _ in range(0, 128, 4):
+            high = result & 0xf
+            result >>= 4
+            result ^= self._reduction[high] << 112
+            result ^= self._product_table[y & 0xf]
+            y >>= 4
+        return result
+
+    @staticmethod
+    def _reverse_bits(value):
+        value = ((value << 2) & 0xc) | ((value >> 2) & 0x3)
+        return ((value << 1) & 0xa) | ((value >> 1) & 0x5)
+
+    @staticmethod
+    def _shift(value):
+        high = value & 1
+        value >>= 1
+        if high:
+            value ^= 0xe1 << 120
+        return value

pycodex/utils/_aes_gcm/source-sha256.json

@@ -0,0 +1,4 @@
+{
+  "pyaes-1.6.1/pyaes/aes.py": "5dc0ff7ad948704ae9814fc2720f9b479599092a7a46e1fd9d55b78953a1a43f",
+  "tlslite-ng-0.8.2/tlslite/utils/aesgcm.py": "958eb056fe56bcec7b4c398a5af2eccda73ed3c3f7d8ca7866e52bbe415621a3"
+}

pycodex/{compat.py → utils/compat.py}

@@ -1,3 +1,5 @@
+"""Compatibility helpers for supported Python versions."""
+
 import asyncio
 import functools
 import shlex

pycodex/utils/crypto.py

@@ -0,0 +1,35 @@
+"""AES-256-GCM using a bundled pure Python implementation."""
+
+from hmac import compare_digest
+
+from ._aes_gcm.gcm import AESGCM
+
+
+def _validate(key, nonce, data):
+    if len(key) != 32:
+        raise ValueError("AES-256-GCM requires a 32-byte key")
+    if len(nonce) != 12:
+        raise ValueError("AES-GCM requires a 12-byte nonce")
+    if len(data) > (1 << 36) - 32:
+        raise ValueError("AES-GCM input exceeds the maximum message length")
+
+
+def aes_gcm_encrypt(key: "bytes", nonce: "bytes", plaintext: "bytes"):
+    """Return ciphertext and a 16-byte authentication tag."""
+    _validate(key, nonce, plaintext)
+    cipher = AESGCM(key)
+    ciphertext = cipher.crypt(nonce, plaintext)
+    return ciphertext, cipher.tag(nonce, ciphertext)
+
+
+def aes_gcm_decrypt(
+    key: "bytes", nonce: "bytes", ciphertext: "bytes", tag: "bytes"
+) -> "bytes":
+    """Verify the authentication tag before decrypting any ciphertext."""
+    _validate(key, nonce, ciphertext)
+    if len(tag) != 16:
+        raise ValueError("AES-GCM requires a 16-byte authentication tag")
+    cipher = AESGCM(key)
+    if not compare_digest(tag, cipher.tag(nonce, ciphertext)):
+        raise ValueError("AES-GCM authentication failed")
+    return cipher.crypt(nonce, ciphertext)

pycodex/utils/debug.py

@@ -10,3 +10,27 @@ def get_debug_dir() -> "typing.Union[Path, None]":
     path = Path(value).expanduser()
     path.mkdir(parents=True, exist_ok=True)
     return path
+
+
+def debug(stop: "bool" = False):
+    import socket
+
+    import debugpy
+
+    if debugpy.is_client_connected():
+        return
+    try:
+        host = socket.gethostbyname(socket.getfqdn(socket.gethostname()))
+        port = 5000
+
+        debugpy.listen((host, port), in_process_debug_adapter=False)
+        print("Waiting for debugger...\a")
+        print(f"ip: {host} port:{port}", flush=True)
+        debugpy.wait_for_client()
+        print("Connected.")
+        if stop:
+            debugpy.breakpoint()
+    except Exception as e:
+        import traceback
+
+        print("\n".join(traceback.format_exception(e)))

pycodex/{doctor.py → utils/doctor.py}

@@ -10,9 +10,9 @@ from pathlib import Path
 
 import requests
 
-from .model import ResponsesModelClient, ResponsesProviderConfig
-from .protocol import AssistantMessage, Prompt, UserMessage
-from .utils.dotenv import DOTENV_FILENAME, load_codex_dotenv
+from ..model import ResponsesModelClient, ResponsesProviderConfig
+from ..protocol import AssistantMessage, Prompt, UserMessage
+from .dotenv import DOTENV_FILENAME, load_codex_dotenv
 
 
 @dataclass

pycodex/utils/image_utils.py

@@ -8,6 +8,7 @@ Expected behavior:
   attached to a model request, matching upstream `PromptImageMode::ResizeToFit`.
 - Keep the original bytes when the caller asks for `original` detail or the
   image already fits.
+- Import Pillow only when resizing is requested.
 """
 
 import base64
@@ -16,8 +17,6 @@ import mimetypes
 import typing
 from pathlib import Path
 
-from PIL import Image
-
 MAX_DIMENSION = 2048
 
 _PRESERVABLE_MIME_TYPES = ("image/png", "image/jpeg", "image/webp")
@@ -48,6 +47,8 @@ def _resize_to_fit(
     mime_type: "str",
     image_bytes: "bytes",
 ) -> "typing.Tuple[str, bytes]":
+    from PIL import Image
+
     with Image.open(io.BytesIO(image_bytes)) as image:
         width, height = image.size
         if width <= MAX_DIMENSION and height <= MAX_DIMENSION:

pycodex/{model_metadata.py → utils/model_metadata.py}

@@ -6,9 +6,9 @@ import typing
 from functools import lru_cache
 from pathlib import Path
 
-from .protocol import JSONDict
+from ..protocol import JSONDict
 
-DEFAULT_MODELS_PATH = Path(__file__).resolve().parent / "prompts" / "models.json"
+DEFAULT_MODELS_PATH = Path(__file__).resolve().parents[1] / "prompts" / "models.json"
 
 
 @lru_cache(maxsize=1)

{python_codex-0.3.3.dist-info → python_codex-0.4.0.dist-info}/METADATA

@@ -1,20 +1,17 @@
 Metadata-Version: 2.1
 Name: python-codex
-Version: 0.3.3
+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,6 +22,8 @@ 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).
@@ -33,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,
@@ -61,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
@@ -81,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:
@@ -94,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
@@ -143,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
 
@@ -266,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
@@ -285,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.
@@ -353,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 `$...$`, `$$...$$`,
@@ -466,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
@@ -659,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