agentforge-core 0.2.3__tar.gz → 0.2.4__tar.gz

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentforge-core
-Version: 0.2.3
+Version: 0.2.4
 Summary: AgentForge core — stable contracts (ABCs, value types) for the agentic framework
 Project-URL: Homepage, https://github.com/Scaffoldic/agentforge-py
 Project-URL: Repository, https://github.com/Scaffoldic/agentforge-py

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/pyproject.toml

@@ -9,7 +9,7 @@
 
 [project]
 name = "agentforge-core"
-version = "0.2.3"
+version = "0.2.4"
 description = "AgentForge core — stable contracts (ABCs, value types) for the agentic framework"
 readme = "README.md"
 requires-python = ">=3.13"

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/src/agentforge_core/__init__.py

@@ -47,6 +47,7 @@ from agentforge_core.contracts import (
     Reranker,
     Tool,
     VectorStore,
+    validate_tool_name,
 )
 from agentforge_core.migrations import discover_migrations
 from agentforge_core.observability import SCOPE_NAME as OBSERVABILITY_SCOPE_NAME
@@ -67,6 +68,7 @@ from agentforge_core.production import (
     RunIdFilter,
     ServiceError,
     TimeoutError,
+    ToolNameInvalidError,
     bind_run,
     current_run,
     install_json_formatter,
@@ -202,6 +204,7 @@ __all__ = [
     "TokenUsage",
     "Tool",
     "ToolCall",
+    "ToolNameInvalidError",
     "ToolSpec",
     "VectorItem",
     "VectorMatch",
@@ -225,4 +228,5 @@ __all__ = [
     "reset_run",
     "uninstall_json_formatter",
     "uninstall_run_id_filter",
+    "validate_tool_name",
 ]

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/src/agentforge_core/config/schema.py

@@ -17,7 +17,35 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any, Literal
 
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+
+def _normalise_named_entry(value: Any) -> Any:
+    """Normalise the terse YAML sugar for `name + config` entries into the
+    canonical mapping before strict validation (bug-019).
+
+    Three shapes are accepted; the first two are sugar:
+
+    - String form ``faithfulness`` → ``{"name": "faithfulness"}``
+    - Single-key mapping ``{geval: {rubric: "..."}}`` →
+      ``{"name": "geval", "config": {"rubric": "..."}}``
+    - Canonical mapping ``{name: x, config: {...}}`` → returned unchanged.
+
+    Anything else is returned untouched so the model's own validation
+    raises a clear error. Used by `EvaluatorEntry` and `GuardrailEntry`,
+    so every list that holds them (`modules.evaluators` and guardrails'
+    `input` / `output` / `tool_gates`) accepts all three forms.
+    """
+    if isinstance(value, str):
+        return {"name": value}
+    if isinstance(value, dict) and "name" not in value and len(value) == 1:
+        ((key, cfg),) = value.items()
+        if isinstance(key, str):
+            entry: dict[str, Any] = {"name": key}
+            if cfg is not None:
+                entry["config"] = cfg
+            return entry
+    return value
 
 
 class BudgetConfig(BaseModel):
@@ -178,13 +206,14 @@ class RetrievalConfig(BaseModel):
 
 
 class EvaluatorEntry(BaseModel):
-    """An entry in `modules.evaluators:`. Two YAML shapes are valid:
+    """An entry in `modules.evaluators:`. Three YAML shapes are valid:
 
     - String form: `- faithfulness` (just the name).
-    - Mapping form: `- faithfulness: {cost_cap_usd: 0.05, ...}`.
+    - Single-key mapping: `- faithfulness: {cost_cap_usd: 0.05, ...}`.
+    - Canonical mapping: `- {name: faithfulness, config: {...}}`.
 
-    We model the mapping form here; the loader normalises strings to
-    `EvaluatorEntry(name=..., config={})` before validation.
+    The first two are sugar; a `mode="before"` validator normalises them
+    to `EvaluatorEntry(name=..., config={...})` before strict validation.
     """
 
     model_config = ConfigDict(strict=True, extra="forbid")
@@ -192,6 +221,11 @@ class EvaluatorEntry(BaseModel):
     name: str = Field(min_length=1)
     config: dict[str, Any] = Field(default_factory=dict)
 
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_sugar(cls, value: Any) -> Any:
+        return _normalise_named_entry(value)
+
 
 class ObservabilityEntry(BaseModel):
     """An entry in `modules.observability:` — same shape as evaluator
@@ -226,13 +260,14 @@ class GuardrailPolicy(BaseModel):
 class GuardrailEntry(BaseModel):
     """One entry inside `modules.guardrails.{input,output,tool_gates}`.
 
-    Two YAML shapes are valid (mirrors `EvaluatorEntry`):
+    Three YAML shapes are valid (mirrors `EvaluatorEntry`):
 
     - String form: `- prompt_injection_basic` (just the name).
-    - Mapping form: `- presidio: {entities: ["EMAIL_ADDRESS"]}`.
+    - Single-key mapping: `- presidio: {entities: ["EMAIL_ADDRESS"]}`.
+    - Canonical mapping: `- {name: presidio, config: {...}}`.
 
-    Both normalise to `GuardrailEntry(name=..., config={})` before
-    validation.
+    The first two are sugar; a `mode="before"` validator normalises them
+    to `GuardrailEntry(name=..., config={...})` before strict validation.
     """
 
     model_config = ConfigDict(strict=True, extra="forbid")
@@ -240,6 +275,11 @@ class GuardrailEntry(BaseModel):
     name: str = Field(min_length=1)
     config: dict[str, Any] = Field(default_factory=dict)
 
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_sugar(cls, value: Any) -> Any:
+        return _normalise_named_entry(value)
+
 
 class ChatHistoryDriverConfig(BaseModel):
     """`modules.chat.history:` — driver + config for a chat history
@@ -269,6 +309,14 @@ class ChatSessionConfig(BaseModel):
     per_session_budget_usd: float | None = Field(default=None, ge=0.0)
     idempotency_window_s: float = Field(default=60.0, ge=0.0)
     concurrency: Literal["queue", "reject", "replace"] = "queue"
+    persist_steps: bool = True
+    """When True (default), intermediate `act` / `observe` agent steps
+    are persisted to `ChatHistoryStore` as `role="assistant"` (with
+    `tool_calls`) and `role="tool"` (with `tool_call_id`) turns
+    respectively, in addition to the final assistant turn. Tool-using
+    chat agents need this on for the next turn's prompt to reflect
+    what tools ran. Opt out by setting to False when an external
+    consumer reconstructs history from another source (bug-010)."""
     safety_mode: Literal["buffer-then-stream", "sentence-window", "stream-then-redact"] = (
         "buffer-then-stream"
     )

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/src/agentforge_core/contracts/__init__.py

@@ -25,7 +25,7 @@ from agentforge_core.contracts.renderer import FindingRenderer
 from agentforge_core.contracts.reranker import Reranker
 from agentforge_core.contracts.strategy import ReasoningStrategy
 from agentforge_core.contracts.task import Task
-from agentforge_core.contracts.tool import Tool
+from agentforge_core.contracts.tool import Tool, validate_tool_name
 from agentforge_core.contracts.vector_store import VectorStore
 
 __all__ = [
@@ -49,4 +49,5 @@ __all__ = [
     "Task",
     "Tool",
     "VectorStore",
+    "validate_tool_name",
 ]

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/src/agentforge_core/contracts/chat.py

@@ -71,9 +71,32 @@ class ChatHistoryStore(ABC):
         """Merge ``metadata`` into the session's metadata dict.
 
         Implementations may overwrite top-level keys; nested merging
-        is the caller's responsibility.
+        is the caller's responsibility. The session need **not** already
+        exist: if it doesn't, the driver creates it (upsert), so callers
+        can record metadata before the first turn is appended (bug-018).
         """
 
+    async def create_session(
+        self,
+        session_id: str,
+        *,
+        owner: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> None:
+        """Ensure a session row exists before any turn is appended.
+
+        Concrete (non-abstract) so it is additive to this locked ABC
+        (ADR-0007): existing and third-party drivers inherit it without
+        change. The default records the initial ``owner`` / ``metadata``
+        via :meth:`update_session_metadata`, which every shipped driver
+        upserts. Idempotent — calling it for an existing session merges
+        the given metadata. Drivers may override with a direct insert.
+        """
+        merged: dict[str, Any] = dict(metadata or {})
+        if owner is not None:
+            merged["owner"] = owner
+        await self.update_session_metadata(session_id, merged)
+
     @abstractmethod
     async def expire_before(self, cutoff: datetime) -> int:
         """TTL sweep: delete every session whose ``last_active_at <

agentforge_core-0.2.4/src/agentforge_core/contracts/protocol_bridge.py

@@ -0,0 +1,50 @@
+"""`ProtocolBridge` — the runtime contract for `modules.protocols`
+handlers (feat-013).
+
+A protocol handler turns a `modules.protocols[*]` config block into a
+set of `Tool`s the agent can call, and owns the lifecycle of whatever
+connections back that (subprocesses, sockets, sessions). The runtime
+(`build_agent_from_config`) resolves each entry's name under the
+``protocols`` resolver category, builds the handler from its config,
+`start()`s it, merges `tools` into the `Agent`, and `close()`s it on
+`Agent.close()`.
+
+The contract is a `@runtime_checkable` `Protocol` rather than an ABC so
+handlers in optional packages (`agentforge-mcp`'s `MCPBridge`, a future
+`agentforge-a2a` bridge) satisfy it structurally — `agentforge` /
+`agentforge-core` never import the handler packages.
+
+Expected construction shape (duck-typed, not part of the Protocol since
+classmethods don't express cleanly here): a classmethod
+``from_config(config: dict) -> ProtocolBridge`` that is **pure data** —
+it must not open transports or drive an event loop (do that in
+``start()``), so it is safe to call from within a running loop.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from agentforge_core.contracts.tool import Tool
+
+
+@runtime_checkable
+class ProtocolBridge(Protocol):
+    """Lifecycle + tool-source contract for a protocols handler."""
+
+    @property
+    def tools(self) -> list[Tool]:
+        """The tools this bridge contributes, populated by `start()`."""
+        ...
+
+    async def start(self) -> None:
+        """Open connections and populate `tools`. Safe to call inside a
+        running event loop."""
+        ...
+
+    async def close(self) -> None:
+        """Tear down every connection this bridge opened."""
+        ...
+
+
+__all__ = ["ProtocolBridge"]

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/src/agentforge_core/contracts/tool.py

@@ -9,13 +9,48 @@ hood.
 from __future__ import annotations
 
 import inspect
+import re
 from abc import ABC, abstractmethod
 from typing import Any, ClassVar
 
 from pydantic import BaseModel
 
+from agentforge_core.production.exceptions import ToolNameInvalidError
 from agentforge_core.values.messages import ToolSpec
 
+# The tool-name charset every major provider enforces: Bedrock Converse,
+# OpenAI function calling, and Anthropic tool use all validate names
+# against `^[a-zA-Z0-9_-]{1,64}$`. A name legal here is portable across
+# all of them.
+_TOOL_NAME_RE = re.compile(r"[a-zA-Z0-9_-]{1,64}")
+
+
+def validate_tool_name(name: str) -> None:
+    """Raise `ToolNameInvalidError` if `name` isn't portable across providers.
+
+    Providers call this at request-build time so an illegal name (e.g. the
+    dotted `kb.search`) surfaces as a local, actionable error *before* the
+    request leaves the process — instead of a cryptic remote validation
+    failure on the first LLM call.
+
+    Core itself does **not** auto-invoke this: `ToolSpec` stays a neutral
+    representation, and each provider opts into the policy it enforces. The
+    charset happens to be identical across today's providers, but it is a
+    per-provider wire constraint, not a property of the tool definition.
+    """
+    if not _TOOL_NAME_RE.fullmatch(name):
+        raise ToolNameInvalidError(
+            f"tool name {name!r} is not portable: it must match [a-zA-Z0-9_-] "
+            f"and be 1-64 characters (the charset Bedrock, OpenAI, and "
+            f"Anthropic all enforce). Try {_suggest_tool_name(name)!r}."
+        )
+
+
+def _suggest_tool_name(name: str) -> str:
+    """Best-effort legal rewrite for the error message (`kb.search` → `kb_search`)."""
+    cleaned = re.sub(r"[^a-zA-Z0-9_-]", "_", name)[:64]
+    return cleaned or "tool"
+
 
 class Tool(ABC):
     """A typed callable the agent can invoke.

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/src/agentforge_core/production/__init__.py

@@ -31,6 +31,7 @@ from agentforge_core.production.exceptions import (
     RateLimitError,
     ServiceError,
     TimeoutError,
+    ToolNameInvalidError,
 )
 from agentforge_core.production.log_filter import (
     RunIdFilter,
@@ -66,6 +67,7 @@ __all__ = [
     "RunIdFilter",
     "ServiceError",
     "TimeoutError",
+    "ToolNameInvalidError",
     "bind_run",
     "current_run",
     "install_json_formatter",

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/src/agentforge_core/production/exceptions.py

@@ -101,6 +101,20 @@ class TimeoutError(ProviderError):
     """
 
 
+class ToolNameInvalidError(ProviderError):
+    """A tool name violates the portable tool-name charset.
+
+    Every major provider (Bedrock Converse, OpenAI, Anthropic) validates
+    tool names against ``^[a-zA-Z0-9_-]{1,64}$``. Provider drivers call
+    `agentforge_core.contracts.tool.validate_tool_name` at request-build
+    time and raise this *before* the request leaves the process, turning a
+    cryptic remote validation failure on the first LLM call into a local,
+    actionable error. Subclasses `ProviderError` so the same handler that
+    catches other provider failures catches this too. Not retryable — the
+    fix is to rename the tool.
+    """
+
+
 class CapabilityNotSupported(AgentForgeError):
     """Raised when an optional capability is invoked on a driver that
     does not declare it.

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/src/agentforge_core/testing/conformance.py

@@ -815,6 +815,29 @@ async def run_task_conformance(
 # ----------------------------------------------------------------------
 
 
+async def _assert_create_before_first_turn(store: ChatHistoryStore) -> None:
+    """A session must be creatable / metadata-settable before its first
+    turn is appended (bug-018), and listable as soon as it is."""
+    from uuid import uuid4  # noqa: PLC0415
+
+    fresh = f"conf-{uuid4().hex[:8]}"
+    await store.create_session(fresh, owner="carol")
+    listed = await store.list_sessions()
+    assert fresh in {s.id for s in listed}, (
+        "create_session() must make a session listable before any turn"
+    )
+    assert any(s.id == fresh and s.owner == "carol" for s in listed), (
+        "create_session(owner=...) must persist the owner"
+    )
+    fresh2 = f"conf-{uuid4().hex[:8]}"
+    await store.update_session_metadata(fresh2, {"owner": "dave"})
+    assert fresh2 in {s.id for s in await store.list_sessions()}, (
+        "update_session_metadata() on an unknown session must upsert it, not raise"
+    )
+    await store.delete_session(fresh)
+    await store.delete_session(fresh2)
+
+
 async def run_chat_history_conformance(store: ChatHistoryStore) -> None:
     """Validate that a `ChatHistoryStore` honours the locked contract.
 
@@ -906,6 +929,9 @@ async def run_chat_history_conformance(store: ChatHistoryStore) -> None:
     removed_b = await store.expire_before(far_future)
     assert isinstance(removed_b, int), "expire_before must return an int"
 
+    # 11. create_session / metadata before any turn (bug-018).
+    await _assert_create_before_first_turn(store)
+
     # 11. capabilities is a set.
     caps = store.capabilities()
     assert isinstance(caps, set)

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/src/agentforge_core/values/messages.py

@@ -24,6 +24,16 @@ StopReason = Literal["end_turn", "tool_use", "max_tokens", "stop_sequence", "oth
 """Provider-normalised reason the LLM stopped emitting tokens."""
 
 
+class ToolCall(BaseModel):
+    """A tool invocation emitted by the LLM."""
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    id: str
+    name: str
+    arguments: dict[str, Any] = Field(default_factory=dict)
+
+
 class Message(BaseModel):
     """One turn in the chat-completion exchange."""
 
@@ -33,16 +43,7 @@ class Message(BaseModel):
     content: str
     name: str | None = None
     tool_call_id: str | None = None
-
-
-class ToolCall(BaseModel):
-    """A tool invocation emitted by the LLM."""
-
-    model_config = ConfigDict(frozen=True, strict=True)
-
-    id: str
-    name: str
-    arguments: dict[str, Any] = Field(default_factory=dict)
+    tool_calls: tuple[ToolCall, ...] = ()
 
 
 class ToolSpec(BaseModel):

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/tests/unit/test_chat_conformance.py

@@ -70,7 +70,9 @@ class _DictHistory(ChatHistoryStore):
         limit: int = 100,
         before: datetime | None = None,
     ) -> list[SessionInfo]:
-        ids = {t.session_id for t in self._turns}
+        # Include metadata-only sessions (created before their first
+        # turn — bug-018), not just sessions that have turns.
+        ids = {t.session_id for t in self._turns} | set(self._meta)
         out: list[SessionInfo] = []
         for sid in ids:
             o = self._owners.get(sid)

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/tests/unit/test_config_feat012.py

@@ -14,7 +14,6 @@ from agentforge_core.config import (
     parse_overrides,
 )
 from agentforge_core.production.exceptions import ModuleError
-from pydantic import ValidationError
 
 # --- widened schema ----------------------------------------------
 
@@ -269,16 +268,14 @@ def test_explicit_env_arg_beats_env_var(tmp_path: Path, monkeypatch: pytest.Monk
     assert cfg.agent.budget.usd == pytest.approx(50.0)
 
 
-# --- evaluator string-shorthand (NYI in this chunk) ------------
+# --- evaluator string-shorthand (normalised since bug-019) -----
 
 
-def test_evaluator_string_shorthand_not_yet_supported(tmp_path: Path) -> None:
-    """The spec §4.1 mentions `evaluators: - faithfulness` (bare
-    string). This loader doesn't yet normalise that — the YAML must
-    spell out `- name: faithfulness`. Tracked under feat-012's
-    Implementation status.
-    """
+def test_evaluator_string_shorthand_loads(tmp_path: Path) -> None:
+    """Spec §4.1's `evaluators: - faithfulness` (bare string) now loads
+    end-to-end: the entry's `mode="before"` validator normalises the
+    string to `{name: faithfulness, config: {}}` (bug-019)."""
     yaml_path = tmp_path / "agentforge.yaml"
     yaml_path.write_text("modules:\n  evaluators:\n    - faithfulness\n")
-    with pytest.raises(ValidationError):
-        load_config(yaml_path)
+    cfg = load_config(yaml_path)
+    assert [(e.name, e.config) for e in cfg.modules.evaluators] == [("faithfulness", {})]

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/tests/unit/test_config_module_schemas.py

@@ -172,6 +172,61 @@ def test_evaluator_entry_invalid_config_raises():
         validate_module_configs(cfg)
 
 
+# --- bug-019: terse string / single-key-mapping sugar normalises ----
+
+
+def test_evaluators_accept_all_three_sugar_forms() -> None:
+    """String, single-key-mapping, and canonical forms all parse from raw
+    YAML-shaped dicts (bug-019)."""
+    modules = ModulesConfig.model_validate(
+        {
+            "evaluators": [
+                "faithfulness",  # string sugar
+                {"geval": {"rubric": "be nice"}},  # single-key mapping sugar
+                {"name": "correctness", "config": {"ground_truth_field": "ref"}},  # canonical
+            ]
+        }
+    )
+    assert [(e.name, e.config) for e in modules.evaluators] == [
+        ("faithfulness", {}),
+        ("geval", {"rubric": "be nice"}),
+        ("correctness", {"ground_truth_field": "ref"}),
+    ]
+
+
+@pytest.mark.parametrize("gate", ["input", "output", "tool_gates"])
+def test_guardrail_gates_accept_all_three_sugar_forms(gate: str) -> None:
+    modules = ModulesConfig.model_validate(
+        {
+            "guardrails": {
+                gate: [
+                    "prompt_injection_basic",  # string sugar
+                    {"presidio": {"entities": ["EMAIL_ADDRESS"]}},  # single-key mapping sugar
+                    {"name": "capability_check", "config": {}},  # canonical
+                ]
+            }
+        }
+    )
+    entries = getattr(modules.guardrails, gate)
+    assert [(e.name, e.config) for e in entries] == [
+        ("prompt_injection_basic", {}),
+        ("presidio", {"entities": ["EMAIL_ADDRESS"]}),
+        ("capability_check", {}),
+    ]
+
+
+def test_string_sugar_rejects_empty_name() -> None:
+    """An empty string still fails (name has min_length=1)."""
+    with pytest.raises(ValueError, match="evaluators"):
+        ModulesConfig.model_validate({"evaluators": [""]})
+
+
+def test_canonical_form_still_forbids_extra_keys() -> None:
+    """Normalisation must not loosen strict/extra=forbid for canonical dicts."""
+    with pytest.raises(ValueError, match="evaluators"):
+        ModulesConfig.model_validate({"evaluators": [{"name": "x", "config": {}, "bogus": 1}]})
+
+
 # --- non-class schema attribute (defensive) --------------------
 
 

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/tests/unit/test_contracts_tool.py

@@ -6,7 +6,8 @@ from abc import abstractmethod
 from typing import Any
 
 import pytest
-from agentforge_core.contracts.tool import Tool
+from agentforge_core.contracts.tool import Tool, validate_tool_name
+from agentforge_core.production.exceptions import ProviderError, ToolNameInvalidError
 from pydantic import BaseModel
 
 
@@ -92,3 +93,50 @@ def test_inherited_attributes_satisfy_the_check() -> None:
             return "child"
 
     assert _Child.name == "base"
+
+
+# ---- validate_tool_name (bug-017) ----
+
+
+@pytest.mark.parametrize(
+    "name",
+    [
+        "search",
+        "kb_search",
+        "fs__read_file",
+        "tool-1",
+        "A",
+        "a" * 64,
+        "Mixed_Case-123",
+    ],
+)
+def test_validate_tool_name_accepts_portable_names(name: str) -> None:
+    validate_tool_name(name)  # does not raise
+
+
+@pytest.mark.parametrize(
+    "name",
+    [
+        "kb.search",  # dot — the bug-012 / bug-017 case
+        "ns:tool",  # colon
+        "a b",  # space
+        "tool/name",  # slash
+        "café",  # non-ascii
+        "",  # empty
+        "a" * 65,  # too long
+    ],
+)
+def test_validate_tool_name_rejects_illegal_names(name: str) -> None:
+    with pytest.raises(ToolNameInvalidError):
+        validate_tool_name(name)
+
+
+def test_validate_tool_name_error_is_a_provider_error() -> None:
+    """Subclasses ProviderError so existing provider-failure handlers catch it."""
+    with pytest.raises(ProviderError):
+        validate_tool_name("kb.search")
+
+
+def test_validate_tool_name_message_includes_actionable_suggestion() -> None:
+    with pytest.raises(ToolNameInvalidError, match="kb_search"):
+        validate_tool_name("kb.search")

{agentforge_core-0.2.3 → agentforge_core-0.2.4}/tests/unit/test_messages.py

@@ -39,6 +39,17 @@ def test_message_accepts_each_valid_role(role: str) -> None:
     Message(role=role, content="ok")  # type: ignore[arg-type]
 
 
+def test_message_default_tool_calls_is_empty_tuple() -> None:
+    m = Message(role="assistant", content="hi")
+    assert m.tool_calls == ()
+
+
+def test_message_carries_tool_calls() -> None:
+    tc = ToolCall(id="t-1", name="search", arguments={"q": "hi"})
+    m = Message(role="assistant", content="", tool_calls=(tc,))
+    assert m.tool_calls == (tc,)
+
+
 # ---- ToolCall ----