agentenv-framework 0.9.1254__py3-none-any.whl

agent_env/task_step/registry.py

@@ -0,0 +1,182 @@
+"""TaskStep registry for type-based deserialization."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from agent_env.plugins import _registration
+
+if TYPE_CHECKING:
+    from agent_env.task_step.task_step import TaskStep
+    from agent_env.config.runtime import Config
+
+# TaskStep defines this only to raise, so a registered class must override it.
+_MUST_IMPLEMENT = ("from_dict",)
+
+
+def _get_type(cls: type["TaskStep"]) -> str:
+    return cls.type
+
+
+
+
+def get_task_step_registry() -> dict[str, type["TaskStep"]]:
+    from agent_env.config import runtime
+
+    return runtime.get_config().task_step_registry()
+
+
+def _builtin_registry() -> dict[str, type["TaskStep"]]:
+    from agent_env.task_step.task_steps.collect_artifacts import CollectArtifactsTaskStep
+    from agent_env.task_step.task_steps.mcp_cli_builder.build_mcp_cli import BuildMcpCliTaskStep
+    from agent_env.task_step.task_steps.deploy_agent import DeployAgentTaskStep
+    from agent_env.task_step.task_steps.deploy_env import DeployEnvTaskStep
+    from agent_env.task_step.task_steps.deploy_human_agent import DeployHumanAgentTaskStep
+    from agent_env.task_step.task_steps.deploy_sandbox import DeploySandboxTaskStep
+    from agent_env.task_step.task_steps.reset_env import ResetEnvTaskStep
+    from agent_env.task_step.task_steps.teardown_sandboxes import TeardownSandboxesTaskStep
+    from agent_env.task_step.task_steps.verifiers.env_outcome_verifier import EnvOutcomeVerifierTaskStep
+    from agent_env.task_step.task_steps.load_artifact import LoadArtifactTaskStep
+    from agent_env.task_step.task_steps.modify_env_tool_access import ModifyEnvToolAccessStep
+    from agent_env.task_step.task_steps.prompt_agent import PromptAgentTaskStep
+    from agent_env.task_step.task_steps.register_env_triggers import RegisterEnvTriggersStep
+    from agent_env.task_step.task_steps.register_agent_triggers import RegisterAgentTriggersStep
+    from agent_env.task_step.task_steps.sync_env_clock import SyncEnvClockTaskStep
+    from agent_env.task_step.task_steps.install_agent import InstallAgentTaskStep
+    from agent_env.task_step.task_steps.verifiers.rubrics_verifier import RubricsVerifierTaskStep
+    from agent_env.task_step.task_steps.verifiers.run_container_unit_tests_verifier import RunContainerUnitTestsVerifierTaskStep
+    from agent_env.task_step.task_steps.run_docker_container import RunDockerContainerTaskStep
+    from agent_env.task_step.task_steps.mcp_env_validator.verify_mcp_tool_schema import VerifyMCPToolSchemaTaskStep
+    from agent_env.task_step.task_steps.mcp_env_validator.verify_spec_conformance import VerifySpecConformanceTaskStep
+    from agent_env.task_step.task_steps.mcp_env_validator.verify_mcp_env_assessment import VerifyMCPEnvAssessmentStep
+    from agent_env.task_step.task_steps.mcp_env_validator.validation_gate_aggregator import ValidationGateAggregatorStep
+    from agent_env.task_step.task_steps.multienv_validator.verify_universe_roundtrip import VerifyUniverseLoadExportRoundtripStep
+    from agent_env.task_step.task_steps.multienv_validator.combine_universe_verdicts import CombineUniverseVerdictsStep
+    from agent_env.task_step.task_steps.env_card_validator.verify_env_card import VerifyEnvironmentCardStep
+    from agent_env.task_step.task_steps.env_card_validator.verify_env_core_protocol import VerifyCoreEnvironmentProtocolStep
+    from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_agent_card import VerifyA2AAgentCardStep
+    from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_agent_config_identity import VerifyA2AAgentConfigIdentityStep
+    from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_agent_mcp import VerifyA2AAgentMCPStep
+    from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_core_protocol import VerifyCoreA2AProtocolStep
+    from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_modalities import VerifyA2AModalitiesStep
+    from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_peer_agents import VerifyA2APeerAgentsStep
+    from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_install import VerifyA2AInstallStep
+    from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_skill_config import VerifyA2ASkillConfigStep
+    from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_snapshot import VerifyA2ASnapshotStep
+    from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_trajectory import VerifyA2ATrajectoryStep
+    from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_role import VerifyA2ARoleStep
+    from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_system_prompt import VerifyA2ASystemPromptStep
+    from agent_env.task_step.task_steps.add_skills import AddSkillsTaskStep
+    from agent_env.task_step.task_steps.apply_server_config import ApplyServerConfigStep
+    from agent_env.task_step.task_steps.verifiers.agent_prompt_response_verifier import AgentPromptResponseVerifierTaskStep
+    from agent_env.task_step.task_steps.snapshot_agent_state import SnapshotAgentStateTaskStep
+    from agent_env.task_step.task_steps.snapshot_env import SnapshotEnvTaskStep
+    from agent_env.task_step.task_steps.peer_agents import PeerAgentsTaskStep
+    from agent_env.task_step.task_steps.verifiers.verify_sandbox import VerifySandboxTaskStep
+    from agent_env.task_step.task_steps.verifiers.aggregate_verifiers import AggregateVerifiersTaskStep
+    from agent_env.task_step.task_steps.run_code import RunCodeTaskStep
+    from agent_env.task_step.task_steps.review import ReviewTaskStep
+
+    return {
+        _get_type(ReviewTaskStep): ReviewTaskStep,
+        _get_type(BuildMcpCliTaskStep): BuildMcpCliTaskStep,
+        _get_type(CollectArtifactsTaskStep): CollectArtifactsTaskStep,
+        _get_type(DeployAgentTaskStep): DeployAgentTaskStep,
+        _get_type(DeployEnvTaskStep): DeployEnvTaskStep,
+        _get_type(DeployHumanAgentTaskStep): DeployHumanAgentTaskStep,
+        _get_type(DeploySandboxTaskStep): DeploySandboxTaskStep,
+        _get_type(ResetEnvTaskStep): ResetEnvTaskStep,
+        _get_type(TeardownSandboxesTaskStep): TeardownSandboxesTaskStep,
+        _get_type(EnvOutcomeVerifierTaskStep): EnvOutcomeVerifierTaskStep,
+        _get_type(LoadArtifactTaskStep): LoadArtifactTaskStep,
+        _get_type(ModifyEnvToolAccessStep): ModifyEnvToolAccessStep,
+        _get_type(PromptAgentTaskStep): PromptAgentTaskStep,
+        _get_type(RegisterEnvTriggersStep): RegisterEnvTriggersStep,
+        _get_type(RegisterAgentTriggersStep): RegisterAgentTriggersStep,
+        _get_type(SyncEnvClockTaskStep): SyncEnvClockTaskStep,
+        _get_type(InstallAgentTaskStep): InstallAgentTaskStep,
+        _get_type(RubricsVerifierTaskStep): RubricsVerifierTaskStep,
+        _get_type(RunContainerUnitTestsVerifierTaskStep): RunContainerUnitTestsVerifierTaskStep,
+        _get_type(RunDockerContainerTaskStep): RunDockerContainerTaskStep,
+        _get_type(VerifyMCPToolSchemaTaskStep): VerifyMCPToolSchemaTaskStep,
+        _get_type(VerifySpecConformanceTaskStep): VerifySpecConformanceTaskStep,
+        _get_type(VerifyMCPEnvAssessmentStep): VerifyMCPEnvAssessmentStep,
+        _get_type(ValidationGateAggregatorStep): ValidationGateAggregatorStep,
+        _get_type(VerifyUniverseLoadExportRoundtripStep): VerifyUniverseLoadExportRoundtripStep,
+        _get_type(CombineUniverseVerdictsStep): CombineUniverseVerdictsStep,
+        _get_type(VerifyEnvironmentCardStep): VerifyEnvironmentCardStep,
+        _get_type(VerifyCoreEnvironmentProtocolStep): VerifyCoreEnvironmentProtocolStep,
+        _get_type(VerifyA2AAgentCardStep): VerifyA2AAgentCardStep,
+        _get_type(VerifyA2AAgentConfigIdentityStep): VerifyA2AAgentConfigIdentityStep,
+        _get_type(VerifyA2AAgentMCPStep): VerifyA2AAgentMCPStep,
+        _get_type(VerifyA2ATrajectoryStep): VerifyA2ATrajectoryStep,
+        _get_type(VerifyA2AInstallStep): VerifyA2AInstallStep,
+        _get_type(VerifyA2ASkillConfigStep): VerifyA2ASkillConfigStep,
+        _get_type(AddSkillsTaskStep): AddSkillsTaskStep,
+        _get_type(ApplyServerConfigStep): ApplyServerConfigStep,
+        _get_type(AgentPromptResponseVerifierTaskStep): AgentPromptResponseVerifierTaskStep,
+        _get_type(VerifyCoreA2AProtocolStep): VerifyCoreA2AProtocolStep,
+        _get_type(SnapshotAgentStateTaskStep): SnapshotAgentStateTaskStep,
+        _get_type(SnapshotEnvTaskStep): SnapshotEnvTaskStep,
+        _get_type(RunCodeTaskStep): RunCodeTaskStep,
+        _get_type(PeerAgentsTaskStep): PeerAgentsTaskStep,
+        _get_type(VerifyA2ASnapshotStep): VerifyA2ASnapshotStep,
+        _get_type(VerifyA2APeerAgentsStep): VerifyA2APeerAgentsStep,
+        _get_type(VerifyA2AModalitiesStep): VerifyA2AModalitiesStep,
+        _get_type(VerifySandboxTaskStep): VerifySandboxTaskStep,
+        _get_type(AggregateVerifiersTaskStep): AggregateVerifiersTaskStep,
+        _get_type(VerifyA2ARoleStep): VerifyA2ARoleStep,
+        _get_type(VerifyA2ASystemPromptStep): VerifyA2ASystemPromptStep,
+    }
+
+
+def _build_registry(source: Config | None = None) -> dict[str, type["TaskStep"]]:
+    """The built-in task steps, then ``agent_env.task_steps`` plugins, then ``[task_steps] impls``
+    in ``source``."""
+    from agent_env.task_step.task_step import TaskStep
+
+    registry = _builtin_registry()
+    validate = _registration.typed_validator(TaskStep, builtins=frozenset(registry), required=_MUST_IMPLEMENT)
+    from_plugins = _registration.merge(registry, _registration.TASK_STEPS, validate, source=source)
+    _merge_config_toml_steps(registry, source=source, from_plugins=from_plugins)
+    return registry
+
+
+def _merge_config_toml_steps(
+    registry: dict[str, type["TaskStep"]],
+    *,
+    source: Config | None = None,
+    from_plugins: _registration.Registrations | None = None,
+) -> None:
+    from agent_env.config import runtime
+    from agent_env.config import ConfigError, load_impl
+    from agent_env.task_step.task_step import TaskStep
+
+    section = (source or runtime.get_config()).section("task_steps")
+    impls = section.get("impls", [])
+    if not isinstance(impls, list):
+        raise ConfigError(
+            f"[task_steps] impls must be a list of 'module:Class' strings, got {type(impls).__name__}"
+        )
+    from_plugins = from_plugins if from_plugins is not None else _registration.Registrations.empty()
+    for impl in impls:
+        if not isinstance(impl, str):
+            raise ConfigError(
+                f"[task_steps] impl must be a 'module:Class' string, got {type(impl).__name__}: {impl!r}"
+            )
+        cls = load_impl(impl, TaskStep)
+        if cls.type == TaskStep.type:
+            raise ConfigError(
+                f"[task_steps] impl {impl!r} does not define its own 'type' "
+                f"(inherits the base default {TaskStep.type!r}); set a unique 'type' ClassVar"
+            )
+        if problem := _registration.unimplemented(cls, TaskStep, _MUST_IMPLEMENT):
+            raise ConfigError(f"[task_steps] impl {impl!r}: {problem}")
+        if from_plugins.refuse(cls.type, f"[task_steps] impl {impl!r}"):
+            continue
+        if not from_plugins.release(cls.type, "task_steps", impl, cls) and cls.type in registry:
+            raise ConfigError(
+                f"[task_steps] impl {impl!r} type {cls.type!r} is already registered "
+                f"(conflicts with a built-in or another custom step)"
+            )
+        registry[cls.type] = cls

agent_env/task_step/review_store.py

@@ -0,0 +1,118 @@
+"""Store for human-in-the-loop review decisions, keyed by ``(instance_id, step_id)``.
+
+Both the worker (``ReviewTaskStep``) and the hub write here, so it lives in
+agent-env and the hub imports it.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional
+
+from agent_env.store import DuplicateKeyError, Eq, Filter, UpdateSpec, get_config
+
+logger = logging.getLogger(__name__)
+
+REVIEWS_COLLECTION = "task_reviews"
+
+AWAITING = "awaiting"
+CONTINUE = "continue"
+ABORT = "abort"
+_DECISIONS = (CONTINUE, ABORT)
+
+# Reap old coordination docs; window dwarfs any realistic review timeout, so active reviews never expire.
+_TTL = timedelta(days=7)
+
+
+class ReviewStore:
+    def __init__(self) -> None:
+        self._indexed = None
+
+    @property
+    def _doc_store(self):
+        # Resolved per call: a cached store outlives reset_config(), so a process that
+        # re-pointed would read the new config and write the old backend.
+        store = get_config().get_document_store()
+        if self._indexed is not store:
+            store.ensure_index(
+                REVIEWS_COLLECTION, ["instance_id", "step_id"], unique=True
+            )
+            store.ensure_index(
+                REVIEWS_COLLECTION, ["expires_at"], ttl_seconds=0
+            )
+            self._indexed = store
+        return store
+
+    @staticmethod
+    def _now() -> str:
+        return datetime.now(timezone.utc).isoformat()
+
+    def put_awaiting(
+        self,
+        instance_id: str,
+        step_id: str,
+        *,
+        label: Optional[str] = None,
+        upstream: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Register a review as awaiting a decision. Idempotent — a retry won't clobber a recorded decision."""
+        doc = {
+            "instance_id": instance_id,
+            "step_id": step_id,
+            "state": AWAITING,
+            "label": label,
+            "upstream": upstream or {},
+            "awaiting_at": self._now(),
+            "expires_at": datetime.now(timezone.utc) + _TTL,
+        }
+        try:
+            self._doc_store.insert(REVIEWS_COLLECTION, doc)
+        except DuplicateKeyError:
+            pass
+
+    def get(self, instance_id: str, step_id: str) -> Optional[dict[str, Any]]:
+        return self._doc_store.find_one(
+            REVIEWS_COLLECTION, Filter.of(instance_id=instance_id, step_id=step_id)
+        )
+
+    def set_decision(
+        self,
+        instance_id: str,
+        step_id: str,
+        decision: str,
+        *,
+        decided_by: Optional[str] = None,
+    ) -> bool:
+        """Record ``continue``/``abort`` on an awaiting review; False if none was awaiting."""
+        if decision not in _DECISIONS:
+            raise ValueError(f"decision must be one of {_DECISIONS}, got {decision!r}")
+        matched = self._doc_store.update(
+            REVIEWS_COLLECTION,
+            Filter.of(instance_id=instance_id, step_id=step_id).where("state", Eq(AWAITING)),
+            UpdateSpec(
+                set={"state": decision, "decided_by": decided_by, "decided_at": self._now()}
+            ),
+        )
+        return matched > 0
+
+    def list_awaiting(self, instance_id: Optional[str] = None) -> list[dict[str, Any]]:
+        filt = Filter.of(state=AWAITING)
+        if instance_id is not None:
+            filt = filt.where("instance_id", Eq(instance_id))
+        return self._doc_store.query(REVIEWS_COLLECTION, filt)
+
+
+_store: Optional[ReviewStore] = None
+
+
+def get_review_store() -> ReviewStore:
+    global _store
+    if _store is None:
+        _store = ReviewStore()
+    return _store
+
+
+def reset_review_store() -> None:
+    global _store
+    _store = None

agent_env/task_step/snapshot_utils/__init__.py

@@ -0,0 +1,2 @@
+"""Agent-state capture. Separate from ``task_steps`` because none of it is a
+``TaskStep`` subclass."""

agent_env/task_step/snapshot_utils/agent_state_capture.py

@@ -0,0 +1,261 @@
+"""The reads a capture makes against a running agent's sidecar.
+
+``capture_workspace`` raises on any failure — without the tar there is nothing to
+grade — while ``read_partial_trajectory`` never does, because the bundle alone is
+what makes a point gradable.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import uuid
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import httpx
+from agentenv_protocol.a2a_agent import ObjectSnapshotSaveResponse
+
+from agent_env.a2a_agent import A2AAgent
+from agent_env.a2a_agent.object_transfer import (
+    SNAPSHOT_TRAJECTORY_OBJECT_NAME,
+    SNAPSHOT_WORKSPACE_OBJECT_NAME,
+    FetchedTrajectory,
+    TrajectoryUpload,
+    bounded_echo,
+    fetch_trajectory,
+    invoke_transfer,
+    snapshot_save_call,
+    trajectory_mode,
+)
+from agent_env.config import get_config
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class WorkspaceCapture:
+    """One ``/ext/snapshot`` call plus the ``FileArtifactUniverse`` wrapping it."""
+
+    universe_id: str
+    universe_version: Optional[int]
+    # Where the files landed; what restores.
+    bundle_object_url: str
+    # What was presigned — not always where the agent wrote. Per-service state,
+    # captured alongside, still goes here.
+    capture_prefix: str
+
+
+@dataclass
+class TrajectoryCapture:
+    trajectory: Any = None
+    object_url: str | None = None
+    # Non-None means this read produced no trajectory; the caller records it as a
+    # `partial` capture reason.
+    reason: Optional[str] = None
+
+
+async def capture_workspace(
+    *,
+    a2a_url: str,
+    a2a_card: dict,
+    agent_name: str,
+    a2a_context_id: str,
+    artifact_id: str,
+    timeout_seconds: float,
+) -> WorkspaceCapture:
+    """Tar the agent's workspace to a fresh S3 prefix and wrap it as a universe.
+
+    Raises on any failure — without the tar there is nothing to grade."""
+    from agent_env.artifact.store import get_artifact_store
+
+    snapshot_ext = A2AAgent.find_extension(a2a_card or {}, A2AAgent.EXT_SNAPSHOT)
+    if not snapshot_ext:
+        raise RuntimeError(f"Agent '{agent_name}' does not advertise the snapshot extension")
+    save_method, save_path = A2AAgent.operation(snapshot_ext, "save")
+
+    # The random suffix, not the version, isolates captures: two concurrent ones
+    # can peek the same version. to_thread because this loop is shared by every
+    # concurrent rollout, so a blocking call here stalls their poll loops.
+    snapshot_version = await asyncio.to_thread(get_artifact_store().next_version, artifact_id)
+    config = get_config()
+    capture_key_prefix = (
+        f"{config.get_artifact_key_prefix()}agent_snapshots/{artifact_id}/{snapshot_version}-{uuid.uuid4().hex[:8]}/"
+    )
+    store = config.get_object_store()
+    capture_prefix = store.object_url(capture_key_prefix)
+
+    call = await asyncio.to_thread(
+        snapshot_save_call,
+        save_method,
+        store,
+        agent_name=agent_name,
+        context_id=a2a_context_id,
+        capture_prefix=capture_prefix,
+    )
+    save_body = await invoke_transfer(
+        a2a_url + save_path,
+        call,
+        verb="POST",
+        operation="snapshot save",
+        timeout=timeout_seconds,
+        response_model=ObjectSnapshotSaveResponse,
+    )
+
+    if call.mode == "objects":
+        # The agent's answer is only a claim: a snapshot missing either object cannot be restored.
+        listed = await asyncio.to_thread(store.list_at, capture_prefix)
+        stored = {url.rsplit("/", 1)[-1] for url in listed}
+        missing = {SNAPSHOT_TRAJECTORY_OBJECT_NAME, SNAPSHOT_WORKSPACE_OBJECT_NAME} - stored
+        if missing:
+            raise RuntimeError(
+                f"snapshot save from agent '{agent_name}' left {sorted(missing)} out of the object store"
+            )
+        registered_prefix = capture_prefix
+    else:
+        echoed = save_body.get("s3_prefix")
+        if not echoed:
+            raise RuntimeError(f"snapshot save response missing 's3_prefix': {save_body}")
+        registered_prefix = bounded_echo(capture_prefix, echoed)
+
+    from agent_env.artifact.artifacts.file_artifact_universe import FileArtifactUniverse
+
+    # Unserialized — a concurrent version race on one artifact id is
+    # `ArtifactStore.put_document`'s retry to absorb.
+    universe = await asyncio.to_thread(
+        FileArtifactUniverse.put_existing, id=artifact_id, s3_url=registered_prefix
+    )
+    # `put_existing` always sets it, but the field is Optional on the artifact, and a
+    # row carrying None here would read as an ungradable capture rather than an error.
+    if not universe.bundle_object_url:
+        raise RuntimeError(
+            f"FileArtifactUniverse {universe.id} v{universe.version} registered no "
+            f"bundle url for {registered_prefix}"
+        )
+    logger.info(
+        "Snapshot captured: agent=%s context_id=%s -> FileArtifactUniverse %s v%s at %s",
+        agent_name, a2a_context_id, universe.id, universe.version,
+        universe.bundle_object_url,
+    )
+    return WorkspaceCapture(
+        universe_id=universe.id,
+        universe_version=universe.version,
+        bundle_object_url=universe.bundle_object_url,
+        capture_prefix=capture_prefix,
+    )
+
+
+async def read_partial_trajectory(
+    *,
+    a2a_url: str,
+    a2a_card: dict,
+    context_id: str,
+    timeout_seconds: float,
+    trajectory_output_prefix: str,
+) -> TrajectoryCapture:
+    """Read the trajectory-so-far for an in-progress run.
+
+    Separate from the workspace bundle because not every harness's snapshot
+    carries the transcript, which would leave interior points with no trajectory.
+
+    Served by ``get`` in its ``context_id`` mode — cumulative, and keyed on the a2a
+    context id each image maps to its own session. An agent advertising ``get`` as
+    ``task_id``-only cannot answer this: a task id names one finished turn, which
+    404s while the run it belongs to is still going.
+
+    Never raises: a failure yields a ``reason`` the caller records as ``partial``,
+    so an agent serving neither shape still yields a usable curve minus the
+    trajectory column.
+    """
+    traj_ext = A2AAgent.find_extension(a2a_card or {}, A2AAgent.EXT_TRAJECTORY)
+    if not traj_ext:
+        return TrajectoryCapture(reason="trajectory_ext_unavailable")
+    # Presence, not truthiness: a card may advertise a method as a bare `{}`,
+    # which is falsy. Testing truth would read such a card as not having it.
+    get_method, get_path = A2AAgent.operation(traj_ext, "get")
+    if get_method is None:
+        return TrajectoryCapture(reason="trajectory_get_unadvertised")
+    # Only an explicit request contract offers the context mode: a `get` that declares
+    # none may be task_id-only, and would 400 on every tick.
+    if "request" not in get_method:
+        return TrajectoryCapture(reason="trajectory_context_unsupported")
+    store = get_config().get_object_store()
+    mode = trajectory_mode(get_method, store, by="context_id")
+    if mode is None:
+        return TrajectoryCapture(reason="trajectory_context_unsupported")
+
+    upload = None
+    if mode == "objects":
+        try:
+            object_url = trajectory_object_url(trajectory_output_prefix, store=store)
+            upload = await asyncio.to_thread(TrajectoryUpload.to, store, object_url)
+        except Exception as exc:
+            logger.warning("partial trajectory grant failed for %s: %s", context_id, exc)
+            return TrajectoryCapture(reason="trajectory_grant_unavailable")
+    try:
+        fetched = await fetch_trajectory(
+            a2a_url + get_path, {"context_id": context_id}, upload=upload, timeout=timeout_seconds
+        )
+    except httpx.HTTPStatusError as exc:
+        if exc.response.status_code == 404:
+            # No transcript yet — the agent hasn't written a turn.
+            return TrajectoryCapture(reason="trajectory_session_missing")
+        return TrajectoryCapture(reason=f"trajectory_http_{exc.response.status_code}")
+    except Exception as exc:
+        logger.warning("partial trajectory read failed for %s: %s", context_id, exc)
+        return TrajectoryCapture(reason="trajectory_read_failed")
+
+    if fetched.object_url is not None:
+        return TrajectoryCapture(object_url=fetched.object_url)
+    if not fetched.inline:
+        return TrajectoryCapture(reason="trajectory_empty")
+    return TrajectoryCapture(trajectory=fetched.inline)
+
+
+def upload_trajectory(
+    trajectory: Any, trajectory_output_prefix: str, *, name: Optional[str] = None
+) -> str:
+    """Serialize a trajectory payload and store it, returning its object URL.
+
+    Always uploaded from the worker side, never by the agent: sandbox VMs hold
+    static STS env vars with a fixed expiry, and long runs exceed it.
+
+    ``name`` makes the object addressable by an id the caller already records
+    (#731); omit it to get a random one, which is what writing repeatedly under a
+    single prefix needs, since a fixed name would overwrite the last upload.
+    """
+
+    store = get_config().get_object_store()
+    # Via the store, not urlparse().path: a prefix naming a different bucket
+    # must fail loudly, not silently write to the configured one.
+    prefix_key = store.get_object_key(trajectory_output_prefix)
+    if prefix_key and not prefix_key.endswith("/"):
+        prefix_key += "/"
+    key = f"{prefix_key}trajectory-{name or uuid.uuid4().hex[:12]}.json"
+    body = json.dumps(trajectory, indent=2, default=str).encode()
+    return store.put(key, body, content_type="application/json")
+
+
+def store_trajectory(
+    fetched: FetchedTrajectory, trajectory_output_prefix: str, *, name: Optional[str] = None
+) -> str | None:
+    """The URL of a fetched trajectory, storing it first when the agent returned it inline."""
+    if fetched.object_url is not None:
+        return fetched.object_url
+    if fetched.legacy_prefix:
+        urls = get_config().get_object_store().list_at(fetched.legacy_prefix)
+        return urls[0] if urls else None
+    if fetched.inline is not None:
+        return upload_trajectory(fetched.inline, trajectory_output_prefix, name=name)
+    return None
+
+
+def trajectory_object_url(
+    trajectory_output_prefix: str, *, store, name: Optional[str] = None
+) -> str:
+    """Return the durable URL used for one agent-written trajectory."""
+    prefix_key = store.get_object_key(trajectory_output_prefix)
+    if prefix_key and not prefix_key.endswith("/"):
+        prefix_key += "/"
+    key = f"{prefix_key}trajectory-{name or uuid.uuid4().hex[:12]}.json"
+    return store.object_url(key)