feat(v1)!: cross-agent judgement is finalize() — env-level decorated signals removed (#2090)

Author: eligotts

assets/lab/environments/AGENTS.md

@@ -295,8 +295,7 @@ class DebateEnv(vf.Environment[DebateConfig]):
         """Sibling-dependent judgement over the finished episode (per-trace
         judgement already ran on each trace's own task); `episode.traces` is
         the flat episode, each trace's `agent_name` stamp naming its agent.
-        Attach via record_reward/record_metric; the env's own
-        `@vf.reward`/`@vf.metric` methods run after this."""
+        Attach via record_reward/record_metric, in program order."""
         by_agent = {t.agent_name: t for t in episode.traces}
         winner = (by_agent["judge"].last_reply or "").strip().lower()
         by_agent["pro"].record_reward("won", float(winner == "pro"))

docs/v1/environments.md

@@ -44,8 +44,7 @@ class DebateEnv(vf.Environment[DebateConfig]):
         """Sibling-dependent judgement over the finished episode (per-trace
         judgement already ran on each trace's own task); `episode.traces` is
         the flat episode, each trace's `agent_name` stamp naming its agent.
-        Attach via record_reward/record_metric; the env's own
-        `@vf.reward`/`@vf.metric` methods run after this."""
+        Attach via record_reward/record_metric, in program order."""
         by_agent = {t.agent_name: t for t in episode.traces}
         winner = (by_agent["judge"].last_reply or "").strip().lower()
         by_agent["pro"].record_reward("won", float(winner == "pro"))

environments/AGENTS.md

@@ -294,8 +294,7 @@ class DebateEnv(vf.Environment[DebateConfig]):
         """Sibling-dependent judgement over the finished episode (per-trace
         judgement already ran on each trace's own task); `episode.traces` is
         the flat episode, each trace's `agent_name` stamp naming its agent.
-        Attach via record_reward/record_metric; the env's own
-        `@vf.reward`/`@vf.metric` methods run after this."""
+        Attach via record_reward/record_metric, in program order."""
         by_agent = {t.agent_name: t for t in episode.traces}
         winner = (by_agent["judge"].last_reply or "").strip().lower()
         by_agent["pro"].record_reward("won", float(winner == "pro"))

environments/code_golf_v1/code_golf_v1/taskset.py

@@ -3,14 +3,14 @@
 Each task asks for a tiny program with a known output. The env fans one env-rollout
 into `--env.attempts` independent attempts by the same "golfer" role and scores them
 against each other. Anything that needs the runtime is measured per attempt, box-live,
-into that attempt's trace; the env's `score()` then just compares the recorded
+into that attempt's trace; the env's `finalize()` then just compares the recorded
 metadata across the finished siblings:
 
   - `evaluate`      per-attempt `@metric`: runs the program once in that attempt's
                     runtime and records `passed` + `latency`. (task, trace, runtime)
   - `correct`       per-attempt `@reward`: reads `passed` off the trace.      (trace)
-  - `most_concise`  env `score()`: of the PASSING attempts, the shortest source wins.
-  - `fastest`       env `score()`: of the PASSING attempts, the lowest recorded
+  - `most_concise`  env `finalize()`: of the PASSING attempts, the shortest source wins.
+  - `fastest`       env `finalize()`: of the PASSING attempts, the lowest recorded
                     `latency` wins — a comparison of trace metadata.
 
 So one env-rollout produces, per attempt: did it work, was it the shorter one, was it
@@ -78,23 +78,23 @@ async def run(self, task: vf.Task, agents: vf.Agents) -> None:
             for _ in range(self.config.attempts):
                 tg.create_task(agents.golfer.run(task))
 
-    @vf.reward(weight=0.5)
-    async def most_concise(self, trace: vf.Trace, traces: list[vf.Trace]) -> float:
-        """The sibling comparison: shortest source among the passing attempts wins
-        (ties share); a failed attempt earns nothing."""
-        if not trace.metrics.get("passed"):
-            return 0.0
-        lengths = [len(extract_program(t)) for t in traces if t.metrics.get("passed")]
-        return float(len(extract_program(trace)) == min(lengths))
-
-    @vf.reward(weight=0.5)
-    async def fastest(self, trace: vf.Trace, traces: list[vf.Trace]) -> float:
-        """The sibling comparison: lowest run latency among the passing attempts
-        wins (ties share); a failed attempt earns nothing."""
-        if not trace.metrics.get("passed"):
-            return 0.0
-        latencies = [t.metrics["latency"] for t in traces if t.metrics.get("passed")]
-        return float(trace.metrics["latency"] == min(latencies))
+    async def finalize(self, task: vf.Task, episode: vf.Episode) -> None:
+        """The sibling comparison: among the PASSING attempts, the shortest source
+        wins `most_concise` and the lowest recorded latency wins `fastest` (ties
+        share); a failed attempt earns nothing on either."""
+        passing = [t for t in episode.traces if t.metrics.get("passed")]
+        min_length = min((len(extract_program(t)) for t in passing), default=None)
+        min_latency = min((t.metrics["latency"] for t in passing), default=None)
+        for trace in episode.traces:
+            if trace not in passing:
+                trace.record_reward("most_concise", 0.0, 0.5)
+                trace.record_reward("fastest", 0.0, 0.5)
+                continue
+            concise = float(len(extract_program(trace)) == min_length)
+            trace.record_reward("most_concise", concise, 0.5)
+            trace.record_reward(
+                "fastest", float(trace.metrics["latency"] == min_latency), 0.5
+            )
 
 
 class CodeGolfTaskset(vf.Taskset[CodeGolfTask, vf.TasksetConfig]):

environments/proposer_solver_v1/proposer_solver_v1/taskset.py

@@ -154,16 +154,15 @@ def _solve_rate(traces: list[vf.Trace]) -> float:
             return 0.0
         return sum(t.rewards.get("correct", 0.0) for t in solves) / len(solves)
 
-    @vf.reward(agent="proposer")
-    async def learnability(self, trace: vf.Trace, traces: list[vf.Trace]) -> float:
-        """The curriculum signal: 1.0 when half the solvers crack the problem, 0
-        when it's trivial or impossible for them (4p(1-p))."""
-        rate = self._solve_rate(traces)
-        return 4.0 * rate * (1.0 - rate)
-
-    @vf.metric(agent="proposer")
-    async def solve_rate(self, trace: vf.Trace, traces: list[vf.Trace]) -> float:
-        return self._solve_rate(traces)
+    async def finalize(self, task: vf.Task, episode: vf.Episode) -> None:
+        """The proposer is judged by what its problem DOES to the solvers:
+        `learnability` — the curriculum signal — is 1.0 when half of them crack
+        the problem, 0 when it's trivial or impossible for them (4p(1-p))."""
+        rate = self._solve_rate(episode.traces)
+        for trace in episode.traces:
+            if trace.agent_name == "proposer":
+                trace.record_metric("solve_rate", rate)
+                trace.record_reward("learnability", 4.0 * rate * (1.0 - rate))
 
 
 class ProposerSolverTaskset(vf.Taskset[ProposeTask, vf.TasksetConfig]):

skills/create-environments/SKILL.md

@@ -136,7 +136,7 @@ Runtime config chooses where code executes. Task hooks should use the `vf.Runtim
 - Prefer deterministic verification grounded in the task's actual artifact or answer.
 - Use an LLM judge only when semantic judgment is unavoidable.
 - Metrics are for observability and do not contribute to reward, but are useful. Use them deliberately and appropriately!
-- Judgement that compares the sibling traces of one env-rollout (best-of-n selection, zero-sum payoffs) lives on `Environment.finalize(task, episode)` or the env's `@vf.reward`/`@vf.metric` methods — attach via `trace.record_reward`/`record_metric`; no live runtime there.
+- Judgement that compares the sibling traces of one env-rollout (best-of-n selection, zero-sum payoffs) lives on `Environment.finalize(task, episode)` — attach via `trace.record_reward`/`record_metric`, in program order; no live runtime there.
 - Raise ordinary Python exceptions from rollout hooks and scoring. The rollout records them as `TaskError`.
 
 ## Validation and lifecycle
@@ -194,7 +194,7 @@ The selected harness must support user simulation, which a lot of the built-in,
 
 ## Multi-agent environments
 
-When one rollout is more than one agent run, export an `Environment` subclass next to the taskset: declare each agent as a `vf.AgentConfig` field with a default instance on a `vf.EnvConfig` subclass (bound via `Environment[YourConfig]`, read as `self.config`, addressed as `--env.<agent>.*`) — the field name is the agent's name, the only naming site, and per-run caps (turns, tokens, stage timeouts, retries) are agent fields. A declared pin is its author default; an unpinned agent runs the taskset's default harness, and its model context defaults to the run's own. Task x agent fit validates per run, on the task each agent actually receives (an env-minted task carries its own `tools`/`NEEDS_CONTAINER`, so a bare verdict task pairs with any taskset). Then write `run(task, agents)` (imperative control flow, returning nothing — every finished run joins the episode automatically, stamped with its standing), and optionally `setup(agents)` (env-hardcoded standing, e.g. `agents.judge.trainable = False`) and `finalize(task, episode)` (sibling-dependent judgement over `episode.traces`; `trace.agent_name` names each agent; the env's `@vf.reward`/`@vf.metric` methods run after it). Before writing one, check the bundled envs (`--env.id best-of-n | agentic-judge`) and the reference implementation (`environments/code_golf_v1`). See docs/v1/environments.md.
+When one rollout is more than one agent run, export an `Environment` subclass next to the taskset: declare each agent as a `vf.AgentConfig` field with a default instance on a `vf.EnvConfig` subclass (bound via `Environment[YourConfig]`, read as `self.config`, addressed as `--env.<agent>.*`) — the field name is the agent's name, the only naming site, and per-run caps (turns, tokens, stage timeouts, retries) are agent fields. A declared pin is its author default; an unpinned agent runs the taskset's default harness, and its model context defaults to the run's own. Task x agent fit validates per run, on the task each agent actually receives (an env-minted task carries its own `tools`/`NEEDS_CONTAINER`, so a bare verdict task pairs with any taskset). Then write `run(task, agents)` (imperative control flow, returning nothing — every finished run joins the episode automatically, stamped with its standing), and optionally `setup(agents)` (env-hardcoded standing, e.g. `agents.judge.trainable = False`) and `finalize(task, episode)` (sibling-dependent judgement over `episode.traces`, via `record_reward`/`record_metric`; `trace.agent_name` names each agent). Before writing one, check the bundled envs (`--env.id best-of-n | agentic-judge`) and the reference implementation (`environments/code_golf_v1`). See docs/v1/environments.md.
 
 ## Custom harnesses
 

skills/evaluate-environments/references/REFERENCE.md

@@ -117,7 +117,7 @@ trace.
 | `id` | `ID` | `""` | Which `Environment` (control flow between agents) runs: a bundled env (`best-of-n`, `agentic-judge`), a local package, or a Hub `org/name[@version]`. Empty = the taskset's own story (its exported `Environment` subclass, else `SingleAgentEnv`). |
 | `taskset` | `TasksetConfig \| None` | `None` | The seed taskset every rollout starts from; resolved to its concrete subclass by `--env.taskset.id` (positional shorthand: `eval <taskset-id>`). See [Taskset config](#taskset-config). `None` only for a taskset-less env; every bundled env requires one. |
 | *(agents)* | `AgentConfig` | env-declared | Each declared agent: `agent` on `SingleAgentEnvConfig`, `solver`/`judge` on the agentic-judge env, the env's own names elsewhere. See [Agent config](#agent-config). |
-| `timeout` | `EnvTimeoutConfig` | `EnvTimeoutConfig()` | The env's own hook bounds: `--env.timeout.episode` (the whole `run()` hook) and `--env.timeout.finalize` (`finalize()` plus the decorated signals). Per-run stage timeouts are each agent's (`--env.<agent>.timeout.*`). |
+| `timeout` | `EnvTimeoutConfig` | `EnvTimeoutConfig()` | The env's own hook bounds: `--env.timeout.episode` (the whole `run()` hook) and `--env.timeout.finalize` (the `finalize()` hook). Per-run stage timeouts are each agent's (`--env.<agent>.timeout.*`). |
 | `retries` | `RolloutRetryConfig` | `RolloutRetryConfig()` | Whole-EPISODE retries, the coarse fallback for faults no agent owns. See [Retry config](#retry-config). Set via `--env.retries.*`. |
 | `interception` | `InterceptionConfig` | `ElasticInterceptionPoolConfig()` | The interception shape: `elastic` (default — servers grown on demand, `multiplex` rollouts each), `server` (one server, tunnel choice incl. bring-your-own endpoint), or `static` (a fixed list). |
 
@@ -181,7 +181,7 @@ fields. Shared by the `serve` CLI, server-backed eval, and prime-rl's orchestrat
 | `finalize` | `float \| None` | `None` | Max wall-clock for the task's `finalize` hook. |
 | `scoring` | `float \| None` | `None` | Max wall-clock for task rewards/metrics/judges and harness metrics. |
 
-`EnvTimeoutConfig` (the env's `--env.timeout.*`) keeps only `episode` — the bound on the whole `run()` interaction — and `finalize` — the bound on the env's `finalize()` hook plus its decorated signals.
+`EnvTimeoutConfig` (the env's `--env.timeout.*`) keeps only `episode` — the bound on the whole `run()` interaction — and `finalize` — the bound on the env's `finalize()` hook.
 
 > Remote sandboxes cap any harness timeout at 24 hours (provider max lifetime).
 

skills/train-with-environments/SKILL.md

@@ -112,7 +112,7 @@ can override it.
 - If groups are mostly all-one, increase difficulty or sample a harder task distribution.
 - Choose `batch_size` with whole groups, packing, sequence length, and GPU memory in mind.
 
-Sibling-dependent scoring (best-of-n selection, zero-sum payoffs) lives on `Environment.finalize(task, episode)` and the env's decorated signals, and runs inside the env — every trace carries its agent name, trainability, and episode stamp, so a flat batch regroups without a side lookup. `-r` stays purely the trainer's group size: n independent env-rollouts per task; env-internal fan-out is the env's own knob (`--env.n`).
+Sibling-dependent scoring (best-of-n selection, zero-sum payoffs) lives on `Environment.finalize(task, episode)`, and runs inside the env — every trace carries its agent name, trainability, and episode stamp, so a flat batch regroups without a side lookup. `-r` stays purely the trainer's group size: n independent env-rollouts per task; env-internal fan-out is the env's own knob (`--env.n`).
 
 ## Difficulty filtering
 

verifiers/v1/decorators.py

@@ -88,49 +88,37 @@ def decorator(f: F) -> F:
 
 
 @overload
-def metric(func: F, priority: int = 0, agent: str | None = None) -> F: ...
+def metric(func: F, priority: int = 0) -> F: ...
 @overload
-def metric(
-    func: None = None, priority: int = 0, agent: str | None = None
-) -> Callable[[F], F]: ...
-def metric(
-    func: F | None = None, priority: int = 0, agent: str | None = None
-) -> F | Callable[[F], F]:
-    """Mark a metric `(self, trace) -> float` (recorded, not summed). On an
-    `Environment` it's a cross-agent signal: run once per episode trace with the
-    finished sibling set in reach (`trace` = the target, `traces` = all of them);
-    `agent=` narrows the targets to one seat's traces (env-only — a task has no
-    agents)."""
+def metric(func: None = None, priority: int = 0) -> Callable[[F], F]: ...
+def metric(func: F | None = None, priority: int = 0) -> F | Callable[[F], F]:
+    """Mark a `Task`/`Harness` metric `(self, trace) -> float` (recorded, not
+    summed) — per-trace judgement; it declares what it needs by name (`task`,
+    `trace`, `runtime`). Cross-agent judgement is an `Environment`'s `finalize()`,
+    imperatively."""
 
     def decorator(f: F) -> F:
-        return mark("metric", metric_priority=priority, _vf_agent=agent)(
-            _async_only("metric")(f)
-        )
+        return mark("metric", metric_priority=priority)(_async_only("metric")(f))
 
     return decorator if func is None else decorator(func)
 
 
 @overload
-def reward(
-    func: F, weight: float = 1.0, priority: int = 0, agent: str | None = None
-) -> F: ...
+def reward(func: F, weight: float = 1.0, priority: int = 0) -> F: ...
 @overload
 def reward(
-    func: None = None, weight: float = 1.0, priority: int = 0, agent: str | None = None
+    func: None = None, weight: float = 1.0, priority: int = 0
 ) -> Callable[[F], F]: ...
 def reward(
-    func: F | None = None,
-    weight: float = 1.0,
-    priority: int = 0,
-    agent: str | None = None,
+    func: F | None = None, weight: float = 1.0, priority: int = 0
 ) -> F | Callable[[F], F]:
-    """Mark a weighted per-rollout reward returning a float or keyed scores. On an
-    `Environment` it's a cross-agent signal — see `metric` for the env semantics
-    (`agent=` picks whose traces it records onto)."""
+    """Mark a weighted `Task` reward returning a float or keyed scores — per-trace
+    judgement over the trace's own run. Cross-agent judgement is an
+    `Environment`'s `finalize()`, imperatively."""
 
     def decorator(f: F) -> F:
-        return mark(
-            "reward", reward_priority=priority, _vf_weight=weight, _vf_agent=agent
-        )(_async_only("reward")(f))
+        return mark("reward", reward_priority=priority, _vf_weight=weight)(
+            _async_only("reward")(f)
+        )
 
     return decorator if func is None else decorator(func)