fix: drop redundant on_trace kwarg from Agent.run

[mikasenghaas]

Summary

• Agent.run returns the Trace, so a public on_trace(trace) callback on it is redundant for the standalone agent — and no external caller ever passed it.
• Its only consumer was _EpisodeAgent, which injected a per-call watch closure to observe each trace at mint (stamp the seat's agent.name/trainable, feed the episode's live view, discard abandoned retry attempts). The base retry loop already knows each attempt, so it can drive this directly.
• Make mint-observation an internal protected mechanism: base Agent grows no-op _observe/_discard hooks; _run_once fires _observe at mint (via RolloutRun's on_trace); the retry loop calls _discard when it abandons an attempt for backoff. _EpisodeAgent overrides both — no per-call closure, no public kwarg.
• Live-dashboard streaming (slot.traces fed at mint) and per-agent retry discard are behaviorally unchanged.

Breaking

• Agent.run / _EpisodeAgent.run no longer accept the on_trace keyword. It was never part of the advertised API (solver.run(task)), had no callers outside the internal watch plumbing, and callers already get the trace as the return value. For mint-time/live observation inside an env, keep going through Env.run_episode(on_trace=...) (unchanged).

🤖 Generated with Claude Code

---

Note

Medium Risk
Breaking removal of Agent.run's on_trace and a behavior-sensitive change to when abandoned retry traces leave live views (now via base retry loop + _discard); episode streaming should be unchanged but callers relying on the old kwarg must migrate.

Overview
Removes the public on_trace kwarg from Agent.run and _EpisodeAgent.run. Mint-time trace handling is now internal: base Agent defines no-op _observe / _discard hooks, _run_once wires RolloutRun to self._observe, and the retry loop calls _discard on abandoned attempts before backoff.

_EpisodeAgent overrides those hooks to stamp seat name / trainable, forward to the episode’s on_trace / on_discard, and drop superseded traces from live views—replacing the previous per-run watch closure (including discard-on-retry logic inlined there).

^{Reviewed by Cursor Bugbot for commit 408b45a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Drop on_trace parameter from Agent.run and replace with _observe/_discard hooks

• Removes the on_trace callback parameter from Agent.run and Agent._run_once; callers passing it will now get a TypeError.
• Adds protected _observe and _discard hook methods to Agent that subclasses can override; _observe fires when a trace is minted, _discard fires when a retried attempt is abandoned before backoff.
• _EpisodeAgent overrides both hooks to stamp traces with seat metadata and forward events to episode-level callbacks, replacing the previous per-run watch() closure.
• Risk: any caller currently passing on_trace to Agent.run or _EpisodeAgent.run will break with a TypeError.

^{Macroscope summarized 408b45a.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This refactor introduces a behavioral change in trace discard timing during retries. An unresolved review comment identifies a potential bug where the live dashboard may show incorrect 'pending' status during retry backoff instead of the failed attempt.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 408b45a. Configure here.}

[cursor]

Live view pending during retry

Medium Severity

Calling _discard before retry backoff removes the failed trace from slot.traces while the env-rollout is still in flight. With a single agent, the live dashboard treats an empty in-progress slot as queued (pending) until the next attempt mints, instead of showing the failed attempt during the wait.

 

^{Reviewed by Cursor Bugbot for commit 408b45a. Configure here.}