agentplane-runtime 0.0.1__tar.gz → 0.0.2__tar.gz

{agentplane_runtime-0.0.1 → agentplane_runtime-0.0.2}/.gitignore

@@ -1,6 +1,7 @@
 # internal working documents — not part of the public repo
 CLAUDE.md
 SPEC.md
+FEEDBACK.md
 .claude/
 
 # python

{agentplane_runtime-0.0.1 → agentplane_runtime-0.0.2}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: agentplane-runtime
-Version: 0.0.1
+Version: 0.0.2
 Summary: agentplane runtime: definitions, resources, flow execution, A2A + MCP serving
 License-Expression: MIT
 Requires-Python: >=3.12
 Requires-Dist: a2a-sdk[http-server]<2,>=1.1
-Requires-Dist: agentplane-core<0.1.0,>=0.0.1
-Requires-Dist: agentplane-sdk<0.1.0,>=0.0.1
+Requires-Dist: agentplane-core<0.1.0,>=0.0.2
+Requires-Dist: agentplane-sdk<0.1.0,>=0.0.2
 Requires-Dist: aiosqlite>=0.20
 Requires-Dist: cryptography>=43
 Requires-Dist: fastapi>=0.115

{agentplane_runtime-0.0.1 → agentplane_runtime-0.0.2}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "agentplane-runtime"
-version = "0.0.1"
+version = "0.0.2"
 description = "agentplane runtime: definitions, resources, flow execution, A2A + MCP serving"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.12"
 dependencies = [
-    "agentplane-core>=0.0.1,<0.1.0",
-    "agentplane-sdk>=0.0.1,<0.1.0",
+    "agentplane-core>=0.0.2,<0.1.0",
+    "agentplane-sdk>=0.0.2,<0.1.0",
     "a2a-sdk[http-server]>=1.1,<2",
     "fastapi>=0.115",
     "sqlalchemy[asyncio]>=2.0.30",
@@ -28,6 +28,9 @@ dependencies = [
 [project.optional-dependencies]
 postgres = ["asyncpg>=0.29", "pgvector>=0.3"]
 
+[project.scripts]
+agentplane-runtime = "agentplane_runtime.__main__:main"
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

agentplane_runtime-0.0.2/src/agentplane_runtime/__main__.py

@@ -0,0 +1,14 @@
+"""Process entrypoint: ``agentplane-runtime`` (console script) / ``python -m agentplane_runtime``.
+
+Configuration comes from the environment (prefix ``AGENTPLANE_RUNTIME_``) or a
+``.env`` file in the working directory — no uvicorn incantation needed.
+"""
+
+from __future__ import annotations
+
+from agentplane_runtime.app import main
+
+if __name__ == "__main__":  # pragma: no cover - process entrypoint
+    main()
+
+__all__ = ["main"]

{agentplane_runtime-0.0.1 → agentplane_runtime-0.0.2}/src/agentplane_runtime/api.py

@@ -15,6 +15,7 @@ from agentplane_core import (
     JsonObject,
     Resource,
     ValidationResult,
+    VersionLabel,
 )
 from agentplane_runtime.auth import Principal
 from agentplane_runtime.definitions import (
@@ -100,14 +101,19 @@ async def deploy_definition(
     state: State,
     caller: Caller,
     version: Annotated[int | None, Query(ge=1)] = None,
+    version_label: Annotated[VersionLabel | None, Query()] = None,
     ephemeral: Annotated[bool, Query()] = False,
 ) -> DeploymentInfo | JSONResponse:
     try:
-        return await state.definitions.deploy(name, version=version, ephemeral=ephemeral)
+        return await state.definitions.deploy(
+            name, version=version, version_label=version_label, ephemeral=ephemeral
+        )
     except DefinitionInvalidError as exc:
         return _validation_response(exc.result)
     except DefinitionNotFoundError as exc:
         raise HTTPException(status.HTTP_404_NOT_FOUND, detail=str(exc)) from None
+    except DefinitionConflictError as exc:
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=str(exc)) from None
 
 
 @router.post("/definitions/{name}/undeploy", status_code=status.HTTP_204_NO_CONTENT)

{agentplane_runtime-0.0.1 → agentplane_runtime-0.0.2}/src/agentplane_runtime/app.py

@@ -9,6 +9,7 @@ from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 
 from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
 
 from agentplane_runtime.api import RuntimeState, health_router, router
 from agentplane_runtime.auth import Authenticator
@@ -72,6 +73,15 @@ def create_app(settings: RuntimeSettings | None = None) -> FastAPI:
     app.include_router(health_router)
     app.mount("/a2a", endpoints.a2a)
     app.mount("/mcp", endpoints.mcp)
+    if cfg.cors_origins:
+        # Outermost middleware, so it also covers the mounted /a2a and /mcp
+        # endpoints — that is the point: a browser talking A2A without a gateway.
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=cfg.cors_origins,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
     setup_tracing(app, service_name="agentplane-runtime")
     return app
 
@@ -79,7 +89,8 @@ def create_app(settings: RuntimeSettings | None = None) -> FastAPI:
 def main() -> None:  # pragma: no cover - process entrypoint
     import uvicorn  # noqa: PLC0415 - only needed for the entrypoint
 
-    uvicorn.run(create_app(), host="0.0.0.0", port=8000)
+    cfg = RuntimeSettings()
+    uvicorn.run(create_app(cfg), host=cfg.host, port=cfg.port)
 
 
 __all__ = ["create_app", "main"]

{agentplane_runtime-0.0.1 → agentplane_runtime-0.0.2}/src/agentplane_runtime/db.py

@@ -45,11 +45,17 @@ class DefinitionRow(Base):
 
 class VersionRow(Base):
     __tablename__ = "definition_versions"
-    __table_args__ = (UniqueConstraint("name", "version", name="uq_versions_name_version"),)
+    __table_args__ = (
+        UniqueConstraint("name", "version", name="uq_versions_name_version"),
+        UniqueConstraint("name", "version_label", name="uq_versions_name_label"),
+    )
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
     name: Mapped[str] = mapped_column(String(64), index=True)
     version: Mapped[int] = mapped_column(Integer)
+    # Publisher-chosen semantic version for this snapshot; unique per definition.
+    # NULL for versions deployed without a label (SQL treats NULLs as distinct).
+    version_label: Mapped[str | None] = mapped_column(String(64), nullable=True)
     definition_json: Mapped[str] = mapped_column(String)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
 
@@ -114,6 +120,20 @@ async def latest_version(session: AsyncSession, name: str) -> int:
     return first or 0
 
 
+async def version_row(session: AsyncSession, name: str, version: int) -> VersionRow | None:
+    result = await session.execute(
+        select(VersionRow).where(VersionRow.name == name, VersionRow.version == version)
+    )
+    return result.scalar_one_or_none()
+
+
+async def version_row_by_label(session: AsyncSession, name: str, label: str) -> VersionRow | None:
+    result = await session.execute(
+        select(VersionRow).where(VersionRow.name == name, VersionRow.version_label == label)
+    )
+    return result.scalar_one_or_none()
+
+
 __all__ = [
     "RESOURCE_ADAPTER",
     "Base",
@@ -126,4 +146,6 @@ __all__ = [
     "latest_version",
     "load_definition",
     "load_resource",
+    "version_row",
+    "version_row_by_label",
 ]

{agentplane_runtime-0.0.1 → agentplane_runtime-0.0.2}/src/agentplane_runtime/definitions.py

@@ -20,6 +20,8 @@ from agentplane_runtime.db import (
     dump_definition,
     latest_version,
     load_definition,
+    version_row,
+    version_row_by_label,
 )
 from agentplane_runtime.registration import RegistryRegistrar
 from agentplane_runtime.resources import ResourceService
@@ -108,31 +110,42 @@ class DefinitionService:
         return await self.info(name)
 
     async def deploy(
-        self, name: str, *, version: int | None = None, ephemeral: bool = False
+        self,
+        name: str,
+        *,
+        version: int | None = None,
+        version_label: str | None = None,
+        ephemeral: bool = False,
     ) -> DeploymentInfo:
+        """Freeze the draft as a new version and serve it — or re-serve an existing one.
+
+        A new deploy may carry a ``version_label`` (semantic version chosen by
+        the publisher, unique per definition). Rollback selects an existing
+        version by ``version`` (the deploy counter) or by ``version_label``;
+        passing both, or a label that is already taken by another version, is a
+        conflict.
+        """
         row = await self._row(name)
         if ephemeral:
             return await self._deploy_ephemeral(row)
+        if version is not None and version_label is not None:
+            raise DefinitionConflictError(
+                "pass either 'version' (rollback by counter) or 'version_label', not both"
+            )
+
+        if version is None and version_label is not None:
+            existing = await self._version_by_label(name, version_label)
+            if existing is not None:
+                version = existing  # rollback: the label already identifies a version
+                version_label = None
 
         if version is None:
-            draft = load_definition(row.draft_json)
-            result = await self.validate(draft)
-            if not result.valid:
-                raise DefinitionInvalidError(result)
-            async with self._db.session() as session, session.begin():
-                new_version = await latest_version(session, name) + 1
-                session.add(
-                    VersionRow(
-                        name=name,
-                        version=new_version,
-                        definition_json=dump_definition(draft),
-                    )
-                )
-            defn, active_version = draft, new_version
+            defn, active_version, active_label = await self._freeze_draft(name, version_label)
         else:
-            defn, active_version = await self._load_version(name, version), version
+            defn, active_label = await self._load_version_row(name, version)
+            active_version = version
 
-        endpoint = await self._endpoints.start(defn, active_version)
+        endpoint = await self._endpoints.start(defn, active_version, version_label=active_label)
         registry_id = await self._registrar.register(
             defn, endpoint.public_url, uuid.UUID(row.registry_id) if row.registry_id else None
         )
@@ -146,10 +159,41 @@ class DefinitionService:
         return DeploymentInfo(
             name=name,
             version=active_version,
+            version_label=active_label,
             endpoint_url=endpoint.public_url,
             registry_id=registry_id,
         )
 
+    async def _freeze_draft(
+        self, name: str, version_label: str | None
+    ) -> tuple[FlowDefinition, int, str | None]:
+        """Validate the draft and freeze it as the next immutable version."""
+        row = await self._row(name)
+        draft = load_definition(row.draft_json)
+        result = await self.validate(draft)
+        if not result.valid:
+            raise DefinitionInvalidError(result)
+        if version_label is not None and await self._version_by_label(name, version_label):
+            raise DefinitionConflictError(
+                f"version label {version_label!r} is already used by {name!r}"
+            )
+        async with self._db.session() as session, session.begin():
+            new_version = await latest_version(session, name) + 1
+            session.add(
+                VersionRow(
+                    name=name,
+                    version=new_version,
+                    version_label=version_label,
+                    definition_json=dump_definition(draft),
+                )
+            )
+        return draft, new_version, version_label
+
+    async def _version_by_label(self, name: str, label: str) -> int | None:
+        async with self._db.session() as session:
+            found = await version_row_by_label(session, name, label)
+        return found.version if found is not None else None
+
     async def _deploy_ephemeral(self, row: DefinitionRow) -> DeploymentInfo:
         """Playground endpoint for the draft: no registry entry, TTL-bound (§6.2)."""
         draft = load_definition(row.draft_json)
@@ -161,15 +205,16 @@ class DefinitionService:
             name=row.name, version=0, endpoint_url=endpoint.public_url, registry_id=None
         )
 
-    async def _load_version(self, name: str, version: int) -> FlowDefinition:
+    async def _load_version_row(self, name: str, version: int) -> tuple[FlowDefinition, str | None]:
         async with self._db.session() as session:
-            result = await session.execute(
-                select(VersionRow).where(VersionRow.name == name, VersionRow.version == version)
-            )
-            row = result.scalar_one_or_none()
+            row = await version_row(session, name, version)
         if row is None:
             raise DefinitionNotFoundError(f"{name} version {version}")
-        return load_definition(row.definition_json)
+        return load_definition(row.definition_json), row.version_label
+
+    async def _load_version(self, name: str, version: int) -> FlowDefinition:
+        defn, _ = await self._load_version_row(name, version)
+        return defn
 
     async def undeploy(self, name: str) -> None:
         row = await self._row(name)
@@ -211,6 +256,11 @@ class DefinitionService:
         draft = load_definition(row.draft_json)
         async with self._db.session() as session:
             latest = await latest_version(session, row.name)
+            deployed = (
+                await version_row(session, row.name, row.deployed_version)
+                if row.deployed_version is not None
+                else None
+            )
         endpoint = self._endpoints.endpoint_for(row.name)
         status = row.status
         if status not in ("draft", "deployed", "undeployed"):  # pragma: no cover
@@ -225,6 +275,7 @@ class DefinitionService:
                 "status": status,
                 "latest_version": latest or None,
                 "deployed_version": row.deployed_version,
+                "deployed_version_label": deployed.version_label if deployed else None,
                 "endpoint_url": endpoint.public_url if endpoint is not None else None,
                 "owner": row.owner,
                 "created_at": row.created_at,
@@ -262,8 +313,8 @@ class DefinitionService:
         for row in rows:
             if row.deployed_version is None:
                 continue
-            defn = await self._load_version(row.name, row.deployed_version)
-            endpoint = await self._endpoints.start(defn, row.deployed_version)
+            defn, label = await self._load_version_row(row.name, row.deployed_version)
+            endpoint = await self._endpoints.start(defn, row.deployed_version, version_label=label)
             await self._registrar.register(
                 defn,
                 endpoint.public_url,

{agentplane_runtime-0.0.1 → agentplane_runtime-0.0.2}/src/agentplane_runtime/engine.py

@@ -58,9 +58,10 @@ _stream_var: ContextVar[StreamCallback | None] = ContextVar("agentplane_stream",
 
 
 class FlowState(TypedDict):
-    """LangGraph state: values keyed by 'node_id.port'."""
+    """LangGraph state: values keyed by 'node_id.port', plus the nodes that ran."""
 
     values: Annotated[dict[str, PortValue], or_]
+    executed: Annotated[set[str], or_]
 
 
 class _NodeFn(Protocol):
@@ -171,6 +172,8 @@ class FlowRunner:
 
     def _executor_for(self, node: Node) -> _NodeFn:
         async def run_node(state: FlowState) -> dict[str, object]:
+            if node.id in state["executed"] or not self._ready(node, state["values"]):
+                return {}
             with tracer.start_as_current_span(
                 "agentplane.node",
                 attributes={
@@ -181,10 +184,26 @@ class FlowRunner:
                 },
             ):
                 outputs = await self._run(node, state["values"])
-            return {"values": outputs}
+            return {"values": outputs, "executed": {node.id}}
 
         return run_node
 
+    def _ready(self, node: Node, values: dict[str, PortValue]) -> bool:
+        """Whether every wired input port of ``node`` carries a value yet.
+
+        LangGraph (Pregel) triggers a node as soon as *any* predecessor wrote, so
+        a node fed from different graph depths would run once per predecessor —
+        the first time with inputs still missing, i.e. a wasted LLM call. Waiting
+        until all wired ports are filled turns such a fan-in into a join, and it
+        gates router branches for free: the port fed by a branch that was not
+        chosen never fills, so the node stays dormant. Every predecessor write
+        re-triggers the node, so a skipped run is retried once the value arrives.
+        """
+        return all(
+            any(source_ref in values for source_ref in source_refs)
+            for source_refs in self._inputs.get(node.id, {}).values()
+        )
+
     def _gather_inputs(self, node: Node, values: dict[str, PortValue]) -> dict[str, PortValue]:
         gathered: dict[str, PortValue] = {}
         for port, source_refs in self._inputs.get(node.id, {}).items():
@@ -296,7 +315,13 @@ class FlowRunner:
         if resource.dsn_secret:
             dsn = await self._context.resources.secret_value(config.resource, "dsn_secret")
         reader = await reader_for(resource, api_key=api_key, dsn=dsn)
-        documents = await reader.search(config.collection, vector, config.top_k, config.filter)
+        documents = await reader.search(
+            config.collection,
+            vector,
+            config.top_k,
+            config.filter,
+            min_score=config.min_score,
+        )
         return {f"{node.id}.documents": documents}
 
     async def _run_mcp_tool(
@@ -346,7 +371,10 @@ class FlowRunner:
             },
         ):
             graph = self._graph
-            result = await graph.ainvoke({"values": seeded})  # type: ignore[attr-defined]
+            empty: set[str] = set()
+            result = await graph.ainvoke(  # type: ignore[attr-defined]
+                {"values": seeded, "executed": empty}
+            )
         values: dict[str, PortValue] = result["values"]
         return values.get(f"{end.id}.output")
 

{agentplane_runtime-0.0.1 → agentplane_runtime-0.0.2}/src/agentplane_runtime/resources.py

@@ -1,4 +1,9 @@
-"""Resource service (SPEC §6.3): CRUD, write-only secrets, E022 dimension check."""
+"""Resource service (SPEC §6.3): CRUD, write-only secrets, E022 dimension check.
+
+Create/update stay offline: a resource carries no collection, so there is
+nothing to compare a dimension against until a retrieval node names one. The
+E022 check therefore runs in definition validation (see ``validation.py``).
+"""
 
 from __future__ import annotations
 
@@ -74,9 +79,15 @@ class ResourceService:
         return await self._secrets.get(secret_ref(resource_name, field))
 
     async def check_collection_dimension(
-        self, resource: VectorDBResource, collection: str
+        self, resource: VectorDBResource, collection: str, path: str
     ) -> ValidationIssue | None:
-        """E022 for a concrete collection (used by definition validation and create)."""
+        """E022 for a concrete collection (SPEC §3.7).
+
+        The collection lives on the retrieval *node*, not on the resource, so
+        this check only has something to compare during definition validation —
+        which is why ``path`` points at the offending node. An unreachable vector
+        DB is not an E022: it surfaces at execution time, not as a schema error.
+        """
         api_key, dsn = "", ""
         try:
             if resource.api_key_secret:
@@ -94,10 +105,11 @@ class ResourceService:
             return ValidationIssue(
                 code="E022",
                 severity="error",
-                path=f"resources/{resource.name}/embedding/dimension",
+                path=path,
                 message=(
-                    f"embedding dimension {resource.embedding.dimension} does not match "
-                    f"collection {collection!r} dimension {actual}"
+                    f"resource {resource.name!r} embeds with dimension "
+                    f"{resource.embedding.dimension}, but collection {collection!r} has "
+                    f"dimension {actual}"
                 ),
             )
         return None

{agentplane_runtime-0.0.1 → agentplane_runtime-0.0.2}/src/agentplane_runtime/serving.py

@@ -34,7 +34,8 @@ from fastmcp import FastMCP
 from fastmcp.tools import Tool, ToolResult
 from pydantic import PrivateAttr
 from starlette.applications import Starlette
-from starlette.responses import PlainTextResponse
+from starlette.requests import Request
+from starlette.responses import JSONResponse, PlainTextResponse
 from starlette.routing import Route
 
 from agentplane_core import (
@@ -47,6 +48,8 @@ from agentplane_runtime.engine import ExecutionContext, FlowRunner, _as_text
 from agentplane_runtime.resources import ResourceService
 from agentplane_runtime.settings import EPHEMERAL_TTL_S, RuntimeSettings
 
+AGENT_CARD_PATH = "/.well-known/agent-card.json"
+
 # ASGI protocol types — inherently loose (the ASGI spec is dict-based).
 Scope = MutableMapping[str, Any]
 Receive = Callable[[], Awaitable[MutableMapping[str, Any]]]
@@ -54,20 +57,26 @@ Send = Callable[[MutableMapping[str, Any]], Awaitable[None]]
 ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]]
 
 
-def build_agent_card(defn: FlowDefinition, public_url: str) -> AgentCard:
-    """Derive the A2A card from the definition (SPEC §6.5)."""
+def build_agent_card(defn: FlowDefinition, public_url: str, version: str = "1") -> AgentCard:
+    """Derive the A2A card from the definition (SPEC §6.5).
+
+    ``version`` is the published version label when the publisher chose one,
+    else the deploy counter — the card always carries the version that is
+    actually being served.
+    """
     skills = [
         AgentSkill(
             id=defn.name,
             name=defn.display_name or defn.name,
             description=defn.description or defn.display_name or defn.name,
             tags=list(defn.tags) or ["flow"],
+            examples=list(defn.expose.examples),
         )
     ]
     return AgentCard(
         name=defn.name,
         description=defn.description,
-        version="1",
+        version=version,
         supported_interfaces=[
             AgentInterface(url=public_url, protocol_binding="JSONRPC", protocol_version="1.0")
         ],
@@ -151,15 +160,35 @@ def build_a2a_app(
     defn: FlowDefinition,
     public_url: str,
     runner_factory: Callable[[], FlowRunner],
+    version: str = "1",
 ) -> Starlette:
     """One Starlette app per A2A-exposed flow: card + JSON-RPC routes."""
-    card = build_agent_card(defn, public_url)
+    card = build_agent_card(defn, public_url, version)
     handler = DefaultRequestHandler(
         agent_executor=FlowAgentExecutor(runner_factory, defn),
         task_store=InMemoryTaskStore(),
         agent_card=card,
     )
+
+    async def endpoint_info(_: Request) -> JSONResponse:
+        """A browser GET on the endpoint lands here — the JSON-RPC binding is POST-only."""
+        return JSONResponse(
+            {
+                "name": defn.name,
+                "description": defn.description,
+                "protocol": "A2A",
+                "protocol_version": "1.0",
+                "agent_card_url": f"{public_url}{AGENT_CARD_PATH}",
+                "jsonrpc_url": public_url,
+                "hint": (
+                    "POST JSON-RPC 2.0 requests here with the header 'A2A-Version: 1.0'; "
+                    "GET the agent card at agent_card_url."
+                ),
+            }
+        )
+
     routes: list[Route] = [
+        Route("/", endpoint_info, methods=["GET"]),
         *create_agent_card_routes(card),
         *create_jsonrpc_routes(handler, "/"),
     ]
@@ -274,6 +303,7 @@ class Endpoint:
     kind: str  # "a2a" | "mcp"
     version: int
     public_url: str
+    version_label: str | None = None
     lifespan: LifespanHost | None = None
     expires_at: float | None = None  # ephemeral only
 
@@ -319,7 +349,12 @@ class EndpointManager:
         return f"{base}/{defn.expose.kind}/{defn.name}"
 
     async def start(
-        self, defn: FlowDefinition, version: int, *, ephemeral: bool = False
+        self,
+        defn: FlowDefinition,
+        version: int,
+        *,
+        version_label: str | None = None,
+        ephemeral: bool = False,
     ) -> Endpoint:
         """(Re)start the endpoint for a definition at a given version."""
         key = f"_draft/{defn.name}" if ephemeral else defn.name
@@ -335,7 +370,7 @@ class EndpointManager:
             await lifespan.start()
             self.mcp.mount(key, http_app)
         else:
-            app = build_a2a_app(defn, public_url, runner_factory)
+            app = build_a2a_app(defn, public_url, runner_factory, version_label or str(version))
             self.a2a.mount(key, app)
 
         endpoint = Endpoint(
@@ -343,6 +378,7 @@ class EndpointManager:
             kind=defn.expose.kind if not ephemeral else "a2a",
             version=version,
             public_url=public_url,
+            version_label=version_label,
             lifespan=lifespan,
             expires_at=time.monotonic() + EPHEMERAL_TTL_S if ephemeral else None,
         )
@@ -373,6 +409,7 @@ class EndpointManager:
 
 
 __all__ = [
+    "AGENT_CARD_PATH",
     "EndpointManager",
     "FlowAgentExecutor",
     "PathDispatcher",

agentplane_runtime-0.0.2/src/agentplane_runtime/settings.py

@@ -0,0 +1,48 @@
+"""Runtime configuration (SPEC §7.2), env prefix ``AGENTPLANE_RUNTIME_``."""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import field_validator
+from pydantic_settings import BaseSettings, NoDecode, SettingsConfigDict
+
+RUNTIME_VERSION = "0.0.2"
+
+EPHEMERAL_TTL_S = 30 * 60  # SPEC §6.2: draft endpoints live 30 minutes
+
+
+class RuntimeSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="AGENTPLANE_RUNTIME_", extra="ignore", env_file=".env"
+    )
+
+    db_url: str = "sqlite+aiosqlite:///runtime.db"
+    public_base_url: str = ""  # required to serve; validated on app start
+    registry_url: str = ""  # required to self-register; empty disables registration
+    registry_token: str = ""
+    secret_key: str = ""  # Fernet key; required for resources with secrets
+    llm_base_url: str = ""  # gateway's OpenAI-compatible endpoint (resource default)
+    auth_mode: Literal["none", "oidc"] = "none"
+    oidc_issuer: str = ""
+    oidc_audience: str = ""
+    roles_claim: str = "realm_access.roles"
+    admin_role: str = "admin"
+    http_timeout_s: float = 60.0
+    host: str = "0.0.0.0"
+    port: int = 8000
+    # Browsers only reach the endpoints directly when the runtime runs without a
+    # gateway (local builder playground). In production agentgateway owns CORS,
+    # so this stays empty and no middleware is installed. "*" allows any origin.
+    cors_origins: Annotated[list[str], NoDecode] = []
+
+    @field_validator("cors_origins", mode="before")
+    @classmethod
+    def _split_origins(cls, value: object) -> object:
+        """Accept a comma-separated env value (``a.example,b.example``) or a JSON list."""
+        if isinstance(value, str):
+            return [origin.strip() for origin in value.split(",") if origin.strip()]
+        return value
+
+
+__all__ = ["EPHEMERAL_TTL_S", "RUNTIME_VERSION", "RuntimeSettings"]

{agentplane_runtime-0.0.1 → agentplane_runtime-0.0.2}/src/agentplane_runtime/validation.py

@@ -81,7 +81,9 @@ async def validate_full(
             )
             continue
         if isinstance(node, RetrievalNode) and isinstance(resource, VectorDBResource):
-            e022 = await resources.check_collection_dimension(resource, node.config.collection)
+            e022 = await resources.check_collection_dimension(
+                resource, node.config.collection, f"nodes/{node.id}/config/collection"
+            )
             if e022 is not None:
                 issues.append(e022)
 

{agentplane_runtime-0.0.1 → agentplane_runtime-0.0.2}/src/agentplane_runtime/vector.py

@@ -50,10 +50,14 @@ class QdrantReader:
         vector: list[float],
         top_k: int,
         filter: JsonObject | None = None,
+        *,
+        min_score: float | None = None,
     ) -> list[Document]:
         body: dict[str, object] = {"vector": vector, "limit": top_k, "with_payload": True}
         if filter is not None:
             body["filter"] = filter
+        if min_score is not None:
+            body["score_threshold"] = min_score
         try:
             async with httpx.AsyncClient(timeout=self._timeout) as client:
                 response = await client.post(
@@ -109,6 +113,8 @@ class PgvectorReader:
         vector: list[float],
         top_k: int,
         filter: JsonObject | None = None,
+        *,
+        min_score: float | None = None,
     ) -> list[Document]:
         import asyncpg  # noqa: PLC0415 - optional [postgres] extra
 
@@ -129,10 +135,11 @@ class PgvectorReader:
             await conn.close()
         documents: list[Document] = []
         for row in rows:
+            score = float(row["score"])
+            if min_score is not None and score < min_score:
+                continue
             metadata = row["metadata"] if isinstance(row["metadata"], dict) else {}
-            documents.append(
-                Document(text=str(row["text"]), score=float(row["score"]), metadata=metadata)
-            )
+            documents.append(Document(text=str(row["text"]), score=score, metadata=metadata))
         return documents
 
 

agentplane_runtime-0.0.2/tests/test_app_cors.py

@@ -0,0 +1,49 @@
+"""Optional CORS middleware (FEEDBACK 1.2).
+
+Without a gateway in front of the runtime, a browser cannot talk A2A to
+``/a2a/{name}`` at all — the builder playground chats straight from the page.
+In production agentgateway owns CORS, so the middleware stays off by default.
+"""
+
+from __future__ import annotations
+
+import httpx
+from asgi_lifespan import LifespanManager
+
+from agentplane_runtime.app import create_app
+
+from .conftest import make_settings
+
+ORIGIN = "http://builder.localhost:5173"
+
+
+async def _preflight(**settings: object) -> httpx.Response:
+    app = create_app(make_settings(**settings))
+    async with LifespanManager(app):
+        transport = httpx.ASGITransport(app=app)
+        async with httpx.AsyncClient(transport=transport, base_url="http://runtime.test") as client:
+            return await client.options(
+                "/a2a/echo-agent/",
+                headers={
+                    "Origin": ORIGIN,
+                    "Access-Control-Request-Method": "POST",
+                    "Access-Control-Request-Headers": "content-type,a2a-version",
+                },
+            )
+
+
+async def test_no_cors_headers_by_default() -> None:
+    response = await _preflight()
+    assert "access-control-allow-origin" not in response.headers
+
+
+async def test_configured_origin_is_allowed_on_the_a2a_mount() -> None:
+    response = await _preflight(cors_origins=[ORIGIN])
+    assert response.status_code == 200
+    assert response.headers["access-control-allow-origin"] == ORIGIN
+    assert "POST" in response.headers["access-control-allow-methods"]
+
+
+async def test_origins_come_from_a_comma_separated_env_value() -> None:
+    settings = make_settings(cors_origins="http://a.test, http://b.test")
+    assert settings.cors_origins == ["http://a.test", "http://b.test"]

{agentplane_runtime-0.0.1 → agentplane_runtime-0.0.2}/tests/test_definitions_api.py

@@ -12,7 +12,13 @@ from asgi_lifespan import LifespanManager
 
 from agentplane_runtime.app import create_app
 
-from .conftest import REGISTRY_BASE, create_default_resources, load_example, make_settings
+from .conftest import (
+    QDRANT_BASE,
+    REGISTRY_BASE,
+    create_default_resources,
+    load_example,
+    make_settings,
+)
 
 
 async def test_validate_endpoint_reports_stateful_codes(client: httpx.AsyncClient) -> None:
@@ -210,3 +216,80 @@ async def test_deploy_registers_with_registry(client: httpx.AsyncClient) -> None
                 await local_client.post("/api/v1/definitions/echo-agent/undeploy")
             ).status_code == 204
             assert delete_route.called
+
+
+async def test_deploy_with_version_label(client: httpx.AsyncClient) -> None:
+    """Publishers may label a deploy with a semantic version (FEEDBACK 2.3)."""
+    await create_default_resources(client)
+    defn = load_example("echo-agent.yaml")
+    await client.post("/api/v1/definitions", json=defn.canonical_dict())
+
+    first = await client.post(
+        "/api/v1/definitions/echo-agent/deploy", params={"version_label": "1.0.0"}
+    )
+    assert first.status_code == 200, first.text
+    assert first.json()["version"] == 1
+    assert first.json()["version_label"] == "1.0.0"
+
+    info = (await client.get("/api/v1/definitions/echo-agent")).json()
+    assert info["deployed_version_label"] == "1.0.0"
+
+    # the label is served on the agent card
+    card = (await client.get("/a2a/echo-agent/.well-known/agent-card.json")).json()
+    assert card["version"] == "1.0.0"
+
+    # a second deploy takes the next counter and its own label
+    updated = defn.model_copy(update={"description": "v2"})
+    await client.put("/api/v1/definitions/echo-agent", json=updated.canonical_dict())
+    second = await client.post(
+        "/api/v1/definitions/echo-agent/deploy", params={"version_label": "1.1.0"}
+    )
+    assert (second.json()["version"], second.json()["version_label"]) == (2, "1.1.0")
+
+    # a known label rolls back to that version instead of freezing a new one
+    rollback = await client.post(
+        "/api/v1/definitions/echo-agent/deploy", params={"version_label": "1.0.0"}
+    )
+    assert (rollback.json()["version"], rollback.json()["version_label"]) == (1, "1.0.0")
+    info = (await client.get("/api/v1/definitions/echo-agent")).json()
+    assert (info["deployed_version"], info["latest_version"]) == (1, 2)
+
+
+async def test_deploy_rejects_malformed_and_conflicting_version_labels(
+    client: httpx.AsyncClient,
+) -> None:
+    await create_default_resources(client)
+    defn = load_example("echo-agent.yaml")
+    await client.post("/api/v1/definitions", json=defn.canonical_dict())
+
+    not_semver = await client.post(
+        "/api/v1/definitions/echo-agent/deploy", params={"version_label": "v1"}
+    )
+    assert not_semver.status_code == 422
+
+    await client.post("/api/v1/definitions/echo-agent/deploy", params={"version_label": "1.0.0"})
+    both = await client.post(
+        "/api/v1/definitions/echo-agent/deploy",
+        params={"version": 1, "version_label": "2.0.0"},
+    )
+    assert both.status_code == 409
+
+
+@respx.mock
+async def test_validate_reports_e022_dimension_mismatch(client: httpx.AsyncClient) -> None:
+    """The collection lives on the retrieval node, so E022 points at that node (FEEDBACK 1.3)."""
+    respx.get(f"{QDRANT_BASE}/collections/support_docs").mock(
+        return_value=httpx.Response(
+            200, json={"result": {"config": {"params": {"vectors": {"size": 768}}}}}
+        )
+    )
+    respx.route(host="runtime.test").pass_through()
+    await create_default_resources(client)  # resource declares dimension 3
+    defn = load_example("support-rag.yaml").canonical_dict()
+
+    body = (await client.post("/api/v1/definitions/validate", json=defn)).json()
+
+    e022 = [i for i in body["issues"] if i["code"] == "E022"]
+    assert body["valid"] is False
+    assert e022[0]["path"] == "nodes/retrieve_1/config/collection"
+    assert "768" in e022[0]["message"]

agentplane_runtime-0.0.2/tests/test_engine_join.py

@@ -0,0 +1,112 @@
+"""Fan-in joins: every node runs at most once, and router branches gate execution.
+
+LangGraph triggers a node as soon as *any* predecessor wrote, so a node fed
+from different graph depths (``start -> call`` AND ``start -> retrieve ->
+call``) used to run twice — the first time with its documents port still empty,
+i.e. a wasted LLM call. In a routed flow it was worse: an LLM node that also
+takes an unconditional edge from ``start`` ran even when the router had chosen
+the other branch, and its output won the race on ``end.input``.
+"""
+
+from __future__ import annotations
+
+import httpx
+import respx
+from cryptography.fernet import Fernet
+
+from agentplane_core import FlowDefinition, ModelProviderResource, VectorDBResource
+from agentplane_runtime.db import Database
+from agentplane_runtime.engine import ExecutionContext, FlowRunner
+from agentplane_runtime.resources import ResourceService
+from agentplane_runtime.secrets import FernetSecretsProvider
+
+from .conftest import LLM_BASE, QDRANT_BASE, load_example, make_settings, vector_db_body
+
+SEARCH_URL = f"{QDRANT_BASE}/collections/support_docs/points/search"
+
+
+async def _runner(defn: FlowDefinition) -> FlowRunner:
+    db = Database("sqlite+aiosqlite://")
+    await db.create_all()
+    resources = ResourceService(db, FernetSecretsProvider(db, Fernet.generate_key().decode()))
+    await resources.create(
+        ModelProviderResource(name="default-llm", base_url=LLM_BASE, default_model="gpt-5-mini"),
+        "anonymous",
+    )
+    await resources.create(VectorDBResource.model_validate(vector_db_body()), "anonymous")
+    return FlowRunner(
+        defn,
+        ExecutionContext(resources=resources, settings=make_settings(), flow_name=defn.name),
+    )
+
+
+def _mock_embeddings() -> None:
+    respx.post(f"{LLM_BASE}/embeddings").mock(
+        return_value=httpx.Response(200, json={"data": [{"embedding": [0.1, 0.2, 0.3]}]})
+    )
+
+
+def _mock_search(*documents: dict[str, object]) -> respx.Route:
+    return respx.post(SEARCH_URL).mock(return_value=httpx.Response(200, json={"result": documents}))
+
+
+def _mock_llm(answer: str) -> respx.Route:
+    return respx.post(f"{LLM_BASE}/chat/completions").mock(
+        return_value=httpx.Response(200, json={"choices": [{"message": {"content": answer}}]})
+    )
+
+
+@respx.mock
+async def test_fan_in_node_runs_once() -> None:
+    """support-rag feeds `call_1` from `start_1` AND `retrieve_1` — one LLM call, not two."""
+    _mock_embeddings()
+    _mock_search({"score": 0.9, "payload": {"text": "Reset the router.", "source": "kb/1"}})
+    llm = _mock_llm("Please reset the router.")
+
+    runner = await _runner(load_example("support-rag.yaml"))
+    result = await runner.execute({"query": "wifi broken"})
+
+    assert result == "Please reset the router."
+    assert llm.call_count == 1
+    # the single call saw the retrieved documents — it did not fire before retrieval
+    assert "Reset the router." in llm.calls.last.request.content.decode()
+
+
+@respx.mock
+async def test_router_gates_the_llm_branch() -> None:
+    """Nothing retrieved -> the LLM node must not run at all, fallback text is returned."""
+    _mock_embeddings()
+    _mock_search()  # empty result set
+    llm = _mock_llm("should never be produced")
+
+    runner = await _runner(load_example("rag-with-fallback.yaml"))
+    result = await runner.execute({"query": "unknown topic"})
+
+    assert result == "I have no information about that in the knowledge base."
+    assert llm.call_count == 0
+
+
+@respx.mock
+async def test_router_found_branch_runs_the_llm_once() -> None:
+    _mock_embeddings()
+    _mock_search({"score": 0.8, "payload": {"text": "Reset the router.", "source": "kb/1"}})
+    llm = _mock_llm("Reset it.")
+
+    runner = await _runner(load_example("rag-with-fallback.yaml"))
+    result = await runner.execute({"query": "wifi broken"})
+
+    assert result == "Reset it."
+    assert llm.call_count == 1
+
+
+@respx.mock
+async def test_min_score_is_sent_to_the_vector_db() -> None:
+    """Without a threshold a filled collection always returns hits (FEEDBACK 2.1)."""
+    _mock_embeddings()
+    search = _mock_search()
+    _mock_llm("unused")
+
+    runner = await _runner(load_example("rag-with-fallback.yaml"))
+    await runner.execute({"query": "unknown topic"})
+
+    assert search.calls.last.request.read().decode().count('"score_threshold":0.5') == 1

{agentplane_runtime-0.0.1 → agentplane_runtime-0.0.2}/tests/test_serving.py

@@ -183,3 +183,36 @@ def test_agent_card_fields_derive_from_definition() -> None:
     assert card.name == "support-rag"
     assert card.skills[0].tags == ["support", "rag"]
     assert card.supported_interfaces[0].protocol_version == "1.0"
+
+
+def test_agent_card_carries_expose_examples() -> None:
+    """expose.examples land on the skill so calling agents can route (FEEDBACK 2.2)."""
+    defn = load_example("echo-agent.yaml")
+    card = build_agent_card(defn, "https://api.example/a2a/echo-agent")
+    assert list(card.skills[0].examples) == [
+        "What is the capital of France?",
+        "Summarise this paragraph in one sentence.",
+    ]
+
+
+def test_agent_card_version_defaults_to_the_deploy_counter() -> None:
+    defn = load_example("echo-agent.yaml")
+    assert build_agent_card(defn, "https://api.example/a2a/echo-agent").version == "1"
+    labelled = build_agent_card(defn, "https://api.example/a2a/echo-agent", "2.1.0")
+    assert labelled.version == "2.1.0"
+
+
+async def test_browser_get_on_the_endpoint_explains_itself(manager: EndpointManager) -> None:
+    """The JSON-RPC binding is POST-only; a plain GET used to be a bare 405 (FEEDBACK 2.4)."""
+    defn = load_example("echo-agent.yaml")
+    await manager.start(defn, 1)
+    transport = httpx.ASGITransport(app=manager.a2a)
+    async with httpx.AsyncClient(transport=transport, base_url="http://rt.test") as client:
+        response = await client.get("/echo-agent/")
+    assert response.status_code == 200
+    body = response.json()
+    assert body["protocol"] == "A2A"
+    assert body["agent_card_url"] == (
+        "https://api.example/a2a/echo-agent/.well-known/agent-card.json"
+    )
+    assert "A2A-Version: 1.0" in body["hint"]

agentplane_runtime-0.0.1/src/agentplane_runtime/settings.py

@@ -1,31 +0,0 @@
-"""Runtime configuration (SPEC §7.2), env prefix ``AGENTPLANE_RUNTIME_``."""
-
-from __future__ import annotations
-
-from typing import Literal
-
-from pydantic_settings import BaseSettings, SettingsConfigDict
-
-RUNTIME_VERSION = "0.0.1"
-
-EPHEMERAL_TTL_S = 30 * 60  # SPEC §6.2: draft endpoints live 30 minutes
-
-
-class RuntimeSettings(BaseSettings):
-    model_config = SettingsConfigDict(env_prefix="AGENTPLANE_RUNTIME_", extra="ignore")
-
-    db_url: str = "sqlite+aiosqlite:///runtime.db"
-    public_base_url: str = ""  # required to serve; validated on app start
-    registry_url: str = ""  # required to self-register; empty disables registration
-    registry_token: str = ""
-    secret_key: str = ""  # Fernet key; required for resources with secrets
-    llm_base_url: str = ""  # gateway's OpenAI-compatible endpoint (resource default)
-    auth_mode: Literal["none", "oidc"] = "none"
-    oidc_issuer: str = ""
-    oidc_audience: str = ""
-    roles_claim: str = "realm_access.roles"
-    admin_role: str = "admin"
-    http_timeout_s: float = 60.0
-
-
-__all__ = ["EPHEMERAL_TTL_S", "RUNTIME_VERSION", "RuntimeSettings"]