pi-python-core 0.9.0__tar.gz → 0.10.1__tar.gz

{pi_python_core-0.9.0 → pi_python_core-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pi-python-core
-Version: 0.9.0
+Version: 0.10.1
 Summary: An embeddable asyncio agent core with opt-in Claude and OpenAI providers
 License-Expression: MIT
 License-File: LICENSE
@@ -23,6 +23,9 @@ Requires-Dist: jsonschema<5,>=4.18
 Requires-Dist: websockets>=14.2
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.10; extra == 'mcp'
+Provides-Extra: mcp-interactive
+Requires-Dist: jsonschema[format-nongpl]<5,>=4.18; extra == 'mcp-interactive'
+Requires-Dist: mcp<3,>=2.3; extra == 'mcp-interactive'
 Provides-Extra: oauth
 Requires-Dist: pyjwt[crypto]<3,>=2.8; extra == 'oauth'
 Provides-Extra: providers
@@ -37,6 +40,9 @@ An embeddable Python agent core, ported from [Pi](https://github.com/earendil-wo
 
 `pi-agent-core` on PyPI is a separate project that ports an older version from pi-mono (early 2026). This library follows the behavior of Pi v1.0.0, compared case by case with the upstream code's actual output, and ships its own connectors for Claude, OpenAI, DeepSeek and local models, with no model SDK required.
 
+**Using a coding agent?** Start with the [library integration guide](docs/CODING_AGENTS.md).
+To build an extension, follow the [plugin development workflow and complete example](docs/PLUGIN_DEVELOPMENT.md).
+
 ## Install
 
 Python 3.11–3.14 (including free-threaded 3.14t) and PyPy 3.11. No Node.js or model SDK needed.
@@ -53,6 +59,7 @@ You install `pi-python-core` and import `pi_python`.
 | `[oauth]` | Verifies the identity token when you sign in with a ChatGPT account (`openai-chatgpt`); it brings in the compiled `cryptography` package. Claude subscription and Codex sign-in do not need it |
 | `[providers]` | Same as `[oauth]`; keeps install commands from 0.8.1 and earlier working |
 | `[mcp]` | Gives the agent the tools of MCP servers, including those a plugin declares |
+| `[mcp-interactive]` | Lets MCP services request host model calls and user forms; includes sampling profiles, metering and retries. See [MCP interaction](docs/MCP_INTERACTION.md) |
 
 Dependencies are version ranges rather than pins, so the package fits into most existing environments.
 
@@ -92,6 +99,7 @@ To try it offline first: `python examples/quickstart.py`.
 | Use MCP tools | `async with connect_stdio(...) as tools`, or `connect_http(url)` for a remote server | [mcp_tools](examples/mcp_tools.py) |
 | Let one agent call another | Wrap the sub-agent as a tool; cancellation propagates down. Plugins can also define subagents in Markdown | [subagent](examples/subagent.py) |
 | Package and share capabilities | A plugin bundles tools, instructions, hooks, skills, prompt templates, subagents and MCP servers; load it by name or path with `load_plugins` and build the agent with `plugins.agent(...)` | [plugin_demo](examples/plugin_demo.py) |
+| Remember across conversations | Not built in, as in Pi's core; an example plugin saves facts to a file and puts them in the system prompt, ready to copy and adapt | [memory_demo](examples/memory_demo.py) |
 | Intervene mid-run | `steer` injects guidance, `follow_up` queues the next task, `abort` cancels at any time (callable from any thread) | |
 | Context full, service errors | `is_context_overflow` and `is_retryable_error` tell you why, `continue_run()` retries, `transform_context` compacts | [recovery](examples/recovery.py) |
 | Save and restore conversations | `encode_messages` / `decode_messages`; your application decides where to store them | [save_restore](examples/save_restore.py) |
@@ -107,6 +115,8 @@ A few differences are deliberate, such as strict tool-argument validation withou
 
 ## Documentation
 
+- [Coding agents: integrate the library, run an offline example, and verify behavior](docs/CODING_AGENTS.md)
+- [Plugin development: scaffold, readiness checks, packaging, and installed verification](docs/PLUGIN_DEVELOPMENT.md)
 - [Concepts on one page: five ideas and one turn](docs/CONCEPTS.md)
 - [Public API](docs/API.md)
 - [Model connectors, subscription sign-in and local models](docs/PROVIDERS.md)
@@ -118,7 +128,7 @@ A few differences are deliberate, such as strict tool-argument validation withou
 ## Development
 
 ```bash
-uv sync --locked --extra oauth --extra mcp
+uv sync --locked --extra oauth --extra mcp-interactive
 uv run pytest -q
 uv run python scripts/verify.py      # every check, including the comparison with upstream (needs Node)
 ```

{pi_python_core-0.9.0 → pi_python_core-0.10.1}/README.md

@@ -6,6 +6,9 @@ An embeddable Python agent core, ported from [Pi](https://github.com/earendil-wo
 
 `pi-agent-core` on PyPI is a separate project that ports an older version from pi-mono (early 2026). This library follows the behavior of Pi v1.0.0, compared case by case with the upstream code's actual output, and ships its own connectors for Claude, OpenAI, DeepSeek and local models, with no model SDK required.
 
+**Using a coding agent?** Start with the [library integration guide](docs/CODING_AGENTS.md).
+To build an extension, follow the [plugin development workflow and complete example](docs/PLUGIN_DEVELOPMENT.md).
+
 ## Install
 
 Python 3.11–3.14 (including free-threaded 3.14t) and PyPy 3.11. No Node.js or model SDK needed.
@@ -22,6 +25,7 @@ You install `pi-python-core` and import `pi_python`.
 | `[oauth]` | Verifies the identity token when you sign in with a ChatGPT account (`openai-chatgpt`); it brings in the compiled `cryptography` package. Claude subscription and Codex sign-in do not need it |
 | `[providers]` | Same as `[oauth]`; keeps install commands from 0.8.1 and earlier working |
 | `[mcp]` | Gives the agent the tools of MCP servers, including those a plugin declares |
+| `[mcp-interactive]` | Lets MCP services request host model calls and user forms; includes sampling profiles, metering and retries. See [MCP interaction](docs/MCP_INTERACTION.md) |
 
 Dependencies are version ranges rather than pins, so the package fits into most existing environments.
 
@@ -61,6 +65,7 @@ To try it offline first: `python examples/quickstart.py`.
 | Use MCP tools | `async with connect_stdio(...) as tools`, or `connect_http(url)` for a remote server | [mcp_tools](examples/mcp_tools.py) |
 | Let one agent call another | Wrap the sub-agent as a tool; cancellation propagates down. Plugins can also define subagents in Markdown | [subagent](examples/subagent.py) |
 | Package and share capabilities | A plugin bundles tools, instructions, hooks, skills, prompt templates, subagents and MCP servers; load it by name or path with `load_plugins` and build the agent with `plugins.agent(...)` | [plugin_demo](examples/plugin_demo.py) |
+| Remember across conversations | Not built in, as in Pi's core; an example plugin saves facts to a file and puts them in the system prompt, ready to copy and adapt | [memory_demo](examples/memory_demo.py) |
 | Intervene mid-run | `steer` injects guidance, `follow_up` queues the next task, `abort` cancels at any time (callable from any thread) | |
 | Context full, service errors | `is_context_overflow` and `is_retryable_error` tell you why, `continue_run()` retries, `transform_context` compacts | [recovery](examples/recovery.py) |
 | Save and restore conversations | `encode_messages` / `decode_messages`; your application decides where to store them | [save_restore](examples/save_restore.py) |
@@ -76,6 +81,8 @@ A few differences are deliberate, such as strict tool-argument validation withou
 
 ## Documentation
 
+- [Coding agents: integrate the library, run an offline example, and verify behavior](docs/CODING_AGENTS.md)
+- [Plugin development: scaffold, readiness checks, packaging, and installed verification](docs/PLUGIN_DEVELOPMENT.md)
 - [Concepts on one page: five ideas and one turn](docs/CONCEPTS.md)
 - [Public API](docs/API.md)
 - [Model connectors, subscription sign-in and local models](docs/PROVIDERS.md)
@@ -87,7 +94,7 @@ A few differences are deliberate, such as strict tool-argument validation withou
 ## Development
 
 ```bash
-uv sync --locked --extra oauth --extra mcp
+uv sync --locked --extra oauth --extra mcp-interactive
 uv run pytest -q
 uv run python scripts/verify.py      # every check, including the comparison with upstream (needs Node)
 ```

{pi_python_core-0.9.0 → pi_python_core-0.10.1}/README.zh-CN.md

@@ -6,6 +6,9 @@
 
 PyPI 上的 `pi-agent-core` 是另一个独立项目，移植的是 2026 年初 pi-mono 中的旧版本。本库对照 Pi v1.0.0 的行为，与上游的实际运行结果逐组比较；并自带 Claude、OpenAI、DeepSeek 和本地模型的接入，不需要安装任何模型 SDK。
 
+**使用 coding agent 开发？** 先读 [library 接入指南](docs/zh/CODING_AGENTS.md)。
+需要扩展能力时，按 [插件开发流程与完整示例](docs/zh/PLUGIN_DEVELOPMENT.md) 实现、打包和验证。
+
 ## 安装
 
 支持 Python 3.11–3.14（包括无 GIL 的 3.14t）和 PyPy 3.11，不需要 Node 或任何模型 SDK。
@@ -22,6 +25,7 @@ pip install pi-python-core      # 或 uv add pi-python-core
 | `[oauth]` | 用 ChatGPT 账号登录（`openai-chatgpt`）时校验身份令牌，会带进需要编译的 `cryptography`。Claude 订阅和 Codex 登录不需要它 |
 | `[providers]` | 与 `[oauth]` 相同，让 0.8.1 及以前的安装命令仍然可用 |
 | `[mcp]` | 把 MCP 服务器的工具交给 agent，插件声明的 MCP 服务器也需要它 |
+| `[mcp-interactive]` | 允许 MCP 服务请求宿主模型调用及用户表单，支持配置选择、计量与重试。见 [MCP 交互](docs/zh/MCP_INTERACTION.md) |
 
 依赖写的是版本范围而不是固定版本，能和大多数已有环境共存。
 
@@ -61,6 +65,7 @@ agent = Agent(provider=llm, model=llm.model("qwen3:8b", context_window=40960), t
 | 用 MCP 工具 | `async with connect_stdio(...) as tools`；远程服务器用 `connect_http(url)` | [mcp_tools](examples/mcp_tools.py) |
 | 让一个 agent 调用另一个 | 把子 agent 包成工具，取消会一路传下去；插件也可以用 Markdown 定义子 agent | [subagent](examples/subagent.py) |
 | 打包和分享能力 | 插件把工具、说明、钩子、技能、提示模板、子 agent 和 MCP 服务器打成一组；用 `load_plugins` 按名字或路径加载，再用 `plugins.agent(...)` 构造 agent | [plugin_demo](examples/plugin_demo.py) |
+| 跨对话记住信息 | 与 Pi 的核心一样不内置；示例插件把事实存进文件，再放进系统提示，可以复制后修改 | [memory_demo](examples/memory_demo.py) |
 | 中途干预 | `steer` 插入指导，`follow_up` 排队后续任务，`abort` 随时取消（任何线程都可以调用） | |
 | 上下文满了、服务出错 | `is_context_overflow`、`is_retryable_error` 判断原因，`continue_run()` 重试，`transform_context` 压缩 | [recovery](examples/recovery.py) |
 | 保存与恢复对话 | `encode_messages` / `decode_messages`，应用决定存在哪里 | [save_restore](examples/save_restore.py) |
@@ -76,6 +81,8 @@ agent = Agent(provider=llm, model=llm.model("qwen3:8b", context_window=40960), t
 
 ## 文档
 
+- [Coding agents：接入 library、运行离线示例、验证行为](docs/zh/CODING_AGENTS.md)
+- [插件开发：目录结构、就绪检查、打包与安装验证](docs/zh/PLUGIN_DEVELOPMENT.md)
 - [一页看懂：五个概念和一轮的流程](docs/zh/CONCEPTS.md)
 - [公开 API](docs/zh/API.md)
 - [模型接入、订阅登录与本地模型](docs/zh/PROVIDERS.md)
@@ -87,7 +94,7 @@ agent = Agent(provider=llm, model=llm.model("qwen3:8b", context_window=40960), t
 ## 开发
 
 ```bash
-uv sync --locked --extra oauth --extra mcp
+uv sync --locked --extra oauth --extra mcp-interactive
 uv run pytest -q
 uv run python scripts/verify.py      # 全部检查，含与上游的差分（需要 Node）
 ```

{pi_python_core-0.9.0 → pi_python_core-0.10.1}/compat/COVERAGE.md

@@ -133,6 +133,7 @@ CI 第一次在 GitHub 上运行，Linux 和 macOS 全部通过，另外发现
 - 上游由命令行程序发现和加载 package（`pi install`、`settings.json`、项目信任）。本库没有应用程序，由应用代码指定加载哪些插件，不自动发现。已安装的插件通过 entry point 组 `pi_python.plugins` 注册，对应 `pi install npm:...`。
 - 插件代码是 Python 的 `setup(api)`，对应 Pi 扩展的工厂函数。`PluginAPI` 只保留与界面无关的部分（工具、系统提示、钩子、事件、MCP），没有命令、快捷键、渲染器等终端界面接口；另加了 `service`（应用提供的对象）、`options`（按插件分开的设置）、`add_check`（自检）和 `on_close`。
 - 插件处理函数出错时交给 `on_error`，默认写日志；上游交给 `emitError`，显示在界面上。`before_tool_call` 与上游一样，出错时让这次调用失败。应用自己的钩子保持核心行为，不做隔离。
+- 插件注册处理函数时检查它能否接收该钩子传入的位置参数（`subscribe` 为事件一个参数，`add_check` 和 `on_close` 没有参数），不能就报 `ConfigurationError`，加载停止（0.10.1 加入）。上游没有这一步：TypeScript 在编译时检查类型，JavaScript 调用时多出的参数会被忽略。Python 会在每次调用时抛出 `TypeError`，插件处理函数的错误又只写日志，不检查的话这样的处理函数会悄悄失效。应用自己的钩子不做这项检查。
 - 模型用 `read_skill` 工具读取技能（上游让模型用通用的 `read` 工具）。它只能读技能目录里的文件，单个文件不超过 256 KiB。
 - 子 agent 在同一进程、同一事件循环里运行（上游为每个子 agent 启动一个 pi 子进程），使用主 agent 的 Provider 和合并后的全部钩子。上游的子进程会加载同样的扩展，所以插件的处理函数同样作用于子 agent，这一点与上游一致。不指定模型时，子 agent 用调用那一刻主 agent 的模型（上游从设置里取默认模型）。没有上游的 `agentScope`、`cwd` 参数和项目级 agent 的确认步骤。
 - MCP：工具名为 `mcp__<服务器>__<工具>`，但工具名里的 `-` 保留（上游换成 `_`）。字符串里只展开 `${PLUGIN_ROOT}`、`${PYTHON}` 和环境变量，前两个是本库新增；不支持 `!命令`。不支持 OAuth、`exposure` / `toolExposure` 和单次请求超时，这些设置会被忽略并给出警告。新增 `pi_python.mcp.connect_http`，连接 streamable HTTP 服务器；在 MCP SDK 1.10、1.30 和 2.3 上测过。

{pi_python_core-0.9.0 → pi_python_core-0.10.1}/compat/results/verification.json

@@ -15,12 +15,12 @@
         "--extra",
         "providers",
         "--extra",
-        "mcp"
+        "mcp-interactive"
       ],
       "exit_code": 0,
-      "seconds": 0.021038709091953933,
+      "seconds": 0.02251266618259251,
       "stdout": "",
-      "stderr": "Resolved 47 packages in 3ms\nAudited 44 packages in 3ms\n"
+      "stderr": "Resolved 60 packages in 2ms\nAudited 57 packages in 8ms\n"
     },
     {
       "command": [
@@ -35,7 +35,7 @@
         "scripts"
       ],
       "exit_code": 0,
-      "seconds": 0.06494950002525002,
+      "seconds": 0.0649345419369638,
       "stdout": "All checks passed!\n",
       "stderr": ""
     },
@@ -53,8 +53,8 @@
         "scripts"
       ],
       "exit_code": 0,
-      "seconds": 0.02588170801755041,
-      "stdout": "89 files already formatted\n",
+      "seconds": 0.024958166992291808,
+      "stdout": "110 files already formatted\n",
       "stderr": ""
     },
     {
@@ -65,8 +65,8 @@
         "src/pi_python"
       ],
       "exit_code": 0,
-      "seconds": 0.35578474996145815,
-      "stdout": "Success: no issues found in 37 source files\n",
+      "seconds": 0.5702685830183327,
+      "stdout": "Success: no issues found in 43 source files\n",
       "stderr": ""
     },
     {
@@ -77,8 +77,8 @@
         "-q"
       ],
       "exit_code": 0,
-      "seconds": 11.12525479204487,
-      "stdout": "........................................................................ [ 18%]\n........................................................................ [ 36%]\n........................................................................ [ 54%]\n........................................................................ [ 72%]\n........................................................................ [ 90%]\n......................................                                   [100%]\n398 passed in 10.69s\n",
+      "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",
       "stderr": ""
     },
     {
@@ -89,7 +89,7 @@
         "examples/in_memory.py"
       ],
       "exit_code": 0,
-      "seconds": 0.10870087496004999,
+      "seconds": 0.6022720420733094,
       "stdout": "The telemetry contains 3 complete records.\n",
       "stderr": ""
     },
@@ -104,8 +104,8 @@
         "test/agent.test.ts"
       ],
       "exit_code": 0,
-      "seconds": 1.1702424169052392,
-      "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  00:19:15\n   Duration  758ms (transform 566ms, setup 0ms, import 1.06s, tests 171ms, environment 0ms)\n\n",
+      "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",
       "stderr": ""
     },
     {
@@ -121,8 +121,8 @@
         "test/openai-codex-stream.test.ts"
       ],
       "exit_code": 0,
-      "seconds": 1.1117059160023928,
-      "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  00:19:16\n   Duration  816ms (transform 907ms, setup 0ms, import 1.59s, tests 244ms, environment 0ms)\n\n",
+      "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",
       "stderr": ""
     },
     {
@@ -133,7 +133,7 @@
         "scripts/conformance.py"
       ],
       "exit_code": 0,
-      "seconds": 4.8161368750734255,
+      "seconds": 5.7676790410187095,
       "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 +145,7 @@
         "scripts/provider_conformance.py"
       ],
       "exit_code": 0,
-      "seconds": 13.814684083103202,
+      "seconds": 15.009326208150014,
       "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 +157,7 @@
         "scripts/websocket_conformance.py"
       ],
       "exit_code": 0,
-      "seconds": 0.42606441595125943,
+      "seconds": 0.9335567080415785,
       "stdout": "codex-continuation-lost-state.json passed\ncodex-continuation-tool-loop.json passed\n",
       "stderr": ""
     },
@@ -169,7 +169,7 @@
         "scripts/recovery_conformance.py"
       ],
       "exit_code": 0,
-      "seconds": 0.1813259170157835,
+      "seconds": 0.628341041970998,
       "stdout": "recovery classifiers: 44/44 match upstream \n",
       "stderr": ""
     },
@@ -181,8 +181,8 @@
         "scripts/plugin_conformance.py"
       ],
       "exit_code": 0,
-      "seconds": 0.39384091598913074,
-      "stdout": ".......                                                                  [100%]\n7 passed in 0.05s\n",
+      "seconds": 1.306608916958794,
+      "stdout": ".......                                                                  [100%]\n7 passed in 0.74s\n",
       "stderr": ""
     },
     {
@@ -193,10 +193,22 @@
         "examples/plugin_demo.py"
       ],
       "exit_code": 0,
-      "seconds": 0.11929479194805026,
+      "seconds": 0.576676958007738,
       "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": ""
     },
+    {
+      "command": [
+        "uv",
+        "run",
+        "python",
+        "examples/mcp_interactive.py"
+      ],
+      "exit_code": 0,
+      "seconds": 1.8445827078539878,
+      "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": ""
+    },
     {
       "command": [
         "uv",
@@ -206,7 +218,7 @@
         "--help"
       ],
       "exit_code": 0,
-      "seconds": 0.10245537490118295,
+      "seconds": 0.6522026660386473,
       "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": ""
     },
@@ -216,9 +228,9 @@
         "build"
       ],
       "exit_code": 0,
-      "seconds": 1.1796516249887645,
+      "seconds": 1.0952744169626385,
       "stdout": "",
-      "stderr": "Building source distribution...\nBuilding wheel from source distribution...\nSuccessfully built dist/pi_python_core-0.9.0.tar.gz\nSuccessfully built dist/pi_python_core-0.9.0-py3-none-any.whl\n"
+      "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"
     }
   ],
   "status": "passed"

{pi_python_core-0.9.0 → pi_python_core-0.10.1}/docs/API.md

@@ -48,6 +48,8 @@ Every event passes the same check: blocks must pair up, deltas must land in an o
 
 Message data also allows `pending` and `deferred`. `pending` is only for in-stream snapshots and cannot be committed to history; `deferred` can hold a background handle, but the library does not yet poll background tasks. For `length`, every tool call gets a not-executed result, and the model may then handle the error. `error` / `aborted` messages cannot declare tool calls: before the message is committed, its tool calls are removed, the rest of the partial content is kept, and a `removed_tool_calls` entry is added to `diagnostics`.
 
+The Agent closes each request's response iterator when the request ends, including error and cancellation paths. Custom iterators that own resources should implement `aclose()`. This does not close the shared Provider.
+
 ## Tool
 
 `Tool(name, description, input_schema, execute, output_schema=None, execution_mode="parallel", prepare_arguments=None)`.
@@ -81,8 +83,34 @@ def search_papers(query: str, year: int | None = None, limit: int = 10) -> list[
 
 Supported parameter types: `str`, `int`, `float`, `bool`, `None`, `list`, `set`, `tuple`, `dict[str, T]`, `Literal`, `Enum`, `Optional` and other unions, `Annotated[T, "description"]`, `TypedDict`, dataclasses, `datetime`, `date`, `UUID`, `Path`, and pydantic models. Before the call, the JSON arguments are converted to the types the function asks for, such as enum members, dates, dataclasses or pydantic models. A parameter annotated as `ToolContext` receives the call context and does not appear in the schema. `*args`, `**kwargs` and types that cannot be represented as JSON raise `ConfigurationError` at registration.
 
+For a union, conversion tries branches in annotation order, using only branches whose JSON Schema matches the input. For example, `list[int] | str` preserves `"abc"` as a string. When several branches match, the first successful conversion wins.
+
+Schema and conversion are compiled together at registration, including recursive types and union branches. Bare `set`, `frozenset` and `tuple` annotations also convert JSON arrays to the requested Python container. Nested pydantic definitions are isolated between parameters and union branches, even when their class names match.
+
+`TypedDict` requiredness follows resolved `Required` and `NotRequired` annotations,
+including inherited fields and `Annotated` wrappers when annotations are postponed.
+
 Concurrency is unlimited by default: a batch of tools all run at once, as in Pi; set `RunLimits(max_concurrency=...)` when you need a cap. If any tool requires `sequential`, the whole batch runs one at a time. When running concurrently, preparation completes in call order before execution starts; end events follow the order in which post-processing finishes, and results in history follow call order.
 
+Parallel tool and subagent batches own their child tasks: failure or cancellation cancels unfinished siblings and waits for their cleanup. Repeated caller cancellation does not interrupt that cleanup. The Run's existing cleanup deadline still applies; `cleanup_complete` reports whether cleanup actually finished.
+
+Inside a tool, use `await context.run_agent(child, message)` to run an exclusively
+owned, idle child Agent. It returns the child's `RunResult` and closes that Agent;
+the shared Provider stays open. See [the subagent example](../examples/subagent.py).
+An already running child is rejected without cancelling or closing it. Ordinary
+model/tool failures remain results that the calling tool can handle.
+
+Nested calls preserve two separate facts: whether an external operation's outcome
+is known, and whether its work has stopped. An unknown child outcome raises
+`ToolOutcomeUnknownError`, marks the enclosing Agent as requiring reconciliation,
+and stops further execution. This also applies across parallel siblings and multiple
+nesting levels. An unfinished child keeps its enclosing tool pending. The parent's
+cleanup deadline still bounds its run, which reports `cleanup_complete=False` until
+the descendant actually finishes. Repeated cancellation cannot abandon that cleanup.
+Standalone `ToolContext` callers must keep awaiting the call or manage its lifetime
+with `TaskScope`; without an enclosing Agent there is no Run cleanup deadline.
+Check `require_features(["nested-agent-ownership-v1"])` when depending on this API.
+
 A standalone program can call `await run_tool_call(tool, call, context, before_tool_call=..., after_tool_call=...)` to reuse the same validation and hook path. For standalone calls, the program manages lifetime, timeouts and cancellation itself; `Agent` adds batch management and `RunLimits`.
 
 ## Hooks
@@ -159,6 +187,23 @@ async with connect_stdio("uvx", ["mcp-server-fetch"], prefix="web") as tools:
 
 Requires `pip install 'pi-python-core[mcp]'` and works with the official MCP SDK 1.10 and later, including 2.x. `connect_stdio` starts a stdio MCP server and closes it when the `async with` block exits. `connect_http(url, headers=None, prefix=None, names=None)` connects to a streamable HTTP server in the same way; the legacy SSE transport is not supported, as in Pi. It follows redirects only within the server's origin, so headers are never sent to another one. It is tested with MCP SDK 1.10, 1.30 and 2.3. If you already have a `ClientSession`, wrap its tools with `await mcp_tools(session, prefix=None, names=None)`. Conversion follows Pi's MCP adapter: text and images convert directly; embedded text or image resources are unpacked; audio, resource links and binary resources become short text descriptions; a result with only structured content becomes JSON text and is also kept as `structured_content`; MCP's `isError` becomes a tool error; progress notifications become `tool_execution_update` events. After the prefix is added, tool names keep only letters, digits, `_` and `-`, up to 64 characters. A tool whose schema cannot be used is skipped with a warning, without affecting the server's other tools. A stdio server written with Python MCP SDK 2.3 cannot start on PyPy (`fcntl.F_DUPFD_CLOEXEC` is missing); this is a limitation of the SDK itself, and the client side is unaffected.
 
+On POSIX, `connect_stdio(..., process_scope=True)` also cleans surviving process
+groups and nested pi-python stdio connections on exit. It is opt-in at the outer
+connection and inherited by nested connections. Non-POSIX systems reject explicit
+enablement. See [process ownership](MCP_INTERACTION.md) for scope and limitations.
+
+All three MCP entry points accept optional `call_metadata`, a JSON object passed to
+`ClientSession.call_tool(meta=...)`. It is copied per registration and call, stays out
+of tool arguments, and requires an SDK with `meta` support; otherwise registration
+raises `ConfigurationError`. See [runtime metadata and readiness](PLUGINS.md#mcp-servers)
+for plugin configuration and startup checks.
+
+`connect_stdio` and `connect_http` also accept `callbacks=MCPCallbacks(...)` for
+host-authorized sampling and form elicitation. `SamplingHandler` adapts a host Provider;
+`SamplingProvider` runs a server Agent through the current MCP request. This opt-in
+feature requires SDK >=2.3,<3. See [MCP interaction](MCP_INTERACTION.md) for public APIs,
+protocol constraints, cancellation, and the runnable offline example.
+
 ## Plugins
 
 `pi_python.plugins` loads plugins: named bundles of tools, system prompt text, hooks, skills, prompt templates, subagents and MCP servers, in the format of Pi's packages. `async with load_plugins([...], services=..., options=...) as plugins:` loads them, and `plugins.agent(...)` builds an Agent with everything they contribute. The [plugin guide](PLUGINS.md) covers writing, distributing and combining plugins.
@@ -216,3 +261,45 @@ OpenAI may add encrypted_content back in the final response. If the visible reas
 `AssistantMessage.provider_thinking_level` matches upstream: it records this answer's effort only for Claude models that use effort markers, so later requests can rebuild the markers in history. Read `thinking_level` when you need the requested level.
 
 When replaying history, Providers skip `error` / `aborted` answers following upstream's rules; reasoning from a different model is converted to plain text and its signature is dropped; a system message that sits between a tool call and its result is moved after the result. The session history itself is unchanged.
+
+Host sampling profiles, usage observation, retry policy, and build feature markers are documented in [MCP interactions](MCP_INTERACTION.md#real-providers-profiles-accounting-and-retries).
+
+
+## Owned tasks and calls from worker threads
+
+`TaskScope` owns the asynchronous calls passed to `await scope.run(awaitable,
+cancel=token)`. Each call runs in a child task. Cancelling the caller or token
+cancels that task and waits for its cleanup. `await scope.aclose()` rejects new
+calls, cancels active calls, and joins them, including calls waiting on an
+application lock. Use `async with TaskScope() as scope`, or a plugin's
+`api.task_scope()` to register automatic cleanup. Exceptions go to the individual
+caller. Closing does not re-raise a completed call's error. Work must cooperate
+with cancellation; this API does not terminate threads or impose a deadline.
+An owned task cannot close its own scope. A scope is bound to its first event loop.
+
+`LoopPortal` submits async work from a synchronous worker thread onto an **existing**
+event loop. This differs from `run_sync`, which owns a separate background loop.
+Create and close the portal on the loop that owns the connection:
+
+```python
+import asyncio
+from pi_python import LoopPortal
+
+async def request(connection):
+    async with LoopPortal() as portal:
+        # A callable is passed, not a coroutine created in the worker thread.
+        return await asyncio.to_thread(portal.call, connection.fetch, "item")
+```
+
+`portal.call(async_function, *args, timeout=None, **kwargs)` returns the result or
+raises the error in the worker thread, preserving its context variables. Blocking
+an event-loop thread is rejected. Closing cancels and joins submitted work without
+closing the borrowed loop. A timeout bounds the blocking wait and requests async
+cancellation; `aclose()` waits for that cleanup. Keep the owning loop running until
+the portal has closed. Application threads themselves remain application-owned.
+
+`FEATURES` is the immutable set of versioned APIs provided by the current build.
+`require_features(names, where="Application")` raises `ConfigurationError` for
+unknown or unavailable features. It does not validate installed optional packages,
+MCP peer capabilities, credentials, or host authorization. `MCP_FEATURES` remains
+available and is a subset. Plugin declarations are described in [Plugins](PLUGINS.md#declaring-required-framework-features).