diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 75aaead43..2d26fbdca 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1397,6 +1397,31 @@ next `await`. A process `run()` started keeps running unless `run()` stops it, so kill it before re-raising. Trajectory events it appended, including any it appends while cleaning up, are kept, and its log ends `canceled`. +#### The control token + +agent-env deploys each agent with a token of its own in `AGENTENV_CONTROL_TOKEN` +(`CONTROL_TOKEN_ENV`), and sends it on every call to the agent's extension routes +in the `AgentEnv-Control-Token` header (`CONTROL_TOKEN_HEADER`; +`client.control_token_headers(token)`), never in `Authorization`, which a front +door may claim. When the application starts serving, under `serve()` or any ASGI +server that runs its lifespan, it takes the token out of the environment, so the +CLIs and tools the agent runs never inherit it, and from then on every extension +operation refuses a call without it with a 401, before its body is read, and logs +the refusal. `/a2a`, the card, `/health`, staging and the peer-agents MCP endpoint +stay open. An agent deployed without a token, or an application that isn't served, +answers anyone, as before. + +An agent that serves its `/ext/*` routes by hand adds `ControlTokenMiddleware` +(`Middleware(ControlTokenMiddleware)`), which takes the token the same way and +guards every `/ext/` path but staging and the peer-agents MCP endpoint. + +An agent installed into a running container (`install/v1`) gets its token when its +declaration lists it in `optional_params` (`optional_params_host` for a host +install): the installer exports it to every install command as +`AGENTENV_CONTROL_TOKEN`, and the agent's install writes it where the agent's +server reads its environment. An optional param is never a `{placeholder}`, so an +installer that doesn't know it still installs the agent, without a token. + #### Live trajectories A runtime that sees its native events as they happen appends each complete diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py index 174561232..af2817887 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py @@ -88,6 +88,7 @@ extension, request_fields, ) +from .control_token import ControlTokenMiddleware from .framework import ( A2AAgentApplication, AgentEnvAgent, @@ -155,6 +156,7 @@ "TRIGGERS_V1", "CLOCK_V1", "A2AAgentApplication", + "ControlTokenMiddleware", "AgentCapabilities", "AgentConfig", "AgentEnvAgent", diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/control_token.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/control_token.py new file mode 100644 index 000000000..78f3dbe5c --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/control_token.py @@ -0,0 +1,80 @@ +"""The agent's control token: agent-env hands each deployed agent one (``CONTROL_TOKEN_ENV``), and the agent's +extension routes refuse a call that doesn't carry it in ``CONTROL_TOKEN_HEADER``. An agent with no token configured +serves them to anyone, as before.""" + +from __future__ import annotations + +import hmac +import logging +import os +from collections.abc import Mapping + +from starlette.datastructures import Headers +from starlette.responses import JSONResponse +from starlette.types import ASGIApp, Receive, Scope, Send + +from ..types import CONTROL_TOKEN_ENV, CONTROL_TOKEN_HEADER +from .peer_agents import PEER_MCP_PATH +from .staging import STAGING_ENDPOINT + +logger = logging.getLogger(__name__) + +REFUSAL = f"this route takes the agent's control token in the {CONTROL_TOKEN_HEADER} header" + + +def take_control_token() -> str | None: + """The token agent-env handed the agent, taken out of the environment so the tools and CLIs the agent runs never + inherit it.""" + return os.environ.pop(CONTROL_TOKEN_ENV, None) or None + + +def carries_control_token(headers: Mapping[str, str], token: str | None) -> bool: + """Whether a call's ``headers`` carry ``token``; with no token, any do.""" + if token is None: + return True + return hmac.compare_digest(headers.get(CONTROL_TOKEN_HEADER, "").encode(), token.encode()) + + +def log_guard(token: str | None) -> None: + """Say, as serving starts, whether the extension routes take a token: an agent deployed without one serves them + open, which is otherwise silent.""" + if token is None: + logger.info("no %s: the extension routes are open", CONTROL_TOKEN_ENV) + else: + logger.info("the extension routes take the agent's control token (%s)", CONTROL_TOKEN_HEADER) + + +def log_refusal(method: str, path: str, client: str | None) -> None: + logger.warning("refused %s %s from %s: no valid %s", method, path, client or "unknown", CONTROL_TOKEN_HEADER) + + +class ControlTokenMiddleware: + """The SDK's check for an agent that serves its ``/ext/*`` routes by hand: each one but staging and the peer-agents + MCP endpoint refuses a call without the agent's token with a 401. The token is taken out of the environment when + the application builds its middleware, as it starts serving, unless one is given.""" + + def __init__(self, app: ASGIApp, *, token: str | None = None) -> None: + self.app = app + self.token = token or take_control_token() + log_guard(self.token) + + async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: + if scope["type"] == "http" and _guarded(_route_path(scope)): + if not carries_control_token(Headers(scope=scope), self.token): + client = scope.get("client") + log_refusal(scope.get("method", ""), scope["path"], client[0] if client else None) + await JSONResponse({"detail": REFUSAL}, status_code=401)(scope, receive, send) + return + await self.app(scope, receive, send) + + +def _route_path(scope: Scope) -> str: + """The path the app's routes match, without the prefix it is mounted under, as Starlette's router reads it.""" + path, root = scope["path"], scope.get("root_path", "") + return path[len(root):] if root and path.startswith(root) else path + + +def _guarded(path: str) -> bool: + return path.startswith("/ext/") and not any( + path == open_path or path.startswith(open_path + "/") for open_path in (STAGING_ENDPOINT, PEER_MCP_PATH) + ) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py index 6851ab3de..ed2faaaa1 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py @@ -64,6 +64,7 @@ ) from ..computer.errors import ComputerError from . import clock as agent_clock +from .control_token import REFUSAL, carries_control_token, log_guard, log_refusal, take_control_token from .peer_agents import PEER_MCP_PATH, PEER_MCP_SERVER_NAME, PeerAgents from .registry import RegisteredOperation, build_registry from .staging import STAGING_ENDPOINT, StagingStore, staging_routes @@ -978,6 +979,26 @@ async def lifespan(app: Starlette) -> AsyncIterator[Any]: return lifespan +def _taking_the_control_token( + application: "A2AAgentApplication", + inner: Callable[[Starlette], AbstractAsyncContextManager] | None, +) -> Callable[[Starlette], AbstractAsyncContextManager]: + """The application's lifespan, ``inner``'s if it has one: serving starts by taking the agent's control token out of + the environment, and the extension routes take it from then on. An application that isn't served stays open.""" + + @asynccontextmanager + async def lifespan(app: Starlette) -> AsyncIterator[Any]: + application.control_token = take_control_token() or application.control_token + log_guard(application.control_token) + if inner is None: + yield None + else: + async with inner(app) as state: + yield state + + return lifespan + + class A2AAgentApplication: """Resolved Agent Card, extension routes, and A2A task executor.""" @@ -1088,10 +1109,12 @@ def __init__(self, agent: Any, definition: _AgentDefinition | None = None) -> No if self.services.peers is not None: routes.append(Route(PEER_MCP_PATH, self.services.peers.app)) lifespan = _serving_peer_tools(self.services.peers, lifespan) - kwargs = {"routes": routes, "middleware": [Middleware(_ServingOnItsPort)]} - if lifespan is not None: - kwargs["lifespan"] = lifespan - self.app = Starlette(**kwargs) + self.control_token: str | None = None + self.app = Starlette( + routes=routes, + middleware=[Middleware(_ServingOnItsPort)], + lifespan=_taking_the_control_token(self, lifespan), + ) try: from a2a.server.apps import A2AStarletteApplication @@ -1158,6 +1181,9 @@ def _route_handler( self, extension_uri: str, operation: RegisteredOperation ) -> Callable: async def invoke(request: Request) -> JSONResponse: + if not carries_control_token(request.headers, self.control_token): + log_refusal(request.method, request.url.path, request.client.host if request.client else None) + return JSONResponse({"detail": REFUSAL}, status_code=401) try: if operation.definition.method == "GET": payload = dict(request.query_params) diff --git a/packages/agentenv-protocol/tests/test_a2a_agent.py b/packages/agentenv-protocol/tests/test_a2a_agent.py index 5e82d5501..8e8bbc709 100644 --- a/packages/agentenv-protocol/tests/test_a2a_agent.py +++ b/packages/agentenv-protocol/tests/test_a2a_agent.py @@ -3,6 +3,7 @@ import asyncio import inspect import json +import os import time from dataclasses import FrozenInstanceError from functools import wraps @@ -44,6 +45,7 @@ AgentEnvAgent, AgentIdentity, AttributionProbeResponse, + ControlTokenMiddleware, BuiltinTools, BundleSkillRequest, ContextObjectTrajectoryRequest, @@ -99,7 +101,12 @@ _SdkServices, _StandardExecutor, ) +from agentenv_protocol import CONTROL_TOKEN_ENV, client as protocol_client from pydantic import BaseModel, Field, ValidationError, field_serializer +from starlette.applications import Starlette +from starlette.middleware import Middleware +from starlette.responses import PlainTextResponse +from starlette.routing import Mount, Route from starlette.testclient import TestClient @@ -3024,3 +3031,64 @@ def state(client: TestClient, task_id: str) -> str: assert cancelled == ["hang"] assert ran == ["hang", "next"] + + +@a2a_agent(identity=AgentIdentity(name="guarded", description="test", version="1"), extensions=(MCP_CONFIG_V1,)) +class _GuardedAgent(AgentEnvAgent): + async def run(self, request: TaskRequest) -> TaskResult: + return TaskResult.text("ok") + + +def test_a_served_agent_takes_its_control_token_out_of_the_environment_and_its_routes_refuse_calls_without_it( + monkeypatch, caplog, +) -> None: + monkeypatch.setenv(CONTROL_TOKEN_ENV, "s3cret") + + with caplog.at_level("INFO", logger="agentenv_protocol.a2a_agent.control_token"), \ + TestClient(_GuardedAgent().create_app()) as agent: + left_in_environment = CONTROL_TOKEN_ENV in os.environ + refused = [ + agent.get("/ext/mcp-config", headers=headers).status_code + for headers in ({}, protocol_client.control_token_headers("guess"), {"Authorization": "Bearer s3cret"}) + ] + detail = agent.get("/ext/mcp-config").json()["detail"] + answered = agent.get("/ext/mcp-config", headers=protocol_client.control_token_headers("s3cret")) + still_open = [agent.get(path).status_code for path in ("/health", "/.well-known/agent.json")] + + assert not left_in_environment and "the extension routes take the agent's control token" in caplog.text + assert "s3cret" not in caplog.text + assert refused == [401, 401, 401] and "AgentEnv-Control-Token" in detail + assert answered.status_code == 200 and answered.json() == {"mcp_servers": {}} + assert still_open == [200, 200] + + +def test_an_agent_with_no_token_or_not_served_keeps_its_routes_open(monkeypatch, caplog) -> None: + monkeypatch.setenv(CONTROL_TOKEN_ENV, "s3cret") + unserved = TestClient(_GuardedAgent().create_app()).get("/ext/mcp-config").status_code + monkeypatch.delenv(CONTROL_TOKEN_ENV) + + with caplog.at_level("INFO", logger="agentenv_protocol.a2a_agent.control_token"), \ + TestClient(_GuardedAgent().create_app()) as agent: + tokenless = agent.get("/ext/mcp-config").status_code + + assert unserved == tokenless == 200 + assert f"no {CONTROL_TOKEN_ENV}: the extension routes are open" in caplog.text + + +def test_the_middleware_guards_a_hand_served_agents_extension_routes_where_its_app_is_mounted_but_staging_and_the_peer_tools( + monkeypatch, +) -> None: + monkeypatch.setenv(CONTROL_TOKEN_ENV, "s3cret") + + async def ok(request): + return PlainTextResponse("ok") + + paths = ("/ext/agent-config", "/ext/staging/abc", "/ext/peer-agents/mcp", "/health") + agent_app = Starlette(routes=[Route(path, ok) for path in paths], middleware=[Middleware(ControlTokenMiddleware)]) + with TestClient(Starlette(routes=[Mount("/agent", agent_app)])) as agent: + without = [agent.get(f"/agent{path}").status_code for path in paths] + with_token = agent.get("/agent/ext/agent-config", headers=protocol_client.control_token_headers("s3cret")) + left_in_environment = CONTROL_TOKEN_ENV in os.environ + + assert without == [401, 200, 200, 200] + assert with_token.status_code == 200 and not left_in_environment diff --git a/src/agent_env/a2a_agent/a2a_agent.py b/src/agent_env/a2a_agent/a2a_agent.py index 79e4bb0dd..efdcfc4f5 100644 --- a/src/agent_env/a2a_agent/a2a_agent.py +++ b/src/agent_env/a2a_agent/a2a_agent.py @@ -12,6 +12,7 @@ from agentenv_protocol import client as protocol_v1 from agentenv_protocol.a2a_agent import STANDARD_EXTENSIONS +from agentenv_protocol.types import CONTROL_TOKEN_ENV from agent_env.config import get_config from agent_env.config.model import MODEL_HEADERS_ENV @@ -541,6 +542,9 @@ async def deploy( resolved_env["LITELLM_BASE_URL"] = (provider or sandbox).url_from_sandbox(resolved_env["LITELLM_BASE_URL"]) merged_env = await asyncio.to_thread(self._build_merged_env, resolved_env, a2a_port) + # Last, so no caller's env var stands in for it: the agent's extension routes take it from here on. + control_token = new_control_token() + merged_env[CONTROL_TOKEN_ENV] = control_token image = self.docker_image_artifact image_name = image.image_name if provider is None: @@ -600,7 +604,7 @@ async def deploy( a2a_url=a2a_url, sandbox_id=self._sandbox.sandbox_id, agent_card=agent_card, sandbox_type=self._sandbox.type, network_policy=self._sandbox.network_policy.to_dict() if self._sandbox.network_policy else None, - control_token=new_control_token(), + control_token=control_token, ) from agent_env.a2a_agent.store import get_a2a_agent_instance_store deployed = get_a2a_agent_instance_store().create_instance(deployed, ttl_seconds) diff --git a/src/agent_env/a2a_agent/protocol.py b/src/agent_env/a2a_agent/protocol.py index 04ae02cfc..5b458b83e 100644 --- a/src/agent_env/a2a_agent/protocol.py +++ b/src/agent_env/a2a_agent/protocol.py @@ -40,6 +40,7 @@ class AgentUnreachableError(TimeoutError): _ERROR_CODE = re.compile(r"[a-z][a-z0-9_]{0,63}") +_REFUSED = " (the agent refused its control token: the record it was sent from has none, or another deployment's)" def raise_for_extension_status( @@ -60,9 +61,11 @@ def raise_for_extension_status( error = body.get("error") if isinstance(body, Mapping) else None code = error.get("code") if isinstance(error, Mapping) else None detail = code if isinstance(code, str) and _ERROR_CODE.fullmatch(code) else "" - message = f"{operation} failed with HTTP {response.status_code}" - if detail: - message += f": {detail}" + status = f"{operation} failed with HTTP {response.status_code}" + refused = _REFUSED if response.status_code == 401 else "" + if refused: + logger.warning(status + refused) + message = status + (f": {detail}" if detail else "") + refused raise httpx.HTTPStatusError(message, request=exc.request, response=response) from exc diff --git a/src/agent_env/a2a_agent/validator.py b/src/agent_env/a2a_agent/validator.py index b0f8a66f6..09a72117e 100644 --- a/src/agent_env/a2a_agent/validator.py +++ b/src/agent_env/a2a_agent/validator.py @@ -209,6 +209,7 @@ async def _run( VerifyA2AAgentCardStep, VerifyA2AAgentConfigIdentityStep, VerifyA2AAgentMCPStep, + VerifyA2AControlTokenStep, VerifyA2ABuiltinToolsStep, VerifyA2AModalitiesStep, VerifyA2APeerAgentsStep, @@ -303,6 +304,7 @@ async def _run( DeployAgentTaskStep(id=deploy_agent_id, version=None, env_ids=[agent.VALIDATION_ENV_ID], a2a_agent_id=agent.id, a2a_agent_version=agent.version), VerifyA2AAgentCardStep(id=f"{task_id}-card", version=None, a2a_agent_id=agent.id, a2a_agent_version=agent.version, depends_on=deploy_agent_dep, fail_task_on_error=False), VerifyA2AAgentConfigIdentityStep(id=f"{task_id}-agent-config-identity", version=None, a2a_agent_id=agent.id, a2a_agent_version=agent.version, depends_on=deploy_agent_dep, fail_task_on_error=False), + VerifyA2AControlTokenStep(id=f"{task_id}-control-token", version=None, a2a_agent_id=agent.id, a2a_agent_version=agent.version, depends_on=deploy_agent_dep, fail_task_on_error=False), VerifyA2ARoleStep(id=f"{task_id}-role", version=None, a2a_agent_id=agent.id, a2a_agent_version=agent.version, depends_on=deploy_agent_dep, fail_task_on_error=False), VerifyA2ABuiltinToolsStep(id=f"{task_id}-builtin-tools", version=None, a2a_agent_id=agent.id, a2a_agent_version=agent.version, depends_on=deploy_agent_dep, fail_task_on_error=False), VerifyA2ASystemPromptStep(id=f"{task_id}-system-prompt", version=None, a2a_agent_id=agent.id, a2a_agent_version=agent.version, depends_on=deploy_agent_dep, fail_task_on_error=False), diff --git a/src/agent_env/agents/agents/claude-code/a2a_server.py b/src/agent_env/agents/agents/claude-code/a2a_server.py index d01b1dce3..77ab702f8 100644 --- a/src/agent_env/agents/agents/claude-code/a2a_server.py +++ b/src/agent_env/agents/agents/claude-code/a2a_server.py @@ -417,8 +417,10 @@ async def _turns_stop_with_the_server(app: Starlette) -> AsyncIterator[None]: description="Commands to install this agent into a running task container, or onto its sandbox's host.", install_commands=_INSTALL_COMMANDS, a2a_port=_A2A_PORT, + optional_params=["control_token"], required_params=["container", "work_dir", "agent_ctx_tar", "a2a_port", *_ENDPOINT_PARAMS], install_commands_host=_INSTALL_COMMANDS_HOST, + optional_params_host=["control_token"], required_params_host=["work_dir", "agent_ctx_tar", "a2a_port", "agent_name", *_ENDPOINT_PARAMS], workdir_host=_HOST_WORKDIR, user_host="root", diff --git a/src/agent_env/agents/agents/claude-code/install.sh b/src/agent_env/agents/agents/claude-code/install.sh index fe35f29be..a4f030723 100755 --- a/src/agent_env/agents/agents/claude-code/install.sh +++ b/src/agent_env/agents/agents/claude-code/install.sh @@ -107,6 +107,7 @@ chmod 0755 "$stage/claude" "$stage/uv-$uv_cpu-unknown-linux-musl/uv" printf '%s=%s\n' "$name" "$(quoted "${!name:-}")" done [ -z "${AGENT_TRUST_ENV:-}" ] || printf '%s\n' "$AGENT_TRUST_ENV" + [ -z "${AGENTENV_CONTROL_TOKEN:-}" ] || printf 'AGENTENV_CONTROL_TOKEN=%s\n' "$(quoted "$AGENTENV_CONTROL_TOKEN")" printf 'A2A_PORT=%s\nCLAUDE_CONFIG_DIR=%s\n' "$(quoted "$port")" "$(quoted "$root/claude")" printf 'DISABLE_AUTOUPDATER=1\nCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1\n' } > "$stage/agent.env" diff --git a/src/agent_env/agents/agents/codex/a2a_server.py b/src/agent_env/agents/agents/codex/a2a_server.py index 4ad2be072..44cf656d4 100644 --- a/src/agent_env/agents/agents/codex/a2a_server.py +++ b/src/agent_env/agents/agents/codex/a2a_server.py @@ -613,8 +613,10 @@ async def _stage_granted_workspace(source: ReadObject | None) -> Path | None: # Port the agent's A2A server listens on inside the container. a2a_port=8000, # Every placeholder referenced in install_commands must be in this list. + optional_params=["control_token"], required_params=["container", "work_dir", "agent_ctx_tar", "a2a_port", *_ENDPOINT_PARAMS], install_commands_host=_INSTALL_COMMANDS_HOST, + optional_params_host=["control_token"], required_params_host=["work_dir", "agent_ctx_tar", "a2a_port", "agent_name", *_ENDPOINT_PARAMS], workdir_host=_HOST_WORKDIR, user_host="root", diff --git a/src/agent_env/agents/agents/codex/install.sh b/src/agent_env/agents/agents/codex/install.sh index 247328b84..57fb9d255 100755 --- a/src/agent_env/agents/agents/codex/install.sh +++ b/src/agent_env/agents/agents/codex/install.sh @@ -123,6 +123,7 @@ case ${AGENT_TRUST_ENV:-} in *SSL_CERT_FILE=*) needs_cas= ;; esac printf '%s=%s\n' "$name" "$(quoted "${!name:-}")" done [ -z "${AGENT_TRUST_ENV:-}" ] || printf '%s\n' "$AGENT_TRUST_ENV" + [ -z "${AGENTENV_CONTROL_TOKEN:-}" ] || printf 'AGENTENV_CONTROL_TOKEN=%s\n' "$(quoted "$AGENTENV_CONTROL_TOKEN")" [ -z "$needs_cas" ] || printf 'SSL_CERT_FILE=%s\n' "$(quoted "$certifi")" printf 'A2A_PORT=%s\nCODEX_HOME=%s\nCODEX_WORKSPACE_DIR=%s\n' \ "$(quoted "$port")" "$(quoted "$root/codex")" "$(quoted "$workspace")" diff --git a/src/agent_env/agents/agents/gemini/a2a_server.py b/src/agent_env/agents/agents/gemini/a2a_server.py index 1d4bfacbb..a9a8fca05 100644 --- a/src/agent_env/agents/agents/gemini/a2a_server.py +++ b/src/agent_env/agents/agents/gemini/a2a_server.py @@ -433,9 +433,11 @@ async def _vertex_openai_bridge( "or directly onto a task VM (host mode)." ), install_commands=_INSTALL_COMMANDS, + optional_params=["control_token"], required_params=["container", "work_dir", "agent_ctx_tar", "a2a_port", *_ENDPOINT_PARAMS], install_commands_host=_INSTALL_COMMANDS_HOST, a2a_port=8000, + optional_params_host=["control_token"], required_params_host=["work_dir", "agent_ctx_tar", "a2a_port", "agent_name", *_ENDPOINT_PARAMS], workdir_host=_HOST_WORKDIR, user_host="root", diff --git a/src/agent_env/agents/agents/gemini/install.sh b/src/agent_env/agents/agents/gemini/install.sh index 9f7b00d1a..954472462 100755 --- a/src/agent_env/agents/agents/gemini/install.sh +++ b/src/agent_env/agents/agents/gemini/install.sh @@ -113,6 +113,7 @@ chmod 0755 "$stage/gemini" printf '%s=%s\n' "$name" "$(quoted "${!name:-}")" done [ -z "${AGENT_TRUST_ENV:-}" ] || printf '%s\n' "$AGENT_TRUST_ENV" + [ -z "${AGENTENV_CONTROL_TOKEN:-}" ] || printf 'AGENTENV_CONTROL_TOKEN=%s\n' "$(quoted "$AGENTENV_CONTROL_TOKEN")" printf 'A2A_PORT=%s\nGEMINI_CLI_HOME=%s\nGEMINI_CWD=%s\n' \ "$(quoted "$port")" "$(quoted "$root/gemini")" "$(quoted "$workspace")" } > "$stage/agent.env" diff --git a/src/agent_env/agents/agents/letta-code/a2a_server.py b/src/agent_env/agents/agents/letta-code/a2a_server.py index 57519820b..d11349b52 100644 --- a/src/agent_env/agents/agents/letta-code/a2a_server.py +++ b/src/agent_env/agents/agents/letta-code/a2a_server.py @@ -295,8 +295,10 @@ async def lifespan(app: Starlette): # Port the agent's A2A server listens on inside the container. a2a_port=8000, # Every placeholder referenced in install_commands must be in this list. + optional_params=["control_token"], required_params=["container", "work_dir", "agent_ctx_tar", "a2a_port", *_ENDPOINT_PARAMS], install_commands_host=_INSTALL_COMMANDS_HOST, + optional_params_host=["control_token"], required_params_host=["work_dir", "agent_ctx_tar", "a2a_port", "agent_name", *_ENDPOINT_PARAMS], workdir_host=_HOST_WORKDIR, user_host="root", diff --git a/src/agent_env/agents/agents/letta-code/install.sh b/src/agent_env/agents/agents/letta-code/install.sh index ee3fd9fd2..a89987fdf 100644 --- a/src/agent_env/agents/agents/letta-code/install.sh +++ b/src/agent_env/agents/agents/letta-code/install.sh @@ -122,6 +122,7 @@ chmod 0755 "$stage/letta" printf '%s=%s\n' "$name" "$(quoted "${!name:-}")" done [ -z "${AGENT_TRUST_ENV:-}" ] || printf '%s\n' "$AGENT_TRUST_ENV" + [ -z "${AGENTENV_CONTROL_TOKEN:-}" ] || printf 'AGENTENV_CONTROL_TOKEN=%s\n' "$(quoted "$AGENTENV_CONTROL_TOKEN")" # Letta Code's state, its sessions and skills, as the image keeps it under /data. printf 'A2A_PORT=%s\nLETTA_CODE_WORKSPACE_DIR=%s\nHOME=%s\n' \ "$(quoted "$port")" "$(quoted "$workspace")" "$(quoted "$root/data")" diff --git a/src/agent_env/agents/agents/opencode/a2a_server.py b/src/agent_env/agents/agents/opencode/a2a_server.py index 5bea2eb74..456781eb5 100644 --- a/src/agent_env/agents/agents/opencode/a2a_server.py +++ b/src/agent_env/agents/agents/opencode/a2a_server.py @@ -318,8 +318,10 @@ def memory_mb(cgroup_limit: Path = Path("/sys/fs/cgroup/memory.max")) -> int: # Port the agent's A2A server listens on inside the container. a2a_port=8000, # Every placeholder referenced in install_commands must be in this list. + optional_params=["control_token"], required_params=["container", "work_dir", "agent_ctx_tar", "a2a_port", *_ENDPOINT_PARAMS], install_commands_host=_INSTALL_COMMANDS_HOST, + optional_params_host=["control_token"], required_params_host=["work_dir", "agent_ctx_tar", "a2a_port", "agent_name", *_ENDPOINT_PARAMS], workdir_host=_HOST_WORKDIR, user_host="root", diff --git a/src/agent_env/agents/agents/opencode/install.sh b/src/agent_env/agents/agents/opencode/install.sh index 678ff410f..5785d3bfe 100755 --- a/src/agent_env/agents/agents/opencode/install.sh +++ b/src/agent_env/agents/agents/opencode/install.sh @@ -112,6 +112,7 @@ chmod 0755 "$stage/opencode" printf '%s=%s\n' "$name" "$(quoted "${!name:-}")" done [ -z "${AGENT_TRUST_ENV:-}" ] || printf '%s\n' "$AGENT_TRUST_ENV" + [ -z "${AGENTENV_CONTROL_TOKEN:-}" ] || printf 'AGENTENV_CONTROL_TOKEN=%s\n' "$(quoted "$AGENTENV_CONTROL_TOKEN")" # OpenCode's state, its sessions and skills, as the image keeps it under /data. printf 'A2A_PORT=%s\nOPENCODE_WORKSPACE_DIR=%s\nHOME=%s\n' \ "$(quoted "$port")" "$(quoted "$workspace")" "$(quoted "$root/data")" diff --git a/src/agent_env/agents/agents/openhands/openhands_agent.py b/src/agent_env/agents/agents/openhands/openhands_agent.py index 8ef037d3b..9c8129f98 100644 --- a/src/agent_env/agents/agents/openhands/openhands_agent.py +++ b/src/agent_env/agents/agents/openhands/openhands_agent.py @@ -89,6 +89,11 @@ "LITELLM_BASE_URL={litellm_base_url}\n" "LITELLM_EXTRA_HEADERS={litellm_extra_headers}\n" "OPENHANDS_A2A_ENV", + # agent-env's control token for the agent, which the runner exports when it has one (install/v1 optional_params), + # the same way: expanded by the install's shell into the heredoc, empty without one, which leaves the agent open. + f"{_DOCKER} exec -i {{container}} sh -c 'cat >> {INSTALL_DIR}/{ENV_FILE}' <> {INSTALL_DIR}/{ENV_FILE}' < None: enable( INSTALL_V1, install_commands=INSTALL_COMMANDS, + optional_params=["control_token"], required_params=["container", "agent_ctx_tar", "a2a_port", "litellm_api_key", "litellm_base_url"], a2a_port=8000, ), diff --git a/src/agent_env/agents/agents/proxy/a2a_server.py b/src/agent_env/agents/agents/proxy/a2a_server.py index 938885ccc..ede7a589e 100644 --- a/src/agent_env/agents/agents/proxy/a2a_server.py +++ b/src/agent_env/agents/agents/proxy/a2a_server.py @@ -17,8 +17,10 @@ extensions=( *EXTENSIONS, enable(INSTALL_V1, install_commands=_INSTALL_COMMANDS, + optional_params=["control_token"], required_params=["container", "work_dir", "agent_ctx_tar", "a2a_port"], install_commands_host=_INSTALL_COMMANDS_HOST, + optional_params_host=["control_token"], required_params_host=["work_dir", "agent_ctx_tar", "a2a_port", "agent_name", "host_workdir", "host_user"], a2a_port=8000), ), diff --git a/src/agent_env/agents/agents/proxy/install.sh b/src/agent_env/agents/agents/proxy/install.sh index 1bff9b21f..4ee4fc44f 100644 --- a/src/agent_env/agents/agents/proxy/install.sh +++ b/src/agent_env/agents/agents/proxy/install.sh @@ -67,7 +67,7 @@ case $mode in python=$root/venv/bin/python fi docker cp "$here/a2a_server.py" "$target:$root/a2a_server.py" >/dev/null - docker exec -d -u 0 -e A2A_PORT="$port" "$target" \ + docker exec -d -u 0 -e A2A_PORT="$port" ${AGENTENV_CONTROL_TOKEN:+-e AGENTENV_CONTROL_TOKEN} "$target" \ sh -c "echo \$\$ > $root/proxy.pid; exec $python $root/a2a_server.py > $root/proxy.log 2>&1" ;; *) echo "usage: install.sh host NAME PORT WORKDIR USER | install.sh container NAME PORT" >&2; exit 2 ;; diff --git a/src/agent_env/agents/agents/pydantic-ai/pydantic_ai_agent.py b/src/agent_env/agents/agents/pydantic-ai/pydantic_ai_agent.py index ea706e084..bd88e824b 100644 --- a/src/agent_env/agents/agents/pydantic-ai/pydantic_ai_agent.py +++ b/src/agent_env/agents/agents/pydantic-ai/pydantic_ai_agent.py @@ -93,6 +93,11 @@ # The KEY='VALUE' lines pointing TLS clients at the local transfer CA, which start.sh applies. "AGENT_TRUST_ENV={trust_env}\n" "PYDANTIC_AI_A2A_ENV", + # agent-env's control token for the agent, which the runner exports when it has one (install/v1 optional_params), + # the same way: expanded by the install's shell into the heredoc, empty without one, which leaves the agent open. + f"{_DOCKER} exec -i {{container}} sh -c 'cat >> {INSTALL_DIR}/{ENV_FILE}' < list[s "always_on_agent_verifier": _rubrics_verifier, **dict.fromkeys(( "verify_a2a_agent_card", "verify_a2a_agent_config_identity", "verify_a2a_agent_mcp", "verify_a2a_builtin_tools", - "verify_a2a_core_protocol", "verify_a2a_install", "verify_a2a_modalities", "verify_a2a_peer_agents", + "verify_a2a_control_token", "verify_a2a_core_protocol", "verify_a2a_install", "verify_a2a_modalities", "verify_a2a_peer_agents", "verify_a2a_role", "verify_a2a_skill_config", "verify_a2a_snapshot", "verify_a2a_system_prompt", "verify_a2a_trajectory", ), _validates_an_agent), diff --git a/src/agent_env/task_step/registry.py b/src/agent_env/task_step/registry.py index c4b5c5b9d..7d42cbb2e 100644 --- a/src/agent_env/task_step/registry.py +++ b/src/agent_env/task_step/registry.py @@ -96,6 +96,7 @@ def _builtin_registry() -> dict[str, type["TaskStep"]]: from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_snapshot import VerifyA2ASnapshotStep from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_trajectory import VerifyA2ATrajectoryStep from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_builtin_tools import VerifyA2ABuiltinToolsStep + from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_control_token import VerifyA2AControlTokenStep from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_role import VerifyA2ARoleStep from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_system_prompt import VerifyA2ASystemPromptStep from agent_env.task_step.task_steps.add_skills import AddSkillsTaskStep @@ -183,6 +184,7 @@ def _builtin_registry() -> dict[str, type["TaskStep"]]: _get_type(AggregateVerifiersTaskStep): AggregateVerifiersTaskStep, _get_type(VerifyA2ABuiltinToolsStep): VerifyA2ABuiltinToolsStep, _get_type(VerifyA2ARoleStep): VerifyA2ARoleStep, + _get_type(VerifyA2AControlTokenStep): VerifyA2AControlTokenStep, _get_type(VerifyA2ASystemPromptStep): VerifyA2ASystemPromptStep, } diff --git a/src/agent_env/task_step/task_steps/a2a_agent_validator/__init__.py b/src/agent_env/task_step/task_steps/a2a_agent_validator/__init__.py index a386ca654..3cd15b66b 100644 --- a/src/agent_env/task_step/task_steps/a2a_agent_validator/__init__.py +++ b/src/agent_env/task_step/task_steps/a2a_agent_validator/__init__.py @@ -1,5 +1,6 @@ from .verify_a2a_agent_card import VerifyA2AAgentCardStep from .verify_a2a_agent_config_identity import VerifyA2AAgentConfigIdentityStep +from .verify_a2a_control_token import VerifyA2AControlTokenStep from .verify_a2a_agent_mcp import VerifyA2AAgentMCPStep from .verify_a2a_builtin_tools import VerifyA2ABuiltinToolsStep from .verify_a2a_core_protocol import VerifyCoreA2AProtocolStep @@ -15,6 +16,7 @@ __all__ = [ "VerifyA2AAgentCardStep", "VerifyA2AAgentConfigIdentityStep", + "VerifyA2AControlTokenStep", "VerifyA2AAgentMCPStep", "VerifyA2ABuiltinToolsStep", "VerifyCoreA2AProtocolStep", diff --git a/src/agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_control_token.py b/src/agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_control_token.py new file mode 100644 index 000000000..bab2b48fa --- /dev/null +++ b/src/agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_control_token.py @@ -0,0 +1,62 @@ +"""Verify the agent's extension routes take its control token: a call without it is refused with a 401, one with it is +not.""" +from __future__ import annotations + +import logging +from typing import ClassVar, Optional + +import httpx + +from agent_env.a2a_agent import A2AAgent +from agent_env.entity.refs import EntityRef +from agent_env.task_step.context import TaskStepContext +from agent_env.task_step.task_step import StepRole, TaskStep, TaskStepDependency + +logger = logging.getLogger(__name__) + +# Reads the SDK serves for every agent that enables the extension, so the check changes nothing on the agent. +_READS = ((A2AAgent.EXT_MCP_CONFIG, "list"), (A2AAgent.EXT_AGENT_CONFIG, "get")) +_REQUEST_TIMEOUT_SECONDS = 30 + + +class VerifyA2AControlTokenStep(TaskStep): + type: ClassVar[str] = "verify_a2a_control_token" + step_role = StepRole.GRADER + entity_refs = (EntityRef.agent("a2a_agent_id", version_field="a2a_agent_version"),) + + def __init__(self, id: str, version: Optional[int], a2a_agent_id: str, a2a_agent_version: Optional[int] = None, + depends_on: Optional[list[TaskStepDependency]] = None, fail_task_on_error: bool = True): + super().__init__(id, version, depends_on=depends_on, fail_task_on_error=fail_task_on_error) + self.a2a_agent_id = a2a_agent_id + self.a2a_agent_version = a2a_agent_version + + def to_dict(self) -> dict: + return {**super().to_dict(), "a2a_agent_id": self.a2a_agent_id, "a2a_agent_version": self.a2a_agent_version} + + @classmethod + def from_dict(cls, data: dict) -> "VerifyA2AControlTokenStep": + return cls(**cls._base_from_dict(data), a2a_agent_id=data["a2a_agent_id"], + a2a_agent_version=data.get("a2a_agent_version")) + + async def execute(self, context: TaskStepContext) -> TaskStepContext: + deployed = next((a for a in context.deployed_agents if a.agent_name == TaskStep.DEFAULT_AGENT_NAME), None) + if deployed is None: + raise RuntimeError("VerifyA2AControlTokenStep: no deployed default-agent in context") + card = deployed.a2a_card or {} + route = next((path for uri, name in _READS + if (path := A2AAgent.operation(A2AAgent.find_extension(card, uri), name)[1]) is not None), None) + entry: dict = {"route": route, "refuses_without_token": False, "accepts_with_token": False} + if route is not None and deployed.control_token: + url = (deployed.a2a_url or deployed.api_url) + route + try: + async with httpx.AsyncClient() as client: + without = await client.get(url, timeout=_REQUEST_TIMEOUT_SECONDS) + with_token = await client.get(url, headers=deployed.control_headers, timeout=_REQUEST_TIMEOUT_SECONDS) + entry["refuses_without_token"] = without.status_code == 401 + entry["accepts_with_token"] = with_token.status_code != 401 + except httpx.HTTPError as e: + logger.warning(f"VerifyA2AControlTokenStep: {url} unreachable: {e}") + entry["passed"] = entry["refuses_without_token"] and entry["accepts_with_token"] + context.metadata.setdefault("verifications", {})["a2a_control_token"] = entry + logger.info(f"control token validation: {entry}") + return context diff --git a/src/agent_env/task_step/task_steps/install_agent.py b/src/agent_env/task_step/task_steps/install_agent.py index c72b74d03..4c0a92d85 100644 --- a/src/agent_env/task_step/task_steps/install_agent.py +++ b/src/agent_env/task_step/task_steps/install_agent.py @@ -4,10 +4,15 @@ varies per install — container name, work dir, agent build context, A2A port, and config-sourced creds. The runner resolves each declared `required_params` entry via the registry below, `shlex.quote`s the value, and `cmd.format(**resolved)`s -each command before exec. No host env vars are exported. +each command before exec. To add a new param: register it in `_build_param_resolvers` (and document what it returns); the agent's extension declares it in `required_params` to opt in. + +`optional_params` lists what an install takes only from a runner that has it, as an +environment variable of every install command rather than a placeholder, so a runner +that doesn't know it still installs the agent: `control_token` is exported as +`AGENTENV_CONTROL_TOKEN`, the token the agent's extension routes then take. """ from __future__ import annotations @@ -37,6 +42,7 @@ from agent_env.task_step.context import DeployedAgent, StepContextError, TaskStepContext from agent_env.entity.refs import EntityRef from agent_env.task_step.task_step import TaskStep, TaskStepDependency +from agentenv_protocol.types import CONTROL_TOKEN_ENV logger = logging.getLogger(__name__) @@ -44,6 +50,8 @@ INSTALL_COMMANDS_HOST_KEY = "install_commands_host" REQUIRED_PARAMS_KEY = "required_params" REQUIRED_PARAMS_HOST_KEY = "required_params_host" +OPTIONAL_PARAMS_KEY = "optional_params" +OPTIONAL_PARAMS_HOST_KEY = "optional_params_host" A2A_PORT_KEY = "a2a_port" WORKDIR_HOST_KEY = "workdir_host" USER_HOST_KEY = "user_host" @@ -278,6 +286,7 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: install_commands = params.get(commands_key) a2a_port = self.a2a_port or params.get(A2A_PORT_KEY) required_params = params.get(REQUIRED_PARAMS_HOST_KEY if host_mode else REQUIRED_PARAMS_KEY) or [] + optional_params = params.get(OPTIONAL_PARAMS_HOST_KEY if host_mode else OPTIONAL_PARAMS_KEY) or [] if host_mode and not install_commands: raise RuntimeError( f"Agent {agent.id} v{agent.version} install/v1 params have no '{INSTALL_COMMANDS_HOST_KEY}'; " @@ -289,6 +298,8 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: raise RuntimeError(f"Agent {agent.id} v{agent.version} install/v1 params missing '{A2A_PORT_KEY}' (int) and the step has no a2a_port override") if not isinstance(required_params, list): raise RuntimeError(f"Agent {agent.id} v{agent.version} install/v1 params 'required_params' must be a list") + if not isinstance(optional_params, list): + raise RuntimeError(f"Agent {agent.id} v{agent.version} install/v1 params 'optional_params' must be a list") if not ds.tunnel_urls or str(a2a_port) not in ds.tunnel_urls: raise RuntimeError( @@ -340,6 +351,9 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: raise RuntimeError(f"Failed to resolve required_param {name!r}: {e}") from e resolved[name] = shlex.quote(raw) + control_token = new_control_token() + exported = f"export {CONTROL_TOKEN_ENV}={shlex.quote(control_token)}\n" if "control_token" in optional_params else "" + target = "the VM host" if host_mode else f"container '{self.container_name}'" logger.info( f"Running {len(install_commands)} install command(s) against {target} " @@ -355,14 +369,14 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: ) # The template, not the command: resolved params carry the model key and headers. logger.info(f" [{i}/{len(install_commands)}] {cmd.splitlines()[0][:140]}") - await sandbox.exec_script(formatted) + await sandbox.exec_script(exported + formatted) if not host_mode: # copied into the container; a host install may run from it await sandbox.exec_script(f"rm -rf {shlex.quote(work_dir)}") agent_card = await self._wait_for_agent_card(a2a_url) logger.info(f"Agent '{self.agent_name}' reachable at {a2a_url} (card name={agent_card.get('name')})") - deployed = self._register_instance(agent, a2a_url, ds, agent_card, new_control_token()) + deployed = self._register_instance(agent, a2a_url, ds, agent_card, control_token) context.deployed_agents.append(DeployedAgent( agent_name=self.agent_name, diff --git a/tst/integration/agent/a2a_agent/agent_triggers_e2e_test.py b/tst/integration/agent/a2a_agent/agent_triggers_e2e_test.py index f8dd27389..2270a1024 100644 --- a/tst/integration/agent/a2a_agent/agent_triggers_e2e_test.py +++ b/tst/integration/agent/a2a_agent/agent_triggers_e2e_test.py @@ -84,8 +84,12 @@ async def test_agent_triggers_e2e(agent): triggers_url = deployed.a2a_url + endpoint decide_url = deployed.a2a_url + methods["decide"]["endpoint"] - async with httpx.AsyncClient(timeout=30) as client: - # 2. Register the full script (every condition type + both actions). + # 2. The extension routes take the agent's control token: a call without it is refused before it runs. + async with httpx.AsyncClient(timeout=30) as anonymous: + assert (await anonymous.post(triggers_url, json=_SCRIPT)).status_code == 401 + + async with httpx.AsyncClient(timeout=30, headers=deployed.control_headers) as client: + # 3. Register the full script (every condition type + both actions). resp = await client.post(triggers_url, json=_SCRIPT) resp.raise_for_status() body = resp.json() @@ -93,7 +97,7 @@ async def test_agent_triggers_e2e(agent): assert set(body["added"]) == _SCRIPT_IDS assert set(body["all"]) >= _SCRIPT_IDS - # 3. Fail-loud: an unknown when.type rejects the whole batch (HTTP 400). + # 4. Fail-loud: an unknown when.type rejects the whole batch (HTTP 400). bad = await client.post(triggers_url, json={"triggers": [ {"when": {"type": "bogus"}, "actions": [{"type": "say", "text": "x"}]}]}) assert bad.status_code == 400 @@ -108,7 +112,7 @@ async def decide(turn, message="", env=None, ctx="default"): r.raise_for_status() return r.json() - # 4. Deterministic firing sequence on context c1 (step -> conversational -> env_trigger -> all/end). + # 5. Deterministic firing sequence on context c1 (step -> conversational -> env_trigger -> all/end). r = await decide(1, "hello", ctx="c1") assert r["fired"] == ["open"] and r["done"] is False assert r["parts"] == [{"kind": "text", "text": "[PM]: Look into LeapBlock."}] @@ -123,25 +127,25 @@ async def decide(turn, message="", env=None, ctx="default"): assert r["fired"] == ["accept"] and r["done"] is True # all -> say + end assert "sending to Arthur" in r["parts"][0]["text"] - # 5. Turn-regression reset: replaying turn 1 clears c1's fired-set -> `open` re-fires (retry-safe). + # 6. Turn-regression reset: replaying turn 1 clears c1's fired-set -> `open` re-fires (retry-safe). r = await decide(1, "hello", ctx="c1") assert r["fired"] == ["open"] - # 6. once:false recurrence + the step branch of `any` on a fresh context. + # 7. once:false recurrence + the step branch of `any` on a fresh context. r = await decide(6, ctx="c2") assert r["fired"] == ["nudge"] and r["done"] is False # any[step >= 6] r = await decide(7, ctx="c2") assert r["fired"] == ["nudge"] # once:false -> fires again - # 7. The conversational branch of `any` (fires on "stuck"). + # 8. The conversational branch of `any` (fires on "stuck"). r = await decide(2, "I am stuck", ctx="c3") assert "nudge" in r["fired"] - # 8. decide validates its turn (non-positive -> 400). + # 9. decide validates its turn (non-positive -> 400). bad_turn = await client.post(decide_url, json={"turn": 0}) assert bad_turn.status_code == 400 - # 9. State read-back: config + trigger summary + firing log. + # 10. State read-back: config + trigger summary + firing log. state = (await client.get(triggers_url)).json() summary = {t["id"]: t for t in state["triggers"]} assert _SCRIPT_IDS <= set(summary) @@ -155,13 +159,14 @@ async def decide(turn, message="", env=None, ctx="default"): fired_ids = {e["trigger_id"] for e in state["firing_log"] if e["kind"] == "fired"} assert {"open", "answer-format", "re-sweep", "accept", "nudge"} <= fired_ids - # 10. The real RegisterAgentTriggersStep drives registration against the live agent's card. + # 11. The real RegisterAgentTriggersStep drives registration against the live agent's card. da = DeployedAgent( agent_name="stakeholder", api_url=deployed.a2a_url, a2a_url=deployed.a2a_url, a2a_card=deployed.agent_card, sandbox_id=deployed.sandbox_id, + control_token=deployed.control_token, ) context = TaskStepContext(deployed_agents=[da]) step = RegisterAgentTriggersStep( @@ -174,6 +179,6 @@ async def decide(turn, message="", env=None, ctx="default"): assert regs[-1]["agent_name"] == "stakeholder" assert "step-reg" in regs[-1]["added"] - async with httpx.AsyncClient(timeout=30) as client: + async with httpx.AsyncClient(timeout=30, headers=deployed.control_headers) as client: state = (await client.get(triggers_url)).json() assert "step-reg" in {t["id"] for t in state["triggers"]} diff --git a/tst/integration/agent/proxy_container_install_test.py b/tst/integration/agent/proxy_container_install_test.py index 58d90fa61..60649635e 100644 --- a/tst/integration/agent/proxy_container_install_test.py +++ b/tst/integration/agent/proxy_container_install_test.py @@ -1,7 +1,9 @@ """The proxy's folder installed into a running container by its own install.sh, as install_agent installs it there. It brings its own Python and serves; its bash runs commands with bash, or with sh in a container that has only sh (Alpine, -musl), and says which. The container installs this checkout's protocol, so the test covers the code beside it.""" +musl), and says which. The container installs this checkout's protocol, so the test covers the code beside it, and its +extension routes take the control token the install was handed, as install_agent hands it.""" +import os import shutil import subprocess import time @@ -11,6 +13,8 @@ import httpx import pytest +from agentenv_protocol import CONTROL_TOKEN_ENV +from agentenv_protocol.client import control_token_headers import agent_env @@ -20,6 +24,7 @@ PROTOCOL_DIR = Path(agent_env.__file__).parents[2] / "packages" / "agentenv-protocol" PORT = 8000 TOKEN = "t" * 32 +CONTROL_TOKEN = "c" * 32 @pytest.fixture(params=[("alpine:3.20", "sh"), ("debian:12-slim", "bash")], ids=["sh-only", "with-bash"]) @@ -46,10 +51,13 @@ def test_installed_into_a_container_the_proxy_serves_and_its_bash_runs_the_shell (folder / "requirements.txt").write_text("agentenv-framework-protocol[agent] @ file:///tmp/protocol\n") subprocess.run(["docker", "cp", f"{PROTOCOL_DIR}/.", f"{name}:/tmp/protocol"], check=True, capture_output=True) - subprocess.run(["bash", str(folder / "install.sh"), "container", name, str(PORT)], check=True) + subprocess.run(["bash", str(folder / "install.sh"), "container", name, str(PORT)], check=True, + env={**os.environ, CONTROL_TOKEN_ENV: CONTROL_TOKEN}) - with httpx.Client(base_url=f"http://{_published(name)}", timeout=30) as client: + base_url = f"http://{_published(name)}" + with httpx.Client(base_url=base_url, timeout=30, headers=control_token_headers(CONTROL_TOKEN)) as client: _serving(client) + assert httpx.post(f"{base_url}/ext/proxy/claim", json={"token": TOKEN}, timeout=30).status_code == 401 assert client.post("/ext/proxy/claim", json={"token": TOKEN}).status_code == 200 task_id = _send(client, "go") tools = _proxy(client, "tools", task_id=task_id).json()["tools"] diff --git a/tst/integration/cli/run_bundle_browser_use_test.py b/tst/integration/cli/run_bundle_browser_use_test.py index 5f7d3309e..bd6339faf 100644 --- a/tst/integration/cli/run_bundle_browser_use_test.py +++ b/tst/integration/cli/run_bundle_browser_use_test.py @@ -117,12 +117,13 @@ async def steps(context): sandbox_type="local").execute(context) (env,), (agent,) = context.deployed_envs, context.deployed_agents base_url = agent.a2a_url - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}, headers=agent.control_headers) outcomes["none"] = await _send(base_url, PROMPT) outcomes["none_asked"] = len(endpoint.completions()) await BrowserConnectCdpTaskStep(id="connect", version=None, env_id=BROWSER).execute(context) - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"connect_by": "http"}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"connect_by": "http"}, + headers=agent.control_headers) outcomes["http"] = await _send(base_url, PROMPT, context_id="kept") asked = len(endpoint.completions()) outcomes["again"] = await _send(base_url, AGAIN, context_id="kept") @@ -130,14 +131,15 @@ async def steps(context): forged = reachable_url(env.environment_url.rstrip("/"), from_sandbox_type=env.sandbox_type, to_sandbox_type=agent.sandbox_type).rstrip("/") + f"/svc/chromium/cdp/{uuid.uuid4().hex}" - async with httpx.AsyncClient(timeout=60) as client: + async with httpx.AsyncClient(timeout=60, headers=agent.control_headers) as client: added = await client.post(f"{base_url}/ext/cdp-config", json={ "name": "forged", "http_url": f"{forged}/", "ws_url": "ws" + forged.removeprefix("http") + "/devtools/browser"}) added.raise_for_status() for connect_by in ("ws", "http"): await protocol.post_agent_config(f"{base_url}/ext/agent-config", - {"browser": "forged", "connect_by": connect_by}) + {"browser": "forged", "connect_by": connect_by}, + headers=agent.control_headers) outcomes[f"forged_{connect_by}"] = await _send(base_url, PROMPT) written = CliRunner().invoke(cli, ["run", str(_writes_the_agent_and_browser(state))]) diff --git a/tst/integration/cli/run_bundle_claude_code_test.py b/tst/integration/cli/run_bundle_claude_code_test.py index c4f59b81e..6f9baeddc 100644 --- a/tst/integration/cli/run_bundle_claude_code_test.py +++ b/tst/integration/cli/run_bundle_claude_code_test.py @@ -204,7 +204,8 @@ async def _send_project_id(step, context): return negotiated = A2AAgent.negotiate_agent_config(agent.a2a_card or {}, {"project_id": project_id}) assert negotiated and "project_id" in negotiated.fields, "the card doesn't take project_id over agent-config" - await protocol.post_agent_config((agent.a2a_url or agent.api_url) + negotiated.endpoint, negotiated.fields) + await protocol.post_agent_config((agent.a2a_url or agent.api_url) + negotiated.endpoint, negotiated.fields, + headers=agent.control_headers) def test_a_project_id_posted_over_agent_config_attributes_every_model_call_to_the_project(state, endpoint): diff --git a/tst/integration/cli/run_bundle_openhands_test.py b/tst/integration/cli/run_bundle_openhands_test.py index 1ecd21167..e1e260e49 100644 --- a/tst/integration/cli/run_bundle_openhands_test.py +++ b/tst/integration/cli/run_bundle_openhands_test.py @@ -186,8 +186,8 @@ async def steps(context): await DeployAgentTaskStep(id="agent", version=None, sandbox_type="local", a2a_agent_id=AGENT).execute(context) (agent,) = context.deployed_agents base_url = agent.a2a_url or agent.api_url - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}) - async with httpx.AsyncClient() as client: + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}, headers=agent.control_headers) + async with httpx.AsyncClient(headers=agent.control_headers) as client: registered = await client.post(f"{base_url}/ext/mcp-config", json={ "name": "probe", "url": f"{endpoint.url}/mcp-probe", "headers": {"X-Probe": "${LITELLM_API_KEY}"}}) registered.raise_for_status() @@ -208,7 +208,7 @@ async def steps(context): await DeployAgentTaskStep(id="agent", version=None, sandbox_type="local", a2a_agent_id=AGENT).execute(context) (agent,) = context.deployed_agents base_url = agent.a2a_url or agent.api_url - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}, headers=agent.control_headers) outcomes["first"] = await _send(base_url, "ctx", "Say pong.") subprocess.run(["docker", "exec", f"agent-{agent.sandbox_id}", "sh", "-c", "for f in ~/.openhands-a2a/conversations/*/base_state.json; do printf '{' > \"$f\"; done"], @@ -253,7 +253,7 @@ async def steps(context): (agent,) = context.deployed_agents base_url = agent.a2a_url or agent.api_url endpoint.respond = respond - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL, "timeout_seconds": 5}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL, "timeout_seconds": 5}, headers=agent.control_headers) endpoint.fail_next(Fault("stall", seconds=15)) started = time.monotonic() outcomes["timed_out"] = await _send(base_url, "ctx", "Say pong.") @@ -261,7 +261,7 @@ async def steps(context): calls = len(endpoint.completions()) await asyncio.sleep(25) # past the stall, so a run left going would have called the endpoint again outcomes["calls_after_the_timeout"] = len(endpoint.completions()) - calls - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 120}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 120}, headers=agent.control_headers) outcomes["after"] = await _send(base_url, "ctx", "Say pong again.") _with_agent(state, steps) @@ -295,11 +295,11 @@ async def steps(context): (agent,) = context.deployed_agents base_url = agent.a2a_url or agent.api_url endpoint.respond = respond - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL, "timeout_seconds": 5}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL, "timeout_seconds": 5}, headers=agent.control_headers) started = time.monotonic() outcomes["timed_out"] = await _send(base_url, "ctx", "Sleep.") outcomes["seconds"] = time.monotonic() - started - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 120}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 120}, headers=agent.control_headers) outcomes["after"] = await _send(base_url, "ctx", "List the processes.") _with_agent(state, steps) diff --git a/tst/integration/cli/run_bundle_pydantic_ai_test.py b/tst/integration/cli/run_bundle_pydantic_ai_test.py index 7953f9dda..d57c62aa2 100644 --- a/tst/integration/cli/run_bundle_pydantic_ai_test.py +++ b/tst/integration/cli/run_bundle_pydantic_ai_test.py @@ -105,12 +105,12 @@ async def run(): asyncio.run(run()) -async def _deployed(context) -> str: +async def _deployed(context) -> tuple[str, dict[str, str]]: await DeployAgentTaskStep(id="agent", version=None, sandbox_type="local", a2a_agent_id=AGENT).execute(context) (agent,) = context.deployed_agents base_url = agent.a2a_url or agent.api_url - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}) - return base_url + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}, headers=agent.control_headers) + return base_url, agent.control_headers async def _send(base_url: str, context_id: str, text: str) -> dict: @@ -187,7 +187,7 @@ def respond(body): endpoint.respond = answer("pong") async def steps(context): - base_url = await _deployed(context) + base_url, headers = await _deployed(context) endpoint.respond = respond outcomes["first"] = await _send(base_url, "ctx", "Say pong.") outcomes["second"] = await _send(base_url, "ctx", "Look at your saved conversation.") @@ -228,13 +228,13 @@ def respond(body): endpoint.respond = answer("pong") async def steps(context): - base_url = await _deployed(context) + base_url, headers = await _deployed(context) endpoint.respond = respond - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 5}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 5}, headers=headers) started = time.monotonic() outcomes["timed_out"] = await _send(base_url, "ctx", "Sleep.") outcomes["seconds"] = time.monotonic() - started - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 120}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 120}, headers=headers) outcomes["after"] = await _send(base_url, "ctx", "List the processes.") _with_agent(state, steps) diff --git a/tst/integration/cli/run_role_models_test.py b/tst/integration/cli/run_role_models_test.py index abfdae4d4..bed763486 100644 --- a/tst/integration/cli/run_role_models_test.py +++ b/tst/integration/cli/run_role_models_test.py @@ -110,8 +110,9 @@ def _reset(): reset() -def _configured_model(url: str) -> str | None: - return httpx.get(f"{url}/ext/agent-config", timeout=30).json()["config"].get("model") +def _configured_model(agent) -> str | None: + return httpx.get(f"{agent.a2a_url}/ext/agent-config", headers=agent.control_headers, + timeout=30).json()["config"].get("model") def test_each_role_runs_on_the_model_its_flag_gives_and_a_rerun_on_others_writes_nothing(bundle): @@ -122,8 +123,8 @@ def test_each_role_runs_on_the_model_its_flag_gives_and_a_rerun_on_others_writes try: [run] = result.runs assert run.outcome is Outcome.PASSED, run.error or run.failed_steps - agents = {agent.agent_name: agent.a2a_url for agent in run.context.deployed_agents} - assert {name: _configured_model(url) for name, url in agents.items()} == { + agents = {agent.agent_name: agent for agent in run.context.deployed_agents} + assert {name: _configured_model(agent) for name, agent in agents.items()} == { "solver": "flag-solver", "user-sim": "flag-user"} assert run.models == {"solver": {"prompt": "flag-solver"}, "user simulator": {"prompt": "flag-user"}, "judge": {"judge": "openai/flag-judge"}} diff --git a/tst/integration/env/task_step/task_steps_test.py b/tst/integration/env/task_step/task_steps_test.py index 54c8a5614..864f02f2e 100644 --- a/tst/integration/env/task_step/task_steps_test.py +++ b/tst/integration/env/task_step/task_steps_test.py @@ -1029,7 +1029,7 @@ async def test_prompt_agent_model_params_reaches_agent(sandbox_provider, multi_e # prompt_agent POSTed the negotiated model_params to /ext/agent-config; read it # back — it must be present (received) but redacted (never echo provider secrets). async with httpx.AsyncClient(timeout=30) as client: - agent_cfg = (await client.get(f"{target_url}/ext/agent-config")).json()["config"] + agent_cfg = (await client.get(f"{target_url}/ext/agent-config", headers=agent.control_headers)).json()["config"] assert agent_cfg.get("model_params") == "***", \ f"expected received-and-redacted model_params, got {agent_cfg}" logger.info("model_params reached the agent and read back redacted") diff --git a/tst/unit/a2a_agent/deploy_cleanup_test.py b/tst/unit/a2a_agent/deploy_cleanup_test.py index 131e6ed91..1a68c24a2 100644 --- a/tst/unit/a2a_agent/deploy_cleanup_test.py +++ b/tst/unit/a2a_agent/deploy_cleanup_test.py @@ -51,9 +51,14 @@ async def wait_for_card(self, url): @pytest.mark.asyncio -async def test_each_deploy_is_recorded_with_a_control_token_of_its_own(monkeypatch, local_stores): +async def test_each_deploy_is_recorded_with_a_control_token_of_its_own_which_the_agent_is_handed( + monkeypatch, local_stores, +): + handed: list[str | None] = [] + class _Provider(SandboxProvider): - async def create_sandbox(self, **_): + async def create_sandbox(self, *, env, **_): + handed.append(env.get("AGENTENV_CONTROL_TOKEN")) return _Sandbox() async def card(self, url): @@ -62,11 +67,12 @@ async def card(self, url): monkeypatch.setattr(sandbox_provider, "build_sandbox_provider", lambda name: _Provider()) monkeypatch.setattr(A2AAgent, "_wait_for_agent_card", card) agent = A2AAgent(id="solver", version=1, docker_image_artifact=DockerImageArtifact(id="img", description="d", image_name="img")) - env_vars = {"LITELLM_API_KEY": "k", "LITELLM_BASE_URL": "http://llm"} + env_vars = {"LITELLM_API_KEY": "k", "LITELLM_BASE_URL": "http://llm", "AGENTENV_CONTROL_TOKEN": "caller-chosen"} first = await agent.deploy(sandbox_type="fake", env_vars=env_vars) second = await agent.deploy(sandbox_type="fake", env_vars=env_vars) assert first.control_token and second.control_token and first.control_token != second.control_token + assert handed == [first.control_token, second.control_token] assert first.control_headers == {"AgentEnv-Control-Token": first.control_token} assert get_a2a_agent_instance_store().get(first.instance_id).control_token == first.control_token diff --git a/tst/unit/a2a_agent/protocol_test.py b/tst/unit/a2a_agent/protocol_test.py index 4c2d803bd..33548d8c5 100644 --- a/tst/unit/a2a_agent/protocol_test.py +++ b/tst/unit/a2a_agent/protocol_test.py @@ -98,6 +98,26 @@ def test_extension_http_error_for_a_request_without_grants_keeps_the_body(): ) +def test_a_refused_control_token_is_named_and_logged_without_the_body(caplog): + response = httpx.Response( + 401, + json={"detail": "this route takes the agent's control token"}, + request=httpx.Request("GET", "https://agent.test/ext/trajectory"), + ) + + with caplog.at_level(logging.WARNING, logger=protocol.__name__), pytest.raises(httpx.HTTPStatusError) as raised: + raise_for_extension_status(response, operation="trajectory read", include_body=True) + + assert str(raised.value) == ( + 'trajectory read failed with HTTP 401: {"detail":"this route takes the agent\'s control token"}' + " (the agent refused its control token: the record it was sent from has none, or another deployment's)" + ) + assert [record.getMessage() for record in caplog.records] == [ + "trajectory read failed with HTTP 401" + " (the agent refused its control token: the record it was sent from has none, or another deployment's)" + ] + + def test_sdk_success_round_trips_through_platform_parser(): result = ( TaskResult.builder() diff --git a/tst/unit/agents/codex/test_card_contract.py b/tst/unit/agents/codex/test_card_contract.py index 4150411d9..a5c20e216 100644 --- a/tst/unit/agents/codex/test_card_contract.py +++ b/tst/unit/agents/codex/test_card_contract.py @@ -169,9 +169,10 @@ def test_request_and_response_contracts(codex): def test_install_params(codex): params = _extensions(codex)["urn:agentenv:install/v1"]["params"] assert list(params) == [ - "install_commands", "a2a_port", "required_params", "install_commands_host", "required_params_host", - "workdir_host", "user_host", + "install_commands", "a2a_port", "optional_params", "required_params", "install_commands_host", + "optional_params_host", "required_params_host", "workdir_host", "user_host", ] + assert params["optional_params"] == params["optional_params_host"] == ["control_token"] assert params["a2a_port"] == 8000 endpoint = ["litellm_api_key", "litellm_base_url", "litellm_extra_headers", "trust_env"] assert params["required_params"] == ["container", "work_dir", "agent_ctx_tar", "a2a_port", *endpoint] diff --git a/tst/unit/agents/gemini/test_card_contract.py b/tst/unit/agents/gemini/test_card_contract.py index eea71acca..0202ac504 100644 --- a/tst/unit/agents/gemini/test_card_contract.py +++ b/tst/unit/agents/gemini/test_card_contract.py @@ -201,9 +201,10 @@ def test_request_and_response_contracts(app): def test_install_params(app): params = _extensions(app)["urn:agentenv:install/v1"]["params"] assert list(params) == [ - "install_commands", "required_params", "install_commands_host", "a2a_port", "required_params_host", - "workdir_host", "user_host", + "install_commands", "optional_params", "required_params", "install_commands_host", "a2a_port", + "optional_params_host", "required_params_host", "workdir_host", "user_host", ] + assert params["optional_params"] == params["optional_params_host"] == ["control_token"] assert params["a2a_port"] == 8000 endpoint = ["litellm_api_key", "litellm_base_url", "litellm_extra_headers", "trust_env"] assert params["required_params"] == ["container", "work_dir", "agent_ctx_tar", "a2a_port", *endpoint] diff --git a/tst/unit/agents/openhands/test_openhands_agent.py b/tst/unit/agents/openhands/test_openhands_agent.py index ac0505bce..aa911af7d 100644 --- a/tst/unit/agents/openhands/test_openhands_agent.py +++ b/tst/unit/agents/openhands/test_openhands_agent.py @@ -656,7 +656,10 @@ def test_install_extension_is_declared_on_the_card(client: TestClient) -> None: for command in install["install_commands"]] assert formatted[-1].endswith("c sh /opt/openhands-a2a/start.sh") assert all("sk-secret" not in command.splitlines()[0] for command in formatted) - assert "LITELLM_API_KEY='sk-secret'" in formatted[-2].splitlines() + [env_file] = [command for command in formatted if "LITELLM_API_KEY" in command] + assert "LITELLM_API_KEY='sk-secret'" in env_file.splitlines() + assert install["optional_params"] == ["control_token"] + assert formatted[-2].splitlines()[1] == "AGENTENV_CONTROL_TOKEN=${AGENTENV_CONTROL_TOKEN:-}" def test_the_card_advertises_the_extensions_agent_env_validates(client: TestClient) -> None: diff --git a/tst/unit/agents/pi/test_pi_agent.py b/tst/unit/agents/pi/test_pi_agent.py index d8ee8027c..641c5bd3a 100644 --- a/tst/unit/agents/pi/test_pi_agent.py +++ b/tst/unit/agents/pi/test_pi_agent.py @@ -740,7 +740,10 @@ def test_install_extension_is_declared_on_the_card(client: TestClient) -> None: litellm_base_url="u") for command in install["install_commands"]] assert formatted[-1].endswith("c sh /opt/pi-a2a/start.sh") assert all("sk-secret" not in command.splitlines()[0] for command in formatted) - assert "LITELLM_API_KEY='sk-secret'" in formatted[-2].splitlines() + [env_file] = [command for command in formatted if "LITELLM_API_KEY" in command] + assert "LITELLM_API_KEY='sk-secret'" in env_file.splitlines() + assert install["optional_params"] == ["control_token"] + assert formatted[-2].splitlines()[1] == "AGENTENV_CONTROL_TOKEN=${AGENTENV_CONTROL_TOKEN:-}" assert all(command.startswith("$(sudo -n true 2>/dev/null && echo sudo) docker ") for command in formatted) diff --git a/tst/unit/agents/pydantic_ai/test_pydantic_ai_agent.py b/tst/unit/agents/pydantic_ai/test_pydantic_ai_agent.py index 6324cb06a..39313b428 100644 --- a/tst/unit/agents/pydantic_ai/test_pydantic_ai_agent.py +++ b/tst/unit/agents/pydantic_ai/test_pydantic_ai_agent.py @@ -634,7 +634,10 @@ def test_install_extension_is_declared_on_the_card(client: TestClient) -> None: for command in install["install_commands"]] assert formatted[-1].endswith("c sh /opt/pydantic-ai-a2a/start.sh") assert all("sk-secret" not in command.splitlines()[0] for command in formatted) - assert "LITELLM_API_KEY='sk-secret'" in formatted[-2].splitlines() + [env_file] = [command for command in formatted if "LITELLM_API_KEY" in command] + assert "LITELLM_API_KEY='sk-secret'" in env_file.splitlines() + assert install["optional_params"] == ["control_token"] + assert formatted[-2].splitlines()[1] == "AGENTENV_CONTROL_TOKEN=${AGENTENV_CONTROL_TOKEN:-}" def test_the_installed_agent_starts_with_the_endpoint_and_trust_lines_install_wrote(tmp_path: Path) -> None: diff --git a/tst/unit/agents/test_installed_control_token.py b/tst/unit/agents/test_installed_control_token.py new file mode 100644 index 000000000..90f03abf4 --- /dev/null +++ b/tst/unit/agents/test_installed_control_token.py @@ -0,0 +1,39 @@ +"""Every bundled agent that installs through install/v1 takes its control token from the installer: its declaration +lists ``control_token`` in ``optional_params`` (and ``optional_params_host`` for a host install), and its install reads +the protocol's ``CONTROL_TOKEN_ENV``, which the installer exports. An agent whose install spelled it otherwise would +install fine and serve its extension routes open.""" + +import re +from pathlib import Path + +import pytest +from agentenv_protocol import CONTROL_TOKEN_ENV + +import agent_env + +AGENTS = Path(agent_env.__file__).parent / "agents" / "agents" + + +def _sources(agent: str) -> dict[str, str]: + return {path.name: path.read_text() for path in (AGENTS / agent).iterdir() if path.suffix in (".py", ".sh")} + + +INSTALLABLE = sorted(path.name for path in AGENTS.iterdir() + if path.is_dir() and any("required_params=" in src for src in _sources(path.name).values())) + + +def test_the_bundled_agents_that_install_are_the_ones_this_test_knows(): + assert INSTALLABLE == ["claude-code", "codex", "gemini", "letta-code", "opencode", "openhands", "pi", "proxy", + "pydantic-ai"] + + +@pytest.mark.parametrize("agent", INSTALLABLE) +def test_an_installed_agent_takes_its_control_token_under_the_protocols_variable(agent): + sources = _sources(agent) + (declaration,) = [src for src in sources.values() if "required_params=" in src] + + assert 'optional_params=["control_token"]' in declaration + if "required_params_host=" in declaration: + assert 'optional_params_host=["control_token"]' in declaration + # The installer exports the variable; the install reads it, as ${...} in a shell (${{...}} in a format template). + assert any(re.search(r"\$\{+" + CONTROL_TOKEN_ENV + r"\b", src) for src in sources.values()) diff --git a/tst/unit/task_step/install_agent_test.py b/tst/unit/task_step/install_agent_test.py index 0eef2a44c..e3f22119d 100644 --- a/tst/unit/task_step/install_agent_test.py +++ b/tst/unit/task_step/install_agent_test.py @@ -161,7 +161,9 @@ def _resolved(value): @pytest.mark.asyncio -async def test_install_logs_show_the_command_template_not_the_model_key_or_headers(monkeypatch, caplog, local_stores): +async def test_install_logs_show_the_command_template_not_the_model_key_headers_or_control_token( + monkeypatch, caplog, local_stores, +): monkeypatch.setenv("LITELLM_BASE_URL", "http://localhost:4000/v1") monkeypatch.setenv("LITELLM_API_KEY", "sk-never-logged") monkeypatch.setattr(local_stores, "_model_cfg", ModelConfig(headers={"X-Bill-To": "org-never-logged"})) @@ -174,9 +176,12 @@ async def test_install_logs_show_the_command_template_not_the_model_key_or_heade step = InstallAgentTaskStep(id="i", version=None, sandbox_name="vm", a2a_agent_id="agent-x", agent_name="solver") monkeypatch.setattr(step, "_extract_install_extension", _resolved({"params": { "install_commands_host": ["start --key {litellm_api_key} --headers {litellm_extra_headers}"], - "required_params_host": ["litellm_api_key", "litellm_extra_headers"], "a2a_port": 8000}})) + "required_params_host": ["litellm_api_key", "litellm_extra_headers"], + "optional_params_host": ["control_token", "a-param-this-runner-doesnt-know"], "a2a_port": 8000}})) monkeypatch.setattr(step, "_wait_for_agent_card", _resolved({})) - monkeypatch.setattr(step, "_register_instance", lambda *args: SimpleNamespace(instance_id="solver-1", control_token=None)) + recorded: list[str] = [] + monkeypatch.setattr(step, "_register_instance", lambda agent, url, ds, card, token: recorded.append(token) + or SimpleNamespace(instance_id="solver-1", control_token=token)) context = TaskStepContext(deployed_sandboxes=[DeployedSandbox( sandbox_name="vm", sandbox_id="sb-1", sandbox_mode="vm", sandbox_type="local", tunnel_urls={"8000": "http://127.0.0.1:8000"})]) @@ -184,10 +189,12 @@ async def test_install_logs_show_the_command_template_not_the_model_key_or_heade with caplog.at_level(logging.INFO, logger="agent_env.task_step.task_steps.install_agent"): await step.execute(context) - [command] = [s for s in sandbox.scripts if s.startswith("start ")] - assert "sk-never-logged" in command and "org-never-logged" in command + [token] = recorded + [script] = [s for s in sandbox.scripts if "start " in s] + assert script.startswith(f"export AGENTENV_CONTROL_TOKEN={token}\nstart --key sk-never-logged --headers ") + assert "org-never-logged" in script and context.deployed_agents[0].control_token == token assert "start --key {litellm_api_key} --headers {litellm_extra_headers}" in caplog.text - assert "never-logged" not in caplog.text + assert "never-logged" not in caplog.text and token not in caplog.text @pytest.mark.asyncio diff --git a/tst/unit/task_step/test_verify_a2a_control_token.py b/tst/unit/task_step/test_verify_a2a_control_token.py new file mode 100644 index 000000000..7d365b272 --- /dev/null +++ b/tst/unit/task_step/test_verify_a2a_control_token.py @@ -0,0 +1,67 @@ +"""The validator's control-token check: a read the SDK serves on every agent, mcp-config's list, is called without the +agent's token and with it; the agent passes when the first is refused with a 401 and the second is not.""" + +import httpx +import pytest + +from agent_env.a2a_agent import A2AAgent +from agent_env.task_step.context import DeployedAgent, TaskStepContext +from agent_env.task_step.task_steps.a2a_agent_validator import verify_a2a_control_token as module +from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_control_token import VerifyA2AControlTokenStep + +_CARD = {"capabilities": {"extensions": [{"uri": A2AAgent.EXT_MCP_CONFIG, "params": {"endpoint": "/ext/mcp-config"}}]}} + + +def _serve(monkeypatch, *, guarded: bool) -> list[tuple[str, str | None]]: + calls: list[tuple[str, str | None]] = [] + + def handle(request: httpx.Request) -> httpx.Response: + token = request.headers.get("AgentEnv-Control-Token") + calls.append((request.url.path, token)) + if guarded and token != "s3cret": + return httpx.Response(401, json={"detail": "this route takes the agent's control token"}) + return httpx.Response(200, json={"mcp_servers": {}}) + + real_client = httpx.AsyncClient + monkeypatch.setattr(module.httpx, "AsyncClient", + lambda **kw: real_client(transport=httpx.MockTransport(handle), **kw)) + return calls + + +async def _check(card: dict = _CARD, token: str | None = "s3cret") -> dict: + context = TaskStepContext(deployed_agents=[DeployedAgent( + agent_name="default-agent", api_url="http://agent", a2a_url="http://agent", a2a_card=card, control_token=token)]) + step = VerifyA2AControlTokenStep(id="v", version=None, a2a_agent_id="agent-x") + return (await step.execute(context)).metadata["verifications"]["a2a_control_token"] + + +@pytest.mark.asyncio +async def test_an_agent_that_refuses_a_call_without_its_token_and_answers_one_with_it_passes(monkeypatch): + calls = _serve(monkeypatch, guarded=True) + + entry = await _check() + + assert entry == {"route": "/ext/mcp-config", "refuses_without_token": True, "accepts_with_token": True, + "passed": True} + assert calls == [("/ext/mcp-config", None), ("/ext/mcp-config", "s3cret")] + + +@pytest.mark.asyncio +async def test_an_agent_that_answers_without_its_token_fails(monkeypatch): + _serve(monkeypatch, guarded=False) + + entry = await _check() + + assert entry["refuses_without_token"] is False and entry["accepts_with_token"] is True + assert entry["passed"] is False + + +@pytest.mark.asyncio +async def test_an_agent_with_no_guarded_read_or_no_token_on_its_record_fails_without_a_call(monkeypatch): + calls = _serve(monkeypatch, guarded=True) + + no_read = await _check(card={}) + no_token = await _check(token=None) + + assert no_read["route"] is None and no_read["passed"] is False + assert no_token["passed"] is False and calls == []