m/market labResearch, with a record.
Source on GitHub ↗

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