Skip to content

feat(task_step)!: require entity_refs on step types; add step_ref_sites - #742

Open
agutmanstein-scale wants to merge 1 commit into
mainfrom
alecgutmanstein/require-step-entity-refs
Open

agutmanstein-scale wants to merge 1 commit into
mainfrom
alecgutmanstein/require-step-entity-refs

Conversation

@agutmanstein-scale

@agutmanstein-scale agutmanstein-scale commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator
Before After
A step type that leaves entity_refs undeclared (None) registers; each tool reading ids handles None itself refused at registration: a plugin is skipped with a failure note (agent-env plugin check lists it), a [task_steps] impls entry fails with ConfigError
A step type with no ids could leave entity_refs unset declares entity_refs = ()
Reading a step's declared refs ref_sites(type(step).entity_refs or (), step.to_dict()), written out by each caller step_ref_sites(step), for a TaskStep or a step dict (looked up in the registry by type), from agent_env.task_step.registry or agent_env.entity_refs

Built-in step types already all declare (a test checks that), so nothing built in changes.

Why. Tools that read or rewrite a step's ids, such as bundle resolvers and pooled-run checks, can't see a step type that declares nothing, and each consumer had to handle None on its own.

Upgrading. A plugin or [task_steps] impls step type must declare entity_refs before it upgrades to this version: the fields that hold env, A2A agent, artifact or task ids, or () if it holds none. Abstract or intermediate classes without their own type are not affected.

Docs. The steps page could say that a custom step type must declare entity_refs (with () for none), and mention step_ref_sites.

Tests

  • tst/unit/plugins_test.py: an undeclared step plugin is skipped with its note while a () one and one declaring an env ref register.
  • tst/unit/task_step/test_config_task_steps.py: an undeclared [task_steps] impls entry fails with ConfigError.
  • tst/unit/task_step/test_entity_refs.py: step_ref_sites on a TaskStep and on a dict, and an unknown type.
  • Test step classes registered as plugins or config impls (plugin, config and installer tiers) now declare entity_refs = ().

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 4/5

The PR appears safe to merge, with a non-blocking startup-cost concern in the compatibility export.

Fix All in CursorFindings

  1. P2 Declaration imports load task steps ▶
Fix with agent prompt
### Issue 1
src/agent_env/entity_refs.py:5
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.

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!

---

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

Summary

Requires custom step types to declare entity_refs and adds step_ref_sites for reading references from instances or dictionaries.

  • Custom step types must declare which entity IDs they contain.
  • Callers can find a step's declared entity IDs from either step form.

Reviews (1) · Last reviewed commit: "feat(task_step)!: require entity_refs on..." · Reviewed by Greptile

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 <noreply@anthropic.com>
@agutmanstein-scale
agutmanstein-scale requested a review from a team as a code owner November 17, 2026 17:35
``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

@andrewpark-scaleai andrewpark-scaleai left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

holding for now. the code looks right and tests pass locally (4888 passed). but 10 of the 14 agentenvhub-sdk step plugins don't declare entity_refs yet (cua_evaluate, hydrator, publish, etc), and the sdk only floors agentenv-framework. so this release plus sdk <=0.40.33 skips them, and every task that uses them fails to load. can we land scaleapi#176128 and get the hub/worker pinned to sdk >=0.40.34 first? happy to approve right after. nit: the entity_refs or () and is None branches in bundle/* are dead now, fine as a follow-up.

@cikowski cikowski left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approving. One sequencing note: this needs scaleapi#176128 (every agentenvhub-sdk step declares entity_refs) to land before agentenvhub-sdk picks up this framework release, otherwise the undeclared SDK steps stop registering.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants