pi-python-core 0.10.1__py3-none-any.whl → 0.11.0__py3-none-any.whl

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/_version.py

@@ -1 +1 @@
-__version__ = "0.10.1"
+__version__ = "0.11.0"

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

pi_python/features.py

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

pi_python/loop.py

@@ -19,6 +19,7 @@ from .messages import (
     message_from_dict,
     message_to_dict,
     validate_history,
+    convert_application_tool_batch,
 )
 from .models import ModelInfo
 from .provider import ModelRequest
@@ -82,6 +83,12 @@ async def stream_response(run: Run) -> tuple[AssistantMessage, bool]:
         messages = await run.hook("transform_context", messages, run.token)
     if run.hooks.convert_to_llm:
         messages = await run.hook("convert_to_llm", deepcopy(messages))
+    messages = [
+        convert_application_tool_batch(m)
+        if isinstance(m, CustomMessage) and m.custom_type == "application_tool_batch"
+        else m
+        for m in messages
+    ]
     if any(isinstance(m, CustomMessage) for m in messages):
         raise UnsupportedCapabilityError("Custom messages require convert_to_llm")
     validate_history(messages)
@@ -98,6 +105,14 @@ async def stream_response(run: Run) -> tuple[AssistantMessage, bool]:
         deepcopy(context.options),
         model_info=deepcopy(model) if isinstance(model, ModelInfo) else None,
     )
+    if (
+        getattr(run.provider, "supports_agent_cache_session", False) is True
+        and not request.options.get("session_id")
+        and request.options.get("cache_retention") != "none"
+    ):
+        cache_session_id = run.agent.cache_session_id
+        if cache_session_id is not None:
+            request._set_cache_session_id(cache_session_id)
     if run.hooks.get_api_key:
         request.api_key = await run.hook(
             "get_api_key", getattr(run.provider, "name", request.model)
@@ -212,6 +227,8 @@ async def execute_batch(run: Run, outcomes: list[ToolOutcome]) -> None:
             agent_context=snapshot["context"],
             _on_reconciliation_required=lambda: run.require_reconciliation(),
         )
+        if run.application_batch:
+            contexts[id(outcome)]._set_origin(outcome.origin, outcome.source)
         return contexts[id(outcome)]
 
     def abort_before_start(outcome: ToolOutcome) -> bool:
@@ -300,6 +317,32 @@ async def execute_batch(run: Run, outcomes: list[ToolOutcome]) -> None:
             await run.commit_outcome(outcome)
 
 
+def exceeds_tool_budget(run: Run, outcomes: list[ToolOutcome], used: int = 0) -> bool:
+    maximum = run.limits.max_tool_calls
+    if maximum is None or used + len(outcomes) <= maximum:
+        return False
+    for outcome in outcomes:
+        outcome.result = error_result("limit", "Entire tool batch exceeds remaining budget")
+    return True
+
+
+async def run_application_batch(run: Run) -> tuple[str, str]:
+    run.checkpoint()
+    await run.emit("agent_start")
+    if exceeds_tool_budget(run, run.active_batch):
+        return "limit_reached", "max_tool_calls"
+    await execute_batch(run, run.active_batch)
+    if run.agent._unknown:
+        return "failed", "outcome_unknown"
+    if run.stuck():
+        run.fail("Tool did not stop after cancellation")
+        return "cancelled" if run.token.cancelled else "failed", "tool_not_stopped"
+    if run.token.cancelled:
+        status, reason, _ = run.cancelled_outcome()
+        return status, reason
+    return "completed", "stop"
+
+
 async def run_loop(run: Run, initial: list[Message]) -> tuple[str, str]:
     context = run.context
     assert context is not None
@@ -366,13 +409,8 @@ async def run_loop(run: Run, initial: list[Message]) -> tuple[str, str]:
             else:
                 status, reason = "cancelled", run.token.reason or "aborted"
         elif outcomes:
-            max_calls = run.limits.max_tool_calls
-            if max_calls is not None and tool_count + len(outcomes) > max_calls:
+            if exceeds_tool_budget(run, outcomes, tool_count):
                 status, reason = "limit_reached", "max_tool_calls"
-                for outcome in outcomes:
-                    outcome.result = error_result(
-                        "limit", "Entire tool batch exceeds remaining budget"
-                    )
             elif message.stop_reason == "length":
                 for outcome in outcomes:
                     await run.emit(

pi_python/messages.py

@@ -361,6 +361,63 @@ def message_from_dict(data: dict[str, Any]) -> Message:
         raise MessageValidationError(str(exc)) from exc
 
 
+def convert_application_tool_batch(message: CustomMessage) -> UserMessage:
+    """Project built-in application feedback, never local details or raw results.
+
+    An allowlist also protects the default visibility boundary for imported records
+    with extra fields. Applications can override conversion with convert_to_llm.
+    """
+    data = message.data
+    if not isinstance(data, dict) or not isinstance(data.get("calls"), list):
+        raise MessageValidationError("Invalid application tool batch")
+    calls = []
+    for call in data["calls"]:
+        if not isinstance(call, dict):
+            raise MessageValidationError("Invalid application tool call record")
+        keys = (
+            "id",
+            "name",
+            "arguments",
+            "prepared_arguments",
+            "origin",
+            "source",
+            "execution_status",
+            "is_error",
+            "error_code",
+            "content",
+        )
+        try:
+            visible = {key: call[key] for key in keys}
+        except KeyError as exc:
+            raise MessageValidationError("Incomplete application tool call record") from exc
+        validate_json(visible)
+        if (
+            visible["origin"] != "application"
+            or not isinstance(visible["id"], str)
+            or not visible["id"]
+            or not isinstance(visible["name"], str)
+            or not visible["name"]
+            or not isinstance(visible["arguments"], dict)
+            or (
+                visible["prepared_arguments"] is not None
+                and not isinstance(visible["prepared_arguments"], dict)
+            )
+            or (visible["source"] is not None and not isinstance(visible["source"], str))
+            or type(visible["is_error"]) is not bool
+            or visible["execution_status"]
+            not in ("not_started", "running", "succeeded", "failed", "cancelled", "unknown")
+            or (visible["error_code"] is not None and not isinstance(visible["error_code"], str))
+        ):
+            raise MessageValidationError("Invalid application tool call record")
+        _blocks(visible["content"], images=True)
+        calls.append(visible)
+    return UserMessage(
+        "Application tool execution results (application-selected, not model tool calls):\n"
+        + json.dumps({"calls": calls}, ensure_ascii=False, allow_nan=False),
+        timestamp=message.timestamp,
+    )
+
+
 def validate_history(messages: list[Message]) -> None:
     pending: dict[str, str] = {}
     for message in messages:

pi_python/provider.py

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

pi_python/providers/openai.py

@@ -318,6 +318,14 @@ class OpenAIProvider(RemoteProvider):
                 position += 1
         return items, transcript
 
+    def _cache_key(self, request: ModelRequest) -> str | None:
+        if request.options.get("cache_retention", "short") == "none":
+            return None
+        key = request.options.get("session_id")
+        if not key and getattr(self, "supports_agent_cache_session", False) is True:
+            key = request.cache_session_id
+        return key[:64] if isinstance(key, str) else key
+
     def build_request(self, request: ModelRequest, chatgpt_sign_in: bool = False) -> dict[str, Any]:
         model = self.model_info(request)
         compat = model.compat
@@ -334,9 +342,7 @@ class OpenAIProvider(RemoteProvider):
         retention = options.get("cache_retention", "short")
         if retention not in {"none", "short", "long"}:
             raise ConfigurationError("Invalid cache_retention")
-        key = options.get("session_id") if retention != "none" else None
-        if isinstance(key, str) and len(key) > 64:
-            key = key[:64]
+        key = self._cache_key(request)
         body: dict[str, Any] = {
             "model": request.model,
             "input": items,
@@ -436,13 +442,17 @@ class OpenAIProvider(RemoteProvider):
                     "OpenAI-Beta": "responses=experimental",
                 }
             )
-            if (
-                request.options.get("session_id")
-                and request.options.get("cache_retention") != "none"
-            ):
-                headers["session-id"] = headers["x-client-request-id"] = request.options[
-                    "session_id"
-                ][:64]
+            cache_key = self._cache_key(request)
+            if cache_key:
+                if request.options.get("session_id"):
+                    # Preserve the existing precedence of explicit session_id.
+                    headers["session-id"] = headers["x-client-request-id"] = cache_key
+                else:
+                    # Automatic defaults must not overwrite application headers.
+                    supplied = {name.lower() for name in headers}
+                    for name in ("session-id", "x-client-request-id"):
+                        if name not in supplied:
+                            headers[name] = cache_key
         if (
             self.name == "openai"
             and request.options.get("session_id")
@@ -458,7 +468,8 @@ class OpenAIProvider(RemoteProvider):
         body = await self.payload(request, self.build_request(request, chatgpt))
         if transport == "websocket-cached" and not request.options.get("session_id"):
             raise ConfigurationError("websocket-cached requires session_id")
-        # Pi caches a connection per session unless caching is disabled for the request.
+        # Only an application-supplied session_id can opt into connection reuse
+        # and response continuation. The Agent's cache fallback never reaches here.
         cached = (
             request.options.get("session_id")
             if request.options.get("cache_retention") != "none"
@@ -645,6 +656,7 @@ class OpenAIProvider(RemoteProvider):
 class OpenAICodexProvider(OpenAIProvider):
     name = "openai-codex"
     api = "openai-codex-responses"
+    supports_agent_cache_session = True
 
     def __init__(
         self, *, base_url: str = "https://chatgpt.com/backend-api/codex", **kwargs: Any

pi_python/run.py

@@ -15,7 +15,9 @@ from .errors import ConfigurationError
 from .hooks import AgentConfigUpdate, Hooks, RunContext, TurnUpdate
 from .messages import (
     AssistantMessage,
+    CustomMessage,
     Message,
+    ToolCall,
     ToolResultMessage,
     message_to_dict,
     validate_history,
@@ -23,7 +25,7 @@ from .messages import (
 from .errors import SubscriptionError
 from .tools import ToolOutcome, error_result, invoke
 from .transcript import declare_tool_changes
-from .loop import abort_error, failure_message, run_loop
+from .loop import abort_error, failure_message, run_loop, run_application_batch
 
 if TYPE_CHECKING:
     from .agent import Agent
@@ -58,11 +60,24 @@ def merge(target: Any, update: AgentConfigUpdate) -> None:
 class Run:
     """State that lives for one run. The Agent keeps everything that outlives it."""
 
-    def __init__(self, agent: Agent, skip_initial_steering: bool = False):
+    def __init__(
+        self,
+        agent: Agent,
+        skip_initial_steering: bool = False,
+        *,
+        application_calls: list[ToolCall] | None = None,
+        source: str | None = None,
+    ):
         self.agent = agent
         self.token = CancelToken()
         self.id = str(uuid4())
         self.turn = 0
+        self.application_batch = application_calls is not None
+        self.origin = "application" if self.application_batch else "model"
+        self.source = source
+        self.include_tool_origin = agent.include_tool_origin
+        self._limits = agent.limits
+        self._execution_mode = agent.execution_mode
         defaults = agent._defaults
         self.context = RunContext(
             deepcopy(agent._messages),
@@ -74,8 +89,16 @@ class Run:
         self.skip_initial_steering = skip_initial_steering
         self.partial: Any = None
         self.started = False  # message_start was published for the current response
-        self.outcomes: list[ToolOutcome] = []
-        self.active_batch: list[ToolOutcome] = []
+        self.outcomes: list[ToolOutcome] = [
+            ToolOutcome(
+                deepcopy(call),
+                original_arguments=deepcopy(call.arguments),
+            )
+            for call in application_calls or []
+        ]
+        for outcome in self.outcomes:
+            outcome._set_origin("application", source)
+        self.active_batch: list[ToolOutcome] = list(self.outcomes)
         self._committed: set[int] = set()
         self._ended: set[int] = set()
         self._owned: set[asyncio.Future] = set()
@@ -95,11 +118,11 @@ class Run:
 
     @property
     def limits(self) -> RunLimits:
-        return self.agent.limits
+        return self._limits if self.application_batch else self.agent.limits
 
     @property
     def execution_mode(self) -> str:
-        return self.agent.execution_mode
+        return self._execution_mode if self.application_batch else self.agent.execution_mode
 
     @property
     def pending_calls(self) -> tuple[str, ...]:
@@ -199,7 +222,16 @@ class Run:
                 await asyncio.gather(cancel_wait, return_exceptions=True)
 
     async def emit(self, kind: str, call_id: str | None = None, **data: Any) -> None:
-        await self.agent._events.emit(kind, self.id, self.turn, data, call_id, self.await_owned)
+        if self.include_tool_origin and kind.startswith("tool_execution_"):
+            data.update(origin=self.origin, source=self.source)
+        await self.agent._events.emit(
+            kind,
+            self.id,
+            None if self.application_batch else self.turn,
+            data,
+            call_id,
+            self.await_owned,
+        )
 
     async def hook(self, name: str, *args: Any) -> Any:
         callback = getattr(self.hooks, name)
@@ -307,6 +339,8 @@ class Run:
         result = outcome.result
         outcome._settled = True
         self._committed.add(id(outcome))
+        if self.application_batch:
+            return  # One custom batch record is appended after all accepted calls settle.
         message = ToolResultMessage(
             outcome.call.id,
             outcome.call.name,
@@ -330,6 +364,37 @@ class Run:
             execution_status=outcome.execution_status,
         )
 
+    async def append_application_batch(self) -> None:
+        calls = []
+        for outcome in self.outcomes:
+            result = outcome.result
+            assert result is not None  # commit_outcome fills unresolved calls during cleanup.
+            calls.append(
+                {
+                    "id": outcome.call.id,
+                    "name": outcome.call.name,
+                    "arguments": deepcopy(outcome.original_arguments),
+                    "prepared_arguments": deepcopy(outcome.prepared_arguments),
+                    "origin": outcome.origin,
+                    "source": outcome.source,
+                    "execution_status": outcome.execution_status,
+                    "is_error": result.is_error,
+                    "error_code": result.error_code,
+                    "content": [asdict(block) for block in result.content],
+                }
+            )
+        await self.append(
+            CustomMessage(
+                "application_tool_batch",
+                {
+                    "run_id": self.id,
+                    "origin": self.origin,
+                    "source": self.source,
+                    "calls": calls,
+                },
+            )
+        )
+
     async def drive(self, pending: list[Message]) -> RunResult:
         agent = self.agent
         self.driver_started = True
@@ -339,7 +404,11 @@ class Run:
         # or aborted assistant message, followed by turn_end.
         failure: AssistantMessage | None = None
         try:
-            status, reason = await run_loop(self, pending)
+            status, reason = (
+                await run_application_batch(self)
+                if self.application_batch
+                else await run_loop(self, pending)
+            )
         except asyncio.CancelledError:
             status, reason, failure = self.cancelled_outcome()
         except Exception as exc:
@@ -366,6 +435,16 @@ class Run:
             except Exception as exc:
                 status = "failed"
                 errors.append(f"{type(exc).__name__}: {exc}")
+        if self.application_batch:
+            failure = None  # No model turn occurred, including on abort or failure.
+            try:
+                await self.append_application_batch()
+            except asyncio.CancelledError:
+                status = "cancelled" if status != "limit_reached" else status
+                errors.append("Batch message delivery cancelled")
+            except Exception as exc:
+                status = "failed"
+                errors.append(f"{type(exc).__name__}: {exc}")
         tail = agent._messages[-1] if len(agent._messages) > self.start else None
         if failure is not None and not (
             isinstance(tail, AssistantMessage) and tail.stop_reason in {"error", "aborted"}
@@ -420,9 +499,10 @@ class Run:
             self.fail(errors[-1])
             await self.cleanup()
         # Explicit config updates persist even if no further model request occurred.
-        for update in agent._updates:
-            merge(agent._defaults, update)
-        agent._updates.clear()
+        if not self.application_batch:
+            for update in agent._updates:
+                merge(agent._defaults, update)
+            agent._updates.clear()
         usage: dict[str, Any] = {}
         for m in agent._messages[self.start :]:
             if isinstance(m, AssistantMessage):

pi_python/tools.py

@@ -348,8 +348,45 @@ def apply_result_update(result: ToolResult, update: ToolResultUpdate) -> None:
         result.terminate = update.terminate
 
 
+@dataclass(frozen=True)
+class ToolInvocation:
+    """An application-requested call; the Agent assigns its ID."""
+
+    name: str
+    arguments: dict[str, Any]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.name, str) or not self.name:
+            raise ConfigurationError("ToolInvocation requires a nonempty tool name")
+        validate_json(self.arguments)
+        if not isinstance(self.arguments, dict):
+            raise ConfigurationError("ToolInvocation arguments must be an object")
+
+
+class _ToolOrigin:
+    """Read-only provenance without changing legacy dataclass fields/asdict output.
+
+    Model calls need no per-instance storage. Application calls attach provenance
+    explicitly; deepcopy preserves it even though dataclasses.asdict excludes it.
+    """
+
+    _origin = "model"
+    _source: str | None = None
+
+    @property
+    def origin(self) -> str:
+        return self._origin
+
+    @property
+    def source(self) -> str | None:
+        return self._source
+
+    def _set_origin(self, origin: str, source: str | None) -> None:
+        self._origin, self._source = origin, source
+
+
 @dataclass
-class ToolContext:
+class ToolContext(_ToolOrigin):
     run_id: str
     call_id: str
     cancel: CancelToken
@@ -449,7 +486,7 @@ class Tool:
 
 
 @dataclass
-class ToolOutcome:
+class ToolOutcome(_ToolOrigin):
     call: ToolCall
     execution_status: str = "not_started"
     original_arguments: dict[str, Any] = field(default_factory=dict)

{pi_python_core-0.10.1.dist-info → pi_python_core-0.11.0.dist-info}/METADATA

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

{pi_python_core-0.10.1.dist-info → pi_python_core-0.11.0.dist-info}/RECORD

@@ -1,34 +1,34 @@
-pi_python/__init__.py,sha256=S_XoKUqwBbptuM9TSffhcy0NSedNhq0oCJ_huFcDvR0,3916
+pi_python/__init__.py,sha256=-32DW8gNgcvPYNQJZUago0hrkgx_v4VZnOsr4BmG46M,3958
 pi_python/_mcp_host.py,sha256=CXio-tiEeUCUfdl65tatwSrzIOYdgecdS00sO6tNy5k,8630
 pi_python/_mcp_interaction.py,sha256=jPL-C8wLjBDV9tOdvGVFfXOl8-1FQIDJLq-MojlzXaM,43851
 pi_python/_mcp_process.py,sha256=4szi5gMEP_0GUGOcV-oLPUuVQAUSb0ToAaiM979zHME,6324
 pi_python/_mcp_sampling.py,sha256=BcWCrPgjsRC-GNx65fIB-JPq2WzWnoBK2w9iTnyPUww,12148
-pi_python/_version.py,sha256=v7Gyp89umFzDtY45tTjCdXqZnQ2RN01AibdYNxEvxYo,23
-pi_python/agent.py,sha256=I4P4waCdkcURDd022H4XgBbHNhpa7LrI5Iwb5ncxhGU,16021
+pi_python/_version.py,sha256=raMu9XA9JEjvdoTmFqcOw7qhJX24rYDP7XmS59TAO-Q,23
+pi_python/agent.py,sha256=5yd5D_hDGwp74dtvH1SCQUQdLFpc1nxTqAEKBbleSDQ,19797
 pi_python/cancellation.py,sha256=DoQVdX7DcQdVLkl4OvhcpMhKZJEW0Kscl2-xxF6i6Y0,608
 pi_python/errors.py,sha256=65lT0nYfzqxRfUlFG-Y9vgYxfDHEuFiBfgqmFnX9_O8,675
 pi_python/estimate.py,sha256=dQQJ9UEGp57F3wO_CcU2oubgPe841ttgpUseK3Fu_0w,5048
-pi_python/events.py,sha256=t05VE-km2ZcsdIXCviVzNFQCob4xBghDfNeBRWpLrCA,4594
-pi_python/features.py,sha256=3jYcbDnQloPQaQn_qro952tehZYqXqbgsejsdGaiOqY,1642
+pi_python/events.py,sha256=HFYaPB9-yjOvmuM2Ly7SgfWDMJJfX9e1Q7ethqOHSB8,4626
+pi_python/features.py,sha256=Q7X1ke7FcGCyb8XURw4iDa2-wfbaWQQCdbR4-Zh5fsk,1720
 pi_python/function_tools.py,sha256=DO8fZD-n5i62w22zLIjblCOTwnG8N-HIoSUo4yOpRM4,18862
 pi_python/hooks.py,sha256=jm6ep78NjdHxIPZvcOXTZIPxkfBMkffVTNzLvnHS9mM,1321
 pi_python/limits.py,sha256=K1aP1cFH4fVhtWIXqpWMmpkB9AI0wK-bz3Xd2hxnOs4,1157
-pi_python/loop.py,sha256=b0X_hNYXPQZcAjsyw3RIGdYLoZQHhKxm3nBtiznejak,17839
+pi_python/loop.py,sha256=Q67rzG0eERY3Y_NMDdCIbKZiadgdcF2sSB83qni92ms,19263
 pi_python/lowlevel.py,sha256=56wtwqD0Ur1AGAXGa7zclb1IpmRPFpSEss_nspkAdrI,5514
 pi_python/mcp.py,sha256=f7VOiOeBwJ48SrowJWmqtH3d-iavrv2GZo2KH45qeTA,16713
-pi_python/messages.py,sha256=w5e-lc9DLW_4vYZ73Wj32RXfNYzDHdp4HCYsF5qkfHY,15665
+pi_python/messages.py,sha256=jUoQxR-UZbIQYWu257dGiCx8K5z_RV89fJpHgv4t-Ww,18068
 pi_python/models.py,sha256=IejtaWvbURM9vv_2kkoDzfto2TR0OSLjuQeOh3IJZ1k,6094
-pi_python/provider.py,sha256=k_VfJu5WOQla_LkglTDAq5s-77ejCj4YRTyhJ8onZBo,4259
+pi_python/provider.py,sha256=WH1-8YQKuV0PrBTLdNJKN9oXYnnOQiCxt4kD2BL-ebw,5047
 pi_python/proxy.py,sha256=kpEUoE1oDkJW7VVaV72slN3uJUFgYR4Q6jtYOEe8LmQ,12159
 pi_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pi_python/queues.py,sha256=nQ5xRSA3MMOHMs_ZJnG9sT3-d_yKn72oSnxXqiKPrcI,3032
 pi_python/recovery.py,sha256=z5ht-6FoKtC5BPEaSgXiRE2KVf94mZDiKMSxV0mkZ-4,8138
-pi_python/run.py,sha256=J53DLttQNcIUwvGryvEjVuoyCBxdmAsqetQvxmliej8,18640
+pi_python/run.py,sha256=S-mJ5xHVzVXdt8aBicRr4jU1-VZW1-QDi4Cru2hPgmE,21831
 pi_python/stream.py,sha256=R3v-qjCHFQJhHQk83qATz7lC3yr8paJguaHwk8RoHow,10729
 pi_python/sync.py,sha256=uTTX07hxe6TOCgwtfBxSJh2oJFDa2UklNmlCJ9g5-ss,5261
 pi_python/tasks.py,sha256=UNPhb_HSTAaALcstV4X9T4q8JZTyMf90LjRR5bFw26M,4738
 pi_python/testing.py,sha256=XfTSOkEv0CenqrBILI_T205jOhyitW53YQZ9yiMXir4,1046
-pi_python/tools.py,sha256=zBrYVoPOgrVHqvrL5sIhMXCf501QjyuDNdmR-tV6Ads,23274
+pi_python/tools.py,sha256=507d9JXMdn1fsoS1Y1TZIauEf4d570vDeRMfavb9itY,24417
 pi_python/transcript.py,sha256=g6Tg8eiyMCAK43iLpcBv220MHBq8kO7Ty-6OYLCzw2A,6685
 pi_python/data/models.json,sha256=oa_LGv7vaRrS-l7_Z7iu8f7WTyoJJLPhUQyptUz7OmE,77549
 pi_python/plugins/__init__.py,sha256=FeYHYxgaOjKuq3QBBv1ezOyfORi5Fl2SdnImN_O0IrE,56156
@@ -41,10 +41,10 @@ pi_python/providers/anthropic.py,sha256=PCH9h9WHNXbz7Pv01NM1d8NtHANthLRaU1mZUVUc
 pi_python/providers/common.py,sha256=z8dB2pIc-dRscPAppnA3ZwF_wJygunQb9pI9Wl4CvaA,8051
 pi_python/providers/completions.py,sha256=vcqoLfJ-9quMREEEAJcHYs3Oq-A0Sz8Q1NV1QLd3OJA,51362
 pi_python/providers/oauth.py,sha256=ZY8j7P-I-R6hZ8sInkGao957KWNGsqfvMF0F-YzlSgU,22786
-pi_python/providers/openai.py,sha256=p0WHDnojAYb7mUX8EbComwEU_XskcYoMhMIR07QlSfc,30196
+pi_python/providers/openai.py,sha256=c2xzfRd0RgYxbtgl-ruA0yLySq5W63mmwyu_HFQm2g0,30931
 pi_python/providers/transport.py,sha256=B1mGKlVEqYGVK1MlcA9opwRhnuUYGuaYuTslNC3O8xs,26772
-pi_python_core-0.10.1.dist-info/METADATA,sha256=AncCL6Sz-4xE1Kx9_iHB2TmHcOtq8jJjBFHxAGExpxs,8939
-pi_python_core-0.10.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pi_python_core-0.10.1.dist-info/licenses/LICENSE,sha256=BFf1vOw7OyEWBd-10aSQQv1jjzaGpBD-CZwkolrxPEg,1069
-pi_python_core-0.10.1.dist-info/licenses/NOTICE,sha256=fJna16fm1ECHN7zVZhtyNmjLw8KGxGp8mL9blISF1K0,633
-pi_python_core-0.10.1.dist-info/RECORD,,
+pi_python_core-0.11.0.dist-info/METADATA,sha256=m36iv6YTPLV0GsXN29gp-rIwgRQSnO8m-uAtgvsovYs,9146
+pi_python_core-0.11.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pi_python_core-0.11.0.dist-info/licenses/LICENSE,sha256=BFf1vOw7OyEWBd-10aSQQv1jjzaGpBD-CZwkolrxPEg,1069
+pi_python_core-0.11.0.dist-info/licenses/NOTICE,sha256=fJna16fm1ECHN7zVZhtyNmjLw8KGxGp8mL9blISF1K0,633
+pi_python_core-0.11.0.dist-info/RECORD,,