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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pi-python-core
-Version: 0.9.0
+Version: 0.10.0
 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.
 
@@ -107,6 +114,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 +127,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.0}/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.
 
@@ -76,6 +80,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 +93,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.0}/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) |
 
 依赖写的是版本范围而不是固定版本，能和大多数已有环境共存。
 
@@ -76,6 +80,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 +93,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.0}/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).

pi_python_core-0.10.0/docs/CODING_AGENTS.md

@@ -0,0 +1,176 @@
+# Using pi-python-core with a coding agent
+
+**English** | [中文](zh/CODING_AGENTS.md)
+
+Use this guide when building an application **with** this library. Start with the
+offline tool call below, then replace its model provider. For a reusable extension,
+follow [Plugin development](PLUGIN_DEVELOPMENT.md). Repository maintenance commands
+are at the end; they are not required in a consuming application.
+
+## 1. Establish the environment
+
+The distribution is `pi-python-core`; the import is `pi_python`. Python 3.11 or later
+is required. The library uses asyncio. Import public APIs from `pi_python`,
+`pi_python.providers`, `pi_python.plugins`, or `pi_python.mcp`, rather than private
+modules whose names start with `_`.
+
+In a consuming project, install with `uv add pi-python-core` or
+`python -m pip install pi-python-core`. Optional extras are `[mcp]` for MCP tools,
+`[mcp-interactive]` for host sampling/forms, and `[oauth]` for ChatGPT identity-token
+verification. Built-in model connectors do not require an extra.
+
+When working from this checkout, run these commands from the repository root:
+
+```bash
+uv sync --locked --extra mcp-interactive
+uv run python examples/quickstart.py
+uv run python examples/plugin_demo.py
+```
+
+These examples are offline and need no credentials. The docs describe the checked-out
+code; its version may not yet be published. Inspect `pyproject.toml` and check the
+installed version with `python -c "from importlib.metadata import version; print(version('pi-python-core'))"`.
+For another project to use this checkout, install it in that project's environment
+with `python -m pip install -e /absolute/path/to/pi-python` (append
+`[mcp-interactive]` to that path if needed).
+
+## 2. Run a complete offline tool call
+
+Save this as `app.py` and run `python app.py` in the installed environment, or
+`uv run python app.py` in this checkout. It prints `3 words.` and checks the actual
+tool result, not just the model's scripted answer.
+
+```python
+import asyncio
+
+from pi_python import (
+    Agent, AssistantMessage, RunLimits, ScriptedProvider, TextContent, ToolCall, tool,
+)
+
+
+@tool
+def count_words(text: str) -> dict[str, int]:
+    """Count whitespace-separated words in text."""
+    return {"words": len(text.split())}
+
+
+async def main() -> None:
+    provider = ScriptedProvider([
+        AssistantMessage([
+            ToolCall("count-1", "count_words", {"text": "one two three"}),
+        ], stop_reason="tool_use"),
+        AssistantMessage.text("3 words."),
+    ])
+    async with Agent(
+        provider=provider,
+        tools=[count_words],
+        limits=RunLimits(max_model_requests=4, max_tool_calls=4, run_timeout=30),
+    ) as agent:
+        result = await agent.prompt("Count the words in: one two three")
+        if result.status != "completed":
+            raise RuntimeError(f"{result.status}: {result.errors}")
+        outcome = result.tool_outcomes[0]
+        assert outcome.execution_status == "succeeded"
+        assert outcome.result.structured_content == {"words": 3}
+        answer = result.messages[-1]
+        assert isinstance(answer, AssistantMessage)
+        print("".join(b.text for b in answer.content if isinstance(b, TextContent)))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+`Agent` owns the conversation and tool loop. A `Provider` supplies model responses.
+`@tool` turns a typed function and its docstring into a tool declaration. The model
+chooses tool names and JSON arguments; the library validates arguments and executes
+the functions. `ScriptedProvider` fixes those choices for a deterministic test. It
+does not demonstrate that a real model will choose the same tool or answer.
+
+## 3. Replace the provider, keep application ownership explicit
+
+For a real model, pass the application's credentials and chosen model explicitly.
+Inside an async function, the replacement looks like this (it makes a paid/network
+call and is not part of the offline example):
+
+```python
+import os
+from pi_python.providers import AnthropicProvider
+
+provider = AnthropicProvider(api_key=os.environ["ANTHROPIC_API_KEY"])
+try:
+    async with Agent(
+        provider=provider,
+        model=os.environ["ANTHROPIC_MODEL"],
+        tools=[count_words],
+        limits=RunLimits(max_model_requests=4, run_timeout=60),
+    ) as agent:
+        result = await agent.prompt("Count the words in: one two three")
+        if result.status != "completed":
+            raise RuntimeError(f"{result.status}: {result.errors}")
+finally:
+    await provider.aclose()
+```
+
+`Agent.aclose()` closes the agent's work, not a shared provider. The application
+closes its provider after all agents using it are done. Keep creation, use and
+cleanup on the same event loop. For another connector, use
+[Providers](PROVIDERS.md) and the runnable [local-model example](../examples/local_model.py).
+
+## 4. Observe the contracts when writing application code
+
+| Concern | Contract to follow |
+|---|---|
+| Async versus sync | In servers/notebooks use `await agent.prompt(...)`. In a plain synchronous script use `agent.prompt_sync(...)`. Do not call a blocking API on an event-loop thread or repeatedly wrap a loop-bound provider in separate `asyncio.run` calls. |
+| Conversation ownership | One agent accepts one active run. Await turns in order; use separate agents for independent conversations. `agent.state` is a copy. |
+| Completion | Check `result.status`: `completed`, `failed`, `cancelled`, or `limit_reached`. Model/tool failures are not all raised as Python exceptions. Inspect `errors` and `tool_outcomes` before accepting a business result. |
+| Tool inputs | Give functions typed parameters and clear docstrings. A `ToolContext` parameter is injected and omitted from the model schema. Arguments are validated without JSON type coercion. |
+| Tool outputs | Return JSON-compatible values or `ToolResult`. Dicts/numbers are available as `structured_content` and text. `details` is application data; it is not automatically sent to the model. |
+| Concurrency and limits | Tool batches run in parallel by default. Set `RunLimits`; use `@tool(execution_mode="sequential")` for tools that require a sequential batch. Plain functions run in worker threads; cancellation cannot forcibly stop those threads. |
+| Cancellation | Use `agent.abort()` and await completion/cleanup. Check `cleanup_complete` and `reconciliation_required` before reusing an agent or retrying a side effect. Prefer async tools for cancellable I/O. |
+| Recovery | `continue_run()` can retry a failed model turn without replaying past tools. It is not a general retry mechanism for failed business operations. See [recovery](../examples/recovery.py). |
+| Persistence | Store `encode_messages(list(agent.state.messages))`; restore with `decode_messages` and `Agent(messages=...)`. `result.messages` contains only the current run's additions. See [save/restore](../examples/save_restore.py). |
+| Streaming | `agent.subscribe(listener)` receives `message_update` events with `delta_type` and `delta`. Critical listeners are awaited, so keep them bounded. See [quickstart](../examples/quickstart.py). |
+
+For application-owned async work use `TaskScope`. To call an existing async connection
+from a synchronous tool's worker thread, use `LoopPortal` created on its owning loop.
+Do not move that connection to `run_sync`'s separate loop. See
+[task ownership and thread calls](API.md#owned-tasks-and-calls-from-worker-threads).
+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.
+
+## 5. Choose the smallest integration surface
+
+| Need | Start here |
+|---|---|
+| A few tools in one application | `Agent(..., tools=[...])`; no plugin is necessary. |
+| Reusable tools, instructions and resources | [Plugin development workflow](PLUGIN_DEVELOPMENT.md), then [plugin API](PLUGINS.md). |
+| Tools from an MCP server | [MCP tools example](../examples/mcp_tools.py); keep the connection open for the agent's lifetime. |
+| MCP server requests a host model or form | [MCP interactions](MCP_INTERACTION.md) and [offline example](../examples/mcp_interactive.py). Use the interactive extra and explicit host callbacks. |
+| A nested agent | Use `await context.run_agent(child, message)` inside a tool to preserve cleanup ownership and unknown outcomes; see the [subagent example](../examples/subagent.py). Plugins can supply definitions in `agents/`. |
+| Your own model adapter | The [Provider contract](API.md#provider); emit exactly one terminal `ModelEvent.done` and honor cancellation. |
+
+MCP incremental sampling is a negotiated extension. It reconstructs the full request
+before host policy and model access. It reduces repeated MCP transmission, not the
+model's history or token count; business code should not manage its internal cache.
+
+## 6. Verify before handing off
+
+For a consuming application, run an offline tool-call test, assert the actual tool
+result, exercise failure/cancellation when relevant, and then test the configured real
+provider separately. Report which paths ran. For plugins, also verify the installed
+wheel using the [plugin workflow](PLUGIN_DEVELOPMENT.md).
+
+When changing this library itself, read the applicable `AGENTS.md`, follow its scope,
+and run the relevant tests. The repository checks are:
+
+```bash
+uv run ruff check src tests examples compat scripts
+uv run ruff format --check src tests examples compat scripts
+uv run mypy src/pi_python
+uv run pytest -q
+```
+
+Use [API](API.md) for exact contracts, [concepts](CONCEPTS.md) for the execution model,
+and [reference verification](../reference/README.md) when a change affects upstream
+compatibility. Do not invent methods or assume a different agent framework's APIs apply.