From 0371357874c648c4c7df0efa2c8f2d6b3931b994 Mon Sep 17 00:00:00 2001 From: Alec Gutmanstein Date: Tue, 17 Nov 2026 12:34:30 -0500 Subject: [PATCH] feat(task_step)!: require entity_refs on step types; add step_ref_sites A step type that leaves entity_refs undeclared is refused at registration: a plugin is skipped with a failure note, a config impl fails with ConfigError. () declares a type that holds no ids. step_ref_sites reads a TaskStep's or a step dict's declared refs. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 8 +++-- src/agent_env/entity/refs.py | 3 +- src/agent_env/entity_refs.py | 6 ++-- src/agent_env/task_step/registry.py | 32 ++++++++++++++++++-- src/agent_env/task_step/task_step.py | 2 +- tst/installer/toys.py | 2 ++ tst/unit/entity_refs_import_test.py | 5 ++- tst/unit/plugins_test.py | 24 +++++++++++++++ tst/unit/task_step/test_config_task_steps.py | 26 ++++++++++++++++ tst/unit/task_step/test_entity_refs.py | 16 +++++++++- 10 files changed, 112 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 784e1ea05..691e753fc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -240,14 +240,16 @@ Out-of-tree code plugs in either through `config.toml`, as a `module:Class` poin `[state.providers.]`, `[explorer.plugins]`: one implementation each. - `[envs]`, `[artifacts]`, `[task_steps]` with `impls = ["module:Class", ...]`: extra classes for the registries. The identity is the class's `type` (a `ClassVar` on envs and steps, the Pydantic `type` - default on artifacts); a class that keeps the base default, collides with a registered type, or - leaves a method its base requires unimplemented fails at registry build with `ConfigError`. + default on artifacts); a class that keeps the base default, collides with a registered type, + leaves a method its base requires unimplemented, or is a step type that declares no `entity_refs` + (`()` when it holds no ids) fails at registry build with `ConfigError`. - For sandbox and state providers the table name must equal the `type` the provider produces, because that string is persisted and used to reconnect. - Entry points register the same kinds from an installed package, with the entry-point name as the registry key: `agent_env.envs`, `agent_env.artifacts`, `agent_env.task_steps`, `agent_env.sandbox_providers`, `agent_env.state_providers` and `agent_env.explorer_plugins`. A - plugin whose name clashes with a built-in is skipped, a name two plugins claim is left out and + plugin whose name clashes with a built-in is skipped, as is a step type that declares no + `entity_refs`; a name two plugins claim is left out and config cannot take it, and config that registers a plugin's name takes it over. `agent-env plugin check` reports each plugin that did not take effect. - Bundles install through `agent_env.bundles` entry points (` = ""`, the folder at diff --git a/src/agent_env/entity/refs.py b/src/agent_env/entity/refs.py index 4b6c359a6..3d8264e0b 100644 --- a/src/agent_env/entity/refs.py +++ b/src/agent_env/entity/refs.py @@ -18,7 +18,8 @@ class LoadArtifactTaskStep(TaskStep): Fields that name something else, such as another step's id, are left out. A step type's declarations are not inherited, so a subclass declares its own; ``toml_refs`` are, as ``from_toml`` -is. +is. A step type registers only once it declares ``entity_refs``, ``()`` if it holds no ids, and +``agent_env.task_step.registry.step_ref_sites`` reads a step's, whether it is a ``TaskStep`` or a step dict. A step's agent field left unset falls back to the configured default agent (``[agents] default_a2a_agent_id``), so a tool reading a step knows which agent it may deploy without being told (``default_agent_refs``). diff --git a/src/agent_env/entity_refs.py b/src/agent_env/entity_refs.py index 3c81027b1..dcbffc7e1 100644 --- a/src/agent_env/entity_refs.py +++ b/src/agent_env/entity_refs.py @@ -1,5 +1,7 @@ -"""Kept so imports of ``agent_env.entity_refs`` keep working; the declarations live in ``agent_env.entity.refs``.""" +"""Kept so imports of ``agent_env.entity_refs`` keep working; the declarations live in ``agent_env.entity.refs``, and +``step_ref_sites``, which reads a step's through the task-step registry, in ``agent_env.task_step.registry``.""" from agent_env.entity.refs import EntityKind, EntityRef, RefRole, RefSite, parse_toml_ref, ref_sites +from agent_env.task_step.registry import step_ref_sites -__all__ = ["EntityKind", "EntityRef", "RefRole", "RefSite", "parse_toml_ref", "ref_sites"] +__all__ = ["EntityKind", "EntityRef", "RefRole", "RefSite", "parse_toml_ref", "ref_sites", "step_ref_sites"] diff --git a/src/agent_env/task_step/registry.py b/src/agent_env/task_step/registry.py index c4b5c5b9d..a93bdbcb5 100644 --- a/src/agent_env/task_step/registry.py +++ b/src/agent_env/task_step/registry.py @@ -2,8 +2,9 @@ from __future__ import annotations -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, Any +from agent_env.entity.refs import RefSite, ref_sites from agent_env.plugins import _registration if TYPE_CHECKING: @@ -18,6 +19,12 @@ def _get_type(cls: type["TaskStep"]) -> str: return cls.type +def undeclared_refs(cls: type["TaskStep"]) -> str | None: + """Why ``cls`` can't register for want of an ``entity_refs`` declaration, if it can't: tools that read or + rewrite a step's ids can't see a type that declares nothing.""" + if cls.entity_refs is None: + return f"{cls.__qualname__} must declare entity_refs, () if it holds no ids" + return None def get_task_step_registry() -> dict[str, type["TaskStep"]]: @@ -26,6 +33,18 @@ def get_task_step_registry() -> dict[str, type["TaskStep"]]: return runtime.get_config().task_step_registry() +def step_ref_sites(step: Any) -> list[RefSite]: + """Every ref ``step``'s type declares that is present in it. ``step`` is a ``TaskStep`` or a step dict, + whose ``type`` is looked up in the registry. Raises ValueError for a type that isn't registered.""" + if isinstance(step, dict): + cls, data = get_task_step_registry().get(step.get("type")), step + if cls is None: + raise ValueError(f"unknown task step type {step.get('type')!r}") + else: + cls, data = type(step), step.to_dict() + return list(ref_sites(cls.entity_refs or (), data)) + + def _builtin_registry() -> dict[str, type["TaskStep"]]: from agent_env.task_step.task_steps.browser.connect_cdp import BrowserConnectCdpTaskStep from agent_env.task_step.task_steps.browser.contexts import ( @@ -193,7 +212,14 @@ def _build_registry(source: Config | None = None) -> dict[str, type["TaskStep"]] from agent_env.task_step.task_step import TaskStep registry = _builtin_registry() - validate = _registration.typed_validator(TaskStep, builtins=frozenset(registry), required=_MUST_IMPLEMENT) + typed = _registration.typed_validator(TaskStep, builtins=frozenset(registry), required=_MUST_IMPLEMENT) + + def validate(name: str, loaded: object) -> type["TaskStep"]: + cls = typed(name, loaded) + if problem := undeclared_refs(cls): + raise TypeError(problem) + return cls + from_plugins = _registration.merge(registry, _registration.TASK_STEPS, validate, source=source) _merge_config_toml_steps(registry, source=source, from_plugins=from_plugins) return registry @@ -227,7 +253,7 @@ def _merge_config_toml_steps( f"[task_steps] impl {impl!r} does not define its own 'type' " f"(inherits the base default {TaskStep.type!r}); set a unique 'type' ClassVar" ) - if problem := _registration.unimplemented(cls, TaskStep, _MUST_IMPLEMENT): + if problem := _registration.unimplemented(cls, TaskStep, _MUST_IMPLEMENT) or undeclared_refs(cls): raise ConfigError(f"[task_steps] impl {impl!r}: {problem}") if from_plugins.refuse(cls.type, f"[task_steps] impl {impl!r}"): continue diff --git a/src/agent_env/task_step/task_step.py b/src/agent_env/task_step/task_step.py index c26c6dc6c..035e365be 100644 --- a/src/agent_env/task_step/task_step.py +++ b/src/agent_env/task_step/task_step.py @@ -89,7 +89,7 @@ class TaskStep(ABC): type: ClassVar[str] = "task_step" DEFAULT_TTL_SECONDS: ClassVar[int] = 7200 DEFAULT_AGENT_NAME: ClassVar[str] = "default-agent" - # Fields holding env, A2A agent or artifact ids; None means undeclared. + # Fields holding env, A2A agent or artifact ids, () for none; None means undeclared, which registration refuses. entity_refs: ClassVar[tuple[EntityRef, ...] | None] = None # Fields holding paths into a run's context (``context_path_segments``), as dotted keys with ``[]`` / ``{}`` for each # element or value; a bundle rewrites the ids in them as it does entity_refs'. diff --git a/tst/installer/toys.py b/tst/installer/toys.py index 320bb3e06..cd5d9ce07 100644 --- a/tst/installer/toys.py +++ b/tst/installer/toys.py @@ -17,6 +17,7 @@ class GradeTaskStep(TaskStep): type: ClassVar[str] = "toy_grade" + entity_refs = () @classmethod def from_dict(cls, data): @@ -34,6 +35,7 @@ async def execute(self, context): class NavigateTaskStep(TaskStep): type: ClassVar[str] = "toy_navigate" + entity_refs = () def __init__(self, id, version, url="about:blank", **base): super().__init__(id, version, **base) diff --git a/tst/unit/entity_refs_import_test.py b/tst/unit/entity_refs_import_test.py index 860d4ca7f..18294a3ab 100644 --- a/tst/unit/entity_refs_import_test.py +++ b/tst/unit/entity_refs_import_test.py @@ -2,7 +2,10 @@ import agent_env.entity.refs as refs import agent_env.entity_refs as old +import agent_env.task_step.registry as registry def test_the_old_import_path_gives_the_same_declarations(): - assert {name: getattr(old, name) for name in old.__all__} == {name: getattr(refs, name) for name in old.__all__} + moved = [name for name in old.__all__ if name != "step_ref_sites"] + assert {name: getattr(old, name) for name in moved} == {name: getattr(refs, name) for name in moved} + assert old.step_ref_sites is registry.step_ref_sites diff --git a/tst/unit/plugins_test.py b/tst/unit/plugins_test.py index b6260a4cf..76b02623e 100644 --- a/tst/unit/plugins_test.py +++ b/tst/unit/plugins_test.py @@ -30,6 +30,7 @@ from agent_env.artifact.artifacts.file import FileArtifact from agent_env.artifact.store import ArtifactStore from agent_env.config import ConfigError, get_config, load_impl, reset_config +from agent_env.entity.refs import EntityRef from agent_env.env.env import DeployedEnv, DeployedSandboxEnv, Env from agent_env.env.envs.website import WebsiteEnv from agent_env.env.registry import _MUST_IMPLEMENT as _ENV_MUST_IMPLEMENT @@ -91,6 +92,7 @@ class _UntypedEnv(_Env): class _PluginStep(_Step): type = "plugin_step" + entity_refs = () class _PluginArtifact(Artifact): @@ -111,6 +113,7 @@ class _SiblingEnv(_Env): class _SiblingStep(_Step): type = "sibling" + entity_refs = () class _SiblingArtifact(Artifact): @@ -244,6 +247,15 @@ class _BareEnvProvider(EnvironmentProvider): type = "bare" +class _RefStep(_Step): + type = "ref_step" + entity_refs = (EntityRef.env("env_id"),) + + +class _UndeclaredStep(_Step): + type = "undeclared" + + class _UnboundStep(_Step): type = "unbound" @@ -253,6 +265,7 @@ def from_dict(cls, data): # the @classmethod left off class _StaticStep(_Step): type = "static" + entity_refs = () @staticmethod def from_dict(data): @@ -508,6 +521,17 @@ def test_a_plugin_class_that_leaves_a_required_method_unimplemented_is_skipped( assert sum(f"{bare} must implement {missing}" in m for m in warnings_logged()) == 1 +def test_a_step_plugin_that_declares_no_entity_refs_is_skipped_and_its_group_loads(monkeypatch): + _install(monkeypatch, task_steps=[_EP("undeclared", "_UndeclaredStep"), _EP("plugin_step", "_PluginStep"), + _EP("ref_step", "_RefStep")]) + + registry = get_config().task_step_registry() + + assert "undeclared" not in registry + assert registry["plugin_step"] is _PluginStep and registry["ref_step"] is _RefStep + assert "_UndeclaredStep must declare entity_refs" in _registration.failure_note(plugins.TASK_STEPS, "undeclared") + + def test_resolving_a_type_whose_class_is_unimplemented_says_what_it_lacks(monkeypatch): _install(monkeypatch, task_steps=[_EP("bare", "_BareStep")]) diff --git a/tst/unit/task_step/test_config_task_steps.py b/tst/unit/task_step/test_config_task_steps.py index e8cac8364..2149fbbb2 100644 --- a/tst/unit/task_step/test_config_task_steps.py +++ b/tst/unit/task_step/test_config_task_steps.py @@ -21,6 +21,7 @@ class _GreetStep(TaskStep): """A minimal infra-free custom step: records a greeting in the context.""" type = "greet_test_step" + entity_refs = () def __init__(self, id, version, message="hi", depends_on=None, fail_task_on_error=True): super().__init__(id, version, depends_on=depends_on, fail_task_on_error=fail_task_on_error) @@ -44,6 +45,7 @@ class _CollidingStep(TaskStep): """Declares a `type` that a built-in already owns.""" type = "prompt_agent" + entity_refs = () @classmethod def from_dict(cls, data: dict) -> "_CollidingStep": @@ -57,6 +59,7 @@ class _GreetStepDup(TaskStep): """A second class claiming the same `type` as _GreetStep.""" type = "greet_test_step" + entity_refs = () @classmethod def from_dict(cls, data: dict) -> "_GreetStepDup": @@ -77,6 +80,19 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: return context +class _UndeclaredStep(TaskStep): + """Leaves `entity_refs` undeclared.""" + + type = "undeclared_test_step" + + @classmethod + def from_dict(cls, data: dict) -> "_UndeclaredStep": + return cls(**cls._base_from_dict(data)) + + async def execute(self, context: TaskStepContext) -> TaskStepContext: + return context + + class _NotAStep: pass @@ -155,6 +171,16 @@ def test_step_without_own_type_raises(monkeypatch, tmp_path): registry.get_task_step_registry() +def test_step_without_entity_refs_raises(monkeypatch, tmp_path): + cfg = _write_config(tmp_path, f""" + [task_steps] + impls = ["{_HERE}:_UndeclaredStep"] + """) + monkeypatch.setenv("AGENT_ENV_CONFIG", str(cfg)) + with pytest.raises(ConfigError, match=r"_UndeclaredStep must declare entity_refs, \(\) if it holds no ids"): + registry.get_task_step_registry() + + def test_unimportable_impl_raises(monkeypatch, tmp_path): cfg = _write_config(tmp_path, """ [task_steps] diff --git a/tst/unit/task_step/test_entity_refs.py b/tst/unit/task_step/test_entity_refs.py index 974a76f2d..cb3bcc076 100644 --- a/tst/unit/task_step/test_entity_refs.py +++ b/tst/unit/task_step/test_entity_refs.py @@ -7,7 +7,7 @@ from agent_env.artifact.registry import get_artifact_registry from agent_env.entity.paths import PATH, field_sites from agent_env.entity.refs import EntityKind, EntityRef, default_agent_refs, parse_toml_ref, ref_sites -from agent_env.task_step.registry import _builtin_registry +from agent_env.task_step.registry import _builtin_registry, step_ref_sites from agent_env.task_step.snapshot_utils.snapshot_series import SnapshotConfig from agent_env.task_step.task_step import TaskStep from agent_env.task_step.task_steps.add_skills import AddSkillsTaskStep @@ -72,6 +72,20 @@ def test_sites_carry_scalar_list_and_element_relative_versions(): ] +@pytest.mark.parametrize("step", [ + DeployEnvTaskStep(id="d", version=None, env_id="crm", artifact_id="seed"), + {"id": "d", "type": "deploy_env", "env_id": "crm", "artifact_id": "seed"}, +], ids=["task_step", "dict"]) +def test_step_ref_sites_reads_a_step_by_its_registered_type(step): + assert [(s.path, s.ref.kind, s.value) for s in step_ref_sites(step)] == [ + ("env_id", EntityKind.ENV, "crm"), ("artifact_id", EntityKind.ARTIFACT, "seed")] + + +def test_step_ref_sites_refuses_a_type_nothing_registers(): + with pytest.raises(ValueError, match="unknown task step type 'no_such_step'"): + step_ref_sites({"id": "s", "type": "no_such_step"}) + + def test_absent_and_null_fields_yield_nothing(): refs = (EntityRef.env("env_id"), EntityRef.artifact("skills[].skill_artifact_id")) assert list(ref_sites(refs, {"env_id": None, "skills": None})) == []