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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pi-python-core
-Version: 0.10.1
+Version: 0.10.2
 Summary: An embeddable asyncio agent core with opt-in Claude and OpenAI providers
 License-Expression: MIT
 License-File: LICENSE

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

@@ -1,6 +1,6 @@
 # 验收映射
 
-首期测试证明的是本文列出的文本和工具行为，不是完整 Pi 或模型智能。27 行是设计中的用例组，不是 27 个单独测试。具体测试总数与命令见 [验证记录](results/verification.json)，逐 fixture 结果见 [差分记录](results/conformance.json)。
+首期测试证明的是本文列出的文本和工具行为，不是完整 Pi 或模型智能。C01–C29 是设计中的用例组，不是 29 个单独测试。具体测试总数与命令见 [验证记录](results/verification.json)，逐 fixture 结果见 [差分记录](results/conformance.json)。
 
 | 用例组 | Python 行为证据 | 上游证据 / 分类 |
 |---|---|---|
@@ -32,6 +32,19 @@
 | C26 release 候选 | test_C26_noop_duplicate_and_synthetic_upgrade 及参数化拒绝测试 | 合成接口演练；独立远端校验脚本另存实际记录 |
 | C27 wheel 安装 | Linux 容器内断网安装、示例、全部 pytest | 实际组合见 linux-3.11/3.12/3.13.json |
 
+## D9：应用工具批次与能力包最小接入
+
+2026-10-16 设计修订的新增合同由 `tests/test_application_tools.py`（C28）和 `tests/test_capability_composition.py`（C29）覆盖。它们是 Python 新增合同，不算作与上游直接一致。
+
+| 用例组 | Python 行为证据 | 分类 |
+|---|---|---|
+| C28 应用工具批次 | 零模型请求；来源与空轮次事件编解码；共享准备、验证、钩子、预算、取消和超时；忙碌互斥；订阅故障保留结果；配置快照；可见性与历史无伪造调用 | intentional_difference，D9 |
+| C29 普通 Python 能力组合 | 同一工具的两种调用方式；名称冲突拒绝；状态与配置隔离；否决不可覆盖；运行完成不掩盖领域验证失败 | intentional_difference，D9；`examples/capability_composition.py` 无网络示例 |
+
+兼容性修订：按用户要求，工具事件的 `origin/source` 改为显式 `Agent(include_tool_origin=True)` 才输出，默认不新增键；两种调用入口都遵守此选项。工具上下文和执行结果通过只读属性提供来源，不改变原有 dataclass 字段及 `asdict` 输出。应用批次历史仍保存来源。`tests/test_application_compatibility.py` 对照 v0.10.1 的字段集合，检查旧解析器、整数轮次及自定义消息转换器；新接口接入时可能的订阅失败和消息被过滤也有明确断言。这是对设计草案中“所有工具事件都携带来源”的兼容性调整，不是将缺失来源默认为已记录。
+
+本次沿用现行版本的默认无预算上限、已知取消与显式未知结果的区分，以及可选扩展能力，不把它们按早期草案回退。跨 run 预算、领域效果、科研判断内化和新的包加载器不在本次实现范围内。上述旧验证文件记录的是各自运行时的版本，不自动成为 D9 的验证证据。
+
 ## 有意差异与范围外行为
 
 D1–D8 保持原设计的含义。D1 严格输入；D2 执行前钩子不能通过原地修改参数改变调用；D3 资源预算；D4 Python 取消及未知结果；D5 状态复制；D6 输出检查；D7 诊断、原始结果和完整流校验；D8 文本与工具子集。每项有独立 Python 断言，不以 skip 代替验收。

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

@@ -6,11 +6,12 @@ Import the public types from `pi_python`. The minimum Python version is 3.11, an
 
 ## Agent and run results
 
-`Agent(provider=..., model="mock" or ModelInfo(...), options={}, system_prompt="", tools=[], messages=[], hooks=Hooks(), limits=RunLimits(), execution_mode="parallel", steering_mode="one_at_a_time", follow_up_mode="one_at_a_time")`. If there is neither a `provider` nor a default stream set with `set_default_stream_fn`, `prompt` raises `ConfigurationError` immediately.
+`Agent(provider=..., model="mock" or ModelInfo(...), options={}, system_prompt="", tools=[], messages=[], hooks=Hooks(), limits=RunLimits(), execution_mode="parallel", steering_mode="one_at_a_time", follow_up_mode="one_at_a_time", include_tool_origin=False)`. If there is neither a `provider` nor a default stream set with `set_default_stream_fn`, `prompt` raises `ConfigurationError` immediately.
 
 | Method | Behavior |
 |---|---|
 | `await prompt(str_or_message_or_list)` | Appends the input and runs; returns a `RunResult` |
+| `await execute_tools(invocations, source=None)` | Runs a nonempty `list[ToolInvocation]` without requesting a model; returns `RunResult` |
 | `await continue_run()` | Continues from a valid user/tool-result history, or consumes input queued after the final answer; if the last answer failed or was cancelled, retries that turn (see "Recovering from failures"); never replays past tools |
 | `prompt_sync(...)` / `continue_run_sync()` | Blocking versions for plain scripts; Ctrl+C cancels the current run; see "Using it from plain scripts" |
 | `steer(message)` | Accepts guidance at the next safe boundary; also takes a string |
@@ -22,12 +23,40 @@ Import the public types from `pi_python`. The minimum Python version is 3.11, an
 | `clear_queues(steering=True, follow_up=True)` | Explicitly clears the given queues |
 | `await aclose()` | Requests cancellation and waits for this instance's cleanup; does not close a shared Provider |
 
-One instance does not accept overlapping `prompt` / `continue_run` calls; the second call raises `AgentBusyError` immediately. `async with Agent(...)` is supported. `state` returns a defensive copy; changing it does not change the history.
+One instance does not accept overlapping `prompt` / `continue_run` / `execute_tools` calls; the second call raises `AgentBusyError` immediately. `async with Agent(...)` is supported. `state` returns a defensive copy; changing it does not change the history.
 
 `RunResult` contains `status` (`completed` / `failed` / `cancelled` / `limit_reached`), the `messages` added by this run, the accumulated numeric `usage`, `stop_reason`, `errors`, `tool_outcomes`, `reconciliation_required`, `cleanup_complete`, and the number of items left in each queue. Usage only sums the top-level numeric fields the Provider reports; it does not estimate cost.
 
 `tool_outcomes` records, in call order, the raw arguments, the prepared arguments, `raw_result` and the final `result`. `execution_status` is `not_started`, `running`, `succeeded`, `failed`, `cancelled` or `unknown`. `cancelled` means the tool was cancelled or timed out; `unknown` only comes from a `ToolOutcomeUnknownError` that the tool raised itself. If execution succeeded but the output check or the after-hook failed, the status is still `succeeded` and the final result is an error. No error triggers an automatic retry.
 
+## Application-selected tools and capability composition
+
+Use `require_features(["application-tool-batches-v1"])` to check that an installed build supports this contract.
+
+```python
+from pi_python import ToolInvocation
+
+result = await agent.execute_tools(
+    [ToolInvocation("check_sample", {"value": -1})], source="sample-checks@1"
+)
+# Inspect tool_outcomes here; completed does not mean a domain check passed.
+await agent.prompt("Interpret the application check results.")
+```
+
+`ToolInvocation(name, arguments)` accepts a registered tool name and a JSON object. Core assigns a unique call ID. Unknown names and schema failures become per-call error results. Empty batches and invalid invocation envelopes are rejected before a run starts. No Provider is required for this entry point.
+
+Each batch is an independent run. It shares argument preparation, schema validation, tool hooks, execution order/concurrency, output checks, tool-call budgets, deadlines and cancellation ownership with model-selected calls. The entire batch is refused if it exceeds `max_tool_calls`. It does not invoke model preparation/conversion hooks or `finish_turn`, consume either input queue, or follow a tool's `terminate` flag into a model loop. Tools and configuration stay fixed during the batch; explicit configuration updates made during it wait until the next run (or a later idle `update_config`), in submission order. Task-wide budgets across several runs belong to the application.
+
+Tool-event payloads keep their previous field sets by default. Set `Agent(include_tool_origin=True)` to add `origin` (`"application"` or `"model"`) and `source` (the caller's diagnostic string, or None) to tool events, for either entry point. This option is captured at run start. `ToolContext` and `ToolOutcome` expose provenance as read-only properties, not dataclass fields: `dataclasses.asdict()` keeps the previous shape and does not include provenance. Read `.origin` / `.source` explicitly or use the batch history record when storing it. Model-selected calls always have `source=None`. A source label is not an authenticated identity.
+
+Existing model runs retain integer `turn_id` values and do not create `application_tool_batch` messages. Application events have `turn_id=None`, because no model turn occurred. Code that computes with turn IDs or stores them in integer-only columns must handle this before adopting `execute_tools` or reading its event logs. An exception from a critical subscriber can fail the run; None itself is valid in the new event codec. Critical end subscribers finish before the Agent becomes idle, subject to the existing cancellation and delivery-failure rules.
+
+History gets one `CustomMessage(custom_type="application_tool_batch", data=...)`, including accepted calls that failed, were cancelled or never started. It contains each call's ID, name, original/prepared arguments, origin/source, execution status, error flag/code and final visible content. It never invents an assistant tool call or an unmatched `ToolResultMessage`. Raw results, structured content and local details stay in `tool_outcomes`; they are not automatically sent to the model. On a subsequent model request, remaining built-in batch messages are converted after the application's `convert_to_llm` hook into explicitly labeled application-result text. Other custom types still require an application converter. This default visibility policy is not a sandbox: application hooks can deliberately expose other fields.
+
+**Custom-converter compatibility:** no converter is needed for built-in batch messages. If an application already supplies `transform_context` or `convert_to_llm`, it should preserve these messages for core to convert, or explicitly convert them itself. Rejecting unknown custom types will fail a subsequent model run; filtering all custom messages may silently remove the feedback. These cases arise when adopting the new entry point or importing its history, not in ordinary pre-existing model history. The `application_tool_batch` type name is now reserved for the built-in record; an application previously using that same custom name must review its converter and payload.
+
+The [offline composition example](../examples/capability_composition.py) uses the same tool with model-selected and application-fixed calls. Plain Python objects supply instruction sections, tools, hooks and validation. The application owns their state and lifecycle, rejects duplicate instruction names, and composes hooks with explicit order and veto rules. Core rejects duplicate tool names. Configuration is recorded in an application-converted `capability_configuration` message; core does not interpret package versions or load a new package format. The example ends with `status="completed"` but `domain_passed=False`: execution success is separate from domain acceptance.
+
 ## Provider
 
 ```python
@@ -122,7 +151,7 @@ Every hook can be a sync or an async function. Contexts and arguments are passed
 | `prepare_request(context, cancel)` | Returns a `TurnUpdate` or None; called before every model request |
 | `prepare_next_turn(context, cancel)` | Returns a `TurnUpdate` or None; called from the second turn on |
 | `transform_context(messages, cancel)` | Returns the message list used for the model request; runs before convert |
-| `convert_to_llm(messages)` | Returns the message list that can be sent to the model; must handle or explicitly filter out `CustomMessage` |
+| `convert_to_llm(messages)` | Returns the message list that can be sent to the model; must handle or explicitly filter out custom types other than the built-in `application_tool_batch` |
 | `before_tool_call(call, args, context)` | True / None allows, False blocks, or return a `ToolResult` to use without executing; if the hook raises, that call gets an error result (`hook_error`) and the run continues, as in Pi |
 | `after_tool_call(call, result, context)` | Returns a full `ToolResult`, a partial `ToolResultUpdate`, or None |
 | `finish_turn(context, cancel)` | Returns `"continue"`, `"end"` or None |

pi_python_core-0.10.2/docs/APPLICATION_TOOLS_IMPLEMENTATION.md

@@ -0,0 +1,76 @@
+# 应用直接执行工具：实现与验证
+
+这次检查的是：应用能否不经过模型决策，直接执行已注册工具，同时保留与模型调用相同的执行规则。现在两种入口共用工具执行路径，应用调用不会伪装成模型调用；无网络示例也验证了“运行完成，但领域检查未通过”。这些结果支持开始在应用侧组合具体能力包，不代表领域方法或科研判断已经实现。
+
+## 新设计如何分工
+
+- **机械 core** 管模型请求、工具执行、参数验证、钩子、事件、预算和取消，不判断领域结论是否正确。
+- **领域能力包** 提供知识、工具、固定步骤和验证规则。应用用普通 Python 代码组合它们，拥有状态与生命周期，并解决名称和规则冲突。
+- **基础模型** 使用这些知识处理具体任务。哪些步骤由模型选择、哪些由应用固定执行，由应用明确决定。
+
+新增的 `Agent.execute_tools([ToolInvocation(...)], source=...)` 让应用可以执行固定检查，而不必先让模型选择工具。它与模型调用共用参数准备、执行前后钩子、输出验证、并发限制、工具预算和取消清理。每批是独立运行；跨批次总预算仍由应用管理。
+
+例如，[组合示例](../examples/capability_composition.py) 检查数值 `-1` 是否达到应用规定的下限 `0`。模型可以选择调用检查工具；应用也可以先执行同一个工具，再把结果交给模型解释。检查程序正常运行，所以运行状态是 `completed`；数值没有达标，所以应用读取的领域验证结果仍是 `False`。
+
+## 记录如何保持可解释
+
+工具上下文和执行结果通过只读属性提供 `origin` 与 `source`，分别表示调用来源和应用自报的诊断标签，不改变原有 dataclass 序列化字段。工具事件默认不新增这两个键，只有显式设置 `Agent(include_tool_origin=True)` 才输出。来源标签不代表认证身份。模型调用标为 `model`，应用调用标为 `application`；应用批次历史始终保存来源。
+
+应用批次不请求模型，不产生模型轮次，也不消费指导或后续输入队列。历史保存一条内置的 `application_tool_batch` 自定义消息，包括各调用的参数、来源、执行状态和整理后的可见内容。后续请求将它转成明确标注的应用结果文本，不制造 assistant 工具调用或悬空工具结果。原始结果和本地详情留在执行结果中，不自动发给模型。
+
+工具名冲突由 core 拒绝。指令段冲突、多个钩子的调用顺序和否决规则由示例中的应用组合器处理。两个能力包实例的可变状态彼此独立。本次没有新增领域包加载器，也没有改动现有插件机制。
+
+## 旧应用的兼容性
+
+按用户要求，来源信息不再默认扩展工具事件或 dataclass 序列化结构。专门的测试使用 v0.10.1 的字段集合，验证严格检查字段的旧消费者仍能走完模型工具循环。来源仍可通过属性显式读取，需要事件记录时再开启选项。
+
+只使用原有 `prompt/continue_run` 且不导入新批次历史的应用，不会收到空轮次或新批次消息。采用 `execute_tools` 后则需要检查接入边界：监听器对 `turn_id=None` 做整数运算会导致订阅失败；已有消息转换器若拒绝新类型，会使后续模型运行失败，若过滤所有自定义消息，则会静默丢掉检查结果。没有自定义转换器时，core 可直接处理内置批次消息；有转换器时，原样保留这类消息也可交给 core 处理。相关成功与失败情况均有测试，但未运行所有实际上层应用的集成测试。
+
+## 验证结果与边界
+
+兼容性修订后的本机全量测试 **798 项通过、2 项跳过**。C28、C29 及兼容性定向测试共 **47 项通过**，覆盖零模型请求、来源与消息编解码、共享执行规则、配置隔离、忙碌互斥、取消与未退出工具、订阅故障和领域验证失败。两项跳过来自既有插件测试：它们只适用于不支持 `meta` 的旧版 SDK，不计入通过数。
+
+实际运行上游和 Python 后，**25 组核心差分全部通过**。新增入口属于 Python 合同 D9，不计作上游直接一致。构建后的 wheel 已在仓库外的独立环境离线安装；43 项应用批次与兼容性测试及组合示例通过。
+
+本报告记录发布准备前的本地验证，环境为 macOS ARM64、Python 3.14。该轮没有重新运行 Linux/HPC、多版本矩阵或真实模型调用；已把新增示例和安装包测试接入现有 CI。0.10.2 的接入说明见[发布说明](releases/0.10.2.md)，远端 CI 结果以对应工作流为准。示例只证明接口能够组合，不测量领域效果，也不包含“把科研判断内化进 PiPilot”。
+
+## 方法与核查附录
+
+### 设计依据
+
+实际采用 `/Users/daidong/Documents/rp-writings/research-ideas/pi-python-core-design/` 下的 2026-10-16 修订，而不是代码仓库中同名的旧副本：
+
+- `DESIGN.md`：“应用直接执行工具”“领域能力包的最小接入约定”。
+- `DEVELOPMENT-PLAN.md`：C28、C29。
+- `UPSTREAM-COMPATIBILITY.md`：D9。
+- `README.md`、`BOOTSTRAP-PROMPT.md`、`DOMAIN-CAPABILITY-PACKS.md`：范围和分工。
+
+现有发布版本已经扩展了早期草案的范围。本次保留已有 Provider、插件、同步接口，以及默认无预算上限、已知取消与显式未知结果的区分，没有按旧草案回退它们。上述实现验证使用未发布的 0.10.1 开发构建，没有升级上游基线。随后经用户确认兼容性方案，安排以 0.10.2 提交、推送和发布；这一授权不构成对所有上层应用的兼容性保证。
+
+### 实现入口
+
+- [Agent API](zh/API.md#应用直接执行工具与能力包组合)：参数、来源、可见性和生命周期合同。
+- `src/pi_python/agent.py`：公开入口和运行互斥。
+- `src/pi_python/loop.py`、`run.py`：共用执行器、批次预算、运行收尾和历史记录。
+- `src/pi_python/messages.py`、`events.py`、`tools.py`：内置消息转换、空轮次事件与调用来源。
+- [兼容性测试](../tests/test_application_compatibility.py)、[C28 测试](../tests/test_application_tools.py)、[C29 测试](../tests/test_capability_composition.py)、[验收映射](../compat/COVERAGE.md#d9应用工具批次与能力包最小接入)。
+- 能力检查：`require_features(["application-tool-batches-v1"])`。
+
+### 实际执行的检查
+
+| 检查 | 命令或方式 | 结果 |
+|---|---|---|
+| 新合同及兼容性 | `.venv/bin/pytest -q tests/test_application_tools.py tests/test_application_compatibility.py tests/test_capability_composition.py` | 47 通过 |
+| 全量测试 | `.venv/bin/pytest -q -ra` | 798 通过，2 跳过 |
+| 静态检查 | `.venv/bin/ruff check src tests examples compat scripts` | 通过 |
+| 格式检查 | `.venv/bin/ruff format --check src tests examples compat scripts` | 114 文件通过 |
+| 类型检查 | `.venv/bin/mypy src/pi_python` | 43 源文件通过 |
+| 补丁检查 | `git diff --check` | 通过 |
+| 实际上游对照 | `.venv/bin/python scripts/conformance.py` | 25 组通过，无差异 |
+| 构建 | `uv build --out-dir /tmp/pi-python-optional-origin-dist` | sdist、wheel 成功 |
+| 独立安装 | 在前一轮建立的独立环境中重新安装本轮 wheel：`uv pip install --python /tmp/pi-python-execute-tools-installed/bin/python --offline --reinstall-package pi-python-core /tmp/pi-python-optional-origin-dist/pi_python_core-0.10.1-py3-none-any.whl` | 成功 |
+| 安装包行为 | 从 `/tmp` 使用独立环境运行组合示例和 `pytest -q -o pythonpath= <仓库>/tests/test_application_tools.py <仓库>/tests/test_application_compatibility.py` | 示例输出 `run=completed; domain_passed=False`；43 测试通过 |
+
+独立安装的导入路径确认为 `/tmp/pi-python-execute-tools-installed/lib/python3.14/site-packages/pi_python/__init__.py`，不是源码目录。本轮全量测试和构建原始输出保留在 `/tmp/pi-python-optional-origin-*.log`；这些是临时日志，不是持久化存储保证。
+
+补充清理边界测试时，首版测试在释放工具后立即调用 `aclose()`，此时清理回调尚未执行，触发了既有的 `CleanupTimeoutError`。测试改为有界等待实际清理完成后关闭，并检查迟到的成功不能改写已提交记录；修正后新合同和全量测试均重新通过。

pi_python_core-0.10.2/docs/releases/0.10.2.md

@@ -0,0 +1,52 @@
+# 0.10.2：应用直接执行工具，来源记录可选输出
+
+本版本新增 `Agent.execute_tools()`，让应用直接执行已注册工具，不必先请求模型决定调用。两种入口共用工具执行与清理路径；旧工具事件默认保持原有字段集合。
+
+## 新增能力
+
+- `ToolInvocation(name, arguments)` 与 `await agent.execute_tools(invocations, source=None)`：独立工具批次，无模型请求，共用参数准备、schema 验证、执行前后钩子、并发限制、预算、超时和取消清理。
+- 应用结果通过内置 `application_tool_batch` 自定义消息记录；不伪造 assistant 工具调用，不生成没有对应调用的 `ToolResultMessage`。
+- `ToolContext.origin/source` 与 `ToolOutcome.origin/source` 只读属性，用于区分模型选择与应用指定的调用。来源标签是诊断信息，不是认证身份。
+- `Agent(include_tool_origin=True)` 可将来源加入工具事件；默认关闭，两种入口都遵守该选项。
+- `require_features(["application-tool-batches-v1"])` 可检查是否支持此合同。
+- 无网络能力包组合示例，演示同一个工具的两种调用方式，以及“运行 completed，但领域验证失败”。没有新增包加载器或领域判断引擎。
+
+## 兼容性与接入注意事项
+
+### 沿用旧接口
+
+原有 `prompt/continue_run` 保持整数轮次 ID，不自动生成应用批次消息。工具事件默认不新增 `origin/source`；`ToolContext` 和 `ToolOutcome` 的 dataclass 字段及 `dataclasses.asdict()` 输出结构保持不变。来源信息需要显式读取属性，或从批次历史、开启来源输出后的事件中保存。
+
+### 采用新接口或读取新记录
+
+1. 应用批次没有模型轮次，其事件的 `turn_id=None`。监听器、数据库字段和事件解析器需要允许这种情况；对 None 做整数运算会出错，关键订阅者失败可能使运行失败。
+2. 没有自定义消息转换器时，core 自动转换内置批次消息。已有 `transform_context/convert_to_llm` 应保留该消息供 core 转换，或自行明确转换。拒绝未知类型可能导致后续模型运行失败；过滤全部自定义消息可能静默丢掉工具反馈。
+3. `application_tool_batch` 是内置消息类型名；已有同名自定义类型的应用应检查其数据与转换规则。
+4. 每批预算只约束当前运行；跨多次运行的任务总预算和领域验收由应用负责。`completed` 不代表领域验证通过。
+
+本版本没有更改默认资源上限、现有插件加载机制或上游参照基线。上述接入边界已经说明，并经项目负责人确认后安排发布；这不等于已验证所有实际上层应用。
+
+## 验证
+
+本地 macOS ARM64 / Python 3.14：全量测试 798 通过、2 跳过；C28、C29 与兼容性定向测试 47 通过；25 组实际上游核心差分通过。Ruff、格式与 mypy 检查通过。两项跳过只适用于不支持 `meta` 的旧版 MCP SDK，不计入通过数。
+
+0.10.2 的 wheel 与源码包通过 `twine check --strict`。wheel 已在仓库外的独立 Python 3.11 环境中安装，版本一致性、组合示例和 43 项应用批次及兼容性测试通过。
+
+发布由 `v0.10.2` 标签触发，CI 验证和构建成功后才上传 PyPI。没有以模拟示例宣称真实模型、HPC 或领域效果已经验证。
+
+## 使用与文档
+
+```python
+from pi_python import ToolInvocation
+
+result = await agent.execute_tools(
+    [ToolInvocation("check_sample", {"value": -1})], source="sample-checks@1"
+)
+# 根据 result.tool_outcomes 验收，而不是仅检查 result.status。
+await agent.prompt("解释应用检查的结果。")
+```
+
+- [中文 API](../zh/API.md#应用直接执行工具与能力包组合)
+- [English API](../API.md#application-selected-tools-and-capability-composition)
+- [无网络组合示例](../../examples/capability_composition.py)
+- [实现与本地验证记录](../APPLICATION_TOOLS_IMPLEMENTATION.md)

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

@@ -6,11 +6,12 @@
 
 ## Agent 与运行结果
 
-`Agent(provider=..., model="mock" 或 ModelInfo(...), options={}, system_prompt="", tools=[], messages=[], hooks=Hooks(), limits=RunLimits(), execution_mode="parallel", steering_mode="one_at_a_time", follow_up_mode="one_at_a_time")`。既没有 `provider` 也没有用 `set_default_stream_fn` 设置默认流时，`prompt` 直接抛 `ConfigurationError`。
+`Agent(provider=..., model="mock" 或 ModelInfo(...), options={}, system_prompt="", tools=[], messages=[], hooks=Hooks(), limits=RunLimits(), execution_mode="parallel", steering_mode="one_at_a_time", follow_up_mode="one_at_a_time", include_tool_origin=False)`。既没有 `provider` 也没有用 `set_default_stream_fn` 设置默认流时，`prompt` 直接抛 `ConfigurationError`。
 
 | 方法 | 行为 |
 |---|---|
 | `await prompt(str_or_message_or_list)` | 追加输入并运行，返回 `RunResult` |
+| `await execute_tools(invocations, source=None)` | 执行非空 `list[ToolInvocation]`，不请求模型，返回 `RunResult` |
 | `await continue_run()` | 从合法的用户/工具结果历史继续，或消费最终回答之后的排队输入；最后一条回答失败或被取消时，重试这一轮（见“从失败中恢复”）；不重放历史工具 |
 | `prompt_sync(...)` / `continue_run_sync()` | 普通脚本里的阻塞版本，按 Ctrl+C 会取消本次运行；见“在普通脚本里使用” |
 | `steer(message)` | 在下一安全边界接纳指导；也接受字符串 |
@@ -22,12 +23,40 @@
 | `clear_queues(steering=True, follow_up=True)` | 显式清除指定队列 |
 | `await aclose()` | 请求取消并等待本实例的清理，不关闭共享 Provider |
 
-同一实例不接受重叠的 `prompt` / `continue_run`，第二次调用立即抛 `AgentBusyError`。支持 `async with Agent(...)`。`state` 返回防御性复制；修改它不会改变历史。
+同一实例不接受重叠的 `prompt` / `continue_run` / `execute_tools`，第二次调用立即抛 `AgentBusyError`。支持 `async with Agent(...)`。`state` 返回防御性复制；修改它不会改变历史。
 
 `RunResult` 包含 `status`（`completed` / `failed` / `cancelled` / `limit_reached`）、本次新增 `messages`、数值用量累计 `usage`、`stop_reason`、`errors`、`tool_outcomes`、`reconciliation_required`、`cleanup_complete` 和两个队列的剩余数量。用量只累加 Provider 报告的顶层数值字段；不推算费用。
 
 `tool_outcomes` 按调用顺序记录原始参数、准备后参数、`raw_result` 和最终 `result`。`execution_status` 是 `not_started`、`running`、`succeeded`、`failed`、`cancelled`、`unknown`。`cancelled` 表示工具被取消或超时；`unknown` 只来自工具主动抛出的 `ToolOutcomeUnknownError`。执行成功但输出检查或后置钩子失败时，状态仍为 `succeeded`，最终结果为错误。所有错误都不触发自动重试。
 
+## 应用直接执行工具与能力包组合
+
+可用 `require_features(["application-tool-batches-v1"])` 检查已安装版本是否支持此合同。
+
+```python
+from pi_python import ToolInvocation
+
+result = await agent.execute_tools(
+    [ToolInvocation("check_sample", {"value": -1})], source="sample-checks@1"
+)
+# 在这里检查 tool_outcomes；completed 不等于领域检查通过。
+await agent.prompt("解释应用执行的检查结果。")
+```
+
+`ToolInvocation(name, arguments)` 接收已注册工具名和 JSON 对象参数，core 分配唯一调用 ID。未知工具名、schema 验证失败成为该调用的错误结果。空批次和不合法的调用对象在运行开始前拒绝。这个入口不要求配置 Provider。
+
+每个批次占用一次独立运行，与模型调用共用参数准备、schema 验证、工具钩子、执行顺序与并发、输出检查、工具预算、超时和取消清理。超过 `max_tool_calls` 时整批不执行。它不调用模型准备或转换钩子，不调用 `finish_turn`，不消费两类输入队列，也不根据工具的 `terminate` 字段启动模型循环。批次的工具与配置保持固定；期间提交的配置更新按提交顺序留到下次运行前应用，或在之后空闲时的 `update_config` 中先应用。跨多次运行的任务总预算由应用管理。
+
+工具事件默认保持原有字段集合。显式设置 `Agent(include_tool_origin=True)` 后，两种入口的工具事件才增加 `origin`（`"application"` 或 `"model"`）及 `source`（调用者提供的诊断字符串或 None）。该选项在每次运行开始时固定。`ToolContext` 和 `ToolOutcome` 通过只读属性提供来源，不新增 dataclass 字段；`dataclasses.asdict()` 保持旧结构，不包含来源信息。需要持久化来源时，显式读取 `.origin` / `.source`，或保存批次历史记录。模型调用的 `source` 始终为 None。来源标签不是认证身份。
+
+原有模型运行仍使用整数 `turn_id`，也不会产生 `application_tool_batch` 消息。应用批次事件的 `turn_id=None`，因为没有发生模型轮次。在采用 `execute_tools` 或读取其事件日志前，对轮次做整数运算或使用仅允许整数的数据库列的应用需要适配。None 本身在新事件编解码器中合法，但关键订阅者抛错可能使运行失败。正常情况下，关键结束订阅完成后实例才空闲；取消和订阅失败仍遵守既有规则。
+
+历史追加一条 `CustomMessage(custom_type="application_tool_batch", data=...)`，记录已接纳调用，包括失败、取消和未执行的调用。每项包含 ID、工具名、原始及准备后参数、来源、执行状态、错误标志与代码、整理后的可见内容。不伪造 assistant 调用，不产生悬空 `ToolResultMessage`。原始结果、结构化内容和本地详情留在 `tool_outcomes`，不自动送模型。后续模型请求中，应用的 `convert_to_llm` 钩子执行后，剩余的内置批次消息自动转成明确标注“应用执行结果”的文本。其他自定义类型仍需应用转换。默认可见性规则不是隔离环境；应用钩子仍可主动公开其他字段。
+
+**已有转换器的兼容性：** 内置批次消息不要求应用编写转换器。若已有 `transform_context` 或 `convert_to_llm`，应保留这类消息交给 core 转换，或自行明确转换。拒绝未知自定义类型会导致后续模型运行失败；过滤所有自定义消息则可能静默丢掉检查结果。这些情况发生在采用新接口或导入其历史之后，普通旧模型历史不会新增这类消息。`application_tool_batch` 现在是内置记录使用的类型名；旧应用若恰好已使用同名自定义类型，需要检查转换器和数据格式。
+
+[无网络组合示例](../../examples/capability_composition.py) 在同一个工具上演示模型选择调用和应用固定调用。普通 Python 对象提供指令段、工具、钩子和验证方法。应用拥有状态与生命周期，拒绝重复指令段名，并明确组合钩子的顺序与否决规则；core 拒绝重复工具名。配置以 `capability_configuration` 自定义消息记录，由应用转换；core 不解释包版本，也不新增包加载格式。示例最终得到 `status="completed"`，但 `domain_passed=False`，保留执行完成与领域验收的区别。
+
 ## Provider
 
 ```python
@@ -110,7 +139,7 @@ def search_papers(query: str, year: int | None = None, limit: int = 10) -> list[
 | `prepare_request(context, cancel)` | 返回 `TurnUpdate` 或 None，在每次模型请求前调用 |
 | `prepare_next_turn(context, cancel)` | 返回 `TurnUpdate` 或 None，从第二轮开始调用 |
 | `transform_context(messages, cancel)` | 返回模型请求使用的消息列表，先于 convert |
-| `convert_to_llm(messages)` | 返回可送模型的消息列表，必须处理或显式过滤 `CustomMessage` |
+| `convert_to_llm(messages)` | 返回可送模型的消息列表，必须处理或显式过滤除内置 `application_tool_batch` 外的自定义消息类型 |
 | `before_tool_call(call, args, context)` | True / None 允许，False 阻止，或返回无需执行的 `ToolResult`；抛异常时该调用得到错误结果（`hook_error`），运行继续，与 Pi 相同 |
 | `after_tool_call(call, result, context)` | 返回完整 `ToolResult`、部分 `ToolResultUpdate` 或 None |
 | `finish_turn(context, cancel)` | 返回 `"continue"`、`"end"` 或 None |

pi_python_core-0.10.2/examples/capability_composition.py

@@ -0,0 +1,149 @@
+"""Offline C29 example: application-owned knowledge, tools, hooks and validation.
+
+This toy check demonstrates composition, not the effectiveness of domain knowledge.
+Run with: python examples/capability_composition.py
+"""
+
+import asyncio
+import json
+from dataclasses import dataclass, field
+
+from pi_python import (
+    Agent,
+    AssistantMessage,
+    ConfigurationError,
+    CustomMessage,
+    Hooks,
+    ScriptedProvider,
+    SystemMessage,
+    Tool,
+    ToolCall,
+    ToolInvocation,
+    ToolResult,
+    UserMessage,
+)
+
+
+@dataclass
+class CheckPack:
+    """A plain Python object owned by one application session, not a plugin loader."""
+
+    name: str = "sample-checks"
+    version: str = "1"
+    minimum: int = 0
+    calls: list[int] = field(default_factory=list)
+
+    @property
+    def instructions(self):
+        return {
+            self.name: "Check the sample before interpreting it. A normal run is not validation."
+        }
+
+    def before(self, call, args, context):
+        # Applications explicitly combine vetoes; a later allow cannot erase a block.
+        return args.get("value") != 999
+
+    async def check(self, args, context):
+        value = args["value"]
+        self.calls.append(value)
+        passed = value >= self.minimum
+        return ToolResult.text(
+            f"sample={value}; domain_passed={passed}",
+            structured_content={"domain_passed": passed},
+        )
+
+    def tools(self):
+        return [
+            Tool(
+                "check_sample",
+                "Check a sample against the application rule",
+                {
+                    "type": "object",
+                    "properties": {"value": {"type": "integer"}},
+                    "required": ["value"],
+                    "additionalProperties": False,
+                },
+                self.check,
+            )
+        ]
+
+
+def compose(packs, provider, mode):
+    """Resolve instruction names and hook order here; Agent checks tool-name conflicts."""
+    sections, tools, metadata = {}, [], []
+    for pack in packs:
+        for name, text in pack.instructions.items():
+            if name in sections:
+                raise ConfigurationError(f"Duplicate instruction section: {name}")
+            sections[name] = text
+        tools.extend(pack.tools())
+        metadata.append({"name": pack.name, "version": pack.version, "minimum": pack.minimum})
+
+    def before(call, args, context):
+        for pack in packs:  # explicit order, stop at the first veto
+            if pack.before(call, args, context) is False:
+                return False
+        return True
+
+    def convert(messages):
+        return [
+            UserMessage("Application capability configuration: " + json.dumps(m.data))
+            if isinstance(m, CustomMessage) and m.custom_type == "capability_configuration"
+            else m  # core handles application_tool_batch, not arbitrary custom types
+            for m in messages
+        ]
+
+    return Agent(
+        provider=provider,
+        tools=tools,
+        messages=[
+            SystemMessage(sections=sections),
+            CustomMessage("capability_configuration", {"packs": metadata, "mode": mode}),
+        ],
+        hooks=Hooks(before_tool_call=before, convert_to_llm=convert),
+    )
+
+
+async def compare():
+    model_pack, application_pack = CheckPack(), CheckPack()
+    model_provider = ScriptedProvider(
+        [
+            AssistantMessage([ToolCall("model-check", "check_sample", {"value": -1})], "tool_use"),
+            AssistantMessage.text("The check failed."),
+        ]
+    )
+    application_provider = ScriptedProvider([AssistantMessage.text("The fixed check failed.")])
+    async with compose([model_pack], model_provider, "model") as model_agent:
+        model_result = await model_agent.prompt("Check sample -1 and interpret it.")
+    async with compose([application_pack], application_provider, "application") as app_agent:
+        batch = await app_agent.execute_tools(
+            [ToolInvocation("check_sample", {"value": -1})], source="sample-checks@1"
+        )
+        assert not application_provider.requests
+        # Domain validation uses the independent tool result, not run status or model prose.
+        domain_passed = batch.tool_outcomes[0].result.structured_content["domain_passed"]
+        interpretation = await app_agent.prompt(
+            "Interpret the fixed check; do not claim it passed."
+        )
+    assert model_result.status == batch.status == interpretation.status == "completed"
+    assert domain_passed is False
+    assert model_pack.calls == application_pack.calls == [-1]
+    assert model_pack.calls is not application_pack.calls
+    assert CheckPack().calls == []
+    return {
+        "model": model_result,
+        "application": batch,
+        "domain_passed": domain_passed,
+        "model_requests": len(model_provider.requests),
+        "application_requests": len(application_provider.requests),
+    }
+
+
+async def main():
+    result = await compare()
+    print(f"run={result['application'].status}; domain_passed={result['domain_passed']}")
+    print("Both paths use the same tool; the application batch made zero model requests.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

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

{pi_python_core-0.10.1 → pi_python_core-0.10.2}/src/pi_python/__init__.py

@@ -64,6 +64,7 @@ from .recovery import (
 )
 from .tools import (
     Tool,
+    ToolInvocation,
     ToolContext,
     ToolExecutor,
     ToolResult,
@@ -151,6 +152,7 @@ __all__ = [
     "is_recoverable_length",
     "is_retryable_error",
     "retry_delay",
+    "ToolInvocation",
     "ToolContext",
     "ToolExecutor",
     "ToolResult",

pi_python_core-0.10.2/src/pi_python/_version.py

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

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

@@ -9,6 +9,7 @@ import asyncio
 from copy import copy, deepcopy
 from dataclasses import dataclass
 from typing import Any, Callable
+from uuid import uuid4
 
 from .cancellation import CancelToken
 from .errors import (
@@ -29,6 +30,7 @@ from .messages import (
     TextContent,
     Message,
     SystemMessage,
+    ToolCall,
     UserMessage,
     validate_history,
     validate_json,
@@ -37,7 +39,7 @@ from .provider import Provider, DefaultProvider, FunctionProvider, has_default_s
 from .queues import MessageQueues
 from .run import CALLER_CANCELLED, Run, RunResult, merge
 from .sync import run_sync
-from .tools import Tool
+from .tools import Tool, ToolInvocation
 from .transcript import current_system_message
 
 
@@ -78,9 +80,13 @@ class Agent:
         execution_mode: str = "parallel",
         steering_mode: str = "one_at_a_time",
         follow_up_mode: str = "one_at_a_time",
+        include_tool_origin: bool = False,
     ):
         if execution_mode not in {"parallel", "sequential"}:
             raise ConfigurationError("Invalid execution mode")
+        if type(include_tool_origin) is not bool:
+            raise ConfigurationError("include_tool_origin must be a boolean")
+        self.include_tool_origin = include_tool_origin
         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")
@@ -204,6 +210,10 @@ class Agent:
         if self._running:
             self._updates.append(update)
         else:
+            # Preserve submission order after an application batch deferred updates.
+            for pending in self._updates:
+                merge(self._defaults, pending)
+            self._updates.clear()
             merge(self._defaults, update)
 
     @staticmethod
@@ -332,6 +342,31 @@ class Agent:
             raise AgentBusyError("Agent already running")
         return await self._start(self._input(message))
 
+    async def execute_tools(
+        self, invocations: list[ToolInvocation], *, source: str | None = None
+    ) -> RunResult:
+        """Execute a nonempty batch without a model request or consuming queued input.
+
+        Shares the model tool path, limits and cancellation ownership. Results are
+        recorded as application feedback, never as assistant/tool-result pairs.
+        ``source`` is caller-supplied diagnostic metadata, not an identity claim.
+        """
+        self._usable()
+        if self._running:
+            raise AgentBusyError("Agent already running")
+        validate_history(self._messages)
+        if not isinstance(invocations, list) or not invocations:
+            raise ConfigurationError("execute_tools requires a nonempty list of ToolInvocation")
+        if source is not None and not isinstance(source, str):
+            raise ConfigurationError("source must be a string or None")
+        calls = []
+        for invocation in invocations:
+            if not isinstance(invocation, ToolInvocation):
+                raise ConfigurationError("Expected ToolInvocation")
+            invocation.__post_init__()
+            calls.append(ToolCall(str(uuid4()), invocation.name, deepcopy(invocation.arguments)))
+        return await self._start([], application_calls=calls, source=source)
+
     def prompt_sync(
         self, message: str | Message | list[Message], images: list[ImageContent] | None = None
     ) -> RunResult:
@@ -369,18 +404,32 @@ class Agent:
         return await self._start([])
 
     async def _start(
-        self, pending: list[Message], skip_initial_steering: bool = False
+        self,
+        pending: list[Message],
+        skip_initial_steering: bool = False,
+        *,
+        application_calls: list[ToolCall] | None = None,
+        source: str | None = None,
     ) -> RunResult:
-        if isinstance(self.provider, DefaultProvider) and not has_default_stream():
+        if (
+            application_calls is None
+            and isinstance(self.provider, DefaultProvider)
+            and not has_default_stream()
+        ):
             raise ConfigurationError(
                 "No model provider: pass Agent(provider=...) or call set_default_stream_fn(...)"
             )
+        for update in self._updates:
+            merge(self._defaults, update)
+        self._updates.clear()
         self._running = True
         self._idle.clear()
         self._settled.clear()
         self._last_error = None
         self._events.failed = False
-        run = self._run = Run(self, skip_initial_steering)
+        run = self._run = Run(
+            self, skip_initial_steering, application_calls=application_calls, source=source
+        )
         run.loop = asyncio.get_running_loop()
         # Driver starts with a checkpoint so cancellation before scheduling still finalizes.
         run.driver = asyncio.create_task(self._drive(run, pending))

{pi_python_core-0.10.1 → pi_python_core-0.10.2}/src/pi_python/events.py

@@ -16,7 +16,7 @@ from .messages import validate_json
 class Event:
     type: str
     run_id: str
-    turn_id: int
+    turn_id: int | None
     sequence: int
     call_id: str | None = None
     data: dict[str, Any] = field(default_factory=dict)
@@ -50,8 +50,7 @@ def decode_event(value: str) -> Event:
         if (
             type(e.sequence) is not int
             or e.sequence < 1
-            or type(e.turn_id) is not int
-            or e.turn_id < 0
+            or (e.turn_id is not None and (type(e.turn_id) is not int or e.turn_id < 0))
         ):
             raise MessageValidationError("Invalid event sequence or turn")
         if e.call_id is not None and not isinstance(e.call_id, str):
@@ -85,7 +84,7 @@ class EventDispatcher:
         self,
         kind: str,
         run_id: str,
-        turn_id: int,
+        turn_id: int | None,
         data: dict[str, Any],
         call_id: str | None,
         await_owned: Callable,