agentenv-framework-protocol 0.1.318__tar.gz → 0.1.320__tar.gz

{agentenv_framework_protocol-0.1.318 → agentenv_framework_protocol-0.1.320}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.318
+Version: 0.1.320
 Summary: Open data-plane protocol and server SDK for agent environments.
 Project-URL: Homepage, https://www.agentenvframework.com
 Project-URL: Documentation, https://www.agentenvframework.com/docs
@@ -324,8 +324,9 @@ executor maps them to and from the wire-level `a2a.types.Task` lifecycle.
 `TaskRequest` is a frozen record whose nested JSON values are detached copies.
 Its `config`, `mcp_servers`, `skills`, `metadata`, and inbound `DataPart.data`
 retain their declared `dict`/`list` types, so normal Pydantic serialization,
-copying, and `json.dumps(...)` work. Within `tasks.v1`, new request fields are
-additive and have framework defaults. Agent code returns a `TaskResult` through
+copying, and `json.dumps(...)` work. `TaskRequest.trajectory` is the exception:
+it is the task's live trajectory log, described below. Within `tasks.v1`, new
+request fields are additive and have framework defaults. Agent code returns a `TaskResult` through
 its factories or builder so additions to the result contract do not break
 existing handlers.
 
@@ -348,7 +349,77 @@ The SDK does not retry tasks.
 A client that gives up on a task sends `tasks/cancel`. The framework marks the
 task canceled and cancels `run()`, which gets `asyncio.CancelledError` at its
 next `await`. A process `run()` started keeps running unless `run()` stops it,
-so kill it before re-raising.
+so kill it before re-raising. Trajectory events it appended, including any it
+appends while cleaning up, are kept, and its log ends `canceled`.
+
+#### Live trajectories
+
+A runtime that sees its native events as they happen appends each complete
+event to `request.trajectory` and enables `TRAJECTORY_V1` with `live=True`:
+
+```python
+@a2a_agent(identity=..., extensions=(enable(TRAJECTORY_V1, live=True),))
+class MyAgent(AgentEnvAgent):
+    async def run(self, request: TaskRequest[MyAgentConfig]) -> TaskResult:
+        request.trajectory.set_format("my-cli-events/1")
+        execution = await run_my_cli(request, on_event=request.trajectory.append)
+        return TaskResult.text(execution.output)
+```
+
+`append(event)` takes a JSON object and serializes it at once, so an event
+never changes after it is appended and a read never returns part of one. It does
+no I/O; call it from one thread at a time. After the task ends the log refuses
+further events. `set_format` names the events' versioned format, which readers
+use to parse them; call it before the first `append`, which otherwise raises.
+Once an event is appended the format cannot change.
+
+The framework keeps each task's log and serves it while the task runs. When the
+result carries no `native_trajectory`, the log is the task's final trajectory:
+the completed-task reads `{task_id}` and `{task_id, objects}` return it as a JSON
+array. A `native_trajectory` remains the final record of a runtime that can only
+produce one at the end, and takes precedence over appended events.
+
+`live=True` adds two cursor reads to `TRAJECTORY_V1.get`, both framework-owned:
+
+| Request | Reads |
+| --- | --- |
+| `{task_id, after, limit?}` | one task's events |
+| `{context_id, after, limit?}` | the events of every task in a context, in execution order |
+
+Both answer `{context_id, task_id, state, format, events, next, has_more}`
+(`TrajectoryEventsResponse`):
+
+- `events` are the events from position `after`, zero-based. `next` is
+  `after` plus the number returned, the position to read from next; `has_more`
+  says more events are already readable past this page. A page holds at most
+  `limit` events (1 to 1,000, default 1,000) and about 4 MiB, but always at
+  least one event when one exists. A `limit` outside 1 to 1,000, or `after` past
+  the last event, is HTTP 400.
+- `state` is `pending` before the first event, `running` while the task runs,
+  then `completed`, `failed` or `canceled`. A terminal state is reported only
+  once the log can no longer change, so a reader that has reached `has_more:
+  false` in a terminal state has every event. The terminal state is recorded
+  before the task's terminal A2A status, so the completed-task reads succeed as
+  soon as a client sees the task end.
+- A context read reports the context's current task, the running one or else the
+  latest, and the most recent `format` any of its tasks set; its `state` is
+  `running` while any task runs.
+- A task or context the agent has not seen, or no longer keeps, is HTTP 404. A
+  task is known from the moment `message/send` returns its id, so a 404 for an
+  id that was readable means it was evicted, and any cursor held for it, or for
+  its context, is no longer valid.
+
+`live=True` also enables the context reads `{context_id}` and
+`{context_id, objects}`; the framework answers them with the context's events
+unless the agent binds its own handlers, which take precedence. An agent that
+overrides the whole `get` operation must accept the cursor requests too.
+Clients detect live support from the card, with
+`card_request_accepts(get_request, {"task_id", "after"})`.
+
+The logs are kept in memory for up to 1,024 contexts. Past that, whole contexts
+are dropped, least recently used first; a context with a task still pending or
+running is never dropped, nor is the one whose task has just ended. A running
+task's log is logged as a warning once it passes 100 MiB.
 
 `enable(..., description="...")` is reserved for declarations carrying
 configuration or metadata. It preserves the agent-specific extension prose
@@ -363,7 +434,8 @@ entry in `extensions=` is required.
 Configuration keywords are definition-owned rather than hardcoded in
 `enable()`. A configurable `ExtensionDefinition` supplies a named keyword-only
 `configuration_validator` returning `ExtensionConfiguration` with card
-`wire_params`, internal `options`, and optional `features`. `enable()` only
+`wire_params`, internal `options`, and optional `features` and request
+`variants`. `enable()` only
 dispatches to that callable. Definitions without a validator reject
 configuration keywords, and third-party definitions use the same public API as
 the built-ins.
@@ -460,9 +532,9 @@ async def get_live_trajectory(self, request: ContextObjectTrajectoryRequest):
 The last handler opts that agent into the optional live-context variant of
 `TRAJECTORY_V1.get` that uploads through an object grant;
 `TRAJECTORY_V1.get.context` (`ContextTrajectoryRequest`) is its inline
-counterpart. Without them the generated card advertises only the
-framework-owned completed-task variants: `{task_id}`, answered inline, and
-`{task_id, objects}`, answered by upload.
+counterpart. Without them, or `enable(TRAJECTORY_V1, live=True)`, the
+generated card advertises only the framework-owned completed-task variants:
+`{task_id}`, answered inline, and `{task_id, objects}`, answered by upload.
 Snapshot `save` and `load` are an atomic core contract, while its optional
 changelog handlers are enabled as an atomic feature group.
 Each operation has at most one response model. The framework validates a
@@ -600,6 +672,7 @@ optional field, `|` an alternative request):
 | skill `add` | `{name, description, skill_md}` \| `{name, description, skill_bundle: {max_total_bytes, files: [{path, object: ReadObject}]}}` | `{name}` |
 | trajectory `get` | `{task_id}` \| `{context_id}` | `{trajectory}` |
 | | `{task_id \| context_id, objects: {trajectory: WriteObject}}` | `{objects: {trajectory: Uploaded}}` |
+| | `{task_id \| context_id, after, limit?}` | `{context_id, task_id, state, format, events, next, has_more}` |
 | snapshot `save` | `{context_id, objects: {trajectory: WriteObject, workspace?: WriteObject}}` | `{context_id, objects: {trajectory: Uploaded, workspace?: Uploaded}}` |
 | snapshot `load` | `{objects: {trajectory: ReadObject, workspace?: ReadObject}, target_context_id?}` | `{context_id}` |
 | `enable-changelog` | `{write_namespace: WriteNamespaceGrant, roots?}` | `{roots}` |

{agentenv_framework_protocol-0.1.318 → agentenv_framework_protocol-0.1.320}/README.md

@@ -280,8 +280,9 @@ executor maps them to and from the wire-level `a2a.types.Task` lifecycle.
 `TaskRequest` is a frozen record whose nested JSON values are detached copies.
 Its `config`, `mcp_servers`, `skills`, `metadata`, and inbound `DataPart.data`
 retain their declared `dict`/`list` types, so normal Pydantic serialization,
-copying, and `json.dumps(...)` work. Within `tasks.v1`, new request fields are
-additive and have framework defaults. Agent code returns a `TaskResult` through
+copying, and `json.dumps(...)` work. `TaskRequest.trajectory` is the exception:
+it is the task's live trajectory log, described below. Within `tasks.v1`, new
+request fields are additive and have framework defaults. Agent code returns a `TaskResult` through
 its factories or builder so additions to the result contract do not break
 existing handlers.
 
@@ -304,7 +305,77 @@ The SDK does not retry tasks.
 A client that gives up on a task sends `tasks/cancel`. The framework marks the
 task canceled and cancels `run()`, which gets `asyncio.CancelledError` at its
 next `await`. A process `run()` started keeps running unless `run()` stops it,
-so kill it before re-raising.
+so kill it before re-raising. Trajectory events it appended, including any it
+appends while cleaning up, are kept, and its log ends `canceled`.
+
+#### Live trajectories
+
+A runtime that sees its native events as they happen appends each complete
+event to `request.trajectory` and enables `TRAJECTORY_V1` with `live=True`:
+
+```python
+@a2a_agent(identity=..., extensions=(enable(TRAJECTORY_V1, live=True),))
+class MyAgent(AgentEnvAgent):
+    async def run(self, request: TaskRequest[MyAgentConfig]) -> TaskResult:
+        request.trajectory.set_format("my-cli-events/1")
+        execution = await run_my_cli(request, on_event=request.trajectory.append)
+        return TaskResult.text(execution.output)
+```
+
+`append(event)` takes a JSON object and serializes it at once, so an event
+never changes after it is appended and a read never returns part of one. It does
+no I/O; call it from one thread at a time. After the task ends the log refuses
+further events. `set_format` names the events' versioned format, which readers
+use to parse them; call it before the first `append`, which otherwise raises.
+Once an event is appended the format cannot change.
+
+The framework keeps each task's log and serves it while the task runs. When the
+result carries no `native_trajectory`, the log is the task's final trajectory:
+the completed-task reads `{task_id}` and `{task_id, objects}` return it as a JSON
+array. A `native_trajectory` remains the final record of a runtime that can only
+produce one at the end, and takes precedence over appended events.
+
+`live=True` adds two cursor reads to `TRAJECTORY_V1.get`, both framework-owned:
+
+| Request | Reads |
+| --- | --- |
+| `{task_id, after, limit?}` | one task's events |
+| `{context_id, after, limit?}` | the events of every task in a context, in execution order |
+
+Both answer `{context_id, task_id, state, format, events, next, has_more}`
+(`TrajectoryEventsResponse`):
+
+- `events` are the events from position `after`, zero-based. `next` is
+  `after` plus the number returned, the position to read from next; `has_more`
+  says more events are already readable past this page. A page holds at most
+  `limit` events (1 to 1,000, default 1,000) and about 4 MiB, but always at
+  least one event when one exists. A `limit` outside 1 to 1,000, or `after` past
+  the last event, is HTTP 400.
+- `state` is `pending` before the first event, `running` while the task runs,
+  then `completed`, `failed` or `canceled`. A terminal state is reported only
+  once the log can no longer change, so a reader that has reached `has_more:
+  false` in a terminal state has every event. The terminal state is recorded
+  before the task's terminal A2A status, so the completed-task reads succeed as
+  soon as a client sees the task end.
+- A context read reports the context's current task, the running one or else the
+  latest, and the most recent `format` any of its tasks set; its `state` is
+  `running` while any task runs.
+- A task or context the agent has not seen, or no longer keeps, is HTTP 404. A
+  task is known from the moment `message/send` returns its id, so a 404 for an
+  id that was readable means it was evicted, and any cursor held for it, or for
+  its context, is no longer valid.
+
+`live=True` also enables the context reads `{context_id}` and
+`{context_id, objects}`; the framework answers them with the context's events
+unless the agent binds its own handlers, which take precedence. An agent that
+overrides the whole `get` operation must accept the cursor requests too.
+Clients detect live support from the card, with
+`card_request_accepts(get_request, {"task_id", "after"})`.
+
+The logs are kept in memory for up to 1,024 contexts. Past that, whole contexts
+are dropped, least recently used first; a context with a task still pending or
+running is never dropped, nor is the one whose task has just ended. A running
+task's log is logged as a warning once it passes 100 MiB.
 
 `enable(..., description="...")` is reserved for declarations carrying
 configuration or metadata. It preserves the agent-specific extension prose
@@ -319,7 +390,8 @@ entry in `extensions=` is required.
 Configuration keywords are definition-owned rather than hardcoded in
 `enable()`. A configurable `ExtensionDefinition` supplies a named keyword-only
 `configuration_validator` returning `ExtensionConfiguration` with card
-`wire_params`, internal `options`, and optional `features`. `enable()` only
+`wire_params`, internal `options`, and optional `features` and request
+`variants`. `enable()` only
 dispatches to that callable. Definitions without a validator reject
 configuration keywords, and third-party definitions use the same public API as
 the built-ins.
@@ -416,9 +488,9 @@ async def get_live_trajectory(self, request: ContextObjectTrajectoryRequest):
 The last handler opts that agent into the optional live-context variant of
 `TRAJECTORY_V1.get` that uploads through an object grant;
 `TRAJECTORY_V1.get.context` (`ContextTrajectoryRequest`) is its inline
-counterpart. Without them the generated card advertises only the
-framework-owned completed-task variants: `{task_id}`, answered inline, and
-`{task_id, objects}`, answered by upload.
+counterpart. Without them, or `enable(TRAJECTORY_V1, live=True)`, the
+generated card advertises only the framework-owned completed-task variants:
+`{task_id}`, answered inline, and `{task_id, objects}`, answered by upload.
 Snapshot `save` and `load` are an atomic core contract, while its optional
 changelog handlers are enabled as an atomic feature group.
 Each operation has at most one response model. The framework validates a
@@ -556,6 +628,7 @@ optional field, `|` an alternative request):
 | skill `add` | `{name, description, skill_md}` \| `{name, description, skill_bundle: {max_total_bytes, files: [{path, object: ReadObject}]}}` | `{name}` |
 | trajectory `get` | `{task_id}` \| `{context_id}` | `{trajectory}` |
 | | `{task_id \| context_id, objects: {trajectory: WriteObject}}` | `{objects: {trajectory: Uploaded}}` |
+| | `{task_id \| context_id, after, limit?}` | `{context_id, task_id, state, format, events, next, has_more}` |
 | snapshot `save` | `{context_id, objects: {trajectory: WriteObject, workspace?: WriteObject}}` | `{context_id, objects: {trajectory: Uploaded, workspace?: Uploaded}}` |
 | snapshot `load` | `{objects: {trajectory: ReadObject, workspace?: ReadObject}, target_context_id?}` | `{context_id}` |
 | `enable-changelog` | `{write_namespace: WriteNamespaceGrant, roots?}` | `{roots}` |

{agentenv_framework_protocol-0.1.318 → agentenv_framework_protocol-0.1.320}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentenv-framework-protocol"
-version = "0.1.318"
+version = "0.1.320"
 description = "Open data-plane protocol and server SDK for agent environments."
 readme = "README.md"
 license = "Apache-2.0"

{agentenv_framework_protocol-0.1.318 → agentenv_framework_protocol-0.1.320}/src/agentenv_protocol/a2a_agent/__init__.py

@@ -16,6 +16,7 @@ from .extensions import (
     AttributionProbeResponse,
     BundleSkillRequest,
     ChangelogIncrement,
+    ContextEventsTrajectoryRequest,
     ContextObjectTrajectoryRequest,
     ContextTrajectoryRequest,
     ExtensionActivation,
@@ -48,9 +49,12 @@ from .extensions import (
     SnapshotReadObjects,
     SnapshotUploadedObjects,
     SnapshotWriteObjects,
+    TaskEventsTrajectoryRequest,
     TaskObjectTrajectoryRequest,
     TaskTrajectoryRequest,
+    TrajectoryEventsResponse,
     TrajectoryObjectsResponse,
+    TrajectoryState,
     TrajectoryUploadedObjects,
     TrajectoryWriteObjects,
     TriggerDecideRequest,
@@ -92,6 +96,7 @@ from .tasks.v1 import (
     TaskResultBuilder,
     TaskStreamItem,
     TextPart,
+    TrajectoryLog,
     Usage,
     WriteOnly,
 )
@@ -131,6 +136,7 @@ __all__ = [
     "AttributionProbeResponse",
     "BundleSkillRequest",
     "ChangelogIncrement",
+    "ContextEventsTrajectoryRequest",
     "ContextObjectTrajectoryRequest",
     "ContextTrajectoryRequest",
     "DataPart",
@@ -177,6 +183,7 @@ __all__ = [
     "SnapshotWriteObjects",
     "StagingStore",
     "TaskError",
+    "TaskEventsTrajectoryRequest",
     "TaskObjectTrajectoryRequest",
     "TaskOutcome",
     "TaskPart",
@@ -187,7 +194,10 @@ __all__ = [
     "TaskStreamItem",
     "TaskTrajectoryRequest",
     "TextPart",
+    "TrajectoryEventsResponse",
+    "TrajectoryLog",
     "TrajectoryObjectsResponse",
+    "TrajectoryState",
     "TrajectoryUploadedObjects",
     "TrajectoryWriteObjects",
     "TransferError",

agentenv_framework_protocol-0.1.320/src/agentenv_protocol/a2a_agent/_trajectory_log.py

@@ -0,0 +1,244 @@
+"""The framework's in-process store of task trajectories, served by the trajectory extension."""
+
+from __future__ import annotations
+
+import logging
+from collections import OrderedDict
+from dataclasses import dataclass
+
+from .extensions import TrajectoryState
+from .tasks.v1 import TrajectoryLog
+
+logger = logging.getLogger(__name__)
+
+MAX_CACHED_CONTEXTS = 1_024
+MAX_TRAJECTORY_READ_BYTES = 4 * 1024 * 1024
+
+
+@dataclass(slots=True)
+class _TaskRecord:
+    context_id: str
+    log: TrajectoryLog
+    started: bool = False
+    cancel_requested: bool = False
+    final_state: TrajectoryState | None = None
+    native: bytes | None = None
+
+    @property
+    def state(self) -> TrajectoryState:
+        if self.final_state is not None:
+            return self.final_state
+        return TrajectoryState.RUNNING if len(self.log) else TrajectoryState.PENDING
+
+
+@dataclass(frozen=True, slots=True)
+class TrajectoryPage:
+    context_id: str
+    task_id: str
+    state: TrajectoryState
+    format: str | None
+    events: list[bytes]
+    total: int
+
+
+class TaskTrajectories:
+    """Each task's log and final record, grouped by context in execution order.
+
+    Past ``max_contexts``, whole contexts are evicted, least recently used first, so
+    positions in a context read never shift. A context with a task pending or running is
+    never evicted, nor is the one whose task just ended, so its final record is readable."""
+
+    def __init__(self, max_contexts: int = MAX_CACHED_CONTEXTS) -> None:
+        if max_contexts < 1:
+            raise ValueError("max_contexts must be positive")
+        self._max_contexts = max_contexts
+        self._tasks: dict[str, _TaskRecord] = {}
+        self._contexts: OrderedDict[str, list[str]] = OrderedDict()
+
+    def register(self, task_id: str, context_id: str) -> TrajectoryLog:
+        """The task's log, created ``pending`` the first time the task is seen."""
+        record = self._tasks.get(task_id)
+        if record is None:
+            log = TrajectoryLog()
+            log._task_id = task_id
+            record = self._tasks[task_id] = _TaskRecord(context_id=context_id, log=log)
+            self._contexts.setdefault(context_id, []).append(task_id)
+        self._touch(record.context_id)
+        return record.log
+
+    def start(self, task_id: str) -> None:
+        """Place the task after the context's started tasks, as it begins to run.
+
+        Only tasks that have not started move; they have no events, so no position shifts."""
+        record = self._tasks[task_id]
+        if record.started:
+            return
+        order = self._contexts[record.context_id]
+        order.remove(task_id)
+        started = sum(1 for other in order if self._tasks[other].started)
+        order.insert(started, task_id)
+        record.started = True
+        self._touch(record.context_id)
+
+    def request_cancel(self, task_id: str) -> None:
+        """Make ``canceled`` the outcome the task is sealed with, whatever ``run`` returns."""
+        record = self._tasks.get(task_id)
+        if record is not None:
+            record.cancel_requested = True
+
+    def seal(
+        self, task_id: str, state: TrajectoryState, *, native: bytes | None = None
+    ) -> None:
+        """End the task's trajectory; the first seal wins."""
+        record = self._tasks[task_id]
+        if record.final_state is not None:
+            return
+        if native is not None:
+            if len(record.log):
+                logger.warning(
+                    "task %s appended trajectory events and returned a native trajectory; "
+                    "the native trajectory is its final record",
+                    task_id,
+                )
+            record.native = native
+        record.log._sealed = True
+        record.final_state = TrajectoryState.CANCELED if record.cancel_requested else state
+        self._touch(record.context_id)
+        self._evict(keep=record.context_id)
+
+    def final(self, task_id: str) -> bytes | None:
+        """The ended task's final trajectory as a JSON array, or None if there is none yet."""
+        record = self._tasks.get(task_id)
+        if record is None or record.final_state is None:
+            return None
+        self._touch(record.context_id)
+        if record.native is not None:
+            return record.native
+        if not len(record.log):
+            return None
+        return _json_array(record.log._events)
+
+    def context_events(self, context_id: str) -> bytes | None:
+        """Every event of the context's tasks in order, as a JSON array."""
+        records = self._context_records(context_id)
+        if records is None:
+            return None
+        return _json_array([event for record in records for event in record.log._events])
+
+    def task_page(
+        self, task_id: str, after: int, max_events: int, max_bytes: int
+    ) -> TrajectoryPage | None:
+        record = self._tasks.get(task_id)
+        if record is None:
+            return None
+        self._touch(record.context_id)
+        # State before length: a terminal state means the length can no longer grow.
+        state = record.state
+        events = record.log._events
+        total = len(events)
+        return TrajectoryPage(
+            context_id=record.context_id,
+            task_id=task_id,
+            state=state,
+            format=record.log.format,
+            events=_page(events, after, total, max_events, max_bytes),
+            total=total,
+        )
+
+    def context_page(
+        self, context_id: str, after: int, max_events: int, max_bytes: int
+    ) -> TrajectoryPage | None:
+        records = self._context_records(context_id)
+        if records is None:
+            return None
+        task_ids = self._contexts[context_id]
+        states = [record.state for record in records]
+        lengths = [len(record.log) for record in records]
+        current = next(
+            (index for index, record in enumerate(records) if record.final_state is None),
+            len(records) - 1,
+        )
+        if TrajectoryState.RUNNING in states:
+            state = TrajectoryState.RUNNING
+        elif TrajectoryState.PENDING in states:
+            state = TrajectoryState.PENDING
+        else:
+            state = states[-1]
+        page: list[bytes] = []
+        offset = 0
+        for record, length in zip(records, lengths):
+            if len(page) >= max_events:
+                break
+            if after < offset + length:
+                start = max(after - offset, 0)
+                page.extend(
+                    _page(
+                        record.log._events,
+                        start,
+                        length,
+                        max_events - len(page),
+                        max_bytes - sum(map(len, page)),
+                        first=not page,
+                    )
+                )
+            offset += length
+        return TrajectoryPage(
+            context_id=context_id,
+            task_id=task_ids[current],
+            state=state,
+            format=next(
+                (record.log.format for record in reversed(records) if record.log.format),
+                None,
+            ),
+            events=page,
+            total=sum(lengths),
+        )
+
+    def _context_records(self, context_id: str) -> list[_TaskRecord] | None:
+        task_ids = self._contexts.get(context_id)
+        if not task_ids:
+            return None
+        self._touch(context_id)
+        return [self._tasks[task_id] for task_id in task_ids]
+
+    def _touch(self, context_id: str) -> None:
+        if context_id in self._contexts:
+            self._contexts.move_to_end(context_id)
+
+    def _evict(self, *, keep: str) -> None:
+        for context_id in tuple(self._contexts):
+            if len(self._contexts) <= self._max_contexts:
+                return
+            task_ids = self._contexts[context_id]
+            if context_id == keep or any(
+                self._tasks[task_id].final_state is None for task_id in task_ids
+            ):
+                continue
+            del self._contexts[context_id]
+            for task_id in task_ids:
+                del self._tasks[task_id]
+
+
+def _page(
+    events: list[bytes],
+    start: int,
+    stop: int,
+    max_events: int,
+    max_bytes: int,
+    *,
+    first: bool = True,
+) -> list[bytes]:
+    """Events from ``start``, within both budgets; the first event of a read is always
+    returned, so one larger than ``max_bytes`` cannot stall a reader."""
+    page: list[bytes] = []
+    used = 0
+    for encoded in events[start:min(stop, start + max_events)]:
+        if used + len(encoded) > max_bytes and (page or not first):
+            break
+        page.append(encoded)
+        used += len(encoded)
+    return page
+
+
+def _json_array(events: list[bytes]) -> bytes:
+    return b"[" + b",".join(events) + b"]"