pi-python-core 0.10.2__tar.gz → 0.11.0__tar.gz

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pi-python-core
-Version: 0.10.2
+Version: 0.11.0
 Summary: An embeddable asyncio agent core with opt-in Claude and OpenAI providers
 License-Expression: MIT
 License-File: LICENSE
@@ -111,7 +111,7 @@ Apart from `provider_chat`, which needs real credentials, every example runs off
 
 The run loop, event order, hooks, queues, and the handling of errors and cancellation all match Pi, and this is checked differentially: the same inputs go to the pinned upstream code and to this library, and the model requests, tool calls, events and final transcript are compared item by item. All cases currently agree: 25 for the core loop, 50 for model connectors, 2 for multi-turn WebSocket, and 44 error-classification samples. The plugin rules for skills, prompt templates and frontmatter are compared the same way against Pi's coding-agent code.
 
-A few differences are deliberate, such as strict tool-argument validation without type coercion, and returning copies of state to callers. Others are additions for Python users, such as `@tool`, blocking calls, and calling `continue_run()` directly after a failure. Each one is recorded in the [coverage map](compat/COVERAGE.md) (Chinese). Features Pi keeps in its application layer (terminal UI, session file format, context compaction) are not in this core; compaction can be built with hooks, and an example shows the full approach. Plugins are the one piece taken from that layer: an optional module that reads Pi's package format and builds an ordinary Agent from it. This project uses its own version numbers and is not an official Pi release.
+A few differences are deliberate, such as strict tool-argument validation without type coercion, and returning copies of state to callers. Others are additions for Python users, such as `@tool`, blocking calls, and calling `continue_run()` directly after a failure. Each one is recorded in the [coverage map](compat/COVERAGE.md) (Chinese). Features Pi keeps in its application layer (terminal UI, session file format, context compaction) are not in this core; compaction can be built with hooks, and an example shows the full approach. The Agent also supplies cache-only session IDs for Codex, a responsibility upstream assigns to its coding-agent layer; see [cache sessions and the opt-out](docs/PROVIDERS.md#automatic-codex-cache-sessions). Plugins are another piece taken from that layer: an optional module that reads Pi's package format and builds an ordinary Agent from it. This project uses its own version numbers and is not an official Pi release.
 
 ## Documentation
 

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/README.md

@@ -77,7 +77,7 @@ Apart from `provider_chat`, which needs real credentials, every example runs off
 
 The run loop, event order, hooks, queues, and the handling of errors and cancellation all match Pi, and this is checked differentially: the same inputs go to the pinned upstream code and to this library, and the model requests, tool calls, events and final transcript are compared item by item. All cases currently agree: 25 for the core loop, 50 for model connectors, 2 for multi-turn WebSocket, and 44 error-classification samples. The plugin rules for skills, prompt templates and frontmatter are compared the same way against Pi's coding-agent code.
 
-A few differences are deliberate, such as strict tool-argument validation without type coercion, and returning copies of state to callers. Others are additions for Python users, such as `@tool`, blocking calls, and calling `continue_run()` directly after a failure. Each one is recorded in the [coverage map](compat/COVERAGE.md) (Chinese). Features Pi keeps in its application layer (terminal UI, session file format, context compaction) are not in this core; compaction can be built with hooks, and an example shows the full approach. Plugins are the one piece taken from that layer: an optional module that reads Pi's package format and builds an ordinary Agent from it. This project uses its own version numbers and is not an official Pi release.
+A few differences are deliberate, such as strict tool-argument validation without type coercion, and returning copies of state to callers. Others are additions for Python users, such as `@tool`, blocking calls, and calling `continue_run()` directly after a failure. Each one is recorded in the [coverage map](compat/COVERAGE.md) (Chinese). Features Pi keeps in its application layer (terminal UI, session file format, context compaction) are not in this core; compaction can be built with hooks, and an example shows the full approach. The Agent also supplies cache-only session IDs for Codex, a responsibility upstream assigns to its coding-agent layer; see [cache sessions and the opt-out](docs/PROVIDERS.md#automatic-codex-cache-sessions). Plugins are another piece taken from that layer: an optional module that reads Pi's package format and builds an ordinary Agent from it. This project uses its own version numbers and is not an official Pi release.
 
 ## Documentation
 

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/README.zh-CN.md

@@ -77,7 +77,7 @@ agent = Agent(provider=llm, model=llm.model("qwen3:8b", context_window=40960), t
 
 执行循环、事件顺序、钩子、队列、出错与取消的处理都与 Pi 一致，并用差分验证：同一组输入分别交给固定版本的上游代码和本库运行，逐项比较模型请求、工具调用、事件和最终记录。目前核心循环 25 组、模型接入 50 组、WebSocket 多轮 2 组、出错判断 44 条样例全部一致。插件里技能、提示模板和文件头元数据的规则，也用同样的方法和 Pi 的 coding-agent 代码对照。
 
-有几处是有意的差异，例如工具参数严格校验、不自动转换类型，返回给调用者的状态是副本；另一些是为 Python 用户加的，例如 `@tool`、同步调用、失败后直接 `continue_run()`。逐项记录见[验收映射](compat/COVERAGE.md)。Pi 放在应用层的功能（终端界面、会话文件格式、上下文压缩）不在本库核心里；压缩可以用钩子实现，示例里有完整做法。插件是从应用层取来的唯一一块：一个可选模块，读取 Pi 的 package 格式，再据此构造普通的 Agent。本项目使用自己的版本号，并非 Pi 官方发行版。
+有几处是有意的差异，例如工具参数严格校验、不自动转换类型，返回给调用者的状态是副本；另一些是为 Python 用户加的，例如 `@tool`、同步调用、失败后直接 `continue_run()`。逐项记录见[验收映射](compat/COVERAGE.md)。Pi 放在应用层的功能（终端界面、会话文件格式、上下文压缩）不在本库核心里；压缩可以用钩子实现，示例里有完整做法。Agent 还为 Codex 自动提供缓存专用会话标识，补齐上游 coding-agent 层承担的职责；见[缓存会话与关闭方式](docs/zh/PROVIDERS.md#codex-自动缓存会话)。插件也是从应用层取来的功能：一个可选模块，读取 Pi 的 package 格式，再据此构造普通的 Agent。本项目使用自己的版本号，并非 Pi 官方发行版。
 
 ## 文档
 

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/compat/COVERAGE.md

@@ -45,6 +45,16 @@
 
 本次沿用现行版本的默认无预算上限、已知取消与显式未知结果的区分，以及可选扩展能力，不把它们按早期草案回退。跨 run 预算、领域效果、科研判断内化和新的包加载器不在本次实现范围内。上述旧验证文件记录的是各自运行时的版本，不自动成为 D9 的验证证据。
 
+## D10：Agent 管理 Codex 缓存会话标识
+
+0.11.0 在 Agent 入口补齐缓存会话生命周期。官方 Pi v1.0.0 的底层 Agent 只转发 `sessionId`，由 coding-agent 的 `createAgentSession()` 从 `SessionManager` 取值；这一分工在核查的 v1.3.0 中也相同。Python 没有对应的完整上层应用，因而默认在 Agent 提供此便利能力。它是经用户确认的有意差异，不是上游 core 行为完全一致的声明，也不升级固定参照。
+
+core 只识别可选的 `supports_agent_cache_session=True` 能力，不绑定模型名或 Provider 类。内置 Codex Provider 使用 `request.cache_session_id` 作为缓存键与会话头的后备值；其他内置 Provider、自定义流和未声明支持的 Provider 不接收自动标识。`DefaultProvider` 转发实际接入的能力。
+
+自动值不写入 `options.session_id`，因此不能满足 `websocket-cached` 的显式配置要求，也不能启动连接复用或 `previous_response_id` 续接。原有显式值、钩子及配置更新的优先级保留；自动值尊重应用自定义请求头。`auto_session_id=False` 恢复旧默认，`cache_retention="none"` 抑制库生成的缓存字段。新增属性与构造参数支持保存、恢复后备标识；消息编解码、事件、结果和 ModelRequest 的 dataclass 字段不变。
+
+证据：`tests/test_cache_sessions.py` 捕获实际构造的 HTTP 请求，覆盖默认头、工具循环、重试、配置替换、跨 Agent/子 Agent 隔离、重置、恢复、显式优先、禁用、通道切换、自定义 Provider 能力及旧请求结构；`tests/test_websocket_continuation.py` 用本地服务器检查连接数、完整输入和续接字段。恢复的自动值也不触发连接复用；显式标识的原有增量行为单独验证。真实后端命中率、订阅配额节省与所有上层应用不在这些离线检查的证明范围内。
+
 ## 有意差异与范围外行为
 
 D1–D8 保持原设计的含义。D1 严格输入；D2 执行前钩子不能通过原地修改参数改变调用；D3 资源预算；D4 Python 取消及未知结果；D5 状态复制；D6 输出检查；D7 诊断、原始结果和完整流校验；D8 文本与工具子集。每项有独立 Python 断言，不以 skip 代替验收。

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/compat/results/verification.json

@@ -18,9 +18,9 @@
         "mcp-interactive"
       ],
       "exit_code": 0,
-      "seconds": 0.02251266618259251,
+      "seconds": 0.021437582792714238,
       "stdout": "",
-      "stderr": "Resolved 60 packages in 2ms\nAudited 57 packages in 8ms\n"
+      "stderr": "Resolved 60 packages in 2ms\nAudited 57 packages in 6ms\n"
     },
     {
       "command": [
@@ -35,7 +35,7 @@
         "scripts"
       ],
       "exit_code": 0,
-      "seconds": 0.0649345419369638,
+      "seconds": 0.061738125048577785,
       "stdout": "All checks passed!\n",
       "stderr": ""
     },
@@ -53,8 +53,8 @@
         "scripts"
       ],
       "exit_code": 0,
-      "seconds": 0.024958166992291808,
-      "stdout": "110 files already formatted\n",
+      "seconds": 0.02676033414900303,
+      "stdout": "115 files already formatted\n",
       "stderr": ""
     },
     {
@@ -65,7 +65,7 @@
         "src/pi_python"
       ],
       "exit_code": 0,
-      "seconds": 0.5702685830183327,
+      "seconds": 0.40783704188652337,
       "stdout": "Success: no issues found in 43 source files\n",
       "stderr": ""
     },
@@ -77,8 +77,8 @@
         "-q"
       ],
       "exit_code": 0,
-      "seconds": 149.19938791706227,
-      "stdout": "........................................................................ [  9%]\n........................................................................ [ 19%]\n........................................................................ [ 28%]\n........................................................................ [ 38%]\n........................................................................ [ 47%]\n........................................................................ [ 57%]\n........................................................................ [ 67%]\n...............................................ss....................... [ 76%]\n........................................................................ [ 86%]\n........................................................................ [ 95%]\n................................                                         [100%]\n750 passed, 2 skipped in 148.30s (0:02:28)\n",
+      "seconds": 143.989434374962,
+      "stdout": "........................................................................ [  8%]\n........................................................................ [ 17%]\n........................................................................ [ 25%]\n........................................................................ [ 34%]\n........................................................................ [ 43%]\n........................................................................ [ 51%]\n........................................................................ [ 60%]\n........................................................................ [ 69%]\n...................................................ss................... [ 77%]\n........................................................................ [ 86%]\n........................................................................ [ 94%]\n..........................................                               [100%]\n832 passed, 2 skipped in 143.31s (0:02:23)\n",
       "stderr": ""
     },
     {
@@ -89,10 +89,22 @@
         "examples/in_memory.py"
       ],
       "exit_code": 0,
-      "seconds": 0.6022720420733094,
+      "seconds": 0.49026058288291097,
       "stdout": "The telemetry contains 3 complete records.\n",
       "stderr": ""
     },
+    {
+      "command": [
+        "uv",
+        "run",
+        "python",
+        "examples/capability_composition.py"
+      ],
+      "exit_code": 0,
+      "seconds": 0.5047036670148373,
+      "stdout": "run=completed; domain_passed=False\nBoth paths use the same tool; the application batch made zero model requests.\n",
+      "stderr": ""
+    },
     {
       "command": [
         "npm",
@@ -104,8 +116,8 @@
         "test/agent.test.ts"
       ],
       "exit_code": 0,
-      "seconds": 1.9349422920495272,
-      "stdout": "\n> @earendil-works/pi-agent-core@1.0.0 test\n> vitest --run test/agent-loop.test.ts test/agent.test.ts\n\n\n RUN  v4.1.11 /Users/daidong/Documents/gitrepos/pi-python/reference/pi/packages/agent\n\n\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\n\n Test Files  2 passed (2)\n      Tests  77 passed (77)\n   Start at  12:01:38\n   Duration  1.40s (transform 916ms, setup 0ms, import 2.00s, tests 281ms, environment 0ms)\n\n",
+      "seconds": 1.0130393749568611,
+      "stdout": "\n> @earendil-works/pi-agent-core@1.0.0 test\n> vitest --run test/agent-loop.test.ts test/agent.test.ts\n\n\n RUN  v4.1.11 /Users/daidong/Documents/gitrepos/pi-python/reference/pi/packages/agent\n\n\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\n\n Test Files  2 passed (2)\n      Tests  77 passed (77)\n   Start at  12:56:57\n   Duration  643ms (transform 451ms, setup 0ms, import 858ms, tests 171ms, environment 0ms)\n\n",
       "stderr": ""
     },
     {
@@ -121,8 +133,8 @@
         "test/openai-codex-stream.test.ts"
       ],
       "exit_code": 0,
-      "seconds": 1.3067305411677808,
-      "stdout": "\n> @earendil-works/pi-ai@1.0.0 test\n> vitest --run test/transcript-tool-changes.test.ts test/validation.test.ts test/anthropic-mid-conversation-effort.test.ts test/openai-codex-stream.test.ts\n\n\n RUN  v4.1.11 /Users/daidong/Documents/gitrepos/pi-python/reference/pi/packages/ai\n\n\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\n\n Test Files  4 passed (4)\n      Tests  70 passed (70)\n   Start at  12:01:39\n   Duration  992ms (transform 1.03s, setup 0ms, import 1.86s, tests 252ms, environment 0ms)\n\n",
+      "seconds": 1.0957162089180201,
+      "stdout": "\n> @earendil-works/pi-ai@1.0.0 test\n> vitest --run test/transcript-tool-changes.test.ts test/validation.test.ts test/anthropic-mid-conversation-effort.test.ts test/openai-codex-stream.test.ts\n\n\n RUN  v4.1.11 /Users/daidong/Documents/gitrepos/pi-python/reference/pi/packages/ai\n\n\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\n\n Test Files  4 passed (4)\n      Tests  70 passed (70)\n   Start at  12:56:58\n   Duration  808ms (transform 968ms, setup 0ms, import 1.57s, tests 208ms, environment 0ms)\n\n",
       "stderr": ""
     },
     {
@@ -133,7 +145,7 @@
         "scripts/conformance.py"
       ],
       "exit_code": 0,
-      "seconds": 5.7676790410187095,
+      "seconds": 4.930072667077184,
       "stdout": "C01-text: passed []\nC02-tool: passed []\nC03-sequential: passed []\nC04-parallel: passed []\nC05-one-sequential: passed []\nC06-one-failure: passed []\nC07-unknown: passed []\nC08-prepare: passed []\nC09-before-error: passed []\nC09-block: passed []\nC09-replace: passed []\nC10-length: passed []\nC11-transform: passed []\nC12-system: passed []\nC13-steering: passed []\nC14-followup-all: passed []\nC14-followup-one: passed []\nC15-prepare: passed []\nC16-continue: passed []\nC16-end: passed []\nC16-mixed: passed []\nC16-terminate: passed []\nC19-abort-stream: passed []\nC19-abort-tools: passed []\nC24-provider-error: passed []\n",
       "stderr": ""
     },
@@ -145,7 +157,7 @@
         "scripts/provider_conformance.py"
       ],
       "exit_code": 0,
-      "seconds": 15.009326208150014,
+      "seconds": 12.895416000159457,
       "stdout": "anthropic-oauth.json passed\nanthropic-request-cache-long.json passed\nanthropic-request-cache-none.json passed\nanthropic-request-replay.json passed\nanthropic-request-tools-image.json passed\nanthropic-text.json passed\nanthropic-thinking.json passed\nanthropic-tool.json passed\ncodex-request-tools-image.json passed\ncodex-text.json passed\ncompletions-compat-strict.json passed\ncompletions-deepseek.json passed\ncompletions-format-ant-ling.json passed\ncompletions-format-baseten.json passed\ncompletions-format-string-thinking.json passed\ncompletions-format-together.json passed\ncompletions-format-zai.json passed\ncompletions-midconvo-tools.json passed\ncompletions-moonshot-usage.json passed\ncompletions-openai-off.json passed\ncompletions-openrouter.json passed\ncompletions-qwen-length.json passed\ncompletions-reasoning-content.json passed\ncompletions-request-replay.json passed\ncompletions-text.json passed\ncompletions-tool-stream.json passed\nopenai-incomplete.json passed\nopenai-request-cache-long.json passed\nopenai-request-cache-none.json passed\nopenai-request-reasoning.json passed\nopenai-request-replay.json passed\nopenai-request-tools-image.json passed\nopenai-text.json passed\nopenai-thinking-backfill.json passed\nopenai-thinking.json passed\nopenai-tool.json passed\nproxy-text.json passed\nproxy-thinking-tool.json passed\nsession-anthropic-collapse-budget.json passed\nsession-anthropic-native-tools.json passed\nsession-anthropic-oauth-effort.json passed\nsession-anthropic-redefinition.json passed\nsession-anthropic-server-fallback.json passed\nsession-anthropic-thinking-off.json passed\nsession-codex-tool-search.json passed\nsession-openai-additional-tools.json passed\nsession-openai-collapse.json passed\nsession-openai-explicit-cache-long.json passed\nsession-openai-explicit-cache-none.json passed\nsession-openai-removal.json passed\n",
       "stderr": ""
     },
@@ -157,7 +169,7 @@
         "scripts/websocket_conformance.py"
       ],
       "exit_code": 0,
-      "seconds": 0.9335567080415785,
+      "seconds": 0.7594145000912249,
       "stdout": "codex-continuation-lost-state.json passed\ncodex-continuation-tool-loop.json passed\n",
       "stderr": ""
     },
@@ -169,7 +181,7 @@
         "scripts/recovery_conformance.py"
       ],
       "exit_code": 0,
-      "seconds": 0.628341041970998,
+      "seconds": 0.5641300419811159,
       "stdout": "recovery classifiers: 44/44 match upstream \n",
       "stderr": ""
     },
@@ -181,8 +193,8 @@
         "scripts/plugin_conformance.py"
       ],
       "exit_code": 0,
-      "seconds": 1.306608916958794,
-      "stdout": ".......                                                                  [100%]\n7 passed in 0.74s\n",
+      "seconds": 1.0472173751331866,
+      "stdout": ".......                                                                  [100%]\n7 passed in 0.63s\n",
       "stderr": ""
     },
     {
@@ -193,7 +205,7 @@
         "examples/plugin_demo.py"
       ],
       "exit_code": 0,
-      "seconds": 0.576676958007738,
+      "seconds": 0.5162342919502407,
       "stdout": "loaded: lab_tools 0.1.0\ncheck: counts_duplicates passed\nprompt: Find duplicate events in events.csv using a 30 second window. Read the dedup-window skill first.\ntools used: ['read_skill', 'subagent']\nanswer: The reviewer found 2 duplicate rows.\n",
       "stderr": ""
     },
@@ -205,7 +217,7 @@
         "examples/mcp_interactive.py"
       ],
       "exit_code": 0,
-      "seconds": 1.8445827078539878,
+      "seconds": 1.685829000081867,
       "stdout": "Model task=demo-run request=1 profile=default attempt=1 usage=None\nModel task=demo-run request=2 profile=default attempt=1 usage=None\nModel task=demo-run request=3 profile=json attempt=1 usage={'input': 4, 'output': 3, 'cacheRead': 1}\nModel task=demo-run request=4 profile=text attempt=1 usage={'input': 4, 'output': 3, 'cacheRead': 1}\nForm from business: Choose output for report\nDemo user chooses: short, confirmed\n{\"label\": \"report\", \"model_reply\": \"[report] [ready]\", \"action\": \"accept\", \"selection\": {\"style\": \"short\", \"confirmed\": true}, \"auxiliary\": {\"json\": {\"ok\": true}, \"text\": \"Ready\"}}\n",
       "stderr": ""
     },
@@ -218,7 +230,7 @@
         "--help"
       ],
       "exit_code": 0,
-      "seconds": 0.6522026660386473,
+      "seconds": 0.5009769999887794,
       "stdout": "usage: provider_chat.py [-h]\n                        --provider {anthropic,openai,openai-codex,openai-chatgpt,deepseek}\n                        --model MODEL [--prompt PROMPT]\n                        [--credential-file CREDENTIAL_FILE] [--login]\n                        [--device]\n                        [--thinking {off,minimal,low,medium,high,xhigh,max}]\n                        [--transport {sse,websocket,websocket-cached,auto}]\n                        [--session-id SESSION_ID]\n\nExplicit API/OAuth example. Invoke --help; never imported by the core.\n\noptions:\n  -h, --help            show this help message and exit\n  --provider {anthropic,openai,openai-codex,openai-chatgpt,deepseek}\n  --model MODEL         Model ID enabled for this account\n  --prompt PROMPT\n  --credential-file CREDENTIAL_FILE\n                        App-owned OAuth file (never reuse another client file)\n  --login\n  --device              Codex device authorization instead of browser callback\n  --thinking {off,minimal,low,medium,high,xhigh,max}\n  --transport {sse,websocket,websocket-cached,auto}\n  --session-id SESSION_ID\n                        Required for websocket-cached\n",
       "stderr": ""
     },
@@ -228,10 +240,11 @@
         "build"
       ],
       "exit_code": 0,
-      "seconds": 1.0952744169626385,
+      "seconds": 0.8976772499736398,
       "stdout": "",
-      "stderr": "Building source distribution...\nBuilding wheel from source distribution...\nSuccessfully built dist/pi_python_core-0.10.1.tar.gz\nSuccessfully built dist/pi_python_core-0.10.1-py3-none-any.whl\n"
+      "stderr": "Building source distribution...\nBuilding wheel from source distribution...\nSuccessfully built dist/pi_python_core-0.11.0.tar.gz\nSuccessfully built dist/pi_python_core-0.11.0-py3-none-any.whl\n"
     }
   ],
-  "status": "passed"
+  "status": "passed",
+  "runner_timeout_seconds": 600
 }

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/docs/API.md

@@ -271,6 +271,8 @@ The event stream uses a bounded queue. If you only wait for the result, `result(
 
 An Agent can also be constructed with `thinking_level`, `thinking_budgets`, `transport`, `session_id`, `get_api_key`, `on_payload`, `on_response` and `on_provider_stream_event`. The last four can also go in Hooks; explicit constructor arguments take precedence. Their protocols, and the Provider parameters, are described in [the connector guide](PROVIDERS.md).
 
+`auto_session_id=True` supplies an Agent-owned cache-only ID to Providers that opt in (the built-in Codex Provider). `agent.cache_session_id` reads that managed fallback; restore it with `Agent(cache_session_id=saved_id, ...)`. Explicit `session_id` takes precedence. `reset()` rotates the managed fallback, and `auto_session_id=False` disables it. Automatic/restored cache IDs never enable connection reuse. See [cache sessions, persistence and Provider opt-in](PROVIDERS.md#automatic-codex-cache-sessions).
+
 ## Fields of messages, tool results and events
 
 `SystemMessage.content` accepts a string or a list of text blocks. `AssistantMessage` also contains `response_model`, `response_id`, `thinking_level`, `diagnostics`, `raw_stop_reason`, `end_turn` and `deferred`. `provider_thinking_level` is the provider's native effort; `thinking_level` is the requested level. Fields whose value is null in arbitrary user JSON are preserved intact.

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/docs/CODING_AGENTS.md

@@ -139,6 +139,8 @@ Do not move that connection to `run_sync`'s separate loop. See
 These APIs and feature declarations are part of the 0.10.0 source line; check
 `require_features(["task-scope-v1", "loop-portal-v1"])` when depending on them.
 
+For Codex subscriptions, Agent supplies a stable cache ID by default. Save `agent.cache_session_id` alongside the message history and restore it with `Agent(cache_session_id=..., messages=...)`. This retains cache-only behavior; it does not enable connection reuse. Use `auto_session_id=False` to opt out. Other built-in Providers and custom streams keep their existing behavior. See [cache sessions](PROVIDERS.md#automatic-codex-cache-sessions).
+
 ## 5. Choose the smallest integration surface
 
 | Need | Start here |

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/docs/PROVIDERS.md

@@ -100,7 +100,7 @@ Claude models that support changing reasoning effort mid-conversation (`supports
 
 OpenAI maps `thinking_level` to reasoning effort. `options` supports `max_tokens`, `reasoning_summary`, `temperature`, `top_p`, `tool_choice`, `parallel_tool_calls`, `metadata`, `service_tier`, `text` and `headers`; Claude also supports `thinking_budgets`, `thinking_display`, `interleaved_thinking`, `top_k`, `stop_sequences`, and direct overrides of `thinking` and `output_config`. As upstream does, Claude forwards only `metadata.user_id`, writes a string `tool_choice` as `{"type": ...}`, and does not send `temperature` when reasoning is on, when the model does not support it, or when effort markers are in use. Which parameters a given model accepts is up to the server.
 
-Claude uses SSE. OpenAI and Codex support `sse`, `websocket`, `websocket-cached` and `auto`. `websocket-cached` requires `session_id`; as upstream does, `auto` also reuses the connection when there is a `session_id`. With `cache_retention="none"`, each request uses a one-off connection. Connections are kept apart by endpoint, session and request headers, and each connection is used by one request at a time. A connection is no longer reused after 5 idle minutes or 55 minutes after it was opened, and a connection the server has closed is rebuilt instead of failing on the old one. These limits can be changed with `HTTPTransport(websocket_idle_ttl=..., websocket_max_age=...)`.
+Claude uses SSE. OpenAI and Codex support `sse`, `websocket`, `websocket-cached` and `auto`. `websocket-cached` requires an application-supplied `session_id`; as upstream does, `auto` also reuses the connection when there is an application-supplied `session_id`. The Agent-managed cache ID does not enable either behavior. With `cache_retention="none"`, each request uses a one-off connection. Connections are kept apart by endpoint, session and request headers, and each connection is used by one request at a time. A connection is no longer reused after 5 idle minutes or 55 minutes after it was opened, and a connection the server has closed is rebuilt instead of failing on the old one. These limits can be changed with `HTTPTransport(websocket_idle_ttl=..., websocket_max_age=...)`.
 
 Expired idle connections are swept on WebSocket requests and cache returns. At most 64 idle connections are retained, evicting the least recently returned first; set `HTTPTransport(websocket_cache_size=...)` to change this limit, or `0` to disable retention. Session locks are removed when their last active or waiting request exits. Sweeping is demand-driven, with no background timer. Call `await provider.aclose()` when you are done; the application manages the lifetime of a shared transport.
 
@@ -123,6 +123,42 @@ Usage is normalized to `input`, `output`, `cache_read`, `cache_write`, `reasonin
 counters remain present for compatibility; those default zeros are not measured consumption.
 MCP sampling observations report `usage=None` for this case. A tool's own usage is stored separately in the tool result and is not mixed into the main model's token counts.
 
+## Automatic Codex cache sessions
+
+From 0.11.0, `Agent` supplies a stable cache ID when using `OpenAICodexProvider` without an application-supplied `session_id`. It fills the `session-id` and `x-client-request-id` headers and `prompt_cache_key`. This applies to the ChatGPT Codex subscription channel, not to OpenAI API-key calls or Claude. The Codex CLI [identifies the session header as the cache-affinity input](https://github.com/openai/codex/blob/e4568a3538c9cab6627d64ff8cdfc7d98b79b7db/codex-rs/core/src/client.rs#L660); sending an ID does not guarantee a cache hit or a particular subscription quota saving.
+
+The ID belongs to the Agent, not to the shared Provider or an individual request. Tool loops, later prompts, retries and configuration replacement keep it. Different Agents, including nested Agents, receive independent IDs. `reset()` discards the managed ID, including a restored one; the next access or request generates a new ID. An explicit `session_id` always takes precedence and retains its existing reset behavior. Automatic headers respect application-supplied header values, including differently cased names.
+
+The automatic ID **never enables connection reuse or response continuation**. The default transport remains SSE. In `auto` or `websocket` mode it still uses one-off connections and full context unless the application explicitly supplies `session_id` to an eligible mode. `websocket-cached` still requires an explicit `session_id`. Cache affinity and transport session state are separate.
+
+Use `Agent(auto_session_id=False, ...)` to keep the previous default. This does not suppress an explicit `session_id`. `options={"cache_retention": "none"}` suppresses library-generated cache keys and session headers for either kind of ID.
+
+Save the read-only `agent.cache_session_id` alongside history and restore it through the constructor's `cache_session_id=` argument:
+
+```python
+from pi_python import Agent, encode_messages, decode_messages
+
+# provider is an application-owned OpenAICodexProvider.
+agent = Agent(provider=provider, model=model_id)
+await agent.prompt("Remember the task constraints.")
+saved = {
+    "messages": encode_messages(list(agent.state.messages)),
+    "cache_session_id": agent.cache_session_id,
+}
+restored = Agent(
+    provider=provider, model=model_id,
+    messages=decode_messages(saved["messages"]),
+    cache_session_id=saved["cache_session_id"],
+)
+await restored.prompt("Continue the task.")
+```
+
+The application chooses how to store this object; message encoding itself has not changed. `cache_session_id` is the Agent-managed fallback, not a report of a request's effective routing ID when an explicit `session_id` or custom headers override it. Applications that manage `session_id` must persist that configuration themselves. Restoring with `cache_session_id=` retains cache-only behavior; restoring it as `session_id=` opts into the existing transport semantics. Restored cache IDs must contain 1–64 printable ASCII characters without spaces and require `auto_session_id=True`. The property returns `None` when automatic handling is disabled or the current Provider does not opt in.
+
+The core uses an optional Provider capability, `supports_agent_cache_session = True`, rather than inspecting model names or importing a Codex adapter. Only the built-in Codex Provider enables it. Custom Providers may opt in and read `request.cache_session_id`; existing Providers and `stream_fn` implementations require no changes. Wrappers that opt in must preserve the request object or use `deepcopy`: rebuilding it from its serialized dataclass fields drops this cache-only metadata. The default-stream wrapper forwards the underlying Provider's capability. The ID is separate from `request.options`, and does not add dataclass fields to `ModelRequest` or fields to messages, events or results. Calling a Provider directly does not generate an ID.
+
+This is an intentional difference from Pi's core Agent, which only forwards an optional ID. Pi's coding-agent layer supplies it through `SessionManager`; pi-python provides that convenience at its primary Agent entry point. The upstream baseline is unchanged. Applications can check `require_features(["codex-auto-cache-session-v1"])` before using this API. See the [0.11.0 compatibility and verification notes](releases/0.11.0.md).
+
 ## Model table and DeepSeek
 
 ```python

pi_python_core-0.11.0/docs/releases/0.11.0.md

@@ -0,0 +1,40 @@
+# 0.11.0：Codex 默认缓存会话，不改变连接复用
+
+使用 Codex 订阅通道的应用过去需要自行提供 `session_id`，漏传时不会自动发送稳定的会话请求头。本版本由 Agent 默认管理缓存标识，减少这种遗漏。自动标识只用于缓存，不会启动 WebSocket 连接复用或上一响应续接。
+
+## 使用与生命周期
+
+- `Agent(auto_session_id=True)` 为主动声明支持的 Provider 提供稳定标识；内置 Provider 中只有 `OpenAICodexProvider` 开启。core 不按模型名或特定 Provider 类分支，自定义 Provider 和流保持原有合同。
+- 同一 Agent 的工具循环、后续请求、重试和配置替换复用标识；不同 Agent（包括子 Agent）独立生成。`reset()` 后换新标识。
+- `agent.cache_session_id` 读取 Agent 管理的后备标识。与历史一起保存后，用 `Agent(cache_session_id=saved_id, messages=..., ...)` 恢复；恢复后仍不启用连接复用。
+- 应用显式 `session_id` 优先，沿用原有传输语义及 reset 行为。自定义请求头也不会被自动头覆盖。
+- `auto_session_id=False` 恢复旧默认；`options={"cache_retention": "none"}` 停止库自动设置缓存键和关联会话头。
+- `require_features(["codex-auto-cache-session-v1"])` 可检查是否支持此合同。
+
+## 兼容性与迁移
+
+未传 `session_id` 的 Codex Agent 请求现在会包含 `prompt_cache_key`、`session-id` 和 `x-client-request-id`。严格检查请求内容、快照或自定义网关的应用需要接纳这些字段，或用 `auto_session_id=False` 保持旧请求形状。默认仍为 SSE；自动值不会让已有 `auto` 模式开始复用连接，`websocket-cached` 仍要求应用显式提供 `session_id`。
+
+消息编码与历史格式、事件和运行结果字段不变。自动标识通过独立的请求元数据传递，不加入 `ModelRequest` 的 dataclass 字段或 `request.options`。只保存消息不会保存缓存会话；需要跨进程复用的应用须另外保存 `cache_session_id`。应用自己管理显式 `session_id` 时，仍应保存自己的配置。
+
+这是对官方 Pi core 的有意扩展：上游底层 Agent 不生成标识，上层 coding-agent 才生成并传入；Python 在主要接入入口补齐该职责。固定参照仍为 Pi v1.0.0。通用 core 仅识别可选能力，其他内置通道不增加自动缓存字段。直接调用 Provider 的应用仍自行管理会话。
+
+这一默认行为变化已在实施前经用户确认。库内测试不等于所有实际上层应用兼容。固定版本环境只有升级后才获得此行为。
+
+## 验证范围
+
+验证覆盖请求头与缓存键、跨轮次与重试、子 Agent 隔离、重置与恢复、显式配置优先、禁用和自定义 Provider。WebSocket 检查使用本地服务器，核对连接次数、完整输入和续接字段。缺少默认会话头的回归测试已在修改前的版本上确认失败。
+
+本地全量测试 832 通过、2 跳过；Ruff、格式、mypy 和全部上游差分检查通过，其中核心差分覆盖 25 组。两项跳过适用于不支持 `meta` 的旧版 MCP SDK。完整记录见 [verification.json](../../compat/results/verification.json)。验证运行器的单命令超时临时放宽至 600 秒，仓库脚本未修改。
+
+wheel 与源码包通过 `twine check --strict`。wheel 在仓库外的独立 Python 3.11 环境中安装后，版本检查、基础示例与 78 项缓存、WebSocket 和应用兼容性定向测试通过。发布标签为 `v0.11.0`，远端验证与构建通过后才上传 PyPI。
+
+首次远端 Windows / Python 3.11 检查发现已有运行超时测试的时序假设：20 毫秒期限可能在工具启动前到达。断言现接受运行超时后的“未启动”或“已取消”，工具自身超时仍要求“已取消”；运行实现没有改变。修正后本地相关定向测试 88 项通过。
+
+没有用这些离线结果宣称真实 Codex 缓存命中率、订阅配额节省或所有模型效果。服务端是否命中应通过实际 `cache_read` 用量观察。
+
+## 文档
+
+- [中文接入与恢复示例](../zh/PROVIDERS.md#codex-自动缓存会话)
+- [English provider guide](../PROVIDERS.md#automatic-codex-cache-sessions)
+- [与上游的差异及验收映射](../../compat/COVERAGE.md#d10agent-管理-codex-缓存会话标识)

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/docs/zh/API.md

@@ -257,6 +257,8 @@ SDK 不支持 `meta` 时，注册会抛出 `ConfigurationError`。
 
 构造 Agent 还可传 `thinking_level`、`thinking_budgets`、`transport`、`session_id`、`get_api_key`、`on_payload`、`on_response`、`on_provider_stream_event`。后四项也可放在 Hooks 中，明确的构造参数优先。它们的协议与 Provider 参数详见 [接入说明](PROVIDERS.md)。
 
+`auto_session_id=True` 为主动声明支持的 Provider（内置 Codex Provider）提供 Agent 管理的缓存专用标识。用 `agent.cache_session_id` 读取后备标识，用 `Agent(cache_session_id=saved_id, ...)` 恢复。显式 `session_id` 优先；`reset()` 更新后备标识，`auto_session_id=False` 关闭自动处理。自动或恢复的缓存标识不会开启连接复用。详见[缓存会话、持久化与 Provider 能力声明](PROVIDERS.md#codex-自动缓存会话)。
+
 ## 消息、工具结果与事件的字段
 
 `SystemMessage.content` 接受字符串或文本块列表。`AssistantMessage` 还包含 `response_model`、`response_id`、`thinking_level`、`diagnostics`、`raw_stop_reason`、`end_turn` 和 `deferred`。`provider_thinking_level` 是原生 effort，`thinking_level` 是请求等级。任意用户 JSON 中值为 null 的字段完整保留。

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/docs/zh/CODING_AGENTS.md

@@ -111,6 +111,8 @@ finally:
 
 应用自己的异步工作可以交给 `TaskScope`。同步工具的工作线程需要访问已有异步连接时，由连接所属事件循环创建 `LoopPortal`，再用它提交调用，不要把连接移到 `run_sync` 的独立循环。见 [任务归属和线程调用](API.md)。这些 API 和能力声明属于 0.10.0 源码系列；依赖它们时可用 `require_features(["task-scope-v1", "loop-portal-v1"])` 检查。
 
+使用 Codex 订阅通道时，Agent 默认提供稳定的缓存标识。将 `agent.cache_session_id` 与消息历史一起保存，并用 `Agent(cache_session_id=..., messages=...)` 恢复，仍保持“只用于缓存”，不会开启连接复用。用 `auto_session_id=False` 关闭自动处理。其他内置 Provider 和自定义流保持原有行为。详见[缓存会话](PROVIDERS.md#codex-自动缓存会话)。
+
 ## 5. 按需求选择接入方式
 
 | 需要什么 | 从哪里开始 |

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/docs/zh/PROVIDERS.md

@@ -100,7 +100,7 @@ Claude 的推理方式由模型记录决定：`compat["forceAdaptiveThinking"]`
 
 OpenAI 将 `thinking_level` 映射到 reasoning effort。`options` 支持 `max_tokens`、`reasoning_summary`、`temperature`、`top_p`、`tool_choice`、`parallel_tool_calls`、`metadata`、`service_tier`、`text`、`headers`；Claude 另支持 `thinking_budgets`、`thinking_display`、`interleaved_thinking`、`top_k`、`stop_sequences`，以及直接覆盖的 `thinking` 和 `output_config`。与上游一致，Claude 只转发 `metadata.user_id`，字符串形式的 `tool_choice` 写成 `{"type": ...}`；推理开启、模型不支持或使用强度标记时不发送 `temperature`。具体模型允许哪些参数由服务端决定。
 
-Claude 使用 SSE。OpenAI/Codex 支持 `sse`、`websocket`、`websocket-cached` 和 `auto`。`websocket-cached` 要求 `session_id`；与上游一致，`auto` 在有 `session_id` 时也复用连接。`cache_retention="none"` 时每次请求使用一次性连接。连接按端点、会话和请求头隔离，同一连接串行使用；空闲 5 分钟或建立满 55 分钟后不再复用，已被服务端关闭的连接也会重建，而不是在旧连接上失败。时限可用 `HTTPTransport(websocket_idle_ttl=..., websocket_max_age=...)` 调整。
+Claude 使用 SSE。OpenAI/Codex 支持 `sse`、`websocket`、`websocket-cached` 和 `auto`。`websocket-cached` 要求应用显式提供 `session_id`；与上游一致，`auto` 在有显式 `session_id` 时也复用连接。Agent 自动管理的缓存标识不会启用上述行为。`cache_retention="none"` 时每次请求使用一次性连接。连接按端点、会话和请求头隔离，同一连接串行使用；空闲 5 分钟或建立满 55 分钟后不再复用，已被服务端关闭的连接也会重建，而不是在旧连接上失败。时限可用 `HTTPTransport(websocket_idle_ttl=..., websocket_max_age=...)` 调整。
 
 每次 WebSocket 请求及归还连接时清扫过期的空闲连接。默认最多保留 64 条空闲连接，超限时先关闭最早归还的连接；可用 `HTTPTransport(websocket_cache_size=...)` 调整，设为 `0` 则不保留连接。会话锁在最后一个运行或等待中的请求退出后移除。清扫由请求触发，没有后台定时器。结束后调用 `await provider.aclose()`；共享 transport 由应用管理生命周期。
 
@@ -120,6 +120,42 @@ OpenAI 对已知模型默认发送模型输出上限（按上下文估算截短
 
 用量归一化为 `input`、`output`、`cache_read`、`cache_write`、`reasoning`、`total_tokens`。工具自己的用量独立保存在工具结果中，不混入主模型 token 计数。
 
+## Codex 自动缓存会话
+
+从 0.11.0 起，使用 `OpenAICodexProvider` 的 Agent 在应用未传 `session_id` 时，自动提供稳定的缓存标识，用于 `session-id`、`x-client-request-id` 请求头和 `prompt_cache_key`。这针对 ChatGPT Codex 订阅通道，不适用于 OpenAI API key 通道或 Claude。Codex CLI [明确说明会话头用于缓存亲和性](https://github.com/openai/codex/blob/e4568a3538c9cab6627d64ff8cdfc7d98b79b7db/codex-rs/core/src/client.rs#L660)；发送标识不保证命中，也不保证具体的订阅配额节省。
+
+标识属于 Agent，不属于共享 Provider 或单次请求。同一 Agent 的工具循环、后续 prompt、重试和配置替换保持标识；不同 Agent（包括子 Agent）各自生成。`reset()` 丢弃自动管理的标识，包括恢复时传入的标识，下次读取或请求时生成新值。应用显式传入的 `session_id` 始终优先，并保持原有 reset 行为。自动请求头尊重应用自行设置的同名头，包括不同大小写形式。
+
+自动标识**不会启用连接复用或上一响应续接**。默认传输仍为 SSE。使用 `auto` 或 `websocket` 时，除非应用显式传入 `session_id` 并选择支持复用的模式，否则仍使用一次性连接、发送完整上下文。`websocket-cached` 仍要求显式 `session_id`。缓存亲和性与传输会话状态分开管理。
+
+用 `Agent(auto_session_id=False, ...)` 恢复旧默认行为；该开关不屏蔽显式 `session_id`。`options={"cache_retention": "none"}` 对两类标识都停止自动设置缓存键和关联会话头。
+
+将只读属性 `agent.cache_session_id` 与历史一起保存，并通过构造参数 `cache_session_id=` 恢复：
+
+```python
+from pi_python import Agent, encode_messages, decode_messages
+
+# provider 是应用管理的 OpenAICodexProvider。
+agent = Agent(provider=provider, model=model_id)
+await agent.prompt("记住任务约束。")
+saved = {
+    "messages": encode_messages(list(agent.state.messages)),
+    "cache_session_id": agent.cache_session_id,
+}
+restored = Agent(
+    provider=provider, model=model_id,
+    messages=decode_messages(saved["messages"]),
+    cache_session_id=saved["cache_session_id"],
+)
+await restored.prompt("继续任务。")
+```
+
+上述对象由应用自行持久化，消息编码格式没有变化。`cache_session_id` 表示 Agent 管理的后备标识；当显式 `session_id` 或自定义请求头覆盖它时，该属性不代表实际请求的路由标识。自行管理 `session_id` 的应用仍需保存自己的配置。通过 `cache_session_id=` 恢复保持“只用于缓存”；改用 `session_id=` 恢复则会采用原有传输语义。恢复值须为 1–64 个不含空格的可打印 ASCII 字符，且 `auto_session_id` 须为 True。关闭自动处理或当前 Provider 未声明支持时，该属性返回 None。
+
+core 通过可选的 Provider 能力 `supports_agent_cache_session = True` 判断，不检查模型名，也不导入 Codex 适配器。内置 Provider 中只有 Codex 开启它。自定义 Provider 可主动声明支持并读取 `request.cache_session_id`；已有 Provider 和 `stream_fn` 不需要修改。主动声明支持的包装器应保留原请求或使用 `deepcopy`；通过序列化的 dataclass 字段重建请求会丢失这项缓存专用元数据。默认流包装器会转发底层 Provider 的能力。标识不放入 `request.options`，不增加 `ModelRequest` 的 dataclass 字段，也不增加消息、事件或结果字段。直接调用底层 Provider 不会自动生成标识。
+
+这是与官方 Pi core 的有意差异：上游底层 Agent 只转发可选标识，由 coding-agent 的 `SessionManager` 提供；pi-python 在主要的 Agent 接入入口补齐该便利功能。上游参照版本不变。应用可用 `require_features(["codex-auto-cache-session-v1"])` 检查支持情况。兼容性与验证范围见 [0.11.0 发布说明](../releases/0.11.0.md)。
+
 ## 模型能力表和 DeepSeek
 
 ```python

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pi-python-core"
-version = "0.10.2"
+version = "0.11.0"
 description = "An embeddable asyncio agent core with opt-in Claude and OpenAI providers"
 readme = "README.md"
 requires-python = ">=3.11"

pi_python_core-0.11.0/src/pi_python/_version.py

@@ -0,0 +1 @@
+__version__ = "0.11.0"

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/src/pi_python/agent.py

@@ -69,6 +69,8 @@ class Agent:
         thinking_budgets: dict[str, int] | None = None,
         transport: str | None = None,
         session_id: str | None = None,
+        auto_session_id: bool = True,
+        cache_session_id: str | None = None,
         get_api_key: Callable | None = None,
         on_payload: Callable | None = None,
         on_response: Callable | None = None,
@@ -87,6 +89,21 @@ class Agent:
         if type(include_tool_origin) is not bool:
             raise ConfigurationError("include_tool_origin must be a boolean")
         self.include_tool_origin = include_tool_origin
+        if type(auto_session_id) is not bool:
+            raise ConfigurationError("auto_session_id must be a boolean")
+        if cache_session_id is not None:
+            if (
+                not isinstance(cache_session_id, str)
+                or not 1 <= len(cache_session_id) <= 64
+                or any(not "!" <= char <= "~" for char in cache_session_id)
+            ):
+                raise ConfigurationError(
+                    "cache_session_id must contain 1–64 printable ASCII characters without spaces"
+                )
+            if not auto_session_id:
+                raise ConfigurationError("cache_session_id requires auto_session_id=True")
+        self._auto_session_id = auto_session_id
+        self._cache_session_id = cache_session_id
         self._queues = MessageQueues(steering_mode, follow_up_mode)
         if provider is not None and stream_fn is not None:
             raise ConfigurationError("Pass provider or stream_fn, not both")
@@ -148,6 +165,23 @@ class Agent:
         self._settled = asyncio.Event()
         self._settled.set()
 
+    @property
+    def cache_session_id(self) -> str | None:
+        """Agent-managed Codex cache fallback, independent of explicit session_id.
+
+        Save this alongside history and restore it with cache_session_id=... .
+        Reading it does not enable connection reuse. Explicit session_id takes
+        precedence on requests; cache_retention='none' suppresses both on the wire.
+        """
+        if (
+            not self._auto_session_id
+            or getattr(self.provider, "supports_agent_cache_session", False) is not True
+        ):
+            return None
+        if self._cache_session_id is None:
+            self._cache_session_id = str(uuid4())
+        return self._cache_session_id
+
     @property
     def steering_mode(self) -> str:
         return self._queues.steering_mode
@@ -265,6 +299,7 @@ class Agent:
             raise AgentBusyError("Cannot reset while running")
         baseline = current_system_message(self._messages)
         self._messages = [baseline] if baseline else []
+        self._cache_session_id = None
         self._last_error = None
         self._run = None
         self.clear_all_queues()

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/src/pi_python/features.py

@@ -20,6 +20,7 @@ FEATURES = MCP_FEATURES | frozenset(
         "loop-portal-v1",
         "nested-agent-ownership-v1",
         "application-tool-batches-v1",
+        "codex-auto-cache-session-v1",
         "plugin-requires-v1",
     }
 )

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/src/pi_python/loop.py

@@ -105,6 +105,14 @@ async def stream_response(run: Run) -> tuple[AssistantMessage, bool]:
         deepcopy(context.options),
         model_info=deepcopy(model) if isinstance(model, ModelInfo) else None,
     )
+    if (
+        getattr(run.provider, "supports_agent_cache_session", False) is True
+        and not request.options.get("session_id")
+        and request.options.get("cache_retention") != "none"
+    ):
+        cache_session_id = run.agent.cache_session_id
+        if cache_session_id is not None:
+            request._set_cache_session_id(cache_session_id)
     if run.hooks.get_api_key:
         request.api_key = await run.hook(
             "get_api_key", getattr(run.provider, "name", request.model)

{pi_python_core-0.10.2 → pi_python_core-0.11.0}/src/pi_python/provider.py

@@ -28,6 +28,20 @@ class ModelRequest:
     on_response: Callable | None = field(default=None, repr=False)
     on_provider_stream_event: Callable | None = field(default=None, repr=False)
 
+    def _set_cache_session_id(self, value: str) -> None:
+        # Per-request metadata, deliberately outside the public dataclass fields
+        # and options. It must never be interpreted as a transport session_id.
+        self._agent_cache_session_id = value
+
+    @property
+    def cache_session_id(self) -> str | None:
+        """Optional Agent-owned cache affinity, never a transport session.
+
+        Providers opt in with supports_agent_cache_session=True. This property
+        is not a dataclass field and does not change serialized request options.
+        """
+        return getattr(self, "_agent_cache_session_id", None)
+
 
 @dataclass
 class ModelEvent:
@@ -109,6 +123,10 @@ def has_default_stream() -> bool:
 
 
 class DefaultProvider:
+    @property
+    def supports_agent_cache_session(self) -> bool:
+        return getattr(_default_stream, "supports_agent_cache_session", False) is True
+
     @property
     def name(self) -> str:
         return getattr(_default_stream, "name", "custom")