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

{agentforge_core-0.2.3 → agentforge_core-0.3.0}/.gitignore

@@ -47,3 +47,13 @@ Thumbs.db
 # Project-local
 *.local
 .agentforge-state/.session-cache
+
+# AI-assistant working state — local session tracking, not part of
+# the published project. The process docs under .claude/ (standards,
+# checklists, CLAUDE.md) are intentionally kept tracked; only the
+# churny per-session state files are ignored.
+.claude/state/
+
+# Launch / go-to-market drafts — local-only marketing material,
+# never published to the repo.
+launch/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentforge-core
-Version: 0.2.3
+Version: 0.3.0
 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.3.0}/pyproject.toml

@@ -9,7 +9,7 @@
 
 [project]
 name = "agentforge-core"
-version = "0.2.3"
+version = "0.3.0"
 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.3.0}/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.3.0}/src/agentforge_core/config/__init__.py

@@ -20,6 +20,10 @@ bump; removing or renaming requires a major bump.
 
 from __future__ import annotations
 
+from agentforge_core.config.app_sections import (
+    discover_app_sections,
+    validate_app_config,
+)
 from agentforge_core.config.loader import load_config, parse_overrides
 from agentforge_core.config.module_schemas import validate_module_configs
 from agentforge_core.config.schema import (
@@ -56,7 +60,9 @@ __all__ = [
     "RerankerEntry",
     "RetrievalConfig",
     "RetrieverModuleConfig",
+    "discover_app_sections",
     "load_config",
     "parse_overrides",
+    "validate_app_config",
     "validate_module_configs",
 ]

agentforge_core-0.3.0/src/agentforge_core/config/app_sections.py

@@ -0,0 +1,124 @@
+"""Registered app-config section validation (feat-026 Phase 2).
+
+Phase 1 (enh-002) added the reserved ``app:`` namespace and the
+``app_as`` accessor: the framework stored the subtree but validated
+nothing inside it — a derived agent owned validation entirely. Phase 2
+closes the parity gap with *module* config. A derived agent or plugin
+registers a Pydantic schema per ``app.<section>`` through a new
+entry-point group, exactly mirroring how modules register their classes
+(ADR-0004)::
+
+    [project.entry-points."agentforge.config_sections"]
+    graph = "agentforge_graph.config:GraphConfig"
+
+``agentforge config validate`` then validates each registered section
+the same way :func:`validate_module_configs` validates ``modules.*``:
+
+- A section present in ``app:`` **and** registered → validated strictly
+  against its schema; a typo or bad value fails the command.
+- A section present in ``app:`` but **not** registered → left untouched
+  (free-form, like an undocumented ``[tool.x]`` in ``pyproject.toml``).
+- A registered section **absent** from ``app:`` → nothing to validate.
+- A section whose package isn't installed → simply never discovered, so
+  validation degrades gracefully with no special-casing (the lenient
+  behaviour ``validate_module_configs`` gets from ``strict=False``).
+
+This keeps the single ``app:`` boundary (feat-026 §8): registration maps
+names *under* ``app:`` to schemas; it never opens new top-level keys.
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib.metadata import entry_points
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ValidationError
+
+from agentforge_core.production.exceptions import ModuleError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from agentforge_core.config.schema import AgentForgeConfig
+
+_log = logging.getLogger("agentforge.config")
+
+#: Entry-point group mapping an ``app.<section>`` name to a Pydantic
+#: schema. Parallel to the ``agentforge.<category>`` groups the resolver
+#: scans, but consumed here rather than by the runtime resolver (the
+#: resolver skips this group — see ``resolver.discover``).
+SECTIONS_GROUP = "agentforge.config_sections"
+
+
+def discover_app_sections() -> dict[str, type[BaseModel]]:
+    """Scan the ``agentforge.config_sections`` entry-point group.
+
+    Returns a mapping of section name → Pydantic model class. Entries
+    that fail to import, or whose target is not a ``BaseModel`` subclass,
+    are skipped with a warning. On a duplicate name across distributions
+    the first registration wins (matches the resolver's §8 conflict
+    rule).
+    """
+    sections: dict[str, type[BaseModel]] = {}
+    for ep in entry_points(group=SECTIONS_GROUP):
+        if ep.name in sections:
+            _log.warning(
+                "duplicate app-config section %r ignored (first registration wins)",
+                ep.name,
+            )
+            continue
+        try:
+            model = ep.load()
+        except Exception as exc:
+            _log.warning(
+                "skipping app-config section %r: load failed (%s: %s)",
+                ep.name,
+                type(exc).__name__,
+                exc,
+            )
+            continue
+        if not (isinstance(model, type) and issubclass(model, BaseModel)):
+            _log.warning(
+                "skipping app-config section %r: %r is not a pydantic BaseModel subclass",
+                ep.name,
+                model,
+            )
+            continue
+        sections[ep.name] = model
+    return sections
+
+
+def validate_app_config(
+    cfg: AgentForgeConfig,
+    *,
+    sections: Mapping[str, type[BaseModel]] | None = None,
+) -> None:
+    """Validate each registered ``app.<section>`` against its schema.
+
+    Mirrors :func:`validate_module_configs`. Only sections that are both
+    present in ``cfg.app`` and registered via an entry point are checked;
+    unregistered sections are left untouched (free-form). A registered
+    section that fails its schema always raises :class:`ModuleError` —
+    validation failures are fatal, the same as for module config.
+
+    Args:
+        cfg: a loaded :class:`AgentForgeConfig` (post-``load_config``).
+        sections: pre-discovered section map. Defaults to
+            :func:`discover_app_sections`; injectable so tests (and
+            future callers with a cached registry) can supply their own.
+
+    Raises:
+        ModuleError: a registered ``app.<section>`` subtree fails its
+            schema.
+    """
+    registry = sections if sections is not None else discover_app_sections()
+    for name, model in registry.items():
+        if name not in cfg.app:
+            continue
+        try:
+            model.model_validate(cfg.app[name])
+        except ValidationError as exc:
+            raise ModuleError(
+                f"app.{name} failed validation: {exc.errors(include_url=False)}"
+            ) from exc

{agentforge_core-0.2.3 → agentforge_core-0.3.0}/src/agentforge_core/config/loader.py

@@ -3,11 +3,13 @@
 Resolution order (last wins) per spec §4.3:
 
     1. Defaults from each Pydantic model.
-    2. agentforge.yaml on disk (if present).
-    3. agentforge.<env>.yaml (if AGENTFORGE_ENV set).
-    4. Env-var interpolation inside YAML values.
-    5. CLI / loader-API `--override agent.budget.usd=10` arguments.
-    6. Constructor kwargs to Agent (handled in `agentforge.agent`).
+    2. Files pulled in via an `imports:` directive (feat-026 Phase 3),
+       lower precedence than the file that imports them.
+    3. agentforge.yaml on disk (if present).
+    4. agentforge.<env>.yaml (if AGENTFORGE_ENV set).
+    5. Env-var interpolation inside YAML values.
+    6. CLI / loader-API `--override agent.budget.usd=10` arguments.
+    7. Constructor kwargs to Agent (handled in `agentforge.agent`).
 
 Env-var interpolation syntax (feat-001):
 - `${VAR}` — required; raises at load if missing.
@@ -155,6 +157,65 @@ def _read_yaml(path: Path) -> dict[str, Any]:
     return raw
 
 
+#: Reserved top-level loader directive (feat-026 Phase 3): a list of
+#: paths to other config files to pull in. Consumed by the loader
+#: (popped before validation), so it never reaches `AgentForgeConfig`.
+_IMPORTS_KEY = "imports"
+
+
+def _load_file_with_imports(path: Path, *, _visiting: tuple[Path, ...] = ()) -> dict[str, Any]:
+    """Read a config file and resolve its ``imports:`` directive (feat-026
+    Phase 3 — pluggable config *sources*).
+
+    ``imports:`` is a top-level list of paths to other config files,
+    resolved **relative to this file's directory** (absolute paths are
+    honoured as-is). Import path strings get ``${ENV}`` interpolation so
+    ``imports: ["${EXTRA_CONFIG}"]`` works.
+
+    Precedence follows Spring Boot's ``spring.config.import``: an imported
+    file is **lower precedence than the file that imports it** — you
+    import shared defaults and override them locally. Within one
+    ``imports:`` list, later entries beat earlier ones. Imports compose
+    transitively (an imported file may itself import); cycles raise
+    ``ModuleError``.
+
+    The directive is consumed here — the returned mapping never contains
+    an ``imports`` key, so it doesn't collide with the root model's
+    ``extra="forbid"`` and ``config show --resolved`` shows the merged
+    result, not the directive.
+    """
+    resolved = path.resolve()
+    if resolved in _visiting:
+        chain = " -> ".join(str(p) for p in (*_visiting, resolved))
+        raise ModuleError(f"Circular config import detected: {chain}")
+
+    raw = _read_yaml(path)
+    imports = raw.pop(_IMPORTS_KEY, None)
+    if imports is None:
+        return raw
+    if not isinstance(imports, list):
+        raise ModuleError(
+            f"`imports:` in {path} must be a list of file paths; got {type(imports).__name__}."
+        )
+
+    merged: dict[str, Any] = {}
+    for entry in imports:
+        if not isinstance(entry, str):
+            raise ModuleError(f"`imports:` entries in {path} must be strings; got {entry!r}.")
+        import_path = Path(_interp(entry))
+        if not import_path.is_absolute():
+            import_path = path.parent / import_path
+        if not import_path.exists():
+            raise ModuleError(
+                f"Imported config file not found: {import_path} (imported by {path})."
+            )
+        imported = _load_file_with_imports(import_path, _visiting=(*_visiting, resolved))
+        merged = _deep_merge(merged, imported)
+
+    # The importing file's own keys win over everything it imports.
+    return _deep_merge(merged, raw)
+
+
 def _env_overlay_path(base: Path, env: str) -> Path:
     """Compute the overlay path next to `base`: foo.yaml → foo.<env>.yaml."""
     return base.with_suffix(f".{env}{base.suffix}")
@@ -191,14 +252,15 @@ def load_config(
     if resolved_path is None or not resolved_path.exists():
         merged: dict[str, Any] = {}
     else:
-        merged = _read_yaml(resolved_path)
+        merged = _load_file_with_imports(resolved_path)
         # Layered env file overlays the base. Missing overlay is fine
-        # (env-without-file is just "use base").
+        # (env-without-file is just "use base"). The overlay is itself
+        # import-aware, so an `agentforge.<env>.yaml` may pull in files too.
         resolved_env = env if env is not None else os.environ.get("AGENTFORGE_ENV")
         if resolved_env:
             overlay_path = _env_overlay_path(resolved_path, resolved_env)
             if overlay_path.exists():
-                merged = _deep_merge(merged, _read_yaml(overlay_path))
+                merged = _deep_merge(merged, _load_file_with_imports(overlay_path))
 
     interpolated = _walk(merged)
     if overrides:

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

@@ -15,9 +15,39 @@ is the data-side representation.
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Literal
+from typing import Any, Literal, TypeVar
 
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+_AppModelT = TypeVar("_AppModelT", bound=BaseModel)
+
+
+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 +208,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 +223,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 +262,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 +277,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 +311,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"
     )
@@ -422,3 +472,34 @@ class AgentForgeConfig(BaseModel):
     logging: LoggingConfig = Field(default_factory=LoggingConfig)
     output: OutputConfig = Field(default_factory=OutputConfig)
     guardrail_policy: GuardrailPolicy = Field(default_factory=GuardrailPolicy)
+    app: dict[str, Any] = Field(default_factory=dict)
+    """Reserved namespace for **application** config (enh-002, feat-026
+    Phase 1). The framework accepts this subtree but does not interpret
+    it: a consuming agent puts its own config here and validates it with
+    its own Pydantic model via :meth:`app_as`. Every other top-level key
+    stays strict (`extra="forbid"`), so framework-key typos are still
+    caught. Values inside `app:` get `${ENV}` interpolation, env-file
+    layering, dotted-path overrides, and `config show --resolved` for
+    free — they ride the same loader passes as framework keys. The
+    framework performs no *registered-schema* validation inside `app:`
+    in Phase 1; that arrives in feat-026 Phase 2."""
+
+    def app_as(self, model: type[_AppModelT], key: str | None = None) -> _AppModelT:
+        """Validate and return an application-config subtree.
+
+        `key=None` validates the whole `app:` mapping; otherwise the
+        `app[key]` subtree (missing key → empty mapping, so the caller's
+        model supplies its own defaults). The caller's model owns its own
+        strictness, so app-key typos surface here — strictness is
+        delegated into `app:`, not lost.
+
+        Example::
+
+            class GraphConfig(BaseModel):
+                store: StoreConfig
+
+
+            graph_cfg = cfg.app_as(GraphConfig, "graph")
+        """
+        raw = self.app if key is None else self.app.get(key, {})
+        return model.model_validate(raw)

{agentforge_core-0.2.3 → agentforge_core-0.3.0}/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.3.0}/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.3.0/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.3.0}/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.3.0}/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.3.0}/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.