agentforge-py 0.2.2__tar.gz → 0.2.4__tar.gz

agentforge_py-0.2.4/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: agentforge-py
+Version: 0.2.4
+Summary: AgentForge — open-source plug-and-play framework for production AI agents
+Project-URL: Homepage, https://github.com/Scaffoldic/agentforge-py
+Project-URL: Repository, https://github.com/Scaffoldic/agentforge-py
+Project-URL: Documentation, https://github.com/Scaffoldic/agentforge-py
+Project-URL: Changelog, https://github.com/Scaffoldic/agentforge-py/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Scaffoldic/agentforge-py/issues
+Author: The AgentForge Authors
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent,agentic,ai,framework,llm,react,tools
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: agentforge-core~=0.2.4
+Requires-Dist: copier>=9.4
+Requires-Dist: pydantic>=2.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.15
+Provides-Extra: a2a
+Requires-Dist: agentforge-a2a~=0.2.4; extra == 'a2a'
+Provides-Extra: all
+Requires-Dist: agentforge-a2a~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-anthropic[anthropic]~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-bedrock~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-chat-history-postgres~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-chat-history-redis~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-chat-http~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-chat-slack~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-chat~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-eval-geval~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-evidently[evidently]~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-guard-llamaguard~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-guard-llmguard~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-guard-nemo~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-guard-presidio~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-langfuse[langfuse]~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-litellm[litellm]~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-mcp[mcp]~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-memory-neo4j~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-memory-postgres~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-memory-sqlite~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-memory-surrealdb~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-ollama[ollama]~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-openai[openai]~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-otel~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-phoenix[phoenix]~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-reranker-cohere[cohere]~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-reranker-mixedbread[mixedbread]~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-reranker-sentence-transformers[sentence-transformers]~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-reranker-voyage[voyage]~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-statsd[statsd]~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-testing~=0.2.4; extra == 'all'
+Requires-Dist: agentforge-voyage[voyage]~=0.2.4; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: agentforge-anthropic[anthropic]~=0.2.4; extra == 'anthropic'
+Provides-Extra: bedrock
+Requires-Dist: agentforge-bedrock~=0.2.4; extra == 'bedrock'
+Provides-Extra: chat
+Requires-Dist: agentforge-chat~=0.2.4; extra == 'chat'
+Provides-Extra: chat-history-postgres
+Requires-Dist: agentforge-chat-history-postgres~=0.2.4; extra == 'chat-history-postgres'
+Provides-Extra: chat-history-redis
+Requires-Dist: agentforge-chat-history-redis~=0.2.4; extra == 'chat-history-redis'
+Provides-Extra: chat-http
+Requires-Dist: agentforge-chat-http~=0.2.4; extra == 'chat-http'
+Provides-Extra: chat-slack
+Requires-Dist: agentforge-chat-slack~=0.2.4; extra == 'chat-slack'
+Provides-Extra: eval
+Requires-Dist: agentforge-eval-geval~=0.2.4; extra == 'eval'
+Provides-Extra: evidently
+Requires-Dist: agentforge-evidently[evidently]~=0.2.4; extra == 'evidently'
+Provides-Extra: guard-llamaguard
+Requires-Dist: agentforge-guard-llamaguard~=0.2.4; extra == 'guard-llamaguard'
+Provides-Extra: guard-llmguard
+Requires-Dist: agentforge-guard-llmguard~=0.2.4; extra == 'guard-llmguard'
+Provides-Extra: guard-nemo
+Requires-Dist: agentforge-guard-nemo~=0.2.4; extra == 'guard-nemo'
+Provides-Extra: guard-presidio
+Requires-Dist: agentforge-guard-presidio~=0.2.4; extra == 'guard-presidio'
+Provides-Extra: langfuse
+Requires-Dist: agentforge-langfuse[langfuse]~=0.2.4; extra == 'langfuse'
+Provides-Extra: litellm
+Requires-Dist: agentforge-litellm[litellm]~=0.2.4; extra == 'litellm'
+Provides-Extra: mcp
+Requires-Dist: agentforge-mcp[mcp]~=0.2.4; extra == 'mcp'
+Provides-Extra: memory-neo4j
+Requires-Dist: agentforge-memory-neo4j~=0.2.4; extra == 'memory-neo4j'
+Provides-Extra: memory-postgres
+Requires-Dist: agentforge-memory-postgres~=0.2.4; extra == 'memory-postgres'
+Provides-Extra: memory-sqlite
+Requires-Dist: agentforge-memory-sqlite~=0.2.4; extra == 'memory-sqlite'
+Provides-Extra: memory-surrealdb
+Requires-Dist: agentforge-memory-surrealdb~=0.2.4; extra == 'memory-surrealdb'
+Provides-Extra: ollama
+Requires-Dist: agentforge-ollama[ollama]~=0.2.4; extra == 'ollama'
+Provides-Extra: openai
+Requires-Dist: agentforge-openai[openai]~=0.2.4; extra == 'openai'
+Provides-Extra: otel
+Requires-Dist: agentforge-otel~=0.2.4; extra == 'otel'
+Provides-Extra: phoenix
+Requires-Dist: agentforge-phoenix[phoenix]~=0.2.4; extra == 'phoenix'
+Provides-Extra: reranker-cohere
+Requires-Dist: agentforge-reranker-cohere[cohere]~=0.2.4; extra == 'reranker-cohere'
+Provides-Extra: reranker-mixedbread
+Requires-Dist: agentforge-reranker-mixedbread[mixedbread]~=0.2.4; extra == 'reranker-mixedbread'
+Provides-Extra: reranker-sentence-transformers
+Requires-Dist: agentforge-reranker-sentence-transformers[sentence-transformers]~=0.2.4; extra == 'reranker-sentence-transformers'
+Provides-Extra: reranker-voyage
+Requires-Dist: agentforge-reranker-voyage[voyage]~=0.2.4; extra == 'reranker-voyage'
+Provides-Extra: statsd
+Requires-Dist: agentforge-statsd[statsd]~=0.2.4; extra == 'statsd'
+Provides-Extra: testing
+Requires-Dist: agentforge-testing~=0.2.4; extra == 'testing'
+Provides-Extra: voyage
+Requires-Dist: agentforge-voyage[voyage]~=0.2.4; extra == 'voyage'
+Description-Content-Type: text/markdown
+
+# agentforge
+
+The default runtime for the AgentForge framework — `Agent`, `ReActLoop`,
+default tools, `SimpleFinding`, in-memory store, basic safety defaults,
+`BudgetPolicy`. Most users install this package and add module extras
+as needed.
+
+## Three-line agent (once feat-001 lands)
+
+```python
+from agentforge import Agent
+
+agent = Agent(model="anthropic:claude-sonnet-4.7")
+result = await agent.run("Say hello in three words.")
+```
+
+## Install
+
+```bash
+pip install agentforge-py                              # core runtime
+pip install "agentforge-py[anthropic]"                 # + Anthropic provider
+pip install "agentforge-py[anthropic,memory-postgres]" # + persistence
+```
+
+## Status
+
+v0.0 — pre-alpha. Repo bootstrapped; feat-001 (Core contracts &
+`Agent` orchestrator) is the next milestone.
+
+## License
+
+Apache 2.0.

agentforge_py-0.2.4/pyproject.toml

@@ -0,0 +1,189 @@
+# agentforge — default runtime + prebuilt for the AgentForge framework.
+#
+# This package ships the sane defaults a developer expects on a fresh
+# install: the `Agent` orchestrator, `ReActLoop` (stable reasoning
+# strategy), the four built-in tools, the `SimpleFinding` variant +
+# scorecard renderer, the in-memory MemoryStore, the basic safety
+# defaults, and the BudgetPolicy.
+#
+# This package depends on `agentforge-core` (locked contracts) and
+# nothing else from the AgentForge family. Optional extras pull in
+# specific provider/persistence/observability modules.
+#
+# Per ADR-0003 (three-tier package model — this is Tier 2).
+
+[project]
+name = "agentforge-py"
+version = "0.2.4"
+description = "AgentForge — open-source plug-and-play framework for production AI agents"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [
+    {name = "The AgentForge Authors"},
+]
+keywords = ["ai", "agent", "llm", "framework", "agentic", "react", "tools"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "agentforge-core ~= 0.2.4",
+    "pydantic>=2.10",
+    "pyyaml>=6.0",
+    "typer>=0.15",
+    # feat-011: Copier is the scaffolding + three-way-merge engine
+    # (ADR-0005). Used by `agentforge new` / `agentforge upgrade`.
+    "copier>=9.4",
+]
+
+# Optional extras — names match the underlying provider/module package.
+# Adding a module via `pip install "agentforge[<name>]"` pulls the
+# corresponding package onto the path; entry-point discovery does the
+# rest (per ADR-0004).
+[project.optional-dependencies]
+# Each extra installs one sister package at the matching coordinated
+# release-train version. `pip install agentforge-py[anthropic]`
+# resolves to `agentforge-py + agentforge-anthropic`, etc.
+# Add a new entry here every time a new sister package ships.
+
+# LLM providers. Where a sister package keeps its vendor SDK behind
+# an optional `[<sdk>]` extra (the lazy-import pattern), the meta extra
+# MUST chain that extra — otherwise `pip install "agentforge-py[x]"`
+# installs the wrapper but not the SDK and the first call raises a
+# ModuleError (bug-015). bedrock hard-deps its SDK (aioboto3/botocore),
+# so it requests no extra — and must NOT request a phantom `[bedrock]`.
+anthropic = ["agentforge-anthropic[anthropic] ~= 0.2.4"]
+openai = ["agentforge-openai[openai] ~= 0.2.4"]
+bedrock = ["agentforge-bedrock ~= 0.2.4"]
+ollama = ["agentforge-ollama[ollama] ~= 0.2.4"]
+litellm = ["agentforge-litellm[litellm] ~= 0.2.4"]
+
+# Embeddings
+voyage = ["agentforge-voyage[voyage] ~= 0.2.4"]
+
+# Memory backends (each hard-deps its driver SDK — no extra to chain)
+memory-sqlite = ["agentforge-memory-sqlite ~= 0.2.4"]
+memory-postgres = ["agentforge-memory-postgres ~= 0.2.4"]
+memory-neo4j = ["agentforge-memory-neo4j ~= 0.2.4"]
+memory-surrealdb = ["agentforge-memory-surrealdb ~= 0.2.4"]
+
+# Chat surface (chat hard-deps aiosqlite; history backends hard-dep their SDK)
+chat = ["agentforge-chat ~= 0.2.4"]
+chat-http = ["agentforge-chat-http ~= 0.2.4"]
+chat-slack = ["agentforge-chat-slack ~= 0.2.4"]
+chat-history-postgres = ["agentforge-chat-history-postgres ~= 0.2.4"]
+chat-history-redis = ["agentforge-chat-history-redis ~= 0.2.4"]
+
+# Rerankers
+reranker-cohere = ["agentforge-reranker-cohere[cohere] ~= 0.2.4"]
+reranker-voyage = ["agentforge-reranker-voyage[voyage] ~= 0.2.4"]
+reranker-mixedbread = ["agentforge-reranker-mixedbread[mixedbread] ~= 0.2.4"]
+reranker-sentence-transformers = ["agentforge-reranker-sentence-transformers[sentence-transformers] ~= 0.2.4"]
+
+# Guardrails (each hard-deps its SDK — no extra to chain)
+guard-llmguard = ["agentforge-guard-llmguard ~= 0.2.4"]
+guard-presidio = ["agentforge-guard-presidio ~= 0.2.4"]
+guard-nemo = ["agentforge-guard-nemo ~= 0.2.4"]
+guard-llamaguard = ["agentforge-guard-llamaguard ~= 0.2.4"]
+
+# Observability
+langfuse = ["agentforge-langfuse[langfuse] ~= 0.2.4"]
+phoenix = ["agentforge-phoenix[phoenix] ~= 0.2.4"]
+otel = ["agentforge-otel ~= 0.2.4"]
+statsd = ["agentforge-statsd[statsd] ~= 0.2.4"]
+evidently = ["agentforge-evidently[evidently] ~= 0.2.4"]
+
+# Protocols
+mcp = ["agentforge-mcp[mcp] ~= 0.2.4"]
+a2a = ["agentforge-a2a ~= 0.2.4"]
+
+# Eval
+eval = ["agentforge-eval-geval ~= 0.2.4"]
+
+# Testing
+testing = ["agentforge-testing ~= 0.2.4"]
+
+# Everything (development / docs / smoke-test convenience — not
+# recommended for production deploys; pick the actual integrations
+# you use to keep the dependency tree small). Vendor-SDK extras are
+# chained here too so `[all]` actually installs every SDK.
+all = [
+    "agentforge-anthropic[anthropic] ~= 0.2.4",
+    "agentforge-openai[openai] ~= 0.2.4",
+    "agentforge-bedrock ~= 0.2.4",
+    "agentforge-ollama[ollama] ~= 0.2.4",
+    "agentforge-litellm[litellm] ~= 0.2.4",
+    "agentforge-voyage[voyage] ~= 0.2.4",
+    "agentforge-memory-sqlite ~= 0.2.4",
+    "agentforge-memory-postgres ~= 0.2.4",
+    "agentforge-memory-neo4j ~= 0.2.4",
+    "agentforge-memory-surrealdb ~= 0.2.4",
+    "agentforge-chat ~= 0.2.4",
+    "agentforge-chat-http ~= 0.2.4",
+    "agentforge-chat-slack ~= 0.2.4",
+    "agentforge-chat-history-postgres ~= 0.2.4",
+    "agentforge-chat-history-redis ~= 0.2.4",
+    "agentforge-reranker-cohere[cohere] ~= 0.2.4",
+    "agentforge-reranker-voyage[voyage] ~= 0.2.4",
+    "agentforge-reranker-mixedbread[mixedbread] ~= 0.2.4",
+    "agentforge-reranker-sentence-transformers[sentence-transformers] ~= 0.2.4",
+    "agentforge-guard-llmguard ~= 0.2.4",
+    "agentforge-guard-presidio ~= 0.2.4",
+    "agentforge-guard-nemo ~= 0.2.4",
+    "agentforge-guard-llamaguard ~= 0.2.4",
+    "agentforge-langfuse[langfuse] ~= 0.2.4",
+    "agentforge-phoenix[phoenix] ~= 0.2.4",
+    "agentforge-otel ~= 0.2.4",
+    "agentforge-statsd[statsd] ~= 0.2.4",
+    "agentforge-evidently[evidently] ~= 0.2.4",
+    "agentforge-mcp[mcp] ~= 0.2.4",
+    "agentforge-a2a ~= 0.2.4",
+    "agentforge-eval-geval ~= 0.2.4",
+    "agentforge-testing ~= 0.2.4",
+]
+
+[project.scripts]
+# feat-010 ships the read-only `list` command. Destructive commands
+# (`add`, `swap`, `remove`) ship in a follow-up sub-feat alongside
+# feat-012 (Configuration system).
+agentforge = "agentforge.cli.main:main"
+
+[project.urls]
+Homepage = "https://github.com/Scaffoldic/agentforge-py"
+Repository = "https://github.com/Scaffoldic/agentforge-py"
+Documentation = "https://github.com/Scaffoldic/agentforge-py"
+Changelog = "https://github.com/Scaffoldic/agentforge-py/blob/main/CHANGELOG.md"
+Issues = "https://github.com/Scaffoldic/agentforge-py/issues"
+
+[tool.uv.sources]
+agentforge-core = { workspace = true }
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentforge"]
+# feat-011: ship Copier templates inside the wheel. The
+# `{{project_slug}}/` subdir is auto-included via the `packages`
+# directive — hatchling walks all files under src/agentforge,
+# including the Jinja2-named subdirs. Do NOT add a force-include
+# for templates: it duplicates every entry and PyPI rejects the
+# wheel with "Duplicate filename in local headers".
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/agentforge",
+    "tests",
+    "README.md",
+    "LICENSE",
+]

{agentforge_py-0.2.2 → agentforge_py-0.2.4}/src/agentforge/__init__.py

@@ -69,7 +69,7 @@ from agentforge.strategies import (
     get_runtime,
 )
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 __all__ = [
     "RUNTIME_KEY",

{agentforge_py-0.2.2 → agentforge_py-0.2.4}/src/agentforge/_tools/decorator.py

@@ -20,7 +20,15 @@ Wraps a typed function as a concrete `Tool` subclass:
 The decorator inspects the wrapped function and constructs:
 
   - `name`              from the function's `__name__` (or the
-                        `name=` override argument).
+                        `name=` override argument). Keep it within
+                        `[a-zA-Z0-9_-]` (1-64 chars): that's the
+                        tool-name charset Bedrock, OpenAI, and
+                        Anthropic all enforce, so a name outside it
+                        is rejected at request-build time with
+                        `ToolNameInvalidError` (bug-017). A plain
+                        function name like `lookup_user` is already
+                        legal; avoid dots / colons / spaces in
+                        `name=` overrides.
   - `description`       from the docstring's summary line + Args
                         section, parsed Google-style. The first
                         non-blank non-arg line is the summary;

{agentforge_py-0.2.2 → agentforge_py-0.2.4}/src/agentforge/agent.py

@@ -22,7 +22,7 @@ from __future__ import annotations
 
 import logging
 import time
-from collections.abc import AsyncIterator, Awaitable, Callable
+from collections.abc import AsyncIterator, Awaitable, Callable, Sequence
 from pathlib import Path
 from types import TracebackType
 from typing import Any
@@ -37,6 +37,7 @@ from agentforge_core.contracts.guardrails import (
 )
 from agentforge_core.contracts.llm import LLMClient
 from agentforge_core.contracts.memory import MemoryStore
+from agentforge_core.contracts.protocol_bridge import ProtocolBridge
 from agentforge_core.contracts.strategy import ReasoningStrategy
 from agentforge_core.contracts.tool import Tool
 from agentforge_core.observability import get_tracer
@@ -119,6 +120,7 @@ class Agent:
         tool_gates: list[ToolCallGate] | None = None,
         guardrail_policy: GuardrailPolicy | None = None,
         pipeline: Pipeline | None = None,
+        protocol_bridges: Sequence[ProtocolBridge] | None = None,
     ) -> None:
         self._config: AgentForgeConfig = load_config(config_path)
 
@@ -198,6 +200,11 @@ class Agent:
             self._pipeline_tool = PipelineFindingsTool()
             self._tools.append(self._pipeline_tool)
 
+        # feat-013: protocol handlers (e.g. MCP bridges) already started
+        # by the config builder. Their tools are passed in via `tools=`;
+        # the Agent only owns tearing them down on `close()`.
+        self._protocol_bridges: list[ProtocolBridge] = list(protocol_bridges or [])
+
         self._closed = False
 
         if install_log_filter and self._config.logging.run_id_filter:
@@ -677,6 +684,8 @@ class Agent:
         await self._memory.close()
         if self._graph_store is not None:
             await self._graph_store.close()
+        for bridge in self._protocol_bridges:
+            await bridge.close()
         uninstall_run_id_filter()
         uninstall_json_formatter()
 

{agentforge_py-0.2.2 → agentforge_py-0.2.4}/src/agentforge/cli/_build.py

@@ -20,6 +20,7 @@ deterministic exit codes (per feat-017 §4 — config invalid → 2).
 
 from __future__ import annotations
 
+import contextlib
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -30,6 +31,7 @@ from agentforge_core.contracts.evaluator import Evaluator
 from agentforge_core.contracts.graph_store import GraphStore
 from agentforge_core.contracts.llm import LLMClient
 from agentforge_core.contracts.memory import MemoryStore
+from agentforge_core.contracts.protocol_bridge import ProtocolBridge
 from agentforge_core.contracts.reranker import Reranker
 from agentforge_core.contracts.vector_store import VectorStore
 from agentforge_core.production.exceptions import ModuleError
@@ -82,18 +84,35 @@ async def build_agent_from_config(
     llm = _resolve_llm(config)
     strategy = config.agent.strategy if isinstance(config.agent.strategy, str) else None
 
-    return Agent(
-        model=llm,
-        memory=memory if memory is not None else InMemoryStore(),
-        evaluators=evaluators,
-        strategy=strategy,
-        retriever=retriever,
-        system_prompt=config.agent.system_prompt,
-        budget_usd=config.agent.budget.usd,
-        max_iterations=config.agent.max_iterations,
-        record_runs=memory if enable_recording and memory is not None else None,
-        pipeline=pipeline,
-    )
+    # feat-013 (bug-020): wire `modules.protocols` — resolve + start each
+    # handler (e.g. the MCP bridge), merge its tools with the native
+    # `agent.tools`, and hand the started bridges to the Agent so they're
+    # closed on `Agent.close()`. `build_protocols_from_config` has already
+    # awaited `start()` for every bridge it returns.
+    native_tools = build_tools_from_config(config)
+    mcp_tools, protocol_bridges = await build_protocols_from_config(config)
+    all_tools = [*native_tools, *mcp_tools]
+
+    try:
+        return Agent(
+            model=llm,
+            tools=all_tools or None,
+            memory=memory if memory is not None else InMemoryStore(),
+            evaluators=evaluators,
+            strategy=strategy,
+            retriever=retriever,
+            system_prompt=config.agent.system_prompt,
+            budget_usd=config.agent.budget.usd,
+            max_iterations=config.agent.max_iterations,
+            record_runs=memory if enable_recording and memory is not None else None,
+            pipeline=pipeline,
+            protocol_bridges=protocol_bridges,
+        )
+    except BaseException:
+        # Agent construction failed after bridges were started — don't
+        # leak the open transports / spawned subprocesses.
+        await _close_bridges(protocol_bridges)
+        raise
 
 
 def build_memory_from_config(config: AgentForgeConfig) -> MemoryStore | None:
@@ -259,6 +278,83 @@ def build_tools_from_config(config: AgentForgeConfig) -> list[Tool]:
     return tools
 
 
+async def build_protocols_from_config(
+    config: AgentForgeConfig,
+) -> tuple[list[Tool], list[ProtocolBridge]]:
+    """Resolve + start every `modules.protocols` handler (feat-013).
+
+    For each entry: resolve its name under the ``protocols`` resolver
+    category, build the handler via its ``from_config(config)``
+    classmethod, ``await start()`` to open connections and discover
+    tools, then collect the merged tool list. The started bridges are
+    returned so the caller can ``close()`` them on agent teardown.
+
+    Returns an empty ``([], [])`` when no protocols are configured.
+
+    Raises:
+        ModuleError: a protocol isn't registered, lacks a
+            ``from_config`` classmethod, doesn't implement
+            `ProtocolBridge`, or requests server-side ``expose`` (not
+            wired into the runtime yet — see `_reject_unsupported_expose`).
+    """
+    from agentforge_core.contracts.tool import Tool as ToolBase  # noqa: PLC0415
+
+    tools: list[ToolBase] = []
+    bridges: list[ProtocolBridge] = []
+    for entry in config.modules.protocols:
+        _reject_unsupported_expose(entry.name, entry.config)
+        cls = _resolve_class("protocols", entry.name)
+        from_config = getattr(cls, "from_config", None)
+        if not callable(from_config):
+            msg = (
+                f"Resolved protocol {entry.name!r} ({cls.__name__}) has no "
+                f"from_config(config) classmethod."
+            )
+            raise ModuleError(msg)
+        bridge = from_config(entry.config)
+        if not isinstance(bridge, ProtocolBridge):
+            msg = (
+                f"Resolved protocol {entry.name!r} ({cls.__name__}) does not "
+                f"implement ProtocolBridge (needs tools / start / close)."
+            )
+            raise ModuleError(msg)
+        try:
+            await bridge.start()
+        except BaseException:
+            # A later bridge failing must not leak earlier ones.
+            await _close_bridges(bridges)
+            raise
+        bridges.append(bridge)
+        tools.extend(bridge.tools)
+    return tools, bridges
+
+
+def _reject_unsupported_expose(name: str, cfg: dict[str, Any]) -> None:
+    """Fail loud on server-side `expose`, which the runtime can't wire yet.
+
+    Auto-serving an MCP server from inside the agent process would hijack
+    the process's stdio. Consume-only is supported; expose runtime-wiring
+    is a follow-up (tracked alongside enh-001, MCP HTTP server transport).
+    """
+    expose = cfg.get("expose") or {}
+    if expose.get("enabled"):
+        msg = (
+            f"modules.protocols[{name!r}]: server-side `expose` is not wired "
+            "into the agent runtime yet (it would hijack the agent process's "
+            "stdio). Use consume-only config for now; expose runtime-wiring is "
+            "a follow-up (see enh-001)."
+        )
+        raise ModuleError(msg)
+
+
+async def _close_bridges(bridges: list[ProtocolBridge]) -> None:
+    """Close every started bridge, swallowing teardown errors so one bad
+    close doesn't mask the original failure."""
+    for bridge in bridges:
+        with contextlib.suppress(Exception):
+            await bridge.close()
+
+
 def _resolve_llm(config: AgentForgeConfig) -> LLMClient | str | None:
     """Pick the LLM definition out of `config.agent.model` /
     `config.providers["default"]`.
@@ -317,6 +413,7 @@ __all__ = [
     "build_evaluators_from_config",
     "build_memory_from_config",
     "build_pipeline_from_config",
+    "build_protocols_from_config",
     "build_retriever_from_config",
     "build_tools_from_config",
     "load_and_build",

{agentforge_py-0.2.2 → agentforge_py-0.2.4}/src/agentforge/cli/_shared_scaffold.py

@@ -150,7 +150,9 @@ def _framework_version() -> str:
     from importlib.metadata import PackageNotFoundError, version  # noqa: PLC0415
 
     try:
-        return version("agentforge")
+        # Distribution name is `agentforge-py`, not the import name
+        # `agentforge` (bug-008). Do NOT change this back to "agentforge".
+        return version("agentforge-py")
     except PackageNotFoundError:  # pragma: no cover
         return "0.0.0+unknown"
 

{agentforge_py-0.2.2 → agentforge_py-0.2.4}/src/agentforge/cli/new_cmd.py

@@ -17,9 +17,11 @@ import sys
 from collections.abc import Sequence
 from pathlib import Path
 
+import yaml
 from agentforge_core.production.exceptions import ModuleError
 
 from agentforge.cli._scaffold_state import (
+    answers_path,
     prepend_markers,
     write_managed_files_lock,
 )
@@ -98,6 +100,19 @@ def _run_new(args: argparse.Namespace) -> int:
     )
     prepend_markers(dst, template_name=args.template, template_version=template_version)
 
+    # bug-007 fix: persist the resolved scaffold answers ourselves.
+    # Copier's `_answers_file` directive doesn't write reliably for
+    # in-package templates; without `answers.yml`, `agentforge upgrade`
+    # has nothing to re-render from. Must precede inject_shared_scaffold
+    # because that step reads answers.yml for its Jinja context.
+    _write_answers_file(
+        dst,
+        template_name=args.template,
+        template_version=template_version,
+        project_slug=args.project_slug,
+        llm_provider=args.provider,
+    )
+
     # feat-019: inject shared runbooks + AGENTS.md / CLAUDE.md /
     # .cursorrules / .github/copilot-instructions.md into every
     # scaffolded agent.
@@ -113,13 +128,55 @@ def _run_new(args: argparse.Namespace) -> int:
     return 0
 
 
+def _write_answers_file(
+    dst: Path,
+    *,
+    template_name: str,
+    template_version: str,
+    project_slug: str,
+    llm_provider: str | None,
+) -> None:
+    """Persist scaffold answers for `agentforge upgrade` to re-render.
+
+    Copier's `_answers_file` directive in `copier.yml` is supposed to
+    write this automatically, but doesn't reliably for in-package
+    templates (bug-007). We write it ourselves with the minimum
+    fields the upgrade path needs: `_template_name` so we can resolve
+    the template root again, plus the four Copier variables
+    (`project_name`, `project_slug`, `llm_provider`, `description`)
+    so the re-render produces the same shape.
+    """
+    target = answers_path(dst)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    project_name = " ".join(word.capitalize() for word in project_slug.split("-"))
+    payload: dict[str, object] = {
+        "_template_name": template_name,
+        "_template_version": template_version,
+        "project_name": project_name,
+        "project_slug": project_slug,
+        "llm_provider": llm_provider or "bedrock",
+        "description": f"An AgentForge agent ({template_name}).",
+    }
+    target.write_text(
+        "# AgentForge scaffold answers — DO NOT EDIT MANUALLY.\n"
+        "# Used by `agentforge upgrade` to re-render managed template files.\n"
+        + yaml.safe_dump(payload, sort_keys=False),
+        encoding="utf-8",
+    )
+
+
 def _template_version() -> str:
-    """Resolve the installed `agentforge` version — used as the
+    """Resolve the installed framework version — used as the
     template's `source_version` in the lock file."""
     from importlib.metadata import PackageNotFoundError, version  # noqa: PLC0415
 
     try:
-        return version("agentforge")
+        # The PyPI *distribution* name is `agentforge-py` (the import name
+        # `agentforge` is a squatted PyPI project). `version()` keys off the
+        # distribution name, so `version("agentforge")` raised on every
+        # install and fell through to the sentinel (bug-008). Do NOT change
+        # this back to "agentforge".
+        return version("agentforge-py")
     except PackageNotFoundError:  # pragma: no cover
         return "0.0.0+unknown"