Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -240,14 +240,16 @@ Out-of-tree code plugs in either through `config.toml`, as a `module:Class` poin
`[state.providers.<name>]`, `[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 (`<name> = "<package>"`, the folder at
Expand Down
3 changes: 2 additions & 1 deletion src/agent_env/entity/refs.py
Original file line number Diff line number Diff line change
Expand Up @@ -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``).
Expand Down
6 changes: 4 additions & 2 deletions src/agent_env/entity_refs.py
Original file line number Diff line number Diff line change
@@ -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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Declaration imports load task steps

Importing only EntityRef from agent_env.entity_refs now loads the whole agent_env.task_step package. Its initializer imports built-in steps, providers, and stores, adding unrelated startup work for existing callers. Export step_ref_sites lazily so declaration imports stay lightweight.

Prompt To Fix With AI
This is a comment left during a code review.
Path: src/agent_env/entity_refs.py
Line: 5

Comment:
**Declaration imports load task steps**

Importing only `EntityRef` from `agent_env.entity_refs` now loads the whole `agent_env.task_step` package. Its initializer imports built-in steps, providers, and stores, adding unrelated startup work for existing callers. Export `step_ref_sites` lazily so declaration imports stay lightweight.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Fix in Cursor Fix in Claude Code Fix in Codex


__all__ = ["EntityKind", "EntityRef", "RefRole", "RefSite", "parse_toml_ref", "ref_sites"]
__all__ = ["EntityKind", "EntityRef", "RefRole", "RefSite", "parse_toml_ref", "ref_sites", "step_ref_sites"]
32 changes: 29 additions & 3 deletions src/agent_env/task_step/registry.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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"]]:
Expand All @@ -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 (
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion src/agent_env/task_step/task_step.py
Original file line number Diff line number Diff line change
Expand Up @@ -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'.
Expand Down
2 changes: 2 additions & 0 deletions tst/installer/toys.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@

class GradeTaskStep(TaskStep):
type: ClassVar[str] = "toy_grade"
entity_refs = ()

@classmethod
def from_dict(cls, data):
Expand All @@ -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)
Expand Down
5 changes: 4 additions & 1 deletion tst/unit/entity_refs_import_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
24 changes: 24 additions & 0 deletions tst/unit/plugins_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -91,6 +92,7 @@ class _UntypedEnv(_Env):

class _PluginStep(_Step):
type = "plugin_step"
entity_refs = ()


class _PluginArtifact(Artifact):
Expand All @@ -111,6 +113,7 @@ class _SiblingEnv(_Env):

class _SiblingStep(_Step):
type = "sibling"
entity_refs = ()


class _SiblingArtifact(Artifact):
Expand Down Expand Up @@ -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"

Expand All @@ -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):
Expand Down Expand Up @@ -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")])

Expand Down
26 changes: 26 additions & 0 deletions tst/unit/task_step/test_config_task_steps.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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":
Expand All @@ -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":
Expand All @@ -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

Expand Down Expand Up @@ -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]
Expand Down
16 changes: 15 additions & 1 deletion tst/unit/task_step/test_entity_refs.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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})) == []
Expand Down
Loading