runner.py
1"""Agent decision runner using a pipeline, independent of research and UI.23The runner owns pipeline/log resources and borrows the prepared market.4An experiment controller owns the runner and market; a standalone runner is a5Platform root. Closing the runner drains the pipeline but does not close market.6The trusted process host owns Agent execution and model I/O. Configured agents use7the built-in template after model setup; trusted programs can replace that template.8"""910from __future__ import annotations11import logging1213from threading import RLock14from typing import TYPE_CHECKING, Any, Callable, Dict, Optional1516from sim_platform.market.pacing import validate_poll17from sim_platform.domain.models import ContractError18from sim_platform.resources import cleanup_after_error19from sim_platform.decisions.base import DecisionRunner2021from sim_platform.experiments.execution.controls import CONTROL_ACK_TIMEOUT_SECONDS2223_log = logging.getLogger(__name__)2425if TYPE_CHECKING: # Annotation only.26 from concurrent.futures import Future2728 from sim_platform.agents.hosting.host import AgentProcessHost29 from sim_platform.agents.operation_log import AgentOperationLog30 from sim_platform.agents.tools.server.router import AgentTools31 from sim_platform.experiments.execution.controls import ExperimentControls32 from sim_platform.experiments.execution.session import ExperimentSession33 from sim_platform.models.contracts import ModelProfile, ModelProvider3435 # Turns the runner's detached snapshot into the display view (AgentPresentation).36 Presentation = Callable[[Dict[str, Any]], Dict[str, Any]]373839class AgentDecisionRunner(DecisionRunner):40 """Platform side of an Agent run: tool admission, work, and lifecycle controls.4142 Owns the pipeline, tool router, recorder, and (once bound) the Agent process host43 and control barrier; close() releases them. It borrows the prepared market. Platform44 binds the host, presentation, local model and barrier during setup, before Play.4546 Args:47 pipeline: Drives the market and orders financial and read requests.48 tools: Validates and dispatches the Agent's tool requests.49 run_id: The run this Agent decides for.50 experiment_id: The experiment that groups this run.51 recorder: The Agent operation log, closed with the runner.52 """5354 background = True5556 def __init__(57 self,58 pipeline: ExperimentSession,59 tools: AgentTools,60 run_id: str,61 experiment_id: str,62 recorder: AgentOperationLog,63 ) -> None:64 self._pipeline = pipeline65 self._tools = tools66 self._run_id = run_id67 self.experiment_id = experiment_id68 self._closed = False69 self._recorder = recorder70 self._process: Optional[AgentProcessHost] = None71 self._tool_used = False72 self._on_close: Callable[[], None] = lambda: None73 self._control_lock = RLock()74 self._barrier: Optional[ExperimentControls] = None75 self._local_model_bound = False76 self._presentation: Optional[Presentation] = None77 # Turn-based experiments only: advances the clock between the Agent's turns.78 self._pacer: Optional[Any] = None7980 def bind_pacer(self, pacer: Any) -> None:81 """Attach the TurnPacer of a turn-based experiment; it starts on the first Play."""82 self._pacer = pacer8384 @property85 def process_host(self) -> Optional[AgentProcessHost]:86 return self._process8788 def bind_process(self, host: AgentProcessHost) -> None:89 """Platform setup only: attach one owned host before Play or tool use."""90 if (91 self._process is not None92 or self._tool_used93 or self._pipeline.snapshot()['state'] != 'ready'94 ):95 raise ContractError('agent process already bound or runner started')96 self._process = host97 if self._tools.controls is not None:98 self._tools.controls.on_end = lambda: host.request_stop()99 self._pipeline.channels.ended.add_done_callback(lambda _: host.request_stop())100101 def on_close(self, callback: Callable[[], None]) -> None:102 self._on_close = callback103104 @property105 def run_id(self) -> str:106 return self._run_id107108 @property109 def output_finished(self) -> bool:110 """Whether terminal output has drained (including an output failure)."""111 return self._pipeline.channels.ended.done()112113 @property114 def archive_ready(self) -> bool:115 return not self.active and self.output_finished116117 @property118 def tool_controls(self) -> AgentDecisionRunner:119 return self120121 @property122 def closed(self) -> bool:123 return self._closed124125 @property126 def pipeline(self) -> ExperimentSession:127 """Lower-level trusted harness access; normal callers use session methods."""128 return self._pipeline129130 def _check_open(self) -> None:131 if self._closed:132 raise ContractError('agent session is closed')133134 @property135 def active(self) -> bool:136 return not self._closed and self._pipeline.snapshot()['state'] in (137 'ready',138 'running',139 'paused',140 'pausing',141 'ending',142 )143144 def snapshot(self) -> Dict[str, Any]:145 """Detached run identity and last published owner status; no market reads."""146 return dict(147 mode='agent',148 run_id=self.run_id,149 experiment_id=self.experiment_id,150 pipeline=self._pipeline.snapshot(),151 agent_process=self._process.snapshot() if self._process is not None else None,152 tools_process=self._tools.snapshot(),153 work=self._tools.controls.snapshot() if self._tools.controls is not None else None,154 control=self._barrier.snapshot() if self._barrier is not None else None,155 pacing='turn' if self._pacer is not None else 'live',156 pacer=self._pacer.snapshot() if self._pacer is not None else None,157 )158159 def bind_presentation(self, presentation: Presentation) -> None:160 """Platform injects the read-only display capability during assembly."""161 self._presentation = presentation162163 def detached_view(self) -> Dict[str, Any]:164 state = self.snapshot()165 return self._presentation(state) if self._presentation is not None else state166167 def poll(168 self, *, max_events: int = 1, budget_seconds: Optional[float] = None169 ) -> Dict[str, Any]:170 validate_poll(max_events, budget_seconds)171 return self.snapshot()172173 def _tool_delivered(self, request_id: str, future: Future[Any]) -> None:174 """Release the request's admission slot and hand a successful result to the tools."""175 self._tools.controls.delivered(request_id)176 try:177 result = future.result()['result']178 except Exception:179 _log.warning('Handled failure in _tool_delivered', exc_info=True)180 return181 self._tools.delivered(request_id, result)182183 def request_tool(self, request: Dict[str, Any]) -> Future[Any]:184 """Ingress validation/admission; owner rechecks current work before effects."""185 self._check_open()186 request = self._tools.validate(request)187 if self._tools.has_retained_request(request):188 return self._submit_tool(request)189 controls = self._tools.controls190 from sim_platform.experiments.scheduling.host import RuntimeError191 from sim_platform.agents.tools.protocol.contracts import ToolError192193 try:194 controls.admit_request(request).result(CONTROL_ACK_TIMEOUT_SECONDS)195 except RuntimeError as exc:196 if exc.code in ('CONTRACT_ERROR', 'STALE_WORK'):197 raise ToolError('STALE_WORK', str(exc)) from exc198 raise199 try:200 future = self._submit_tool(request)201 except Exception:202 controls.delivered(request['request_id'])203 raise204 future.add_done_callback(lambda f: self._tool_delivered(request['request_id'], f))205 self._tool_used = True206 return future207208 def _submit_tool(self, request: Dict[str, Any]) -> Future[Any]:209 """Market reads use the read path; every other tool is an ordered operation."""210 from sim_platform.agents.tools.protocol.contracts import MARKET_TOOLS211212 if request['tool'] in MARKET_TOOLS:213 return self._pipeline.submit_read(request)214 return self._pipeline.submit(request)215216 def _runtime_result(217 self, command: str, data: Optional[Dict[str, Any]] = None218 ) -> Future[Dict[str, Any]]:219 """Submit a Runtime command; the returned future resolves to {'result': value}."""220 from concurrent.futures import Future221222 result: Future[Dict[str, Any]] = Future()223 source = self._tools.controls.runtime.submit(command, data)224225 def complete(future: Future[Any]) -> None:226 try:227 result.set_result(dict(result=future.result()))228 except Exception as exc:229 _log.warning('Handled failure in complete', exc_info=True)230 result.set_exception(exc)231232 source.add_done_callback(complete)233 return result234235 def next_work(self) -> Future[Dict[str, Any]]:236 """Subscribe to independently scheduled Runtime work."""237 self._check_open()238 return self._runtime_result('next_work')239240 def begin_attempt(self) -> Future[Dict[str, Any]]:241 """Trusted test/control capability; provider IO remains Agent-local."""242 self._check_open()243 identity = self._tools.controls.snapshot()244 return self._runtime_result('begin_attempt', {k: identity[k] for k in ('work_id', 'epoch')})245246 def receive_attempt(self, attempt_id: str, **reply: Any) -> bool:247 """Deliver a model attempt's reply to the Runtime; False once the run is inactive."""248 if not self.active:249 return False250 return self._tools.controls.runtime.submit(251 'receive_attempt', dict(attempt_id=attempt_id, **reply)252 ).result(CONTROL_ACK_TIMEOUT_SECONDS)['accepted']253254 def agent_exited(self, status: str, reason: Optional[str]) -> None:255 if status == 'failed':256 self._tools.controls.agent_failed(reason or 'AGENT_CRASH')257 self._pipeline.wake()258259 @property260 def model_configured(self) -> bool:261 return self._local_model_bound262263 def bind_local_model(self, profile: ModelProfile, secret: str, provider: ModelProvider) -> None:264 """Setup the selected Agent host; App owns no model service or payload."""265 self._check_open()266 if (267 self.model_configured268 or self._process is None269 or self._pipeline.snapshot()['state'] != 'ready'270 ):271 raise ContractError('bind one local model before Play')272 self._process.configure_model(profile, secret, provider)273 self._local_model_bound = True274 recorded: Dict[str, Any] = dict(275 provider=profile.provider,276 model=profile.model,277 network_timeout_seconds=profile.network_timeout_seconds,278 max_output_tokens=profile.max_output_tokens,279 temperature=profile.temperature,280 )281 if profile.base_url is not None:282 recorded['base_url'] = profile.base_url283 self._tools.controls.record_notice('model_profile', recorded)284285 def bind_barrier(self, barrier: ExperimentControls) -> None:286 self._barrier = barrier287288 def _play(self, speed: Optional[float] = None) -> Any:289 self._check_open()290 if speed not in (None, 1) or isinstance(speed, bool):291 raise ContractError('agent experiments currently support only 1x')292 # Suspected bug: Play before Platform calls bind_barrier() raises AttributeError293 # on None instead of a ContractError. Left unchanged (no behaviour changes here).294 result = self._barrier.play() # type: ignore[union-attr]295 if self._pacer is not None:296 self._pacer.start()297 return result298299 def _pause(self) -> Any:300 self._check_open()301 # Suspected bug: same unbound-barrier AttributeError as _play().302 return self._barrier.pause() # type: ignore[union-attr]303304 def play(self, speed: Optional[float] = None) -> None:305 with self._control_lock:306 self._play(speed)307308 def pause(self) -> None:309 with self._control_lock:310 self._pause()311312 def _release(self) -> None:313 # Retain ownership for retry if the child has not drained; do not let314 # the controller close its market while process cleanup is unconfirmed.315 if self._pacer is not None:316 self._pacer.stop()317 if self._process is not None:318 self._process.close()319 runtime = self._tools.controls.runtime320 if not runtime.snapshot()['closed']:321 runtime.close()322 self._tools.close() # Retain runner ownership if the tools child cannot close.323 self._recorder.close()324 self._closed = True325 if self._barrier is not None:326 self._barrier.resources_closed()327 self._on_close()328329 def close(self) -> None:330 if self._closed:331 return332 if self._process is not None:333 self._process.request_stop()334 try:335 if self._barrier is None:336 self._pipeline.close() # Roll back a failed, not-yet-bound host setup.337 else:338 self._barrier.stop()339 except Exception as exc:340 if self._pipeline.quiescent:341 cleanup_after_error(exc, self._release)342 raise343 self._release()344345 def __enter__(self) -> AgentDecisionRunner:346 self._check_open()347 return self