Skip to content
Merged
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
30 changes: 30 additions & 0 deletions packages/agentenv-protocol/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1666,6 +1666,36 @@ extension names the state the SDK keeps (`"state": ["turns"]` in its params,
`SNAPSHOT_STATE_PARAM`), and agent-env grants the object only to an agent whose
card has it, since an SDK from before it refuses the object.

Every `atif/1` read leaves out the secrets the SDK knows, each written
`[redacted:<length>]` wherever it occurs: in the document, the aux log and the
turn context, inline, uploaded and in cursor pages, whose byte budget counts
what they serve. The SDK knows:

- its control token, and the model credentials in its environment:
`LITELLM_API_KEY` and the values of `LITELLM_EXTRA_HEADERS`;
- write-only agent-config values: a string whole, and in a mapping what a
credential-like key names (`Authorization`, `api_key`, `token`, `password`,
...), so a mapping of sampling parameters keeps its ordinary words;
- an MCP registration's header values and credential-like query values, and a
CDP endpoint's header values and the token in its URLs;
- every transfer grant an extension call hands the agent: the parts of its URL
that carry the credential (a presigned URL's credential-like query values,
`X-Amz-Signature` but not `X-Amz-Algorithm`, decoded and as the URL writes
them; else a token-like path segment; a password), its headers other than `Content-Type` and the
like, and a signed upload form's signing fields. Every copy of the URL holds
those parts, so a URL an agent prints keeps its host and path and loses its
signature;
- a clock follower's read token;
- whatever the agent registers with `self.register_secret(value)`, once its app
exists (in `run`, say).

They're taken from each extension call before any handler runs, the agent's own
included. A value under 8 characters isn't scrubbed, with a warning naming where
it came from. Each is matched raw, JSON-escaped and percent-encoded, the longest
first, and a read scrubs as it serves, so a secret learned after a step was
written is left out too. Native reads keep every secret byte for byte, so a
replay of the served inputs holds what the served copy redacts.

`enable(..., description="...")` is reserved for declarations carrying
configuration or metadata. It preserves the agent-specific extension prose
published in the Agent Card. The versioned SDK definition provides a generic
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
from contextlib import contextmanager
from dataclasses import dataclass, field
from datetime import datetime, timezone
from typing import Any, Iterable, Iterator, Sequence
from typing import Any, Callable, Iterable, Iterator, Sequence
from urllib.parse import urlsplit, urlunsplit

from ..atif import FORMAT, Adapter, AdapterRun, AuxEntry, Media, ServedTurn, TurnContext
Expand Down Expand Up @@ -64,12 +64,15 @@ class AtifPage:


class AtifCopy:
"""One A2A context's atif/1 document. Safe to feed from the agent's thread while the loop reads it."""
"""One A2A context's atif/1 document. Safe to feed from the agent's thread while the loop reads it. Everything it
serves goes through ``scrub``, the agent's secrets redacted."""

def __init__(self, adapter: type[Adapter], context_id: str) -> None:
def __init__(self, adapter: type[Adapter], context_id: str, *,
scrub: Callable[[Any], Any] = lambda served: served) -> None:
self._run = AdapterRun(adapter, trajectory_id=uuid.uuid4().hex)
self._adapter = adapter.__name__
self._context_id = context_id
self._scrub = scrub
self._lock = threading.Lock()
self._tasks: dict[str, _Task] = {}
self._failed: str | None = None
Expand Down Expand Up @@ -126,28 +129,32 @@ def end(self, task_id: str, *, state: str, final: Sequence[Any] = (), error: Tas
task.turn = ServedTurn.of(task.context, **ending)
task.ended = True

def task_read(self, task_id: str) -> tuple[dict[str, Any], list[AuxEntry], ServedTurn] | None:
"""An ended task's document as it stood when the task ended, its aux log and its served turn context."""
def task_read(self, task_id: str) -> tuple[dict[str, Any], list[dict[str, Any]], dict[str, Any]] | None:
"""An ended task's document as it stood when the task ended, its aux log and its served turn context, as served:
on the wire and scrubbed."""
with self._lock:
self._check()
task = self._tasks.get(task_id)
if task is None or task.turn is None:
return None
document = self._run.document(through=task.place)
assert document is not None
return document, list(task.aux), task.turn
return (self._scrub(document), self._scrub([entry.wire() for entry in task.aux]),
self._scrub(task.turn.wire()))

def context_read(self) -> dict[str, Any] | None:
"""The context's live page: every closed step a reader may be served, or None before the first."""
with self._lock:
self._check()
return self._run.page()
page = self._run.page()
return None if page is None else self._scrub(page)

def page(self, after: int, max_steps: int, max_bytes: int, *, task_id: str | None = None) -> AtifPage:
"""The closed steps after step ``after``, of the whole context or of task ``task_id``, within both budgets; the
first is always returned, so one larger than ``max_bytes`` can't stall a reader. With them, the sub-agents of
every task they belong to, as far as each is served: a sub-agent can gain steps while its task runs, and the
page that serves a task's last step, which closes only as the task ends, carries them whole."""
page that serves a task's last step, which closes only as the task ends, carries them whole. The byte budget
counts what it serves, scrubbed."""
with self._lock:
self._check()
document = self._run.page()
Expand All @@ -162,21 +169,25 @@ def page(self, after: int, max_steps: int, max_bytes: int, *, task_id: str | Non
served: list[dict[str, Any]] = []
tasks: set[str | None] = set()
used = 0
last = after
for step, owner in pending[:max_steps]:
size = len(json.dumps(step))
scrubbed = self._scrub(step)
size = len(json.dumps(scrubbed))
if served and used + size > max_bytes:
break
served.append(step)
served.append(scrubbed)
tasks.add(owner)
used += size
last = step["step_id"]
header = None
subagents: list[dict[str, Any]] = []
if document is not None:
header = {key: value for key, value in document.items() if key not in ("steps", "subagent_trajectories")}
subagents = [sub for sub in document.get("subagent_trajectories", [])
if sub_tasks.get(sub["trajectory_id"]) in tasks]
header = self._scrub({key: value for key, value in document.items()
if key not in ("steps", "subagent_trajectories")})
subagents = self._scrub([sub for sub in document.get("subagent_trajectories", [])
if sub_tasks.get(sub["trajectory_id"]) in tasks])
return AtifPage(header=header, subagents=subagents, steps=served,
next=served[-1]["step_id"] if served else after, has_more=len(served) < len(pending))
next=last, has_more=len(served) < len(pending))

def _open(self, task_id: str) -> _Task | None:
if self._failed is not None:
Expand Down
Loading
Loading