PyPI - python-codex - Versions diffs - 0.2.6__tar.gz → 0.2.7__tar.gz - Mend

python-codex 0.2.6tar.gz → 0.2.7tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (130) hide show

{python_codex-0.2.6 → python_codex-0.2.7}/.github/workflows/publish.yml RENAMED Viewed

@@ -54,7 +54,10 @@ jobs:
     steps:
       - name: Install system dependencies
         run: |
-          apt-get update
+          printf '%s\n' \
+            'deb [check-valid-until=no] https://archive.debian.org/debian bullseye main' \
+            > /etc/apt/sources.list
+          apt-get -o APT::Update::Error-Mode=any update
           apt-get install -y --no-install-recommends git nodejs npm
       - name: Check out repository
@@ -80,7 +83,8 @@ jobs:
             "requests>=2.27.1" \
             "prompt-toolkit>=3.0.36,<3.1" \
             "loguru>=0.7.3,<1" \
-            "cryptography>=40.0.2,<41" \
+            "pycryptodomex>=3.20" \
+            "pillow>=8.4.0,<9" \
             "fastapi>=0.83,<0.84" \
             "uvicorn>=0.16,<0.17" \
             "pytest>=6.2.5,<7" \

{python_codex-0.2.6 → python_codex-0.2.7}/.github/workflows/test.yml RENAMED Viewed

@@ -44,7 +44,10 @@ jobs:
     steps:
       - name: Install system dependencies
         run: |
-          apt-get update
+          printf '%s\n' \
+            'deb [check-valid-until=no] https://archive.debian.org/debian bullseye main' \
+            > /etc/apt/sources.list
+          apt-get -o APT::Update::Error-Mode=any update
           apt-get install -y --no-install-recommends git nodejs npm
       - name: Check out repository
@@ -70,7 +73,8 @@ jobs:
             "requests>=2.27.1" \
             "prompt-toolkit>=3.0.36,<3.1" \
             "loguru>=0.7.3,<1" \
-            "cryptography>=40.0.2,<41" \
+            "pycryptodomex>=3.20" \
+            "pillow>=8.4.0,<9" \
             "fastapi>=0.83,<0.84" \
             "uvicorn>=0.16,<0.17" \
             "pytest>=6.2.5,<7" \

{python_codex-0.2.6 → python_codex-0.2.7}/AGENTS.md RENAMED Viewed

@@ -19,7 +19,7 @@
 - `responses_server` 如果要兼容下游 `/v1/messages`，也优先保持这条边界：内部继续用 canonical chat request / chat-like chunk 流，只有真正发请求和读取 SSE 时才做 messages 适配，这样 tool hydration、mock `web_search` follow-up、provider payload post-process 都能复用。
 - 真实 vLLM `0.19.0` 的 `/v1/messages` 会对缺失 `max_tokens` 直接返回 `400`；messages 适配层必须总是补这个字段。当前约定是优先透传请求里的 `max_output_tokens`/`max_tokens`，否则回退到默认 `32000`。
 - 对 vLLM chat-completions 打开 `return_token_ids=true` 时，streaming `prompt_token_ids` 只出现在首个 chunk，后续每个 chunk 的 `choices[*].token_ids` 都是 decode delta；要在 `responses_server` 侧导出 trajectory 时，按“首个 `prompt_token_ids` + 按序拼接所有 chunk 的 `token_ids`”重建即可。
-- `pycodex` 默认是最小交互 CLI；无 prompt 时进入 REPL，并通过 `AgentRuntime` 跑外层提交循环。当前会显示最小事件流、assistant 流式输出、简单 title/history（`/title`, `/history`），并默认注册一组与原版一一对应的本地工具子集。
+- `pycodex` 默认是最小交互 CLI；无 prompt 时进入 REPL，并通过 `AgentRuntime` 跑外层提交循环。当前会显示最小事件流、assistant 流式输出、简单 title/history（`/title`, `/history`），并默认注册上游对齐工具子集和明确标记的本地扩展。
 - Web workspace lives in the standalone `workspace_server/` package and is launched with `pycodex-ws --listen <host:port> --board <html>`, not through `pycodex` CLI dispatch. CLI and web share `pycodex.interactive_session.run_interactive_session`; slash-command semantics such as `/resume`, `/compact`, `/model`, and `/link` belong to that shared interactive shell loop, while workspace only supplies a web view/input adapter and tab/session lifecycle.
 - Relative images in board HTML resolve to HTTP siblings such as `/w/<workspace-id>/<image>` (or `/<image>` in single-workspace mode), not to `/board/...`. Keep the image fallback routes after concrete workspace/API routes, resolve files from the board's directory, and reject non-`image/*` files or paths that escape that directory.
 - 交互 CLI 的事件流展示优先表达用户可感知的阶段（例如工具开始/完成、模型回看工具结果），不要直接把内部 `iteration` 计数暴露成主要状态文案；`iterations` 应继续保留在 `TurnResult` 等程序化结果里。
@@ -33,7 +33,7 @@
 - `README.md` 和 `docs/` 属于对齐工作的一部分：只要实现状态、对齐结论或使用方式发生实质变化，就应及时更新，不要让文档滞后于当前代码。
 - 新工具必须继承 `BaseTool`，然后通过 `ToolRegistry.register(tool_instance)` 接入；不要再给 registry 传散装 name/description/handler 参数。
 - request/tool schema 对齐应落在实际建模层（`ToolSpec` / `BaseTool` / request builder）本身，不要再引入 prompt 级别的 `serialized_tools` 旁路覆盖。
-- 当前已接入的内置工具子集：`shell`、`shell_command`、`exec_command`、`write_stdin`、`exec`、`wait`、`web_search`、`update_plan`、`request_user_input`、`request_permissions`、`spawn_agent`、`send_input`、`resume_agent`、`wait_agent`、`close_agent`、`apply_patch`、`grep_files`、`read_file`、`list_dir`、`view_image`。后续继续新增时，仍然按原版 Codex 内置工具逐个补齐。
+- 当前已接入的默认工具集：`shell`、`shell_command`、`exec_command`、`write_stdin`、`clock`、`exec`、`wait`、`web_search`、`update_plan`、`request_user_input`、`request_permissions`、`spawn_agent`、`send_input`、`resume_agent`、`wait_agent`、`close_agent`、`apply_patch`、`grep_files`、`read_file`、`list_dir`、`view_image`。其中 `clock` 是明确的 pycodex 扩展；其余新增工具仍优先逐个对齐原版 Codex。
 - `exec_command` / `write_stdin` 的 unified-exec 对齐要注意两层默认截断语义：省略 `max_output_tokens` 时也要按 upstream 默认 `10_000` token 预算裁剪 tool response；同时长时间未轮询的未读输出缓冲不能无限累积，需保留 upstream 同款 `1 MiB` head/tail。
 - 当前协议层已经支持两类原版工具载荷：普通 function tools，以及 `apply_patch` 这类 freeform/custom tools；工具结果也支持结构化 `input_image` content items，用于 `view_image` 这类会把图片喂回模型的工具。
 - 当前本地 runtime 已支持一个最小的 in-process sub-agent 管理层：`spawn_agent` / `send_input` / `resume_agent` / `wait_agent` / `close_agent` 通过共享的 `SubAgentManager` 驱动新的 `AgentRuntime` 实例，不依赖 CLI harness 自带的多 agent 基础设施。
@@ -41,7 +41,7 @@
 - `request_user_input` 对齐上游时要注意两层：Default mode 默认返回固定错误 `request_user_input is unavailable in Default mode`；Plan mode happy path 则要求每个问题都有非空 `options`、handler 会补 `isOther=true`，并把结构化答案序列化成 JSON 字符串加 `success=true` 塞回 `function_call_output`。
 - 在 `/data/pycodex` 本机已安装的 `codex-cli 0.115.0` 上，用 `tests/compare_request_user_input_roundtrip.py` 做 Plan-mode deterministic proxy live capture 时，upstream 的 second request `function_call_output` 当前不带 `success`；而 GitHub `openai/codex` `main` 源码里的 `FunctionCallOutputPayload` / `request_user_input` handler 支持传递 `success`。写对齐结论时要明确区分“installed CLI live capture”与“upstream main 源码建模”。
 - 当前 `exec` / `wait` 已有一个最小 code-mode 实现：底层通过 Node 子进程运行 JavaScript，自带 `text` / `image` / `store` / `load` / `exit` / `notify` / `yield_control` helper，并允许通过 `tools.<name>(...)` 调回本地已注册工具；`web_search` 当前作为 Responses API provider-native tool declaration 暴露给模型，不经过本地 ToolRegistry 执行。
-- 我们支持的 tools 必须和原版 Codex 内置 tools 一一对应：名称、定位、参数形状、交互模型、输出语义都应尽量对齐；不要混合多个原版工具的语义做一个“折中工具”。
+- 除明确记录的 pycodex 扩展（当前为 `clock`）外，我们支持的 tools 必须和原版 Codex 内置 tools 一一对应：名称、定位、参数形状、交互模型、输出语义都应尽量对齐；不要混合多个原版工具的语义做一个“折中工具”。
 - 代码风格上不要使用 `*` 定义 keyword-only 参数；接口默认允许位置参数。
 - runtime 包和会在 import 阶段执行的测试辅助代码需要保持 Python 3.6.2 语法兼容；不要引入 walrus `:=`、`match` 等仅 3.8+/3.10+ 可解析的新语法，哪怕分支在运行时不会走到。
 - 本仓库使用 `uv`；本地默认没有预装测试依赖，开始工作前先跑 `uv sync --dev`，验证用 `uv run pytest`。
@@ -62,6 +62,7 @@
 - 对接真实 `~/.codex/sessions/.../rollout-*.jsonl` 时，不要假设它一定是严格的一行一个 JSON object：本机样本可能包含 pretty-printed 多行对象，且文件尾部偶尔带未完成记录。恢复历史时用 concatenated-JSON 方式读取，并容忍尾部残缺。
 - `pycodex` 本地 session 保存现在也按上游思路走：新 session 一开始就分配稳定的 uuidv7 thread/session id，并把历史增量追加到 `CODEX_HOME/sessions/.../rollout-*.jsonl`；`/resume` 列表应只展示至少有真实 user message 的 rollout，避免空白新 session 污染恢复列表。
 - auto-compact 对齐上游配置名 `model_auto_compact_token_limit`；为空时关闭，触发依据是最近一次模型上报的 `usage.total_tokens`，pre-turn 压缩上一轮历史，mid-turn 压缩工具 follow-up 前的当前历史，并继续复用现有 compacted rollout 记录。
+- Local compact templates intentionally diverge from upstream: the prompt explicitly preserves the latest real user request/language, and the summary prefix tells the next model to continue instead of merely acknowledging the handoff. Do not mechanically replace these additions with `codex-rs/core/templates/compact/{prompt.md,summary_prefix.md}`. Real `compacted` rollout entries remain append-only checkpoints whose `replacement_history` can be summary-only; the old transcript stays on disk for audit but is not part of the next active prompt.
 - Responses streaming 里的 `response.incomplete` 不是连接断开：不要让 `ResponsesModelClient` 把它当 retryable incomplete stream 反复重连。普通 turn 应明确报 `response.incomplete`；compact 请求如果已经收到 assistant partial summary，可以用这个 partial summary 完成 replacement history，避免 midturn auto-compact 卡在 5 次 retry。
 - 上游 Codex Responses 请求当前不传模型级 `max_output_tokens`，也没有读取 `model_max_output_tokens` 这个 config key；这个名字在上游主要用于工具输出截断，不要为了上游对齐把它加进模型请求。
 - `service_tier = "fast"` 在 config 中是 Fast mode 的持久写法，但 Responses wire 值是 `priority`；只对模型 metadata 的 `service_tiers` 明确包含该 id 的模型发送，`default` 和不支持的 tier 都省略。
@@ -69,4 +70,5 @@
 - Feishu card tests read `~/.codex/.feishu_refresh_token` through production code; when running `tests/test_feishu_card.py` locally, isolate HOME (for example `HOME=/tmp/pycodex-empty-home env -u VIRTUAL_ENV uv run pytest tests/test_feishu_card.py tests/test_feishu_link.py`) unless the test itself controls `HOME`.
 - `lark_oapi.ws.client` creates a module-level asyncio `loop` at import time and `Client.start()` always uses that global. For `/link` long-connection listeners, bind that SDK global to a listener-thread-owned loop before constructing the client, and stop it through private `_disconnect()` plus `loop.stop()` on `/unlink`; otherwise unlink/link can reuse a still-running SDK loop and fail with `RuntimeError: This event loop is already running`.
 - `exec_command` background completion auto-resume is intentionally Agent-idle-only: when a session exits, it may call `Agent.maybe_invoke(...)` and start a synthetic `<exec_command_completed>` turn only if that Agent is not already running a turn. Do not enqueue/cache these events in `CliSubmissionQueue`; direct Agent/IPython use should share the same Agent-level hook.
+- `clock` is a per-Agent/session pycodex extension with one global period value. Reuse `Agent.maybe_invoke(...)` for `<clock_tick>` wake-ups and include the timezone-aware ISO 8601 `current_time` captured when the timer expires: cancel the pending countdown when any turn starts, restart it only after a successful reply, and cancel it on `clock(null)` or runtime shutdown. Terminal events expose only aggregate `background_work_count`, which includes running exec sessions and an enabled clock after a successful reply; CLI/workspace idle status should use that single field. Do not add a second submission queue or shell-based sleep loop.
 - The tool description JSON fallbacks (`pycodex/prompts/exec_tools.json` and `pycodex/prompts/subagent_tools.json`) were deleted after moving schemas into class-level `BaseTool` specs. `ToolSpec.serialize()` intentionally skips function-tool `output_schema`, matching upstream `ResponsesApiTool.output_schema #[serde(skip)]`; keep output schemas as local metadata only unless upstream wire format changes.

{python_codex-0.2.6 → python_codex-0.2.7}/PKG-INFO RENAMED Viewed

@@ -1,17 +1,18 @@
 Metadata-Version: 2.1
 Name: python-codex
-Version: 0.2.6
+Version: 0.2.7
 Summary: A minimal Python extraction of Codex's main agent loop
 License-File: LICENSE
 Requires-Python: >=3.6.2
-Requires-Dist: cryptography<41,>=40.0.2; python_version < '3.7'
-Requires-Dist: cryptography>=40.0.2; python_version >= '3.7'
 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: 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'
@@ -254,17 +255,29 @@ Current behavior:
   later steer text is appended to the next model request's `input` in order;
   for explicit queueing, use `/queue <message>`, which prints
   `[steer] queued: ...` and later `[steer] inserted: ...`
-- the default built-in tool subset currently exposed as local tools is:
-  `shell`, `shell_command`, `exec_command`, `write_stdin`, `exec`, `wait`,
-  `web_search`, `update_plan`, `request_user_input`, `request_permissions`,
-  `spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, `close_agent`,
-  `apply_patch`, `grep_files`, `read_file`, `list_dir`, `view_image`
+- the default local tool set includes the upstream-aligned subset plus the
+  pycodex `clock` extension: `shell`, `shell_command`, `exec_command`,
+  `write_stdin`, `clock`, `exec`, `wait`, `web_search`, `update_plan`,
+  `request_user_input`, `request_permissions`, `spawn_agent`, `send_input`,
+  `resume_agent`, `wait_agent`, `close_agent`, `apply_patch`, `grep_files`,
+  `read_file`, `list_dir`, `view_image`
+- `clock(period_m)` sets one periodic clock for the current Agent session;
+  `null` cancels it. The countdown restarts after each reply and wakes the
+  Agent with a `<clock_tick>` message containing the current timezone-aware
+  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
 - `--vllm-endpoint http://host:port` automatically launches a local
   `responses_server` compatibility layer; when the URL path is empty it is
   normalized to `/v1`, and `/responses` requests are still forwarded to the
-  downstream `/v1/chat/completions` endpoint. For `model_provider = "vllm"`,
-  reasoning is now preserved across this path: chat chunks with `reasoning` or
-  `reasoning_content` are translated back into Responses `reasoning` items, and
+  downstream `/v1/chat/completions` endpoint. This local compat path always
+  uses the canonical Responses request shape, even when the selected model's
+  metadata enables `responses_lite`. With `--vllm-endpoint`, startup also reads
+  `/v1/models` and uses the last returned model id for the downstream request.
+  For `model_provider = "vllm"`, reasoning is preserved across this path:
+  chat chunks with `reasoning` or `reasoning_content` are translated back into
+  Responses `reasoning` items, and
   historical `reasoning` items are replayed into downstream assistant messages
   via the `reasoning` field. Streaming token usage is also requested from vLLM
   and forwarded to the final `response.completed.response.usage`. If a
@@ -408,6 +421,7 @@ Upstream low-frequency / special-mode tools not yet modeled separately:
 Repository-specific compatibility / transition tools:
+- [x] `clock` - pycodex periodic Agent wake-up extension.
 - [x] `exec` - current local approximation of code mode.
 - [x] `wait` - current local approximation of code-mode waiting behavior.
@@ -422,8 +436,8 @@ Repository-specific compatibility / transition tools:
   matches upstream.
 - [x] `AGENTS.md` + `<environment_context>` injection alignment - context
   assembly order matches upstream.
-- [x] non-interactive `exec` tool subset alignment - the model-visible tool set
-  has converged.
+- [x] non-interactive `exec` upstream tool subset alignment - the aligned
+  subset has converged; pycodex additionally exposes `clock`.
 - [x] `include = ["reasoning.encrypted_content"]` - reasoning include field is
   aligned.
 - [x] `prompt_cache_key` - request-level prompt cache key is implemented.
@@ -432,8 +446,8 @@ Repository-specific compatibility / transition tools:
 - [x] `originator` - mode-aware originator header is implemented.
 - [x] exact `user-agent` string alignment - aligned on the non-interactive
   `exec` path.
-- [x] field-by-field exec-mode tool schema alignment - currently reuses the
-  upstream snapshot directly through the tool layer.
+- [x] field-by-field upstream exec-mode tool schema alignment - aligned tools
+  use class-level specs; `clock` is documented separately as an extension.
 - [ ] full interactive-mode and non-`exec` behavior alignment - the non-exec
   first-turn context is now on the `codex-tui` path, but continuous REPL
   multi-turn behavior is not fully verified yet.

{python_codex-0.2.6 → python_codex-0.2.7}/README.md RENAMED Viewed

@@ -233,17 +233,29 @@ Current behavior:
   later steer text is appended to the next model request's `input` in order;
   for explicit queueing, use `/queue <message>`, which prints
   `[steer] queued: ...` and later `[steer] inserted: ...`
-- the default built-in tool subset currently exposed as local tools is:
-  `shell`, `shell_command`, `exec_command`, `write_stdin`, `exec`, `wait`,
-  `web_search`, `update_plan`, `request_user_input`, `request_permissions`,
-  `spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, `close_agent`,
-  `apply_patch`, `grep_files`, `read_file`, `list_dir`, `view_image`
+- the default local tool set includes the upstream-aligned subset plus the
+  pycodex `clock` extension: `shell`, `shell_command`, `exec_command`,
+  `write_stdin`, `clock`, `exec`, `wait`, `web_search`, `update_plan`,
+  `request_user_input`, `request_permissions`, `spawn_agent`, `send_input`,
+  `resume_agent`, `wait_agent`, `close_agent`, `apply_patch`, `grep_files`,
+  `read_file`, `list_dir`, `view_image`
+- `clock(period_m)` sets one periodic clock for the current Agent session;
+  `null` cancels it. The countdown restarts after each reply and wakes the
+  Agent with a `<clock_tick>` message containing the current timezone-aware
+  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
 - `--vllm-endpoint http://host:port` automatically launches a local
   `responses_server` compatibility layer; when the URL path is empty it is
   normalized to `/v1`, and `/responses` requests are still forwarded to the
-  downstream `/v1/chat/completions` endpoint. For `model_provider = "vllm"`,
-  reasoning is now preserved across this path: chat chunks with `reasoning` or
-  `reasoning_content` are translated back into Responses `reasoning` items, and
+  downstream `/v1/chat/completions` endpoint. This local compat path always
+  uses the canonical Responses request shape, even when the selected model's
+  metadata enables `responses_lite`. With `--vllm-endpoint`, startup also reads
+  `/v1/models` and uses the last returned model id for the downstream request.
+  For `model_provider = "vllm"`, reasoning is preserved across this path:
+  chat chunks with `reasoning` or `reasoning_content` are translated back into
+  Responses `reasoning` items, and
   historical `reasoning` items are replayed into downstream assistant messages
   via the `reasoning` field. Streaming token usage is also requested from vLLM
   and forwarded to the final `response.completed.response.usage`. If a
@@ -387,6 +399,7 @@ Upstream low-frequency / special-mode tools not yet modeled separately:
 Repository-specific compatibility / transition tools:
+- [x] `clock` - pycodex periodic Agent wake-up extension.
 - [x] `exec` - current local approximation of code mode.
 - [x] `wait` - current local approximation of code-mode waiting behavior.
@@ -401,8 +414,8 @@ Repository-specific compatibility / transition tools:
   matches upstream.
 - [x] `AGENTS.md` + `<environment_context>` injection alignment - context
   assembly order matches upstream.
-- [x] non-interactive `exec` tool subset alignment - the model-visible tool set
-  has converged.
+- [x] non-interactive `exec` upstream tool subset alignment - the aligned
+  subset has converged; pycodex additionally exposes `clock`.
 - [x] `include = ["reasoning.encrypted_content"]` - reasoning include field is
   aligned.
 - [x] `prompt_cache_key` - request-level prompt cache key is implemented.
@@ -411,8 +424,8 @@ Repository-specific compatibility / transition tools:
 - [x] `originator` - mode-aware originator header is implemented.
 - [x] exact `user-agent` string alignment - aligned on the non-interactive
   `exec` path.
-- [x] field-by-field exec-mode tool schema alignment - currently reuses the
-  upstream snapshot directly through the tool layer.
+- [x] field-by-field upstream exec-mode tool schema alignment - aligned tools
+  use class-level specs; `clock` is documented separately as an extension.
 - [ ] full interactive-mode and non-`exec` behavior alignment - the non-exec
   first-turn context is now on the `codex-tui` path, but continuous REPL
   multi-turn behavior is not fully verified yet.

{python_codex-0.2.6 → python_codex-0.2.7}/README_ZH.md RENAMED Viewed

@@ -157,8 +157,11 @@ pycodex doctor
   刚结束的 history fork 成一个不落盘的临时 follow-up 会话，并把文件内容作为下一条
   user 指令提交；适合做 Feishu 通知这类副作用收尾动作
 - 交互模式默认支持 steer：普通输入会走 runtime 的 steer 路径，当前请求会在下一个安全边界尽快停下，后续 steer 文本会按顺序并入下一次模型请求的 `input`；如需明确排队可用 `/queue <message>`，会打印 `[steer] queued: ...`，随后等该 turn 真正开始时再打印 `[steer] inserted: ...`
-- 当前默认注册一组与原版 Codex 一一对应的本地工具子集：`shell`、`shell_command`、`exec_command`、`write_stdin`、`exec`、`wait`、`web_search`、`update_plan`、`request_user_input`、`request_permissions`、`spawn_agent`、`send_input`、`resume_agent`、`wait_agent`、`close_agent`、`apply_patch`、`grep_files`、`read_file`、`list_dir`、`view_image`
-- `--vllm-endpoint http://host:port` 会自动拉起一个本地 `responses_server` compat 层；当 path 为空时会内部补 `/v1`，继续把 `/responses` 请求转到下游 `/v1/chat/completions`。当前对 `model_provider = "vllm"` 已补上 reasoning 兼容：会把 chat chunk 里的 `reasoning` / `reasoning_content` 翻回 Responses `reasoning` item，并把历史里的 `reasoning` item 回放成下游 assistant message 的 `reasoning` 字段；同时会向 vLLM 请求 streaming usage，并在最终 `response.completed.response.usage` 中回传
+- 当前默认工具集由上游对齐子集和 pycodex 的 `clock` 扩展组成：`shell`、`shell_command`、`exec_command`、`write_stdin`、`clock`、`exec`、`wait`、`web_search`、`update_plan`、`request_user_input`、`request_permissions`、`spawn_agent`、`send_input`、`resume_agent`、`wait_agent`、`close_agent`、`apply_patch`、`grep_files`、`read_file`、`list_dir`、`view_image`
+- `clock(period_m)` 为当前 Agent session 设置一个周期计时器，传 `null` 取消；每次回复后重新计时，到期后用包含当前时区时间的 `<clock_tick>` 消息唤醒 Agent
+- 后台命令或 clock 正在等待时，空闲状态统一显示为 `idle: sleeping`
+- workspace 只在当前活动 tab 上显示关闭按钮
+- `--vllm-endpoint http://host:port` 会自动拉起一个本地 `responses_server` compat 层；当 path 为空时会内部补 `/v1`，继续把 `/responses` 请求转到下游 `/v1/chat/completions`。这条本地 compat 路径始终使用标准 Responses request shape，即使所选模型的 metadata 打开了 `responses_lite` 也不会切换成 lite wire format；启动时还会读取下游 `/v1/models`，自动使用返回列表中的最后一个 model id。当前对 `model_provider = "vllm"` 已补上 reasoning 兼容：会把 chat chunk 里的 `reasoning` / `reasoning_content` 翻回 Responses `reasoning` item，并把历史里的 `reasoning` item 回放成下游 assistant message 的 `reasoning` 字段；同时会向 vLLM 请求 streaming usage，并在最终 `response.completed.response.usage` 中回传
 - `pycodex doctor` 会检查配置、`.env`、API key、DNS、TCP/TLS，以及可选的 live Responses API 请求
 它目前主要用于：
@@ -280,6 +283,7 @@ asyncio.run(main())
 本仓库额外兼容层 / 过渡工具：
+- [x] `clock` — pycodex 的周期性 Agent 唤醒扩展。
 - [x] `exec` — 当前对 code-mode 的本地近似实现。
 - [x] `wait` — 当前对 code-mode 等待行为的本地近似实现。
@@ -290,13 +294,13 @@ asyncio.run(main())
 - [x] 非交互 `exec` 路径的 `input` 对齐 — prompt input 已对齐上游。
 - [x] developer/contextual-user message 的 shape 对齐 — message/content 结构已对齐。
 - [x] `AGENTS.md` + `<environment_context>` 注入逻辑对齐 — 上下文拼接顺序已对齐。
-- [x] 非交互 `exec` 路径的工具子集对齐 — 暴露给模型的工具集合已收敛。
+- [x] 非交互 `exec` 路径的上游工具子集对齐 — 对齐子集已收敛；pycodex 额外暴露 `clock`。
 - [x] `include = ["reasoning.encrypted_content"]` — reasoning include 字段已对齐。
 - [x] `prompt_cache_key` — 请求级 prompt cache key 已补齐。
 - [x] `x-client-request-id` — 请求 id header 已补齐。
 - [x] `x-codex-turn-metadata` — turn id / sandbox header 已补齐。
 - [x] `originator` — mode-aware originator header 已补齐。
 - [x] `user-agent` 精确字符串对齐 — 非交互 `exec` 路径已对齐上游字符串。
-- [x] exec-mode tool schema 的逐字段对齐 — 当前通过工具层直接复用上游 snapshot。
+- [x] 上游 exec-mode tool schema 的逐字段对齐 — 对齐工具使用类内 spec；`clock` 作为扩展单独记录。
 - [ ] 交互模式与非 `exec` 路径的完整行为对齐 — non-exec 首轮 context 已切到 `codex-tui` 路径，但 REPL 连续多轮行为还未完全验证。
 - [ ] sandbox / approvals / compact / memory 等外围行为对齐 — 外围系统仍在后续范围。

{python_codex-0.2.6 → python_codex-0.2.7}/docs/ALIGNMENT.md RENAMED Viewed

@@ -126,9 +126,10 @@ At the time of writing:
 - class-level tool descriptions, input schemas, output schemas, and notable
   runtime result shapes have been refreshed across the default local tool set
-The current implementation already matches:
+The current upstream-aligned subset already matches:
-- exec-mode tool subset size and membership for the compared path
+- exec-mode upstream tool subset membership for the compared path; pycodex
+  additionally inserts its `clock` extension after `write_stdin`
 - `include = ["reasoning.encrypted_content"]`
 - model-visible prompt fields (`instructions` and `input`)
 - request-scoped `prompt_cache_key`
@@ -194,6 +195,8 @@ schema 一致的工具有：
   schema 对齐。
 - `request_user_input`：`pycodex` 按 upstream source main 建模，带
   `autoResolutionMs`；installed `codex-cli 0.138.0` 的 live capture 仍未带该字段。
+- `clock`：pycodex 特有的 per-Agent/session 周期唤醒扩展，不属于 upstream
+  schema 对齐集合。
 - `spawn_agent` / `send_input` / `resume_agent` / `wait_agent` /
   `close_agent`：upstream 当前首轮 request 不再平铺暴露这些工具，而是暴露
   `tool_search`，并由 deferred discovery 加载 Multi-agent tools。`pycodex` 仍在首轮
@@ -375,6 +378,7 @@ schema 一致的工具有：
 | `shell_command` | `not exposed` | `class aligned` | 默认首轮路径不带；类内 desc/schema 已刷新为 shell-string command 语义 |
 | `exec_command` | `intentional approval-field/description delta; round-trip same` | `class aligned except skipped auth + local idle resume` | 删除 fallback 后不再暴露 `sandbox_permissions` / `justification` / `prefix_rule`，这是 pycodex 刻意跳过鉴权逻辑的差异；description 额外提示长任务可以先回复用户，任务完成时 agent 会被 invoke 来继续处理；其余参数按 schema 执行，`function_call` / `function_call_output` 外层 shape 一致；默认 `10_000` token 截断和未读输出 `1 MiB` head/tail cap 已补齐，仅剩动态值差异 |
 | `write_stdin` | `first-request same; round-trip same` | `class aligned` | 删除 fallback 后首轮 schema 相等；`function_call` / `function_call_output` 外层 shape 一致；默认 `10_000` token 截断和未读输出 `1 MiB` head/tail cap 已补齐，仅剩动态值差异 |
+| `clock` | `pycodex-only` | `local extension` | 每个 Agent/session 一个周期计时器；每次成功回复后重新计时，到期复用 Agent idle auto-resume 注入带 `current_time` 的 `<clock_tick>`，传 `null` 或关闭 session 时取消 |
 | `exec` | `not exposed` | `class aligned` | 默认首轮路径不带；code-mode custom/freeform desc 和 grammar 已刷新，仍需 code-mode request-visible 抓包复测 |
 | `wait` | `not exposed` | `class aligned` | 默认首轮路径不带；code-mode wait schema/runtime 已刷新，仍需 code-mode request-visible 抓包复测 |
 | `web_search` | `first-request same; round-trip same` | `class aligned` | 删除 fallback 后 provider-native payload 相等，包含 `search_content_types=["text","image"]`；`web_search_call` shape 一致；provider-native tool 无单独客户端 `tool_result` |
@@ -402,7 +406,7 @@ same:
 - instructions
 - input
 - include
-- exec-mode tool subset membership
+- upstream exec-mode tool subset membership
 - request context field presence
 - exec-mode tool schemas
 - current default-path schemas for `write_stdin`, `web_search`, `update_plan`,
@@ -411,6 +415,7 @@ same:
 different:
 - dynamic request metadata values
+- pycodex inserts the local `clock` extension after `write_stdin`
 - intentional `exec_command` approval/sandbox field omission and idle-resume
   description in pycodex
 - transport-layer header casing / normalization
@@ -543,9 +548,9 @@ including the IANA timezone name (`Asia/Hong_Kong` rather than `HKT`).
 ### 7. Exec-mode tool exposure
-For non-interactive `pycodex`, `get_tools(exec_mode=True)` now matches the
-upstream `codex exec` tool subset so prompt comparison is done against the same
-tool surface.
+For non-interactive `pycodex`, `get_tools(exec_mode=True)` keeps the upstream
+`codex exec` subset and inserts the documented local `clock` extension after
+`write_stdin`. Alignment comparisons exclude that extra tool.
 ## Files involved

{python_codex-0.2.6 → python_codex-0.2.7}/docs/CONTEXT.md RENAMED Viewed

@@ -398,7 +398,8 @@ CodexNonExecConfirmedFacts = {
 当前代码已知差异：
 - `collaboration_mode` 内容来自 `./pycodex/prompts/collaboration_default.md` / `./pycodex/prompts/collaboration_plan.md`。
-- 默认 CLI 的 non-exec 路径当前使用 12 个 exec-mode tools。
+- 默认 CLI 的 non-exec 路径在 12 个上游对齐 exec-mode tools 之外，还会在
+  `write_stdin` 后暴露 pycodex 扩展 `clock`。
 - REPL 连续多轮路径还没有单独 fake-server capture，所以现在不能声称它已经完全和 Codex 对齐。
 ## 4. Tool Schema
@@ -422,6 +423,9 @@ ExecModeToolOrder = [
 ]
 ```
+`pycodex` 的实际默认顺序会在 `write_stdin` 后插入扩展工具 `clock`；上面的列表仍是
+Codex 基准。
 ### 4.2 schema 形状
 ```python

{python_codex-0.2.6 → python_codex-0.2.7}/docs/responses_server/README.md RENAMED Viewed

@@ -8,6 +8,14 @@
 当前 HTTP backend 使用 FastAPI。
 当前独立测试里的 fake outcomming chat backend 也使用 FastAPI。
+compat runtime 的下游 chat-completions / messages 流读取 timeout 默认是
+`300` 秒，与 pycodex Responses client 的 `300_000 ms` SSE idle timeout
+对齐。
+Responses 请求里的 `reasoning.effort` 会转换为下游 chat 请求的
+`chat_template_kwargs.reasoning_effort`。这与 vLLM Responses renderer 的
+prompt 渲染路径一致，也保留 provider 自定义 effort 值（例如 `max`）。
 ## 目录边界
 - incomming server 实现在 `responses_server/`
@@ -26,19 +34,19 @@
 - vLLM chat-completions `reasoning` / `reasoning_content` -> Responses `reasoning` item 适配
 - vLLM 历史 `reasoning` item -> assistant message `reasoning` 字段回放
 - vLLM streaming `usage` -> final `response.completed.response.usage`
-- 当环境变量 `PYCODEX_DUMP` 存在时，为每条 outcomming 请求附加 `return_token_ids = true`，并把抓到的 `prompt_token_ids` / `token_ids` 以 JSONL 追加到 `{PYCODEX_DUMP}/dump.jsonl`
+- 当环境变量 `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
 - 普通 function tools
 - custom tools 的 function-wrapper 兼容适配
 - mock `web_search` 接口对齐（返回空结果）
 - function / custom tool follow-up history 重建
+- 结构化 `input_image` content items：user message 里的图片直接转成 chat `image_url` part；tool output 里的图片会在该 `tool` message 之后补一条只带图片的 `user` message（chat backend 普遍会丢弃 `tool` role 里的图片）；`/v1/messages` 侧再转成 Anthropic `image` block
 ## 当前明确不支持
 这些能力当前会被显式拒绝，而不是静默降级：
 - 真正的 Responses `web_search` 执行；当前只做空结果 mock
-- 结构化 `input_image` tool output
 - 非流式 incomming 请求
 ## Incomming / Outcomming 分层
@@ -87,15 +95,23 @@ server 会为每条实际转发到下游的请求附上 `return_token_ids = true
 trajectory 追加到 `${PYCODEX_DUMP}/dump.jsonl`，当前记录格式是：
 ```json
-{"tokens":{"prefill":[1,2,3],"decode":[4,5,6]},"send_timestamp":2222.0}
+{"request":{"model":"water18","messages":[],"stream":true,"return_token_ids":true},"usage":{"prompt_tokens":100,"completion_tokens":6,"total_tokens":106,"prompt_tokens_details":{"cached_tokens":64}},"tokens":{"prefill":[1,2,3],"decode":[4,5,6]},"send_timestamp":2222.0}
 ```
+`request` 是 provider post-process 之后真正发出的 JSON body；HTTP headers 和
+API key 不会写入 dump。对多轮 tool-call，可以逐条比较
+`request.messages` 是否是上一轮的严格前缀扩展，并读取
+`usage.prompt_tokens_details.cached_tokens` 核对下游 prefix-cache 命中。
+重试和 mock tool follow-up 都会各写一条独立记录。
 如果下游 provider 需要对 chat payload 做定制化改写，可以在
 `responses_server/payload_processors.py` 里注册对应 `model_provider -> proc_fn`
 映射；server 会在真正发出每一条 outcomming `/v1/chat/completions` 请求前，
 对 canonical `outcomming_request` 调一次这个 hook，默认按 `vllm` 处理。
 当前内置规则里，`vllm` 仍走 chat-completions compat 路径，但会额外保留
-reasoning；`stepfun` 会删除所有 `developer` role。
+reasoning；`stepfun` 会把 `developer` role 转成 `system`。Step4 chat
+template 不消费 `developer` role；使用该模板的 provider 应显式配置为
+`stepfun`，否则 base instructions / AGENTS context 会被静默忽略。
 如果下游 chat stream 一轮结束时只给了 `reasoning` / `reasoning_content`，
 没有 assistant `content` 且没有 tool call，server 会丢弃这次 partial reasoning 并用

{python_codex-0.2.6 → python_codex-0.2.7}/packages/pycodex-ws/pyproject.toml RENAMED Viewed

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

{python_codex-0.2.6 → python_codex-0.2.7}/pycodex/__init__.py RENAMED Viewed

@@ -39,6 +39,8 @@ from .runtime_services import (
 from .tools import (
     ApplyPatchTool,
     BaseTool,
+    ClockManager,
+    ClockTool,
     CloseAgentTool,
     CodeModeManager,
     ExecTool,
@@ -96,6 +98,8 @@ __all__ = [
     "ApplyPatchTool",
     "AssistantMessage",
     "BaseTool",
+    "ClockManager",
+    "ClockTool",
     "CloseAgentTool",
     "create_agent_runtime_environment",
     "CodeModeManager",

{python_codex-0.2.6 → python_codex-0.2.7}/pycodex/agent.py RENAMED Viewed

@@ -17,7 +17,14 @@ from .protocol import (
     TurnResult,
     UserMessage,
 )
-from .tools import ExecCommandTool, ToolContext, ToolRegistry, UnifiedExecManager
+from .tools import (
+    ClockManager,
+    ClockTool,
+    ExecCommandTool,
+    ToolContext,
+    ToolRegistry,
+    UnifiedExecManager,
+)
 from .utils.truncation import truncate_tool_results_for_history
 from .utils import uuid7_string
 import typing
@@ -96,6 +103,14 @@ class Agent:
         )
         if self._exec_manager is not None:
             self._exec_manager.set_notify_hook(self.maybe_invoke)
+        clock_tool = self._tool_registry.get_tool("clock")
+        self._clock_manager: 'typing.Union[ClockManager, None]' = (
+            clock_tool._manager
+            if isinstance(clock_tool, ClockTool)
+            else None
+        )
+        if self._clock_manager is not None:
+            self._clock_manager.set_notify_hook(self.maybe_invoke)
     @property
     def history(self) -> 'typing.Tuple[ConversationItem, ...]':
@@ -141,6 +156,8 @@ class Agent:
         self, texts: 'typing.List[str]', turn_id: 'typing.Union[str, None]' = None
     ) -> 'TurnResult':
         self._turn_running = True
+        if self._clock_manager is not None:
+            self._clock_manager.turn_started()
         turn_id = turn_id or uuid7_string()
         self.interrupt_asap = False
         new_user_messages = [UserMessage(text=text) for text in texts]
@@ -198,6 +215,8 @@ class Agent:
                         output_text=last_assistant_message,
                     )
                     self._turn_running = False
+                    if self._clock_manager is not None:
+                        self._clock_manager.arm_after_reply()
                     return TurnResult(
                         turn_id=turn_id,
                         output_text=last_assistant_message,
@@ -240,17 +259,28 @@ class Agent:
             raise
     async def maybe_invoke(self, event: 'typing.Dict[str, object]') -> 'bool':
-        if self._turn_running or event.get("type") != "exec_command_completed":
+        if self._turn_running:
+            return False
+        event_type = event.get("type")
+        if event_type == "exec_command_completed":
+            payload = {
+                "session_id": event.get("session_id"),
+                "exit_code": event.get("exit_code"),
+                "command": event.get("command"),
+            }
+            tag = "exec_command_completed"
+        elif event_type == "clock_tick":
+            payload = {
+                "period_m": event.get("period_m"),
+                "current_time": event.get("current_time"),
+            }
+            tag = "clock_tick"
+        else:
             return False
-        payload = {
-            "session_id": event.get("session_id"),
-            "exit_code": event.get("exit_code"),
-            "command": event.get("command"),
-        }
         text = (
-            "<exec_command_completed>\n"
+            f"<{tag}>\n"
             f"{json.dumps(payload, ensure_ascii=False, separators=(',', ':'))}\n"
-            "</exec_command_completed>"
+            f"</{tag}>"
         )
         self._turn_running = True
         task = asyncio.create_task(self.run_turn([text]))
@@ -259,6 +289,10 @@ class Agent:
         )
         return True
+    def shutdown(self) -> 'None':
+        if self._clock_manager is not None:
+            self._clock_manager.cancel()
     async def _execute_tool_batch(
         self,
         turn_id: 'str',
@@ -328,16 +362,22 @@ class Agent:
     def _emit(self, kind: 'str', turn_id: 'str', **payload: 'object') -> 'None':
         if kind in TERMINAL_TURN_EVENTS:
-            payload["background_exec_count"] = self._background_exec_count()
+            payload["background_work_count"] = self._background_work_count(kind)
         self._event_handler(
             AgentEvent(kind=kind, turn_id=turn_id, payload=dict(payload))
         )
-    def _background_exec_count(self) -> 'int':
+    def _background_work_count(self, terminal_event: 'str') -> 'int':
         manager: 'typing.Union[UnifiedExecManager, None]' = self._exec_manager
-        if manager is None:
-            return 0
-        return manager.running_session_count()
+        count = 0 if manager is None else manager.running_session_count()
+        clock_manager = self._clock_manager
+        if (
+            terminal_event == "turn_completed"
+            and clock_manager is not None
+            and clock_manager.enabled
+        ):
+            count += 1
+        return count
     def _persist_history_items(
         self,

python-codex 0.2.6__tar.gz → 0.2.7__tar.gz

python-codex 0.2.6tar.gz → 0.2.7tar.gz