Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .agentenv/config.example.toml
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,8 @@ agent_default = "local" # agents too

# [trajectories]
# formats = ["atif/1"] # the formats beside native a run prescribes to each agent whose trajectory it reads;
# # none by default, so agents build native only. Per run: user_overrides.trajectory_formats
# # none by default, so agents build native only. Per run: user_overrides.trajectory_formats.
# # With atif/1, prompt steps store each turn's copy under {prefix}atif/instance_id=<id>/<agent>/

# [envs]
# default_gateway_env_id = "default" # the gateway every gateway deploy runs
Expand Down
7 changes: 6 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,12 @@ or one of them only where it is used.
agent whose trajectory it reads (prompt_agent and always_on call the trajectory extension's `prescribe` on the agent
they prompt before its conversation starts); a run's `user_overrides.trajectory_formats` beats it. None by default,
so an agent builds native only, and an `atif/1` read of a conversation not prescribed it is refused
(`format_not_prescribed`).
(`format_not_prescribed`). A prompt step of a run that prescribes `atif/1` reads each turn's copy inline once the
turn ends, off the turn's path, and stores it as `<trajectory_id>.json` under `{prefix}atif/instance_id=<id>/<agent>/`
(`metadata["atif_copies"]`, `task_step/snapshot_utils/atif_copies.py`), overwritten each turn, with the turn's aux
log and turn context under `turns/` and the media it names pulled into `media/`; after a restart the session's
earlier document names the next in `continued_trajectory_ref`. Each turn's record says how its copy checked
(`AtifRecord`: `valid`, `invalid`, `newer`, `unavailable`), and a copy never fails the run; judges read native.
- Secrets never live in the file: use `secret:KEY` or `env:NAME` references, resolved through
`[stores.secret]`.
- agent-env has no stage concept: "dev" versus "prod" is which file `AGENT_ENV_CONFIG` names. A
Expand Down
6 changes: 4 additions & 2 deletions packages/agentenv-protocol/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1307,8 +1307,10 @@ the profile's spec, and `fixtures/` holds its canonical examples. The package ne
terminal state on its last step. Its `page()` is the live view, built when it's read: closed steps only, so a
reader's earlier page is always a prefix of a later one. A step is rendered once a page serves it and kept, so a
read costs one parse of the document, not a render of every step.
- **Readers** (`load`, `tasks`, `media_paths`, `strip_profile`, `is_prefix`) take any valid ATIF document, with or
without the profile, such as a Harbor task's trajectory.json.
- **Readers** (`load`, `tasks`, `media_paths`, `media_refs`, `strip_profile`, `is_prefix`) take any valid ATIF
document, with or without the profile, such as a Harbor task's trajectory.json. `media_refs` names each place a media
file is named, with the profile's details for it; `validate(document, media=StoredMedia(sizes))` checks those
details against files stored beside the document without reading their bytes.

## A2A agent framework

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,10 @@ cross-check that reads them; per-part origins, when a reader needs them; and an
producer's output to profile 1.0. `reader=True` checks someone else's document for reading instead: what a producer
must not write only warns, and the document fails only where agentenv couldn't read it. `media` is the folder the
document's media paths are relative to, the one holding `media/`, or the files by path; without it only the paths' form
is checked. `validate_live(pages, final)` checks what a live reader was served, page by page, with the final read. A sub-agent's task is its spawning call's, found through the references, so an embedded sub-agent that no served step references isn't held to `live-unanswered`. On
is checked. `StoredMedia(sizes)` stands for files stored beside the document whose bytes were checked against their
names as they were stored, as agent-env's worker checks each file an agent pushes: `media-bytes` then holds the
profile's sha256 to each file's name and its size to the stored one, without reading the bytes. `media_refs` lists each
place a document names a media file, with the profile's details for it, as these checks walk them. `validate_live(pages, final)` checks what a live reader was served, page by page, with the final read. A sub-agent's task is its spawning call's, found through the references, so an embedded sub-agent that no served step references isn't held to `live-unanswered`. On
the command line: `python -m agentenv_protocol.atif validate FILE [--media DIR] [--reader]`, which prints each finding
and exits 1 when one is an error.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -46,20 +46,33 @@
read_profile,
)
from .kit import KIT_RULES, KitResult, check_adapter
from .reader import MEDIA_PATH, Task, check, check_media, is_prefix, load, media_file, media_paths, strip_profile, tasks
from .reader import (
MEDIA_PATH,
MediaRef,
Task,
check,
check_media,
is_prefix,
load,
media_file,
media_paths,
media_refs,
strip_profile,
tasks,
)
from .runner import AdapterRun, Fed, RecordedTask, replay
from .served import AuxEntry, ContentItem, MediaItem, ServedData, ServedError, ServedMedia, ServedTurn
from .validator import RULES, Finding, Rule, errors_in, validate, validate_live
from .validator import RULES, Finding, Rule, StoredMedia, errors_in, validate, validate_live

__all__ = [
"Adapter", "AdapterRef", "AdapterRun", "AdapterSpec", "Agent", "AgentProfile", "Arrival", "atif_adapter",
"AtifError", "AtifTurn", "AudioSource", "aux", "AuxEntry", "check", "check_adapter", "check_media", "ContentItem", "ContentPart",
"Document", "dump_profile", "errors_in", "Fed", "FinalMetrics", "FinalMetricsProfile", "Finding", "finish",
"FORMAT", "ImageSource", "is_prefix", "KIT_RULES", "KitResult", "load", "Media", "MEDIA_PATH", "media_file", "media_paths", "MediaInfo",
"MediaItem", "Metrics", "MetricsProfile", "Native", "native", "Observation", "ObservationResult",
"MediaItem", "MediaRef", "media_refs", "Metrics", "MetricsProfile", "Native", "native", "Observation", "ObservationResult",
"ObservationResultProfile", "PROFILE_KEY", "profile_of", "PROFILE_VERSION", "PROFILES", "RAW_ARGUMENTS",
"read_profile", "ReasoningBlock", "RecordedTask", "replay", "Rule", "RULES", "SCHEMA_VERSION", "Selector",
"ServedData", "ServedError", "ServedMedia", "ServedTurn", "Step", "StepData", "StepError", "StepProfile",
"ServedData", "ServedError", "ServedMedia", "ServedTurn", "Step", "StepData", "StepError", "StepProfile", "StoredMedia",
"strip_profile", "SubagentTrajectoryRef", "SubagentTrajectoryRefProfile", "Task", "tasks", "timestamp", "ToolCall",
"ToolCallProfile", "Trajectory", "TrajectoryProfile", "TurnContext", "validate", "validate_live", "VOCABULARIES",
]
71 changes: 51 additions & 20 deletions packages/agentenv-protocol/src/agentenv_protocol/atif/reader.py
Original file line number Diff line number Diff line change
Expand Up @@ -85,14 +85,11 @@ def tasks(document: Mapping[str, Any]) -> list[Task]:
return out


def _trajectories(document: Mapping[str, Any]) -> Iterator[Mapping[str, Any]]:
yield document
for sub in document.get("subagent_trajectories") or []:
yield from _trajectories(sub)


def _parts(value: Any) -> list[Mapping[str, Any]]:
return [p for p in value if isinstance(p, Mapping)] if isinstance(value, list) else []
def _trajectories(document: Mapping[str, Any], prefix: str = "") -> Iterator[tuple[str, Mapping[str, Any]]]:
"""The document and every sub-agent embedded in it, at any depth, with the path prefix of each."""
yield prefix, document
for index, sub in enumerate(document.get("subagent_trajectories") or []):
yield from _trajectories(sub, f"{prefix}subagent_trajectories[{index}].")


#: A media file's name, ``<sha256>.<ext>``: what its bytes are, never a secret.
Expand All @@ -118,21 +115,55 @@ def check_media(path: str, data: bytes) -> None:
raise AtifError(f"{path}'s bytes have sha256 {digest}")


@dataclass(frozen=True)
class MediaRef:
"""One place a document names a media file: its ``path``, ``where`` it's named (such as
``steps[2].message[1].source.path``), the profile's details for it ({} without) and the media type of the part
that names it, else the details' own."""

path: str
where: str
info: Mapping[str, Any]
media_type: str | None


def media_refs(document: Mapping[str, Any]) -> list[MediaRef]:
"""Every place the document and the sub-agents embedded in it name a media file, in order: in each step's message
and each result's content, the image and audio parts' paths, then the files the profile records beside them for
media ATIF has no part type for."""
refs: list[MediaRef] = []
for prefix, trajectory in _trajectories(document):
for index, step in enumerate(trajectory.get("steps") or []):
where = f"{prefix}steps[{index}]"
holders = [(where, step, step.get("message"), "message")] + [
(f"{where}.observation.results[{n}]", result, result.get("content"), "content")
for n, result in enumerate((step.get("observation") or {}).get("results") or [])]
for owner, holder, content, field_name in holders:
details = profile_of(holder).get("media") or {}
details = details if isinstance(details, Mapping) else {}
named: set[str] = set()
for n, part in enumerate(content if isinstance(content, list) else []):
source = part.get("source") if isinstance(part, Mapping) else None
if isinstance(source, Mapping) and isinstance(source.get("path"), str):
path, info = source["path"], _details(details, source["path"])
named.add(path)
refs.append(MediaRef(path, f"{owner}.{field_name}[{n}].source.path", info,
source.get("media_type") or info.get("media_type")))
refs += [MediaRef(path, f"{owner}.extra.{PROFILE_KEY}.media[{path}]", _details(details, path),
_details(details, path).get("media_type"))
for path in details if path not in named]
return refs


def _details(details: Mapping[str, Any], path: str) -> Mapping[str, Any]:
info = details.get(path)
return info if isinstance(info, Mapping) else {}


def media_paths(document: Mapping[str, Any]) -> list[str]:
"""Every media file the document names, once each, in the order they appear: image and audio parts' paths, and
the files the profile records for media ATIF has no part type for."""
seen: dict[str, None] = {}
for trajectory in _trajectories(document):
for step in trajectory.get("steps") or []:
holders = [step] + list((step.get("observation") or {}).get("results") or [])
for holder in holders:
for part in _parts(holder.get("message") if holder is step else holder.get("content")):
path = (part.get("source") or {}).get("path")
if isinstance(path, str):
seen.setdefault(path)
for path in profile_of(holder).get("media") or {}:
seen.setdefault(path)
return list(seen)
return list(dict.fromkeys(ref.path for ref in media_refs(document)))


def strip_profile(document: Mapping[str, Any]) -> dict[str, Any]:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@
StepError,
profile_of,
)
from .reader import MEDIA_PATH, is_prefix, tasks
from .reader import MEDIA_PATH, _trajectories, is_prefix, media_refs, tasks

ERROR = "error"
WARNING = "warning"
Expand Down Expand Up @@ -131,17 +131,26 @@ def no_constant(name: str) -> Any:
return None, [Finding("json", ERROR, "", str(exc))]


@dataclass(frozen=True)
class StoredMedia:
"""Media files stored beside a document by one who checked each file's bytes against its name, as the worker does
each file an agent pushes: their sizes by path, None where the store can't tell. Given these, ``validate`` holds
the profile's sha256 to each name and its size to the stored file's without reading the bytes."""

sizes: Mapping[str, int | None]


def validate(document: Any, *, reader: bool = False,
media: Path | Mapping[str, bytes] | None = None) -> list[Finding]:
media: Path | Mapping[str, bytes] | StoredMedia | None = None) -> list[Finding]:
"""Every finding for ``document``. ``reader`` checks someone else's document for reading rather than a producer's
output. ``media`` is the folder the document's media paths are relative to, or the files by path; without it, only
the paths' form is checked."""
output. ``media`` is the folder the document's media paths are relative to, the files by path, or the files stored
beside it (``StoredMedia``); without it, only the paths' form is checked."""
found = _Findings(reader)
_check(document, found, media)
return found.items


def _check(document: Any, found: _Findings, media: Path | Mapping[str, bytes] | None) -> None:
def _check(document: Any, found: _Findings, media: Path | Mapping[str, bytes] | StoredMedia | None) -> None:
if not isinstance(document, Mapping):
found.add("json", "", "a document is a JSON object")
return
Expand Down Expand Up @@ -210,13 +219,6 @@ def validate_live(pages: Sequence[Mapping[str, Any] | None], final: Mapping[str,

# What the document holds

def _trajectories(document: Mapping[str, Any], prefix: str = "") -> Iterator[tuple[str, Mapping[str, Any]]]:
"""The document and every sub-agent embedded in it, at any depth, with the path prefix of each."""
yield prefix, document
for index, sub in enumerate(document.get("subagent_trajectories") or []):
yield from _trajectories(sub, f"{prefix}subagent_trajectories[{index}].")


def _count(value: Any) -> int | None:
"""A token count as ATIF's models read it, a numeric string included, or None when there is none."""
try:
Expand Down Expand Up @@ -397,8 +399,10 @@ def _usage(document: Mapping[str, Any], found: _Findings) -> None:
f"cache reads and writes ({cache}) exceed prompt_tokens ({prompt}), which include them")


def _media(document: Mapping[str, Any], found: _Findings, media: Path | Mapping[str, bytes] | None) -> None:
for where, path, info in _media_paths(document):
def _media(document: Mapping[str, Any], found: _Findings,
media: Path | Mapping[str, bytes] | StoredMedia | None) -> None:
for ref in media_refs(document):
where, path, info = ref.where, ref.path, ref.info
if "://" in path:
found.add("media-path", where, f"{path!r} is a URL; the profile's media are files beside the document")
continue
Expand All @@ -407,6 +411,9 @@ def _media(document: Mapping[str, Any], found: _Findings, media: Path | Mapping[
found.add("media-path", where, f"{path!r} isn't media/<sha256>.<ext>")
if media is None:
continue
if isinstance(media, StoredMedia):
_stored(found, where, path, named, info, media)
continue
data = _media_bytes(media, path)
if data is None:
found.add("media-bytes", where, f"{path} isn't in the media given")
Expand All @@ -420,24 +427,16 @@ def _media(document: Mapping[str, Any], found: _Findings, media: Path | Mapping[
found.add("media-bytes", where, f"the profile gives {info['bytes']} bytes, but the file has {len(data)}")


def _media_paths(document: Mapping[str, Any]) -> Iterator[tuple[str, str, Mapping[str, Any]]]:
"""Each media path the document names, where, and the profile's details for it."""
for where, step in _steps(document):
holders = [(f"{where}.message", step, step.get("message"))] + [
(f"{where}.observation.results[{n}].content", result, result.get("content"))
for n, result in enumerate(_results(step))]
for at, holder, parts in holders:
details = profile_of(holder).get("media") or {}
details = details if isinstance(details, Mapping) else {}
paths = [(f"{at}[{n}].source.path", part["source"]["path"])
for n, part in enumerate(parts if isinstance(parts, list) else [])
if isinstance(part, Mapping) and isinstance((part.get("source") or {}).get("path"), str)]
listed = {path for _, path in paths}
owner = at.rsplit(".", 1)[0]
paths += [(f"{owner}.extra.{PROFILE_KEY}.media[{path}]", path) for path in details if path not in listed]
for path_where, path in paths:
info = details.get(path)
yield path_where, path, info if isinstance(info, Mapping) else {}
def _stored(found: _Findings, where: str, path: str, named: re.Match[str] | None, info: Mapping[str, Any],
media: StoredMedia) -> None:
if path not in media.sizes:
found.add("media-bytes", where, f"{path} isn't in the media given")
return
if named and info.get("sha256") is not None and info["sha256"] != named["sha256"]:
found.add("media-bytes", where, f"the profile gives sha256 {info['sha256']}, but the name has {named['sha256']}")
size = media.sizes[path]
if info.get("bytes") is not None and size is not None and info["bytes"] != size:
found.add("media-bytes", where, f"the profile gives {info['bytes']} bytes, but the file has {size}")


def _media_bytes(media: Path | Mapping[str, bytes], path: str) -> bytes | None:
Expand Down
15 changes: 14 additions & 1 deletion packages/agentenv-protocol/tests/test_atif_reader.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

import pytest

from agentenv_protocol.atif import AtifError, check, is_prefix, load, media_paths, strip_profile, tasks
from agentenv_protocol.atif import AtifError, check, is_prefix, load, media_paths, media_refs, strip_profile, tasks
from atif_cases import FIXTURES


Expand Down Expand Up @@ -52,6 +52,19 @@ def test_media_paths_lists_every_file_once_including_the_ones_atif_has_no_part_f
assert all((FIXTURES / path).exists() for path in media_paths(fixture(name)))


def test_media_refs_name_each_place_a_file_is_named_with_its_details_and_media_type():
refs = media_refs(fixture("computer_use"))
assert list(dict.fromkeys(ref.path for ref in refs)) == media_paths(fixture("computer_use"))
part = next(ref for ref in refs if ref.where.endswith(".source.path"))
assert part.media_type and part.media_type.startswith("image/") and part.info.get("sha256") == part.path[6:70]
odd = media_refs(fixture("odd_parts"))
noted = [ref for ref in odd if ".extra.agentenv.media[" in ref.where]
assert noted and all(ref.media_type == ref.info.get("media_type") for ref in noted)
nested = {**fixture("coding"), "subagent_trajectories": [fixture("computer_use")]}
assert all(ref.where.startswith("subagent_trajectories[0].steps[") for ref in media_refs(nested))
assert len(media_refs(nested)) == len(refs)


def test_a_page_is_a_prefix_only_when_its_steps_lead_every_trajectory():
final = fixture("subagent")
page = {**final, "steps": final["steps"][:2],
Expand Down
Loading
Loading