agentplane-runtime 0.0.1__tar.gz

agentplane_runtime-0.0.1/.gitignore

@@ -0,0 +1,34 @@
+# internal working documents — not part of the public repo
+CLAUDE.md
+SPEC.md
+.claude/
+
+# python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+
+# tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# local databases and state
+*.db
+registry.db
+runtime.db
+
+# environments / secrets
+.env
+.env.*
+
+# editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

agentplane_runtime-0.0.1/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: agentplane-runtime
+Version: 0.0.1
+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: aiosqlite>=0.20
+Requires-Dist: cryptography>=43
+Requires-Dist: fastapi>=0.115
+Requires-Dist: fastmcp==3.4.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: langgraph<2,>=1.0
+Requires-Dist: opentelemetry-api>=1.27
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27
+Requires-Dist: opentelemetry-sdk>=1.27
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: pyjwt[crypto]>=2.9
+Requires-Dist: sqlalchemy[asyncio]>=2.0.30
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Requires-Dist: pgvector>=0.3; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# agentplane-runtime
+
+Owns flow definitions and resources; executes flows (LangGraph); serves each
+deployed flow as an **A2A agent** (`/a2a/{name}`, a2a-sdk, A2A v1.0) or an
+**MCP server** (`/mcp/{name}`, FastMCP streamable HTTP); self-registers with
+the agentplane registry.
+
+Required configuration (env prefix `AGENTPLANE_RUNTIME_`):
+
+| Variable | Purpose |
+|---|---|
+| `PUBLIC_BASE_URL` | externally reachable base (a gateway route) |
+| `REGISTRY_URL` | where to self-register (empty disables registration) |
+| `SECRET_KEY` | Fernet key for resource credentials |
+| `LLM_BASE_URL` | gateway's OpenAI-compatible endpoint (resource default) |
+
+Run it:
+
+```
+uvicorn --factory agentplane_runtime.app:create_app --port 8000
+```

agentplane_runtime-0.0.1/README.md

@@ -0,0 +1,21 @@
+# agentplane-runtime
+
+Owns flow definitions and resources; executes flows (LangGraph); serves each
+deployed flow as an **A2A agent** (`/a2a/{name}`, a2a-sdk, A2A v1.0) or an
+**MCP server** (`/mcp/{name}`, FastMCP streamable HTTP); self-registers with
+the agentplane registry.
+
+Required configuration (env prefix `AGENTPLANE_RUNTIME_`):
+
+| Variable | Purpose |
+|---|---|
+| `PUBLIC_BASE_URL` | externally reachable base (a gateway route) |
+| `REGISTRY_URL` | where to self-register (empty disables registration) |
+| `SECRET_KEY` | Fernet key for resource credentials |
+| `LLM_BASE_URL` | gateway's OpenAI-compatible endpoint (resource default) |
+
+Run it:
+
+```
+uvicorn --factory agentplane_runtime.app:create_app --port 8000
+```

agentplane_runtime-0.0.1/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "agentplane-runtime"
+version = "0.0.1"
+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",
+    "a2a-sdk[http-server]>=1.1,<2",
+    "fastapi>=0.115",
+    "sqlalchemy[asyncio]>=2.0.30",
+    "aiosqlite>=0.20",
+    "httpx>=0.27",
+    "pydantic-settings>=2.4",
+    "pyjwt[crypto]>=2.9",
+    "cryptography>=43",
+    "langgraph>=1.0,<2",
+    # exact pin — fastmcp ships breaking changes in minor releases (CLAUDE.md)
+    "fastmcp==3.4.4",
+    "opentelemetry-api>=1.27",
+    "opentelemetry-sdk>=1.27",
+    "opentelemetry-exporter-otlp-proto-http>=1.27",
+    "uvicorn>=0.30",
+]
+
+[project.optional-dependencies]
+postgres = ["asyncpg>=0.29", "pgvector>=0.3"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentplane_runtime"]
+
+[tool.uv.sources]
+agentplane-core = { workspace = true }
+agentplane-sdk = { workspace = true }

agentplane_runtime-0.0.1/src/agentplane_runtime/__init__.py

@@ -0,0 +1,8 @@
+"""agentplane-runtime: definitions, resources, flow execution, A2A + MCP serving."""
+
+from agentplane_runtime.app import create_app
+from agentplane_runtime.settings import RUNTIME_VERSION, RuntimeSettings
+
+__version__ = RUNTIME_VERSION
+
+__all__ = ["RUNTIME_VERSION", "RuntimeSettings", "create_app"]

agentplane_runtime-0.0.1/src/agentplane_runtime/api.py

@@ -0,0 +1,232 @@
+"""Runtime REST API (SPEC §6.1/§6.3), prefix ``/api/v1``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Annotated, Literal
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
+from fastapi.responses import JSONResponse
+
+from agentplane_core import (
+    DefinitionInfo,
+    DeploymentInfo,
+    FlowDefinition,
+    JsonObject,
+    Resource,
+    ValidationResult,
+)
+from agentplane_runtime.auth import Principal
+from agentplane_runtime.definitions import (
+    DefinitionConflictError,
+    DefinitionInvalidError,
+    DefinitionNotFoundError,
+    DefinitionService,
+    DefinitionStateError,
+)
+from agentplane_runtime.resources import (
+    ResourceConflictError,
+    ResourceNotFoundError,
+    ResourceService,
+    ResourceValidationError,
+)
+
+
+@dataclass
+class RuntimeState:
+    definitions: DefinitionService
+    resources: ResourceService
+
+
+def _state(request: Request) -> RuntimeState:
+    state: RuntimeState = request.app.state.runtime
+    return state
+
+
+async def _principal(request: Request) -> Principal:
+    principal: Principal = await request.app.state.authenticator.authenticate(request)
+    return principal
+
+
+State = Annotated[RuntimeState, Depends(_state)]
+Caller = Annotated[Principal, Depends(_principal)]
+
+router = APIRouter(prefix="/api/v1")
+health_router = APIRouter()
+
+
+def _validation_response(result: ValidationResult) -> JSONResponse:
+    return JSONResponse(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        content=result.model_dump(mode="json"),
+    )
+
+
+@router.post("/definitions/validate", response_model=ValidationResult)
+async def validate_definition(body: JsonObject, state: State, caller: Caller) -> ValidationResult:
+    """Always 200 with a ValidationResult, even when invalid (SPEC §6.1)."""
+    return await state.definitions.validate(dict(body))
+
+
+@router.post("/definitions", status_code=status.HTTP_201_CREATED, response_model=DefinitionInfo)
+async def create_definition(
+    body: FlowDefinition, state: State, caller: Caller
+) -> DefinitionInfo | JSONResponse:
+    try:
+        return await state.definitions.create_draft(body, caller.sub)
+    except DefinitionInvalidError as exc:
+        return _validation_response(exc.result)
+    except DefinitionConflictError as exc:
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=str(exc)) from None
+
+
+@router.put("/definitions/{name}", response_model=DefinitionInfo)
+async def update_definition(
+    name: str, body: FlowDefinition, state: State, caller: Caller
+) -> DefinitionInfo | JSONResponse:
+    try:
+        return await state.definitions.update_draft(name, body)
+    except DefinitionInvalidError as exc:
+        return _validation_response(exc.result)
+    except DefinitionNotFoundError:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"no definition {name!r}") from None
+    except DefinitionConflictError as exc:
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=str(exc)) from None
+
+
+@router.post("/definitions/{name}/deploy", response_model=DeploymentInfo)
+async def deploy_definition(
+    name: str,
+    state: State,
+    caller: Caller,
+    version: Annotated[int | None, Query(ge=1)] = None,
+    ephemeral: Annotated[bool, Query()] = False,
+) -> DeploymentInfo | JSONResponse:
+    try:
+        return await state.definitions.deploy(name, version=version, 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
+
+
+@router.post("/definitions/{name}/undeploy", status_code=status.HTTP_204_NO_CONTENT)
+async def undeploy_definition(name: str, state: State, caller: Caller) -> None:
+    try:
+        await state.definitions.undeploy(name)
+    except DefinitionNotFoundError:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"no definition {name!r}") from None
+    except DefinitionStateError as exc:
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=str(exc)) from None
+
+
+@router.get("/definitions", response_model=list[DefinitionInfo])
+async def list_definitions(
+    state: State,
+    caller: Caller,
+    status_filter: Annotated[
+        Literal["draft", "deployed", "undeployed"] | None, Query(alias="status")
+    ] = None,
+) -> list[DefinitionInfo]:
+    return await state.definitions.list(status_filter)
+
+
+@router.get("/definitions/{name}", response_model=DefinitionInfo)
+async def get_definition(
+    name: str,
+    state: State,
+    caller: Caller,
+    include: Annotated[Literal["definition"] | None, Query()] = None,
+) -> DefinitionInfo:
+    try:
+        return await state.definitions.info(name, include_definition=include == "definition")
+    except DefinitionNotFoundError:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"no definition {name!r}") from None
+
+
+@router.get("/definitions/{name}/export")
+async def export_definition(
+    name: str,
+    state: State,
+    caller: Caller,
+    version: Annotated[int | None, Query(ge=1)] = None,
+) -> JsonObject:
+    try:
+        defn = await state.definitions.export(name, version)
+    except DefinitionNotFoundError as exc:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=str(exc)) from None
+    return defn.canonical_dict()
+
+
+@router.delete("/definitions/{name}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_definition(name: str, state: State, caller: Caller) -> None:
+    try:
+        await state.definitions.delete(name)
+    except DefinitionNotFoundError:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"no definition {name!r}") from None
+    except DefinitionStateError as exc:
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=str(exc)) from None
+
+
+@router.post("/resources", status_code=status.HTTP_201_CREATED, response_model=Resource)
+async def create_resource(body: Resource, state: State, caller: Caller) -> Resource:
+    try:
+        return await state.resources.create(body, caller.sub)
+    except ResourceConflictError as exc:
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=str(exc)) from None
+    except ResourceValidationError as exc:
+        raise HTTPException(
+            status.HTTP_422_UNPROCESSABLE_ENTITY, detail=exc.result.model_dump(mode="json")
+        ) from None
+
+
+@router.get("/resources", response_model=list[Resource])
+async def list_resources(
+    state: State,
+    caller: Caller,
+    kind: Annotated[str | None, Query()] = None,
+) -> list[Resource]:
+    return await state.resources.list(kind)
+
+
+@router.get("/resources/{name}", response_model=Resource)
+async def get_resource(name: str, state: State, caller: Caller) -> Resource:
+    try:
+        return await state.resources.get(name)
+    except ResourceNotFoundError:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"no resource {name!r}") from None
+
+
+@router.put("/resources/{name}", response_model=Resource)
+async def update_resource(name: str, body: Resource, state: State, caller: Caller) -> Resource:
+    try:
+        return await state.resources.update(name, body, caller.sub)
+    except ResourceNotFoundError:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"no resource {name!r}") from None
+    except ResourceValidationError as exc:
+        raise HTTPException(
+            status.HTTP_422_UNPROCESSABLE_ENTITY, detail=exc.result.model_dump(mode="json")
+        ) from None
+
+
+@router.delete("/resources/{name}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_resource(name: str, state: State, caller: Caller) -> None:
+    try:
+        await state.resources.delete(name)
+    except ResourceNotFoundError:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"no resource {name!r}") from None
+    except ResourceConflictError as exc:
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=str(exc)) from None
+
+
+@health_router.get("/healthz")
+async def healthz() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@health_router.get("/readyz")
+async def readyz() -> dict[str, str]:
+    return {"status": "ready"}
+
+
+__all__ = ["RuntimeState", "health_router", "router"]

agentplane_runtime-0.0.1/src/agentplane_runtime/app.py

@@ -0,0 +1,85 @@
+"""Runtime app factory: API + dynamic /a2a and /mcp endpoint serving."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from agentplane_runtime.api import RuntimeState, health_router, router
+from agentplane_runtime.auth import Authenticator
+from agentplane_runtime.db import Database
+from agentplane_runtime.definitions import DefinitionService
+from agentplane_runtime.registration import RegistryRegistrar
+from agentplane_runtime.resources import ResourceService
+from agentplane_runtime.secrets import FernetSecretsProvider
+from agentplane_runtime.serving import EndpointManager
+from agentplane_runtime.settings import RUNTIME_VERSION, RuntimeSettings
+from agentplane_runtime.tracing import setup_tracing
+
+logger = logging.getLogger(__name__)
+
+_REAP_INTERVAL_S = 60.0
+
+
+def create_app(settings: RuntimeSettings | None = None) -> FastAPI:
+    cfg = settings or RuntimeSettings()
+    if not cfg.public_base_url:
+        raise RuntimeError("AGENTPLANE_RUNTIME_PUBLIC_BASE_URL is required")
+    if not cfg.secret_key:
+        raise RuntimeError("AGENTPLANE_RUNTIME_SECRET_KEY is required")
+
+    db = Database(cfg.db_url)
+    secrets = FernetSecretsProvider(db, cfg.secret_key)
+    resources = ResourceService(db, secrets)
+    endpoints = EndpointManager(resources, cfg)
+    registrar = RegistryRegistrar(cfg)
+    definitions = DefinitionService(db, resources, endpoints, registrar)
+
+    @asynccontextmanager
+    async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+        await db.create_all()
+        try:
+            await definitions.restore_deployed_endpoints()
+        except Exception:
+            logger.exception("failed to restore deployed endpoints")
+
+        async def reaper() -> None:
+            while True:
+                await asyncio.sleep(_REAP_INTERVAL_S)
+                await endpoints.reap_expired()
+
+        reap_task = asyncio.create_task(reaper(), name="ephemeral-reaper")
+        try:
+            yield
+        finally:
+            reap_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await reap_task
+            await registrar.shutdown()
+            await endpoints.stop_all()
+            await db.dispose()
+
+    app = FastAPI(title="agentplane-runtime", version=RUNTIME_VERSION, lifespan=lifespan)
+    app.state.runtime = RuntimeState(definitions=definitions, resources=resources)
+    app.state.authenticator = Authenticator(cfg)
+    app.state.endpoints = endpoints
+    app.include_router(router)
+    app.include_router(health_router)
+    app.mount("/a2a", endpoints.a2a)
+    app.mount("/mcp", endpoints.mcp)
+    setup_tracing(app, service_name="agentplane-runtime")
+    return app
+
+
+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)
+
+
+__all__ = ["create_app", "main"]

agentplane_runtime-0.0.1/src/agentplane_runtime/auth.py

@@ -0,0 +1,137 @@
+"""Optional OIDC auth for the runtime API (SPEC §7.1), same model as the registry.
+
+Deliberately a sibling implementation — services never import each other
+(architecture invariant 3), and core stays free of HTTP/JWT dependencies.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+import httpx
+import jwt
+from fastapi import HTTPException, Request, status
+from jwt.types import Options
+
+from agentplane_runtime.settings import RuntimeSettings
+
+
+@dataclass(frozen=True)
+class Principal:
+    sub: str
+    roles: frozenset[str] = field(default_factory=frozenset)
+    is_admin: bool = False
+
+
+ANONYMOUS = Principal(sub="anonymous", roles=frozenset(), is_admin=False)
+
+
+def _claim_path(claims: dict[str, object], path: str) -> object:
+    value: object = claims
+    for part in path.split("."):
+        if not isinstance(value, dict):
+            return None
+        value = value.get(part)
+    return value
+
+
+class OidcValidator:
+    def __init__(
+        self,
+        issuer: str,
+        audience: str,
+        roles_claim: str,
+        admin_role: str,
+        *,
+        jwks_ttl_s: float = 300.0,
+    ) -> None:
+        self._issuer = issuer.rstrip("/")
+        self._audience = audience
+        self._roles_claim = roles_claim
+        self._admin_role = admin_role
+        self._jwks_ttl_s = jwks_ttl_s
+        self._jwks: dict[str, jwt.PyJWK] = {}
+        self._jwks_fetched_at = 0.0
+
+    async def _refresh_jwks(self) -> None:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            discovery = await client.get(f"{self._issuer}/.well-known/openid-configuration")
+            discovery.raise_for_status()
+            jwks_uri = discovery.json().get("jwks_uri")
+            if not isinstance(jwks_uri, str):
+                raise RuntimeError("issuer discovery returned no jwks_uri")
+            jwks_response = await client.get(jwks_uri)
+            jwks_response.raise_for_status()
+        keys = jwt.PyJWKSet.from_dict(jwks_response.json()).keys
+        self._jwks = {key.key_id: key for key in keys if key.key_id}
+        self._jwks_fetched_at = time.monotonic()
+
+    async def _key_for(self, kid: str) -> jwt.PyJWK:
+        stale = time.monotonic() - self._jwks_fetched_at > self._jwks_ttl_s
+        if kid not in self._jwks or stale:
+            await self._refresh_jwks()
+        key = self._jwks.get(kid)
+        if key is None:
+            raise jwt.InvalidTokenError(f"unknown key id {kid!r}")
+        return key
+
+    async def validate(self, token: str) -> Principal:
+        header = jwt.get_unverified_header(token)
+        kid = header.get("kid")
+        if not isinstance(kid, str):
+            raise jwt.InvalidTokenError("token has no kid header")
+        key = await self._key_for(kid)
+        options: Options = {"verify_aud": bool(self._audience)}
+        claims = jwt.decode(
+            token,
+            key=key.key,
+            algorithms=["RS256", "ES256"],
+            audience=self._audience or None,
+            issuer=self._issuer,
+            options=options,
+        )
+        roles_value = _claim_path(claims, self._roles_claim)
+        roles = (
+            frozenset(str(role) for role in roles_value)
+            if isinstance(roles_value, list)
+            else frozenset()
+        )
+        sub = claims.get("sub")
+        if not isinstance(sub, str) or not sub:
+            raise jwt.InvalidTokenError("token has no sub")
+        return Principal(sub=sub, roles=roles, is_admin=self._admin_role in roles)
+
+
+class Authenticator:
+    def __init__(self, settings: RuntimeSettings) -> None:
+        self.mode = settings.auth_mode
+        self._validator: OidcValidator | None = None
+        if self.mode == "oidc":
+            if not settings.oidc_issuer:
+                raise RuntimeError("AUTH_MODE=oidc requires AGENTPLANE_RUNTIME_OIDC_ISSUER")
+            self._validator = OidcValidator(
+                settings.oidc_issuer,
+                settings.oidc_audience,
+                settings.roles_claim,
+                settings.admin_role,
+            )
+
+    async def authenticate(self, request: Request) -> Principal:
+        if self.mode == "none" or self._validator is None:
+            return ANONYMOUS
+        header = request.headers.get("Authorization", "")
+        scheme, _, token = header.partition(" ")
+        if scheme.lower() != "bearer" or not token:
+            raise HTTPException(status.HTTP_401_UNAUTHORIZED, detail="missing bearer token")
+        try:
+            return await self._validator.validate(token)
+        except jwt.InvalidTokenError as exc:
+            raise HTTPException(status.HTTP_401_UNAUTHORIZED, detail=str(exc)) from exc
+        except httpx.HTTPError as exc:
+            raise HTTPException(
+                status.HTTP_503_SERVICE_UNAVAILABLE, detail=f"issuer unreachable: {exc}"
+            ) from exc
+
+
+__all__ = ["ANONYMOUS", "Authenticator", "OidcValidator", "Principal"]