python-codex 0.3.0__tar.gz → 0.3.1__tar.gz

{python_codex-0.3.0 → python_codex-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-codex
-Version: 0.3.0
+Version: 0.3.1
 Summary: A minimal Python extraction of Codex's main agent loop
 License-File: LICENSE
 Requires-Python: >=3.6.2
@@ -77,6 +77,32 @@ 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
+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
+chat in the left sidebar using VS Code's stable WebviewView API. Each chat
+creates a workspace session with no code context attached. You can insert code
+from editors, diffs or file-tree selections as editable tokens among your words.
+Each token expands at its position when you send the message.
+Previous chats fold into live status entries; each can be
+reopened or closed, and models can be changed with `/model`.
+Remote workspaces run Python on the remote host. A stdin pipe ties each backend
+to its extension host; normal closure or host failure triggers draining and exit.
+`pycodex-ws` always shuts down on stdin EOF, after accepted work finishes.
+Keep stdin open while running the server; redirecting it from `/dev/null`
+causes the server to shut down.
+Workspace configuration uses a temporary JSON file passed to `--workspace-config`;
+normal backend exit removes the temporary directory.
+The extension uses that host's `~/.codex/config.toml` by default.
+The chat settings menu selects a project venv or another Python interpreter
+and edits the Codex profile. Changes offer a window reload when a backend is
+already running.
+Its context ring shows the same remaining budget and usage details as the
+workspace web frontend.
+See the extension README for building a VSIX, server setup and Remote SSH usage.
+
 ## Design Tradeoffs
 
 This is not a 1:1 port of the Rust implementation. The current goal is a
@@ -111,6 +137,7 @@ nailing the core tool-augmented reasoning loop first.
 - `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
 
 ## Current Alignment Status
@@ -158,6 +185,9 @@ Chained failures also retain `stream_error_cause_type` and, for HTTP errors,
 `stream_error_http_status`; exception messages, headers and URLs are not
 copied into these diagnostic fields.
 
+Downstream errors include elapsed time, timeout, failure stage, response-header
+and first-chunk timing, and received chunk count directly in the error message.
+
 ## Live Model Integration
 
 If this machine already has a Codex CLI configuration, `pycodex` can reuse the
@@ -330,6 +360,15 @@ 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
+- 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
+  before its local tools execute
+- downstream connection failures before HTTP response headers or during SSE
+  reading are converted to `response.failed` for provider retries. Downstream
+  requests honor environment proxies; see the
+  [connection troubleshooting notes](docs/responses_server/README.md#连接排查)
+  for `RemoteDisconnected` and proxy bypass configuration
 - standalone `responses_server` now also supports downstream `/v1/messages`
   backends via `--outcomming-api messages`, while keeping the internal
   canonical request/route logic in chat-completions shape

{python_codex-0.3.0 → python_codex-0.3.1}/README.md

@@ -54,6 +54,32 @@ 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
+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
+chat in the left sidebar using VS Code's stable WebviewView API. Each chat
+creates a workspace session with no code context attached. You can insert code
+from editors, diffs or file-tree selections as editable tokens among your words.
+Each token expands at its position when you send the message.
+Previous chats fold into live status entries; each can be
+reopened or closed, and models can be changed with `/model`.
+Remote workspaces run Python on the remote host. A stdin pipe ties each backend
+to its extension host; normal closure or host failure triggers draining and exit.
+`pycodex-ws` always shuts down on stdin EOF, after accepted work finishes.
+Keep stdin open while running the server; redirecting it from `/dev/null`
+causes the server to shut down.
+Workspace configuration uses a temporary JSON file passed to `--workspace-config`;
+normal backend exit removes the temporary directory.
+The extension uses that host's `~/.codex/config.toml` by default.
+The chat settings menu selects a project venv or another Python interpreter
+and edits the Codex profile. Changes offer a window reload when a backend is
+already running.
+Its context ring shows the same remaining budget and usage details as the
+workspace web frontend.
+See the extension README for building a VSIX, server setup and Remote SSH usage.
+
 ## Design Tradeoffs
 
 This is not a 1:1 port of the Rust implementation. The current goal is a
@@ -88,6 +114,7 @@ nailing the core tool-augmented reasoning loop first.
 - `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
 
 ## Current Alignment Status
@@ -135,6 +162,9 @@ Chained failures also retain `stream_error_cause_type` and, for HTTP errors,
 `stream_error_http_status`; exception messages, headers and URLs are not
 copied into these diagnostic fields.
 
+Downstream errors include elapsed time, timeout, failure stage, response-header
+and first-chunk timing, and received chunk count directly in the error message.
+
 ## Live Model Integration
 
 If this machine already has a Codex CLI configuration, `pycodex` can reuse the
@@ -307,6 +337,15 @@ 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
+- 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
+  before its local tools execute
+- downstream connection failures before HTTP response headers or during SSE
+  reading are converted to `response.failed` for provider retries. Downstream
+  requests honor environment proxies; see the
+  [connection troubleshooting notes](docs/responses_server/README.md#连接排查)
+  for `RemoteDisconnected` and proxy bypass configuration
 - standalone `responses_server` now also supports downstream `/v1/messages`
   backends via `--outcomming-api messages`, while keeping the internal
   canonical request/route logic in chat-completions shape

{python_codex-0.3.0 → python_codex-0.3.1}/README_ZH.md

@@ -82,6 +82,7 @@ uv run pycodex
 - `pycodex/tools/`：具体工具实现
 - `pycodex/agent.py`：主循环
 - `pycodex/runtime.py`：统一会话命令、提交队列和前端事件订阅
+- `extensions/vscode/`：通过 workspace HTTP API 接入的 VS Code 聊天前端
 - `tests/test_agent.py`：核心行为测试
 
 ## 当前对齐状态
@@ -92,6 +93,32 @@ worker 启停及连接清理都由后端统一处理，前端只做输入和展
 Web 不再导入或运行 CLI shell，飞书运行中也能提交 steer 和回答问题。
 IPython 是明确的例外：`ipython_agent()` 仍返回裸 Agent。
 
+VS Code 前端为每个项目在项目所在机器上启动独立的 workspace 后端，通过稳定
+WebviewView 在左侧活动栏的 Pycodex 入口显示聊天。首次使用优先复用已有
+`python-codex>=0.3.1`，版本足够时不联网；缺失或版本太旧时，在对应的 Python
+环境中通过 pip 安装或升级。检查、安装和启动都在工作区所在主机完成。
+新建 session 会展开新会话、
+折叠上一个会话，保留后台任务和草稿；折叠条目继续更新状态，可直接点击展开或关闭。
+每个会话提供 Markdown 回复和固定输入框，新会话默认没有代码上下文，也不绑定源文件。
+需要引用代码时，可从编辑器、Diff（含只读一侧）或文件树/工作树右键插入上下文。
+片段像 emoji 一样插在文字光标处，可点击编辑，也可整体删除或复制粘贴。
+发送时按照文字和片段的原始顺序展开为普通 prompt，后续消息不会自动附加。
+模型名称仅作展示，通过 `/model <name>` 切换模型，
+`/model` 列出可用模型；关闭会话会等待后端正常收尾。隐藏侧边栏只解除订阅。
+后端通过既有 `--workspace-config <path>` 读取临时 JSON 配置文件，正常退出后清理临时目录。
+`pycodex-ws` 默认在 stdin EOF 时排空已接收任务并退出；运行期间须保持 stdin 打开，
+重定向到 `/dev/null` 会触发关闭。扩展通过保持管道打开管理后端生命周期；
+关闭项目或宿主崩溃使管道关闭，插件正常停用会等待退出确认。
+Remote SSH 等远程工作区的 Python 后端在远程服务器上启动；
+短暂断联但远端宿主仍在运行时，会话继续保留。
+默认读取后端所在主机的 `~/.codex/config.toml`，欢迎页会说明这一点。
+聊天栏设置菜单可选择项目 `.venv`、`venv` 或浏览其他 Python 解释器，
+也可修改 Profile；例如 `step` 等价于 `--profile step`。
+已有后端运行时会提示重新加载窗口后生效。输入框底部的 context meter 与 workspace 前端一致，
+可查看剩余比例、最近一次模型上报的用量、压缩阈值和上下文上限。
+构建 VSIX、Python 环境配置及 Remote SSH 用法见
+[`extensions/vscode/README.md`](extensions/vscode/README.md)。
+
 外部程序使用 `pycodex.bootstrap.build_model/build_agent/build_runtime` 装配，
 通过 `await runtime.start()`、`runtime.attach(handler)`、
 `await runtime.submit_input(text, sender)` 和 `await receipt.future` 交互。

{python_codex-0.3.0 → python_codex-0.3.1}/docs/RUNTIME.md

@@ -63,6 +63,7 @@ Session wrapper. Queue data remains internal to Runtime.
 
 ```text
 CLI / Web / Feishu -> AgentRuntime -> Agent
+VS Code -> workspace_server HTTP -> AgentRuntime
 IPython ---------------------------> Agent
 ```
 
@@ -89,6 +90,69 @@ commands and invalid arguments produce explicit command errors. Destructive
 commands reject active or queued work; a command lock serializes asynchronous
 commands and lets close wait for accepted command work.
 
+The [VS Code frontend](../extensions/vscode/README.md) starts a workspace backend
+per project using the existing CLI. Before startup it reads package metadata
+from the selected Python interpreter. Automatic detection resolves an existing
+console script's interpreter or finds Python on the workspace host. A compatible
+`python-codex>=0.3.1` is reused without a network check; missing or older packages
+are installed/upgraded through that interpreter's pip, including the optional
+`pycodex-ws` metapackage when present. It launches `python -m workspace_server`
+with the same interpreter, including when a selected venv initially has no Pycodex.
+Installation finishes before the backend startup deadline starts. Pending
+installs are shared per Python environment, and closing during preparation waits
+for pip before discarding the launch. No private environment is created.
+It uses the backend host's
+`~/.codex/config.toml` by default; the welcome screen explains the local/remote
+configuration source. The header settings menu selects project `.venv`/`venv`
+interpreters or browses for another Python, and edits the Profile name.
+Selections are validated without installing packages and saved to the project's
+`pycodex.pythonPath` and `pycodex.profile` settings. A profile adds
+`--profile <name>` to the launch. Changing either setting through the menu
+offers a window reload if the backend is running; existing sessions keep their
+startup settings until it restarts.
+Sessions have no source-file binding or
+automatically attached editor context. On request, the frontend captures the
+source file, one-based cursor/selection and a bounded editor-buffer excerpt.
+Read-only Git diff documents and Explorer/SCM file selections use VS Code's
+document API. Context appears as atomic tokens interleaved with ordinary text in
+the composer. Insertion uses the saved cursor/selection; clicking a token edits
+its content. Sending expands text and tokens in their original order into the
+ordinary `prompt` field.
+Commands and pending answers use
+the same existing HTTP API.
+Connections are keyed by workspace endpoint and session id.
+Each new chat creates a session; clicking a collapsed entry
+activates that chat. A stable WebviewView in the Pycodex activity-bar container
+displays one expanded chat and collapsed entries for the others, preserving each
+chat's draft. All opened entries retain live status while the
+sidebar is visible; hiding it stops observation without closing sessions.
+Model changes use typed `/model` commands; the model label is read-only.
+Closing an entry uses the existing session DELETE endpoint and waits for normal
+backend draining before removing the entry. HTTP snapshot polling uses the
+existing Web projection. In remote workspaces, the extension host starts Python
+and makes HTTP requests on the remote machine; the webview only exchanges
+messages with the extension host.
+The input footer's context ring uses the existing snapshot fields
+`context_remaining_percent`, `usage_tokens`, `auto_compact_token_limit` and
+`max_context_window`. It shares the Web meter semantics below, including compact
+thresholds, unknown usage and reset after compaction. Hover/focus shows exact
+values, click pins them, and Escape, outside click or session switching closes
+the details. The frontend does not estimate draft tokens or recalculate limits.
+The launcher writes UTF-8 workspace JSON into a private temporary directory
+and passes the filename through the existing `--workspace-config` option.
+It removes that directory after backend exit or failed startup; an abrupt host
+crash can leave the temporary files behind. The `pycodex-ws` CLI always
+shuts down on stdin EOF. Stdin stays open for the backend's lifetime.
+EOF on folder removal, deactivation,
+or extension-host death starts normal server shutdown, including when EOF arrives
+before startup finishes. Accepted turns and queues drain through existing Runtime
+closure; no turn timeout or forced cancellation is added. Deactivation waits for
+all owned processes to exit. A temporary remote disconnection leaves sessions
+running if their extension host remains alive.
+Other CLI launchers must also keep stdin open; closed stdin (including
+`/dev/null`) requests shutdown. Programmatic FastAPI app construction does not
+read stdin.
+
 Web command output preserves the event's plain text, including resume-list
 numbering and line breaks.
 Assistant replies render fenced `mermaid` blocks as diagrams. The browser loads
@@ -111,6 +175,9 @@ updating other tab state. A save targets the edited session even if another
 tab is selected before its response arrives.
 Selected tabs use a tinted background without a click-focus border; keyboard
 focus on the title uses an underline.
+The browser page title gains a `●` prefix while any session in the workspace
+is running, using the same session summaries as the tab activity dots. It returns
+to the original workspace title when all sessions are idle.
 
 The workspace presents assistant replies as open text and user messages as
 right-aligned bubbles. Commands and thinking use quieter secondary styling;
@@ -182,7 +249,13 @@ own; unlinking a Feishu card only detaches that frontend. Web submits directly
 to the backend, including across its worker-thread boundary: it does not run a
 CLI shell or maintain an extra prompt queue.
 
-Workspace tab persistence follows recording changes as well as explicit titles.
+Workspace state stores every open tab in order, starting when the tab is created.
+An empty tab stores an empty title and rollout path, so restoring it creates a
+fresh empty session without writing a rollout. Manual titles and first messages
+are not prerequisites for keeping a tab across a server restart. Changes to
+automatic or explicit titles and recorded paths update the same saved tab.
+Startup restores the full tab list before saving it; closing a tab removes its
+entry.
 Once a fork's first turn or successful compact creates its rollout, the saved tab
 points to that file, including when the model subsequently fails. Before the
 file exists, the tab stores the recorded ancestor's path with an explicit
@@ -532,7 +605,8 @@ context; `ResponsesModelClient.model` uses the same provider config as metadata.
 
 Only the Responses provider classifies external error text:
 
-- Transient/disconnected streams use `ResponsesRetryableError`.
+- Transient/disconnected streams and retryable `response.failed` events
+  use `ResponsesRetryableError`.
 - Context overflow uses `ContextLengthExceeded`, with optional usage and limit
   parsed from the provider's error details.
 - A genuine terminal incomplete response uses `ResponsesIncompleteError` and
@@ -540,6 +614,22 @@ Only the Responses provider classifies external error text:
 
 Custom clients must raise the corresponding exception rather than rely on
 arbitrary `RuntimeError` text being reinterpreted by the Agent or compactor.
+
+The local `responses_server` validates ordinary function-call arguments after
+assembling the downstream stream. Malformed JSON produces `response.failed` with
+`type = "server_error"` before any final output items are emitted. The error names
+the tool and JSON parsing failure without including raw arguments.
+`ResponsesModelClient` handles this through its generic provider error path and
+retries only the current request under `stream_max_retries`; it does not classify
+tool argument parse failures as retryable locally. Earlier completed tools stay
+in history and retries do not restart the turn. Valid JSON that decodes to a
+non-object still raises a terminal API error; freeform/custom tool inputs remain
+plain text.
+
+Assistant message text remains text, including content that resembles a tool
+call. Tool parse errors require a structured tool item or an explicit provider
+error; the client does not infer them from patterns in assistant prose.
+
 For max-output incomplete responses, the Agent persists done assistant/reasoning
 items for continuation, but not bare text deltas or tool calls without results.
 

{python_codex-0.3.0 → python_codex-0.3.1}/docs/responses_server/README.md

@@ -35,8 +35,9 @@ prompt 渲染路径一致，也保留 provider 自定义 effort 值（例如 `ma
 - vLLM 历史 `reasoning` item -> assistant message `reasoning` 字段回放
 - vLLM streaming `usage` -> final `response.completed.response.usage`
 - 当环境变量 `PYCODEX_DUMP` 存在时，为每条 outcomming 请求附加 `return_token_ids = true`，并把实际下发的 request body、下游 usage/cache、`prompt_token_ids` / `token_ids` 以 JSONL 追加到 `{PYCODEX_DUMP}/dump.jsonl`
-- 下游 chat stream 如果半路断开，会转成上游可解析的 `response.failed` 事件，而不是直接截断 HTTP body
+- 下游请求在等待响应头或读流时失败，会返回 `response.failed`，错误直接包含耗时、timeout、失败阶段、响应头/首个 chunk 的时间和 chunk 数量
 - 普通 function tools
+- 普通 function-call 参数拼接完成后校验 JSON；解析失败返回 `response.failed(type=server_error)`，由客户端按现有策略重试
 - custom tools 的 function-wrapper 兼容适配
 - mock `web_search` 接口对齐（返回空结果）
 - function / custom tool follow-up history 重建
@@ -123,6 +124,14 @@ template 不消费 `developer` role；使用该模板的 provider 应显式配
 length-stopped thinking 被持久化成 terminal reasoning-only history，并在下一轮转换成
 下游 chat 后端不接受的裸 assistant message。
 
+普通 function-call 的 `arguments` 在拼接完成后由 server 校验 JSON。解析失败时，
+server 在发出本次最终 output items 之前返回 `response.failed(type=server_error)`；
+错误只包含工具名和解析位置，不包含原始参数。`ResponsesModelClient` 通过通用
+`response.failed` 处理按 `stream_max_retries` 重试当前请求，默认最多重试 5 次。
+这条路径不增加 server 内部重试，也不把本次失败响应里的工具交给 Agent 执行。
+合法 JSON 的内容保持原样；非 object 的参数仍由客户端按既有契约报错。
+custom/freeform 工具继续使用原有适配流程，assistant 正文也继续作为文本处理。
+
 `messages` compat 则故意不改这层 canonical request：仍然先构造 chat 风格
 `outcomming_request`，只有在真正发请求和读 SSE 时，才在边界把它翻译成
 messages request / event。这样 tool hydration、mock `web_search`
@@ -132,6 +141,11 @@ follow-up、provider payload post-process 仍然复用同一套主逻辑。
 `max_tokens`，则优先透传上游请求里的 `max_output_tokens` / `max_tokens`；
 如果上游没给，当前默认补 `32000`，避免直接被下游 `400` 拒绝。
 
+下游失败无需开启调试模式。正常错误里的 `phase=waiting_response_headers`
+表示尚未收到响应头，`waiting_first_chunk` 表示响应头已到但尚无完整 chunk，
+`reading_stream` 表示流已开始；`elapsed` 是本次请求耗时，`idle` 是距离
+最近一个完整 chunk 的时间。SSE 心跳不计入 chunk 数。
+
 ## 验证
 
 当前独立测试：

{python_codex-0.3.0 → python_codex-0.3.1}/packages/pycodex-ws/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycodex-ws"
-version = "0.3.0"
+version = "0.3.1"
 description = "Browser workspace install alias for python-codex"
 readme = "README.md"
 requires-python = ">=3.6.2"
 dependencies = [
-    "python-codex==0.3.0",
+    "python-codex==0.3.1",
 ]
 
 [tool.hatch.build.targets.wheel]