jharness-toolkit 0.1.0__tar.gz

jharness_toolkit-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# OS/editor noise
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+
+# Local AI assistant/workspace state
+.codex/
+.claude/
+.gemini/
+.aider*
+
+# Pinned specification snapshot generated by scripts/sync_spec.py
+.jharness-spec/
+
+# Python
+__pycache__/
+*.py[cod]
+.python-version
+.venv/
+venv/
+ENV/
+
+# Python tooling caches
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Packaging/build artifacts
+dist/
+build/
+*.egg-info/
+
+# Node/TypeScript SDK artifacts
+node_modules/
+coverage/
+.turbo/
+.next/
+*.tsbuildinfo
+
+# Logs
+*.log

jharness_toolkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
++MIT License
+
+Copyright (c) 2026 JHarness contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jharness_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: jharness-toolkit
+Version: 0.1.0
+Summary: JHarness tool registry, validation helpers, and execution decorators
+Project-URL: Documentation, https://github.com/Ezio2000/jharness-python/tree/main/docs
+Project-URL: Homepage, https://github.com/Ezio2000/jharness-python
+Project-URL: Issues, https://github.com/Ezio2000/jharness-python/issues
+Project-URL: Repository, https://github.com/Ezio2000/jharness-python.git
+Author: JHarness contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,json-schema,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: jharness-kernel<0.2.0,>=0.1.0
+Requires-Dist: jsonschema>=4.23.0
+Requires-Dist: referencing>=0.35.0
+Description-Content-Type: text/markdown
+
+# jharness-toolkit
+
+`jharness-toolkit` is the concrete Python tool-support distribution for
+`jharness.kernel`. It provides an immutable tool registry, JSON Schema
+validation, async function adapters, and retry and circuit-breaking decorators.
+
+```bash
+uv add jharness-toolkit
+```
+
+```python
+from jharness.toolkit import ToolRegistry, function_tool
+```
+
+Runtime semantics and portable tool values remain in `jharness.kernel`;
+`jharness.toolkit` only implements concrete adaptation and execution policies. See the
+[tool protocol](https://github.com/Ezio2000/jharness/blob/v0.1.0/docs/tool-protocol.md) and
+[Python package boundaries](https://github.com/Ezio2000/jharness-python/blob/main/docs/python-package-boundaries.md).

jharness_toolkit-0.1.0/README.md

@@ -0,0 +1,18 @@
+# jharness-toolkit
+
+`jharness-toolkit` is the concrete Python tool-support distribution for
+`jharness.kernel`. It provides an immutable tool registry, JSON Schema
+validation, async function adapters, and retry and circuit-breaking decorators.
+
+```bash
+uv add jharness-toolkit
+```
+
+```python
+from jharness.toolkit import ToolRegistry, function_tool
+```
+
+Runtime semantics and portable tool values remain in `jharness.kernel`;
+`jharness.toolkit` only implements concrete adaptation and execution policies. See the
+[tool protocol](https://github.com/Ezio2000/jharness/blob/v0.1.0/docs/tool-protocol.md) and
+[Python package boundaries](https://github.com/Ezio2000/jharness-python/blob/main/docs/python-package-boundaries.md).

jharness_toolkit-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "jharness-toolkit"
+version = "0.1.0"
+description = "JHarness tool registry, validation helpers, and execution decorators"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "JHarness contributors" }]
+keywords = ["ai", "agent", "json-schema", "tools"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+  "jsonschema>=4.23.0",
+  "jharness-kernel>=0.1.0,<0.2.0",
+  "referencing>=0.35.0",
+]
+
+[project.urls]
+Documentation = "https://github.com/Ezio2000/jharness-python/tree/main/docs"
+Homepage = "https://github.com/Ezio2000/jharness-python"
+Issues = "https://github.com/Ezio2000/jharness-python/issues"
+Repository = "https://github.com/Ezio2000/jharness-python.git"
+
+[tool.uv.sources]
+jharness-kernel = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jharness"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

jharness_toolkit-0.1.0/src/jharness/toolkit/__init__.py

@@ -0,0 +1,15 @@
+"""Concrete tool catalog, adapters, and decorators for kernel."""
+
+from jharness.toolkit.decorators import CircuitBreakingTool, RetryingTool
+from jharness.toolkit.registry import ToolRegistry
+from jharness.toolkit.tool import FunctionTool, Tool, ToolFunction, function_tool
+
+__all__ = [
+    "CircuitBreakingTool",
+    "FunctionTool",
+    "RetryingTool",
+    "Tool",
+    "ToolFunction",
+    "ToolRegistry",
+    "function_tool",
+]

jharness_toolkit-0.1.0/src/jharness/toolkit/decorators.py

@@ -0,0 +1,75 @@
+"""Composable tool execution policies outside kernel state-machine semantics."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from threading import Lock
+
+from jharness.kernel import SettledResult, ToolCall, ToolContext, ToolFailure, ToolResult, ToolSpec
+from jharness.toolkit.tool import Tool
+
+
+@dataclass(frozen=True, slots=True)
+class RetryingTool:
+    """Retry implementation exceptions for an explicitly idempotent tool."""
+
+    tool: Tool
+    max_attempts: int = 2
+    attempt_timeout_seconds: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.max_attempts < 1:
+            raise ValueError("max_attempts must be >= 1")
+        if self.max_attempts > 1 and not self.spec.execution.idempotent:
+            raise ValueError("retrying tool must be idempotent")
+        if self.attempt_timeout_seconds is not None and self.attempt_timeout_seconds <= 0:
+            raise ValueError("attempt_timeout_seconds must be > 0")
+
+    @property
+    def spec(self) -> ToolSpec:
+        return self.tool.spec
+
+    async def invoke(self, call: ToolCall, context: ToolContext) -> ToolResult:
+        attempt = 1
+        while True:
+            try:
+                async with asyncio.timeout(self.attempt_timeout_seconds):
+                    return await self.tool.invoke(call, context)
+            except Exception:
+                if attempt == self.max_attempts:
+                    raise
+                attempt += 1
+                await asyncio.sleep(0)
+
+
+@dataclass(slots=True)
+class CircuitBreakingTool:
+    """Reject calls after consecutive implementation exceptions."""
+
+    tool: Tool
+    failure_threshold: int = 3
+    _lock: Lock = field(default_factory=Lock, init=False, repr=False, compare=False)
+    _failures: int = field(default=0, init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        if self.failure_threshold < 1:
+            raise ValueError("failure_threshold must be >= 1")
+
+    @property
+    def spec(self) -> ToolSpec:
+        return self.tool.spec
+
+    async def invoke(self, call: ToolCall, context: ToolContext) -> ToolResult:
+        with self._lock:
+            if self._failures >= self.failure_threshold:
+                return SettledResult(ToolFailure.from_error("circuit_open", "tool circuit is open"))
+        try:
+            result = await self.tool.invoke(call, context)
+        except Exception:
+            with self._lock:
+                self._failures += 1
+            raise
+        with self._lock:
+            self._failures = 0
+        return result

jharness_toolkit-0.1.0/src/jharness/toolkit/py.typed

@@ -0,0 +1 @@
+

jharness_toolkit-0.1.0/src/jharness/toolkit/registry.py

@@ -0,0 +1,181 @@
+"""Immutable invocation catalogs with compiled JSON Schema validation."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass
+from inspect import iscoroutinefunction
+from threading import Lock
+from types import MappingProxyType
+from typing import Any, cast
+from uuid import uuid4
+
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import SchemaError, ValidationError
+from jsonschema.protocols import Validator
+from referencing import Registry
+from referencing.jsonschema import DRAFT202012, Schema, SchemaRegistry, SchemaResource
+
+from jharness.kernel import (
+    SettledResult,
+    ToolBinding,
+    ToolCall,
+    ToolCatalog,
+    ToolContext,
+    ToolError,
+    ToolResult,
+    ToolSpec,
+    WaitingResult,
+    thaw_json_value,
+)
+from jharness.toolkit.tool import Tool
+
+
+@dataclass(frozen=True, slots=True)
+class _Registered:
+    tool: Tool
+    spec: ToolSpec
+    input_validator: Validator
+    output_validator: Validator | None
+
+
+class ToolRegistry:
+    """Thread-safe registry that opens immutable invocation catalogs."""
+
+    __slots__ = ("_entries", "_lock")
+
+    def __init__(self, tools: Sequence[Tool] = ()) -> None:
+        self._lock = Lock()
+        self._entries: dict[str, _Registered] = {}
+        for tool in tools:
+            self.register(tool)
+
+    def register(self, tool: Tool) -> None:
+        _validate_tool(tool)
+        spec = tool.spec
+        registered = _Registered(
+            tool,
+            spec,
+            _compile_schema(spec.input_schema, f"tool {spec.name} input_schema"),
+            (
+                None
+                if spec.output_schema is None
+                else _compile_schema(
+                    spec.output_schema,
+                    f"tool {spec.name} output_schema",
+                )
+            ),
+        )
+        with self._lock:
+            if spec.name in self._entries:
+                raise ValueError(f"duplicate tool name: {spec.name}")
+            self._entries[spec.name] = registered
+
+    async def open_catalog(self) -> ToolCatalog:
+        with self._lock:
+            return _Catalog(self._entries)
+
+
+class _Catalog:
+    __slots__ = ("_entries", "_specs")
+
+    def __init__(self, entries: Mapping[str, _Registered]) -> None:
+        self._entries = MappingProxyType(dict(entries))
+        self._specs = tuple(entry.spec for entry in self._entries.values())
+
+    def specs(self) -> tuple[ToolSpec, ...]:
+        return self._specs
+
+    def spec(self, name: str) -> ToolSpec | None:
+        entry = self._entries.get(name)
+        return None if entry is None else entry.spec
+
+    def bind(self, call: ToolCall) -> ToolBinding:
+        entry = self._entries.get(call.name)
+        if entry is None:
+            raise ToolError(f"unknown tool: {call.name}")
+        try:
+            entry.input_validator.validate(thaw_json_value(call.arguments))
+        except ValidationError as exc:
+            raise ToolError(
+                f"tool {call.name} arguments do not match input_schema: {exc.message}"
+            ) from exc
+        return _Binding(call, entry)
+
+
+@dataclass(frozen=True, slots=True)
+class _Binding:
+    call: ToolCall
+    _entry: _Registered
+
+    @property
+    def spec(self) -> ToolSpec:
+        return self._entry.spec
+
+    async def invoke(self, context: ToolContext) -> ToolResult:
+        result = _ensure_result(await self._entry.tool.invoke(self.call, context))
+        validator = self._entry.output_validator
+        if validator is not None:
+            try:
+                validator.validate(thaw_json_value(result.outcome.structured_content))
+            except ValidationError as exc:
+                raise ToolError(
+                    f"tool {self.call.name} structured_content does not match "
+                    f"output_schema: {exc.message}"
+                ) from exc
+        return result
+
+
+def _compile_schema(
+    schema: Mapping[str, Any] | bool,
+    label: str,
+) -> Validator:
+    plain: Schema = (
+        schema if isinstance(schema, bool) else cast(dict[str, Any], thaw_json_value(schema))
+    )
+    try:
+        Draft202012Validator.check_schema(plain)
+    except SchemaError as exc:
+        raise ValueError(f"{label} must be a valid JSON Schema: {exc.message}") from exc
+    base = (
+        cast(str, plain.get("$id"))
+        if isinstance(plain, dict) and isinstance(plain.get("$id"), str)
+        else f"urn:jharness:toolkit:schema:{uuid4()}"
+    )
+    resource: SchemaResource = DRAFT202012.create_resource(plain)
+    registry: SchemaRegistry = Registry[Schema]().with_resource(base, resource).crawl()
+    resolver = registry.resolver(base)
+    try:
+        for reference in _references(plain):
+            resolver.lookup(reference)
+    except Exception as exc:
+        raise ValueError(f"{label} contains an unresolvable reference") from exc
+    return Draft202012Validator(plain, registry=registry)
+
+
+def _ensure_result(value: object) -> ToolResult:
+    if not isinstance(value, SettledResult | WaitingResult):
+        raise ToolError("tool invoke must return SettledResult or WaitingResult")
+    return value
+
+
+def _validate_tool(value: object) -> None:
+    if not isinstance(value, Tool):
+        raise TypeError("registered tool must implement Tool")
+    if not isinstance(cast(object, value.spec), ToolSpec):
+        raise TypeError("registered tool spec must be ToolSpec")
+    if not iscoroutinefunction(value.invoke):
+        raise TypeError("registered tool invoke must be async")
+
+
+def _references(value: object) -> Iterator[str]:
+    if isinstance(value, Mapping):
+        mapping = cast(Mapping[object, object], value)
+        reference = mapping.get("$ref")
+        if isinstance(reference, str):
+            yield reference
+        for item in mapping.values():
+            yield from _references(item)
+    elif isinstance(value, Sequence) and not isinstance(value, str | bytes | bytearray):
+        for item in cast(Sequence[object], value):
+            yield from _references(item)

jharness_toolkit-0.1.0/src/jharness/toolkit/tool.py

@@ -0,0 +1,75 @@
+"""Concrete Python tool protocol and function adapter."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Coroutine, Mapping
+from dataclasses import dataclass
+from inspect import iscoroutinefunction
+from typing import Any, Protocol, cast, runtime_checkable
+
+from jharness.kernel import (
+    ToolCall,
+    ToolContext,
+    ToolExecution,
+    ToolResult,
+    ToolRisk,
+    ToolSpec,
+)
+
+
+@runtime_checkable
+class Tool(Protocol):
+    """One async invocation operation and one immutable specification."""
+
+    @property
+    def spec(self) -> ToolSpec: ...
+
+    async def invoke(self, call: ToolCall, context: ToolContext) -> ToolResult: ...
+
+
+ToolFunction = Callable[[ToolCall, ToolContext], Coroutine[Any, Any, ToolResult]]
+
+
+@dataclass(frozen=True, slots=True)
+class FunctionTool:
+    """Adapt one async function to the concrete tool protocol."""
+
+    spec: ToolSpec
+    function: ToolFunction
+
+    def __post_init__(self) -> None:
+        if not isinstance(cast(object, self.spec), ToolSpec):
+            raise TypeError("function tool spec must be ToolSpec")
+        if not iscoroutinefunction(self.function):
+            raise TypeError("function tool must be async")
+
+    async def invoke(self, call: ToolCall, context: ToolContext) -> ToolResult:
+        return await self.function(call, context)
+
+
+def function_tool(
+    *,
+    name: str,
+    description: str,
+    input_schema: Mapping[str, Any] | bool,
+    output_schema: Mapping[str, Any] | bool | None = None,
+    execution: ToolExecution | None = None,
+    risk: ToolRisk | None = None,
+) -> Callable[[ToolFunction], FunctionTool]:
+    """Create a `FunctionTool` while keeping schemas and policies explicit."""
+
+    tool_execution = ToolExecution() if execution is None else execution
+    tool_risk = ToolRisk() if risk is None else risk
+    spec = ToolSpec(
+        name,
+        description,
+        input_schema,
+        output_schema,
+        tool_execution,
+        tool_risk,
+    )
+
+    def decorate(function: ToolFunction) -> FunctionTool:
+        return FunctionTool(spec, function)
+
+    return decorate

jharness_toolkit-0.1.0/tests/test_toolkit.py

@@ -0,0 +1,372 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, cast
+
+import pytest
+
+from jharness.kernel import (
+    ContentPart,
+    RunContext,
+    SettledResult,
+    Suspension,
+    ToolCall,
+    ToolContext,
+    ToolError,
+    ToolExecution,
+    ToolFailure,
+    ToolResult,
+    ToolSpec,
+    ToolSuccess,
+    ToolWaiting,
+    WaitingResult,
+)
+from jharness.toolkit import (
+    CircuitBreakingTool,
+    FunctionTool,
+    RetryingTool,
+    ToolRegistry,
+    function_tool,
+)
+
+
+async def no_progress(_value: Mapping[str, Any]) -> None: ...
+
+
+def context() -> ToolContext:
+    return ToolContext(RunContext("run-1", 1.0), no_progress, lambda: False)
+
+
+@dataclass(slots=True)
+class ValueTool:
+    spec: ToolSpec
+    value: object
+    calls: int = 0
+
+    async def invoke(self, call: ToolCall, context: ToolContext) -> ToolResult:
+        self.calls += 1
+        return SettledResult(ToolSuccess((ContentPart.text_part("ok"),), self.value))
+
+
+async def test_registry_opens_immutable_invocation_catalogs() -> None:
+    first = ValueTool(ToolSpec("first", "first", {"type": "object"}), {"value": 1})
+    second = ValueTool(ToolSpec("second", "second", {"type": "object"}), {"value": 2})
+    registry = ToolRegistry((first,))
+    before = await registry.open_catalog()
+    binding = before.bind(ToolCall("call", "first"))
+    registry.register(second)
+    after = await registry.open_catalog()
+
+    assert [spec.name for spec in before.specs()] == ["first"]
+    assert before.spec("second") is None
+    assert [spec.name for spec in after.specs()] == ["first", "second"]
+    assert binding.spec is first.spec
+    assert isinstance(await binding.invoke(context()), SettledResult)
+
+
+async def test_binding_validates_input_and_output_schemas() -> None:
+    tool = ValueTool(
+        ToolSpec(
+            "strict",
+            "strict",
+            {
+                "type": "object",
+                "required": ["count"],
+                "properties": {"count": {"type": "integer"}},
+                "additionalProperties": False,
+            },
+            {
+                "type": "object",
+                "required": ["value"],
+                "properties": {"value": {"type": "integer"}},
+                "additionalProperties": False,
+            },
+        ),
+        {"value": 1},
+    )
+    catalog = await ToolRegistry((tool,)).open_catalog()
+
+    with pytest.raises(ToolError, match="input_schema"):
+        catalog.bind(ToolCall("bad", "strict", {"count": "one"}))
+    call = ToolCall("ok", "strict", {"count": 1})
+    binding = catalog.bind(call)
+    result = await binding.invoke(context())
+    assert binding.call is call
+    assert isinstance(result, SettledResult)
+    assert isinstance(result.outcome, ToolSuccess)
+    assert result.outcome.structured_content == {"value": 1}
+
+    invalid_output = ValueTool(tool.spec, {"value": "one"})
+    invalid_catalog = await ToolRegistry((invalid_output,)).open_catalog()
+    with pytest.raises(ToolError, match="output_schema"):
+        await invalid_catalog.bind(ToolCall("bad-output", "strict", {"count": 1})).invoke(context())
+
+
+async def test_binding_preserves_waiting_result_and_validates_its_output() -> None:
+    spec = ToolSpec(
+        "wait",
+        "wait",
+        {"type": "object"},
+        {
+            "type": "object",
+            "required": ["ticket"],
+            "properties": {"ticket": {"type": "string"}},
+        },
+    )
+
+    @dataclass(frozen=True, slots=True)
+    class WaitingTool:
+        spec: ToolSpec
+
+        async def invoke(self, call: ToolCall, context: ToolContext) -> ToolResult:
+            return WaitingResult(
+                ToolWaiting(
+                    (ContentPart.text_part("pending"),),
+                    structured_content={"ticket": "ticket-1"},
+                ),
+                Suspension("external", "tool", "ticket-1"),
+            )
+
+    result = (
+        await (await ToolRegistry((WaitingTool(spec),)).open_catalog())
+        .bind(ToolCall("call", "wait"))
+        .invoke(context())
+    )
+
+    assert isinstance(result, WaitingResult)
+    assert result.outcome.kind == "waiting"
+    assert result.suspension.wait_id == "ticket-1"
+
+
+async def test_binding_rejects_an_unwrapped_outcome() -> None:
+    @dataclass(frozen=True, slots=True)
+    class InvalidTool:
+        spec: ToolSpec
+
+        async def invoke(self, call: ToolCall, context: ToolContext) -> ToolResult:
+            return cast(Any, ToolSuccess((ContentPart.text_part("invalid"),)))
+
+    catalog = await ToolRegistry(
+        (InvalidTool(ToolSpec("invalid", "invalid", {"type": "object"})),)
+    ).open_catalog()
+    with pytest.raises(ToolError, match="SettledResult or WaitingResult"):
+        await catalog.bind(ToolCall("call", "invalid")).invoke(context())
+
+
+async def test_function_tool_decorator_preserves_explicit_spec() -> None:
+    @function_tool(
+        name="sum",
+        description="sum values",
+        input_schema={"type": "object"},
+        execution=ToolExecution(read_only=True, idempotent=True),
+    )
+    async def sum_tool(call: ToolCall, tool_context: ToolContext) -> ToolResult:
+        return SettledResult(
+            ToolSuccess((ContentPart.text_part(str(sum(call.arguments.values()))),))
+        )
+
+    result = await sum_tool.invoke(ToolCall("call", "sum", {"a": 1, "b": 2}), context())
+    assert sum_tool.spec.name == "sum"
+    assert isinstance(result, SettledResult)
+    assert result.outcome.parts[0].text == "3"
+
+
+def test_function_tool_and_registry_reject_synchronous_implementations() -> None:
+    spec = ToolSpec("sync", "sync", {"type": "object"})
+
+    def sync_function(call: ToolCall, tool_context: ToolContext) -> ToolResult:
+        return SettledResult(ToolSuccess((ContentPart.text_part("no"),)))
+
+    with pytest.raises(TypeError, match="must be async"):
+        FunctionTool(spec, cast(Any, sync_function))
+
+    @dataclass(frozen=True, slots=True)
+    class SyncTool:
+        spec: ToolSpec
+
+        def invoke(self, call: ToolCall, tool_context: ToolContext) -> ToolResult:
+            return sync_function(call, tool_context)
+
+    with pytest.raises(TypeError, match="must be async"):
+        ToolRegistry((cast(Any, SyncTool(spec)),))
+
+
+def test_tool_adapters_reject_invalid_values_and_policy_limits() -> None:
+    spec = ToolSpec(
+        "valid",
+        "valid",
+        {"type": "object"},
+        execution=ToolExecution(read_only=True, idempotent=True),
+    )
+
+    async def valid_function(call: ToolCall, tool_context: ToolContext) -> ToolResult:
+        return SettledResult(ToolSuccess((ContentPart.text_part("ok"),)))
+
+    with pytest.raises(TypeError, match="spec must be ToolSpec"):
+        FunctionTool(cast(Any, object()), valid_function)
+    with pytest.raises(TypeError, match="implement Tool"):
+        ToolRegistry((cast(Any, object()),))
+
+    @dataclass(frozen=True, slots=True)
+    class InvalidSpecTool:
+        spec: object
+
+        async def invoke(self, call: ToolCall, tool_context: ToolContext) -> ToolResult:
+            return await valid_function(call, tool_context)
+
+    with pytest.raises(TypeError, match="spec must be ToolSpec"):
+        ToolRegistry((cast(Any, InvalidSpecTool(object())),))
+    base = FunctionTool(spec, valid_function)
+    with pytest.raises(ValueError, match="max_attempts"):
+        RetryingTool(base, max_attempts=0)
+    with pytest.raises(ValueError, match="attempt_timeout_seconds"):
+        RetryingTool(base, attempt_timeout_seconds=0)
+    with pytest.raises(ValueError, match="failure_threshold"):
+        CircuitBreakingTool(base, failure_threshold=0)
+
+
+class FlakyTool:
+    spec = ToolSpec(
+        "flaky",
+        "flaky",
+        {"type": "object"},
+        execution=ToolExecution(read_only=True, idempotent=True),
+    )
+
+    def __init__(self, failures: int) -> None:
+        self.failures = failures
+        self.calls = 0
+
+    async def invoke(self, call: ToolCall, context: ToolContext) -> ToolResult:
+        self.calls += 1
+        if self.calls <= self.failures:
+            raise RuntimeError("temporary")
+        return SettledResult(ToolSuccess((ContentPart.text_part("ok"),)))
+
+
+async def test_retry_decorator_retries_one_logical_idempotent_call() -> None:
+    base = FlakyTool(2)
+    result = await RetryingTool(base, max_attempts=3).invoke(ToolCall("call", "flaky"), context())
+
+    assert isinstance(result, SettledResult)
+    assert isinstance(result.outcome, ToolSuccess)
+    assert base.calls == 3
+    with pytest.raises(ValueError, match="idempotent"):
+        RetryingTool(
+            ValueTool(ToolSpec("unsafe", "unsafe", {"type": "object"}), None),
+            max_attempts=2,
+        )
+
+
+async def test_retry_decorator_owns_attempt_timeout() -> None:
+    @dataclass(slots=True)
+    class SlowTool:
+        spec: ToolSpec
+        calls: int = 0
+
+        async def invoke(self, call: ToolCall, context: ToolContext) -> ToolResult:
+            self.calls += 1
+            await asyncio.sleep(1)
+            return SettledResult(ToolSuccess((ContentPart.text_part("late"),)))
+
+    slow = SlowTool(
+        ToolSpec(
+            "slow",
+            "slow",
+            {"type": "object"},
+            execution=ToolExecution(read_only=True, idempotent=True),
+        )
+    )
+    with pytest.raises(TimeoutError):
+        await RetryingTool(slow, max_attempts=2, attempt_timeout_seconds=0.001).invoke(
+            ToolCall("call", "slow"), context()
+        )
+    assert slow.calls == 2
+
+
+async def test_decorators_propagate_cancellation_without_recording_failure() -> None:
+    @dataclass(slots=True)
+    class CancellingTool:
+        spec: ToolSpec
+        calls: int = 0
+
+        async def invoke(self, call: ToolCall, context: ToolContext) -> ToolResult:
+            self.calls += 1
+            raise asyncio.CancelledError
+
+    base = CancellingTool(
+        ToolSpec(
+            "cancel",
+            "cancel",
+            {"type": "object"},
+            execution=ToolExecution(read_only=True, idempotent=True),
+        )
+    )
+    call = ToolCall("call", "cancel")
+    with pytest.raises(asyncio.CancelledError):
+        await RetryingTool(base, max_attempts=2).invoke(call, context())
+    breaker = CircuitBreakingTool(base, failure_threshold=1)
+    assert breaker.spec is base.spec
+    with pytest.raises(asyncio.CancelledError):
+        await breaker.invoke(call, context())
+    with pytest.raises(asyncio.CancelledError):
+        await breaker.invoke(call, context())
+    assert base.calls == 3
+
+
+async def test_circuit_breaker_success_resets_consecutive_failure_count() -> None:
+    @dataclass(slots=True)
+    class AlternatingTool:
+        spec: ToolSpec
+        calls: int = 0
+
+        async def invoke(self, call: ToolCall, context: ToolContext) -> ToolResult:
+            self.calls += 1
+            if self.calls % 2:
+                raise RuntimeError("temporary")
+            return SettledResult(ToolSuccess((ContentPart.text_part("ok"),)))
+
+    base = AlternatingTool(ToolSpec("alternating", "alternating", {"type": "object"}))
+    breaker = CircuitBreakingTool(base, failure_threshold=2)
+    call = ToolCall("call", "alternating")
+    for _ in range(2):
+        with pytest.raises(RuntimeError, match="temporary"):
+            await breaker.invoke(call, context())
+        result = await breaker.invoke(call, context())
+        assert isinstance(result, SettledResult)
+        assert isinstance(result.outcome, ToolSuccess)
+    assert base.calls == 4
+
+
+async def test_circuit_breaker_opens_after_consecutive_failures() -> None:
+    base = FlakyTool(10)
+    breaker = CircuitBreakingTool(base, failure_threshold=2)
+    call = ToolCall("call", "flaky")
+    for _ in range(2):
+        with pytest.raises(RuntimeError, match="temporary"):
+            await breaker.invoke(call, context())
+
+    result = await breaker.invoke(call, context())
+    assert isinstance(result, SettledResult)
+    assert isinstance(result.outcome, ToolFailure)
+    assert result.outcome.error.code == "circuit_open"
+    assert base.calls == 2
+
+
+def test_registry_rejects_duplicate_names_and_invalid_schemas() -> None:
+    tool = ValueTool(ToolSpec("same", "same", {"type": "object"}), None)
+    with pytest.raises(ValueError, match="duplicate"):
+        ToolRegistry((tool, tool))
+    with pytest.raises(ValueError, match="valid JSON Schema"):
+        ToolRegistry(
+            (
+                ValueTool(
+                    ToolSpec("bad", "bad", {"type": "not-a-json-schema-type"}),
+                    None,
+                ),
+            )
+        )
+    with pytest.raises(ValueError, match="unresolvable"):
+        ToolRegistry((ValueTool(ToolSpec("ref", "ref", {"$ref": "missing"}), None),))