Skip to content

Agent Zero AI framework

Page connector history replay

Alessandroaff70f19bbc3
diff --git a/plugins/AGENTS.md b/plugins/AGENTS.md
index 0d91dea83..a104fce06 100644
--- a/plugins/AGENTS.md
+++ b/plugins/AGENTS.md
@@ -30,6 +30,7 @@
- `hooks.py` runs in the framework runtime. Explicitly target another runtime if a plugin must prepare the agent execution environment.
- `execute.py` is manual user-triggered setup, maintenance, repair, migration, or refresh work; automatic framework behavior belongs in hooks or lifecycle extensions.
- Plugin routes are `GET /plugins/<name>/<path>`, `POST /api/plugins/<name>/<handler>`, and `POST /api/plugins` for management actions.
+- `_a0_connector` WebSocket history replay must stay bounded: emit large chat history as paged `connector_context_snapshot` payloads, keep `last_sequence` as the Agent Zero log-output cursor, and avoid sending an entire long transcript in one frame.
- Frontend plugin HTML extensions live under `extensions/webui/<point>/`, include a root Alpine scope, and use `x-move-*` directives when targeting static breakpoints.
- Frontend plugin JS extensions live under `extensions/webui/<point>/` and export a default function.
- Plugin UI must use the A0 notification system for errors, warnings, success, and info instead of inline success/error boxes.
diff --git a/plugins/_a0_connector/api/ws_connector.py b/plugins/_a0_connector/api/ws_connector.py
index 2f15c671f..0152eeb4c 100644
--- a/plugins/_a0_connector/api/ws_connector.py
+++ b/plugins/_a0_connector/api/ws_connector.py
@@ -62,6 +62,9 @@ WS_FEATURES = [
"connector_browser_op",
]
+_SNAPSHOT_REPLAY_PAGE_SIZE = 50
+_LIVE_STREAM_PAGE_SIZE = 100
+
class WsConnector(WsHandler):
_streaming_tasks: ClassVar[dict[tuple[str, str], asyncio.Task[None]]] = {}
@@ -253,19 +256,25 @@ class WsConnector(WsHandler):
)
subscribe_sid_to_context(sid, context_id)
- events, last_sequence = get_context_log_entries(context_id, after=from_sequence)
- await self.emit_to(
+ events, last_sequence = get_context_log_entries(
+ context_id,
+ after=from_sequence,
+ limit=_SNAPSHOT_REPLAY_PAGE_SIZE,
+ )
+ await self._emit_context_snapshot(
sid,
- "connector_context_snapshot",
- {
- "context_id": context_id,
- "events": events,
- "last_sequence": last_sequence,
- "message_queue": self._queue_items_for_context(context),
- },
+ context_id=context_id,
+ events=events,
+ last_sequence=last_sequence,
+ context=context,
correlation_id=data.get("correlationId"),
)
- self._start_streaming(sid, context_id, from_sequence=last_sequence)
+ self._start_streaming(
+ sid,
+ context_id,
+ from_sequence=last_sequence,
+ replay_history=True,
+ )
return {
"context_id": context_id,
@@ -349,19 +358,25 @@ class WsConnector(WsHandler):
if context_id not in subscribed_contexts_for_sid(sid):
subscribe_sid_to_context(sid, context_id)
- events, last_sequence = get_context_log_entries(context_id, after=0)
- await self.emit_to(
+ events, last_sequence = get_context_log_entries(
+ context_id,
+ after=0,
+ limit=_SNAPSHOT_REPLAY_PAGE_SIZE,
+ )
+ await self._emit_context_snapshot(
sid,
- "connector_context_snapshot",
- {
- "context_id": context_id,
- "events": events,
- "last_sequence": last_sequence,
- "message_queue": self._queue_items_for_context(context),
- },
+ context_id=context_id,
+ events=events,
+ last_sequence=last_sequence,
+ context=context,
correlation_id=data.get("correlationId"),
)
- self._start_streaming(sid, context_id, from_sequence=last_sequence)
+ self._start_streaming(
+ sid,
+ context_id,
+ from_sequence=last_sequence,
+ replay_history=True,
+ )
message_id = client_message_id or data.get("correlationId") or ""
context.log.log(
@@ -865,14 +880,48 @@ class WsConnector(WsHandler):
f"[a0-connector] failed to emit connector_context_complete to {target_sid}: {exc}"
)
- def _start_streaming(self, sid: str, context_id: str, *, from_sequence: int) -> None:
+ async def _emit_context_snapshot(
+ self,
+ sid: str,
+ *,
+ context_id: str,
+ events: list[dict[str, Any]],
+ last_sequence: int,
+ context: AgentContext | None = None,
+ correlation_id: str | None = None,
+ ) -> None:
+ await self.emit_to(
+ sid,
+ "connector_context_snapshot",
+ {
+ "context_id": context_id,
+ "events": events,
+ "last_sequence": last_sequence,
+ "message_queue": self._queue_items_for_context(context),
+ },
+ correlation_id=correlation_id,
+ )
+
+ def _start_streaming(
+ self,
+ sid: str,
+ context_id: str,
+ *,
+ from_sequence: int,
+ replay_history: bool = False,
+ ) -> None:
key = (sid, context_id)
task = self._streaming_tasks.get(key)
if task is not None and not task.done():
return
task = asyncio.create_task(
- self._stream_events(sid, context_id, from_sequence=from_sequence)
+ self._stream_events(
+ sid,
+ context_id,
+ from_sequence=from_sequence,
+ replay_history=replay_history,
+ )
)
self._streaming_tasks[key] = task
@@ -887,14 +936,26 @@ class WsConnector(WsHandler):
context_id: str,
*,
from_sequence: int,
+ replay_history: bool = False,
) -> None:
# `from_sequence` is a log-output cursor (not an event sequence number).
cursor = max(int(from_sequence or 0), 0)
last_queue_signature, _ = self._queue_state_for_context_id(context_id)
was_running = self._context_is_running(context_id)
try:
+ if replay_history:
+ cursor = await self._replay_history_snapshots(
+ sid,
+ context_id,
+ from_sequence=cursor,
+ )
+
while context_id in subscribed_contexts_for_sid(sid):
- events, next_cursor = get_context_log_entries(context_id, after=cursor)
+ events, next_cursor = get_context_log_entries(
+ context_id,
+ after=cursor,
+ limit=_LIVE_STREAM_PAGE_SIZE,
+ )
for event in events:
await self.emit_to(sid, "connector_context_event", event)
cursor = max(cursor, int(next_cursor or cursor))
@@ -920,7 +981,7 @@ class WsConnector(WsHandler):
},
)
was_running = is_running
- await asyncio.sleep(0.5)
+ await asyncio.sleep(0 if events else 0.5)
except asyncio.CancelledError:
raise
except Exception as exc:
@@ -929,3 +990,41 @@ class WsConnector(WsHandler):
)
finally:
self._streaming_tasks.pop((sid, context_id), None)
+
+ async def _replay_history_snapshots(
+ self,
+ sid: str,
+ context_id: str,
+ *,
+ from_sequence: int,
+ ) -> int:
+ cursor = max(int(from_sequence or 0), 0)
+
+ while context_id in subscribed_contexts_for_sid(sid):
+ events, next_cursor = get_context_log_entries(
+ context_id,
+ after=cursor,
+ limit=_SNAPSHOT_REPLAY_PAGE_SIZE,
+ )
+ next_cursor = max(cursor, int(next_cursor or cursor))
+ if not events:
+ return next_cursor
+
+ _, queue_items = self._queue_state_for_context_id(context_id)
+ await self.emit_to(
+ sid,
+ "connector_context_snapshot",
+ {
+ "context_id": context_id,
+ "events": events,
+ "last_sequence": next_cursor,
+ "message_queue": queue_items,
+ },
+ )
+
+ if next_cursor == cursor:
+ return cursor + len(events)
+ cursor = next_cursor
+ await asyncio.sleep(0)
+
+ return cursor
diff --git a/plugins/_a0_connector/helpers/event_bridge.py b/plugins/_a0_connector/helpers/event_bridge.py
index 9a35e6729..c453a6e78 100644
--- a/plugins/_a0_connector/helpers/event_bridge.py
+++ b/plugins/_a0_connector/helpers/event_bridge.py
@@ -79,6 +79,7 @@ def log_entry_to_connector_event(
def get_context_log_entries(
context_id: str,
after: int = 0,
+ limit: int | None = None,
) -> tuple[list[dict[str, Any]], int]:
"""Return connector events plus the next log cursor for the context."""
try:
@@ -88,7 +89,20 @@ def get_context_log_entries(
if context is None:
return [], 0
- log_output = context.log.output(start=max(int(after or 0), 0))
+ start = max(int(after or 0), 0)
+ end: int | None = None
+ if limit is not None:
+ limit = max(int(limit or 0), 0)
+ if limit > 0:
+ log_lock = getattr(context.log, "_lock", None)
+ log_updates = getattr(context.log, "updates", None)
+ if log_lock is not None and isinstance(log_updates, list):
+ with log_lock:
+ end = min(start + limit, len(log_updates))
+ else:
+ end = start + limit
+
+ log_output = context.log.output(start=start, end=end)
events = [
log_entry_to_connector_event(entry, context_id)
for entry in log_output.items