power-loop 7.3.1__tar.gz → 9.0.0__tar.gz

{power_loop-7.3.1 → power_loop-9.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 7.3.1
+Version: 9.0.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: anthropic
@@ -27,6 +27,8 @@ Provides-Extra: openai
 Requires-Dist: openai>=1.52.0; extra == "openai"
 Provides-Extra: skills
 Requires-Dist: pyyaml>=6.0; extra == "skills"
+Provides-Extra: workflow
+Requires-Dist: pyyaml>=6.0; extra == "workflow"
 Provides-Extra: pdf
 Requires-Dist: pypdf>=5.3.0; extra == "pdf"
 Provides-Extra: images
@@ -303,7 +305,8 @@ Every event carries a process-wide `seq` and a monotonic clock, so streams total
 from power_loop.contrib.mcp import StdioMCPClient, register_mcp_tools   # power-loop[mcp]
 
 client = await StdioMCPClient("npx", ["-y", "@modelcontextprotocol/server-filesystem", "/data"]).connect()
-await register_mcp_tools(registry, client, prefix="fs.")   # MCP tools → power-loop ToolDefinitions
+from power_loop.runtime.pricing import Free
+await register_mcp_tools(registry, client, pricing=Free("local_filesystem"), prefix="fs.")   # MCP tools → power-loop ToolDefinitions
 ```
 
 The seam is a tiny `MCPToolSource` Protocol, so the `mcp` SDK is optional and any client works.
@@ -342,7 +345,7 @@ POWER_LOOP_API_KEY=sk-...
 POWER_LOOP_MODEL=gpt-4o-mini
 ```
 
-Python 3.10+. See [Getting Started](docs/en/getting-started.md). Optional extras: `postgres`, `mysql`, `skills`, `pdf`, `prometheus`, `statsd`, `otel`, `mcp`.
+Python 3.11+. See [Getting Started](docs/en/getting-started.md). Optional extras: `postgres`, `mysql`, `skills`, `pdf`, `prometheus`, `statsd`, `otel`, `mcp`.
 
 ---
 
@@ -375,3 +378,43 @@ power-loop **orchestrates; it does not, by itself, isolate.** The built-in `bash
 - **Used by:** DeepTalk — the agent runtime for a 1-on-1 relationship-IM product's in-conversation agents. *(Using it in production? PR a line here.)*
 - **Develop:** `pip install -e ".[dev]"` · `ruff check .` · `pytest -q --no-real` (drop `--no-real` for the live-LLM suite; set a `POWER_LOOP_TEST_PG_DSN` / `POWER_LOOP_TEST_MYSQL_DSN` to run the server-backend conformance suites).
 - [Docs](docs/en/index.md) · [Architecture](docs/en/architecture.md) · [Storage backends](docs/en/user-guide/storage-backends.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [License](LICENSE)
+
+Trusted host tools declare roles, admission and background behavior through the
+[RuntimeTool interface](docs/runtime-tool-contracts.md); names do not grant capabilities.
+
+
+### Explicit tool pricing
+
+Every registered tool definition must provide `pricing`, including local and
+control tools: `ToolDefinition(name="local", description="...", pricing=Free("local"))`.
+Import `Free` or implement `PricingSpec` from `power_loop.runtime.pricing`.
+Registration rejects a missing declaration. The rule version is retained with the
+registration and pending call identity; changing it requires a new registration,
+and cannot silently reprice a previously planned call. Pricing metadata is not
+sent to the model as part of the tool schema.
+
+MCP registration requires either one explicit server pricing rule or a mapping
+from remote tool names to rules. Missing entries reject the batch before any tool
+is registered. An external service is not assumed free.
+
+Native callbacks can return `ToolResult(content, billing_receipt=receipt)`; only
+`content` is shown to the model. Async callbacks can instead
+`await record_billing_receipt(receipt)` immediately after receiving provider billing
+facts, before subsequent response processing might fail. Both helpers are
+provisional top-level exports; `BillingReceipt` is in `power_loop.runtime.pricing`.
+The awaited capture is bound to the original callback task and persisted call,
+and repeating the same receipt is idempotent. A different receipt is rejected.
+Receipt capture requires the native callback checkpoint path; it does not yet
+support managed recovery adapters or legacy invocation. Persisting a receipt
+does not acknowledge successful execution or settle a charge. Host budget and
+settlement wiring is still required before paid tools can be enabled.
+
+An ordinary native callback can invoke a priced internal tool with the provisional
+`await invoke_priced_tool(definition, arguments, handler)` export. Each invocation
+gets a separate budget attempt linked to its original source callback. Its price
+must already be bound, and provider facts use the same `record_billing_receipt` API.
+Internal concurrent tasks are retained and joined before the source callback ends.
+After the exact charge is locally durable, API delivery failure leaves a pending
+budget submission and preserves the real tool result. Reconciliation never calls
+the handler again or reads a replacement price. Managed recovery sources without
+an ordinary callback checkpoint still need a separate adapter.

{power_loop-7.3.1 → power_loop-9.0.0}/README.md

@@ -227,7 +227,8 @@ Every event carries a process-wide `seq` and a monotonic clock, so streams total
 from power_loop.contrib.mcp import StdioMCPClient, register_mcp_tools   # power-loop[mcp]
 
 client = await StdioMCPClient("npx", ["-y", "@modelcontextprotocol/server-filesystem", "/data"]).connect()
-await register_mcp_tools(registry, client, prefix="fs.")   # MCP tools → power-loop ToolDefinitions
+from power_loop.runtime.pricing import Free
+await register_mcp_tools(registry, client, pricing=Free("local_filesystem"), prefix="fs.")   # MCP tools → power-loop ToolDefinitions
 ```
 
 The seam is a tiny `MCPToolSource` Protocol, so the `mcp` SDK is optional and any client works.
@@ -266,7 +267,7 @@ POWER_LOOP_API_KEY=sk-...
 POWER_LOOP_MODEL=gpt-4o-mini
 ```
 
-Python 3.10+. See [Getting Started](docs/en/getting-started.md). Optional extras: `postgres`, `mysql`, `skills`, `pdf`, `prometheus`, `statsd`, `otel`, `mcp`.
+Python 3.11+. See [Getting Started](docs/en/getting-started.md). Optional extras: `postgres`, `mysql`, `skills`, `pdf`, `prometheus`, `statsd`, `otel`, `mcp`.
 
 ---
 
@@ -299,3 +300,43 @@ power-loop **orchestrates; it does not, by itself, isolate.** The built-in `bash
 - **Used by:** DeepTalk — the agent runtime for a 1-on-1 relationship-IM product's in-conversation agents. *(Using it in production? PR a line here.)*
 - **Develop:** `pip install -e ".[dev]"` · `ruff check .` · `pytest -q --no-real` (drop `--no-real` for the live-LLM suite; set a `POWER_LOOP_TEST_PG_DSN` / `POWER_LOOP_TEST_MYSQL_DSN` to run the server-backend conformance suites).
 - [Docs](docs/en/index.md) · [Architecture](docs/en/architecture.md) · [Storage backends](docs/en/user-guide/storage-backends.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [License](LICENSE)
+
+Trusted host tools declare roles, admission and background behavior through the
+[RuntimeTool interface](docs/runtime-tool-contracts.md); names do not grant capabilities.
+
+
+### Explicit tool pricing
+
+Every registered tool definition must provide `pricing`, including local and
+control tools: `ToolDefinition(name="local", description="...", pricing=Free("local"))`.
+Import `Free` or implement `PricingSpec` from `power_loop.runtime.pricing`.
+Registration rejects a missing declaration. The rule version is retained with the
+registration and pending call identity; changing it requires a new registration,
+and cannot silently reprice a previously planned call. Pricing metadata is not
+sent to the model as part of the tool schema.
+
+MCP registration requires either one explicit server pricing rule or a mapping
+from remote tool names to rules. Missing entries reject the batch before any tool
+is registered. An external service is not assumed free.
+
+Native callbacks can return `ToolResult(content, billing_receipt=receipt)`; only
+`content` is shown to the model. Async callbacks can instead
+`await record_billing_receipt(receipt)` immediately after receiving provider billing
+facts, before subsequent response processing might fail. Both helpers are
+provisional top-level exports; `BillingReceipt` is in `power_loop.runtime.pricing`.
+The awaited capture is bound to the original callback task and persisted call,
+and repeating the same receipt is idempotent. A different receipt is rejected.
+Receipt capture requires the native callback checkpoint path; it does not yet
+support managed recovery adapters or legacy invocation. Persisting a receipt
+does not acknowledge successful execution or settle a charge. Host budget and
+settlement wiring is still required before paid tools can be enabled.
+
+An ordinary native callback can invoke a priced internal tool with the provisional
+`await invoke_priced_tool(definition, arguments, handler)` export. Each invocation
+gets a separate budget attempt linked to its original source callback. Its price
+must already be bound, and provider facts use the same `record_billing_receipt` API.
+Internal concurrent tasks are retained and joined before the source callback ends.
+After the exact charge is locally durable, API delivery failure leaves a pending
+budget submission and preserves the real tool result. Reconciliation never calls
+the handler again or reads a replacement price. Managed recovery sources without
+an ordinary callback checkpoint still need a separate adapter.

{power_loop-7.3.1 → power_loop-9.0.0}/power_loop/__init__.py

@@ -15,7 +15,7 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "7.3.1"
+__version__ = "9.0.0"
 
 # Public LLM contract (SDK-free) re-exported so callers (e.g. writing llm.* hooks or
 # a custom LLMService) don't reach into the internal vendored transport package (H3.4).
@@ -76,6 +76,7 @@ from power_loop.contracts.event_payloads import (
     LlmCallCompletedPayload,
     LlmCallStartedPayload,
     LlmDegradedPayload,
+    LlmResponseReceivedPayload,
     LlmRetryAttemptedPayload,
     LoopCancelledPayload,
     MemoryFailedPayload,
@@ -97,6 +98,7 @@ from power_loop.contracts.event_payloads import (
     SubagentTaskStartPayload,
     SubagentTextPayload,
     SystemLogPayload,
+    TaskSupervisionClosedPayload,
     TimerFiredPayload,
     TodoUpdatedPayload,
     ToolCallCompletedPayload,
@@ -136,7 +138,7 @@ from power_loop.contracts.protocols import (
     HookManagerProtocol,
     ToolArgsValidator,
 )
-from power_loop.contracts.tools import ToolDefinition, validate_tool_args
+from power_loop.contracts.tools import ToolDefinition, ToolResult, validate_tool_args
 from power_loop.core.agent_context import get_effective_tools
 from power_loop.core.events import AgentEventBus
 from power_loop.core.hooks import AgentHooks
@@ -174,6 +176,7 @@ from power_loop.runtime.memory import (
     MemorySnapshot,
     tag_as_memory,
 )
+from power_loop.runtime.nested_tools import invoke_priced_tool
 from power_loop.runtime.notes import (
     DEFAULT_NOTES_POLICY,
     NoteMemory,
@@ -239,6 +242,7 @@ from power_loop.runtime.structured import (
     parse_structured,
 )
 from power_loop.runtime.timers import TimerDelivery, TimerRunner
+from power_loop.runtime.tool_billing import record_billing_receipt, tool_billing_active, tool_billing_managed
 from power_loop.runtime.tool_context import ToolContextConfig
 from power_loop.tools import (
     DEFAULT_TOOL_HANDLERS,
@@ -254,6 +258,7 @@ from power_loop.tools.default_manifest import (
     TOOL_PRESETS,
     get_tool_definitions,
 )
+from power_loop.tools.jobs import JOBS_DEFINITION, register_jobs_tools
 from power_loop.tools.registry import AsyncToolInSyncContext
 from power_loop.tools.spawn_agent import (
     SPAWN_AGENT_DEFINITION,
@@ -397,6 +402,7 @@ __all__ = [
 	"request_user_input",
 	"LlmCallStartedPayload",
 	"LlmCallCompletedPayload",
+	"LlmResponseReceivedPayload",
 	"LlmRetryAttemptedPayload",
 	"SteerInterruptedPayload",
 	"LlmDegradedPayload",
@@ -489,6 +495,7 @@ __all__ = [
 	"SubagentTextPayload",
 	"SubagentLimitPayload",
 	"SubagentCompletedPayload",
+    "TaskSupervisionClosedPayload",
 	"EventHandler",
 	"HookHandler",
 	"ToolHandler",
@@ -499,6 +506,11 @@ __all__ = [
 	"ChildRunGuard",
 	"get_effective_tools",
 	"ToolDefinition",
+	"ToolResult",
+	"record_billing_receipt",
+	"tool_billing_managed",
+	"tool_billing_active",
+	"invoke_priced_tool",
 	"validate_tool_args",
 	"ToolRegistry",
 	"AsyncToolInSyncContext",
@@ -523,6 +535,8 @@ __all__ = [
 	"build_explore_subagent_system_prompt",
 	"format_tool_catalog",
 	"register_spawn_agent",
+	"register_jobs_tools",
+	"JOBS_DEFINITION",
 	"SPAWN_AGENT_DEFINITION",
 	"LOAD_SKILL_DEFINITION",
 	"SkillLoader",

{power_loop-7.3.1 → power_loop-9.0.0}/power_loop/_vendor/llm_client/llm_factory.py

@@ -634,7 +634,8 @@ class OpenAICompatibleChatLLMService(LLMService):
         current_request = request
         restart_count = 0
         max_restarts = max(0, int(self._cfg.stream_max_restarts or 0))
-        resume_enabled = bool(self._cfg.stream_resume_on_error)
+        from .attempt_scope import single_attempt
+        resume_enabled = bool(self._cfg.stream_resume_on_error) and not single_attempt.get()
 
         def _as_dict(obj: Any) -> Any:
             if obj is None:

{power_loop-7.3.1 → power_loop-9.0.0}/power_loop/_vendor/llm_client/multimodal.py

@@ -27,7 +27,7 @@ class AttachmentRef:
     mime_type: str
     kind: str
     #: 宿主给的「怎么把这张图找回来」坐标，原样带进蒸馏与降级文案（DeepTalk 放
-    #: ``file_uuid=…``，模型可直接拿去 see_image）。空字符串 = 没有。
+    #: 宿主提供的不透明资源引用）。空字符串 = 没有。
     ref: str = ""
 
 
@@ -192,7 +192,7 @@ def _render_image_attachment(ref: AttachmentRef, path: Path, capabilities: Model
     为什么降级不等于回到老毛病：老实现塞的是一句含糊的
     "The current model does not support image input"，混在附件描述里，模型读过去照样按
     「我看过这张图」的语气编答案。这里的占位必须做到两件事——**说清楚模型没有看到**，并且
-    **给出把图找回来的坐标**（``ref``，DeepTalk 放 file_uuid，可直接喂给 see_image）。
+    **给出把图找回来的坐标**（``ref``，由宿主解释和回取原件）。
     调用方想要「发图给看不了图的模型就报错」，用 ``capabilities.require_image_input()`` 自查。
     """
     if capabilities.supports_image_input is True:
@@ -226,7 +226,7 @@ def _render_image_attachment(ref: AttachmentRef, path: Path, capabilities: Model
     )
     text = (
         f"[图片 {describe_attachment_ref(ref)}——**当前模型看不了图片，你没有看到它的内容**。"
-        "不要凭空描述这张图；需要看就用 see_image 之类的视觉工具，按上面的坐标取它。]"
+        "不要凭空描述这张图；需要时由可看图的工具或模型按上面的坐标回取原图。]"
     )
     return PreparedAttachment(
         ref=ref,

{power_loop-7.3.1 → power_loop-9.0.0}/power_loop/agent/sink.py

@@ -17,6 +17,8 @@ import logging
 from typing import Any, Protocol, runtime_checkable
 
 from power_loop.agent.types import LoopMessage
+from power_loop.contracts.errors import InboxClaimChanged
+from power_loop.core.agent_context import get_current_loop
 from power_loop.runtime.store.store import SessionStore
 from power_loop.runtime.store.types import (
     CONTENT_ENCODING_JSON,
@@ -149,6 +151,11 @@ class SQLiteSink:
 
     # ── messages ───────────────────────────────────────────────
 
+    @property
+    def persisted_assistant_seq(self) -> int | None:
+        """Actual DB seq, never the index of an in-memory/projected history row."""
+        return self._assistant_seq
+
     async def on_round_started(self, round_index: int) -> None:
         await self.store.set_round_index(self.session_id, round_index)
 
@@ -171,6 +178,8 @@ class SQLiteSink:
             )
             self._history_seqs.append(seq)
             self._history_ord.append(seq)
+            from power_loop.runtime.task_runtime import bind_tool_receipt
+            await bind_tool_receipt(self.store, self.session_id, self._assistant_seq, tool_call_id, seq)
             # Auto-resolve pending: when the matching tool message lands,
             # drop it from the unresolved set and clear pending once empty.
             if tool_call_id and tool_call_id in self._unresolved:
@@ -204,6 +213,9 @@ class SQLiteSink:
         if role == "assistant":
             tool_calls = message.get("tool_calls")
             text, structured = _encode_content(message.get("content"))
+            from power_loop.runtime.task_runtime import atomic_pending_required
+            options = ({"pending_tool_calls": True}
+                       if tool_calls and atomic_pending_required(self.store, self.session_id) else {})
             seq = await self.store.append_message(
                 self.session_id,
                 role="assistant",
@@ -213,6 +225,7 @@ class SQLiteSink:
                 meta=_meta_with_content_encoding(message.get("meta"), structured=structured),
                 send_index=message.get("send_index"),
                 hook_injected=message.get("hook_injected"),
+                **options,
             )
             self._history_seqs.append(seq)
             self._history_ord.append(seq)
@@ -227,16 +240,26 @@ class SQLiteSink:
             # Which inbox items this row carries (dedupe/audit; design/124 §6).
             meta = {**(meta or {}), "inbox": {k: inbox[k] for k in ("item_ids", "kinds")
                                               if k in inbox}}
-        seq = await self.store.append_message(
-            self.session_id,
-            role=str(role or "user"),
-            content=text,
-            name=message.get("name"),
-            round_index=round_index,
-            meta=meta,
-            send_index=message.get("send_index"),
-            inbox=inbox,
-        )
+        try:
+            seq = await self.store.append_message(
+                self.session_id,
+                role=str(role or "user"),
+                content=text,
+                name=message.get("name"),
+                round_index=round_index,
+                meta=meta,
+                send_index=message.get("send_index"),
+                inbox=inbox,
+            )
+        except InboxClaimChanged:
+            # The batch was rolled back. Release only its surviving claim rows;
+            # the pipeline will render a fresh batch, never reuse the old text.
+            await self.store.inbox_release(self.session_id, inbox["claim_token"])
+            pending = (await self.store.inbox_counts(self.session_id))["pending"]
+            loop = get_current_loop()
+            if pending and loop is not None:
+                loop._note_committed_inbox(self.session_id)
+            raise
         self._history_seqs.append(seq)
         self._history_ord.append(seq)