Skip to content

Agent Zero AI framework

Document connector payload contracts

Alessandro697f3ea4768e
diff --git a/helpers/AGENTS.md b/helpers/AGENTS.md
index 39d24d71e..5a8f75fb0 100644
--- a/helpers/AGENTS.md
+++ b/helpers/AGENTS.md
@@ -17,6 +17,14 @@
- Keep path handling constrained to intended roots for user files, uploads, downloads, projects, and workdirs.
- Project metadata defaults must remain backwards-compatible; missing `include_agents_md` is treated as enabled, project instruction file content is injected with an explicit source path, and active-project AGENTS.md path-chain guidance is assembled into prompt protocol without duplicating the project root AGENTS.md.
- Do not hardcode secrets, provider keys, local absolute paths, or environment-specific values.
+- `helpers.ws_limits` owns the process-start WebSocket payload ceiling shared by
+ transport configuration and connector capability negotiation. Protocol
+ senders pass the negotiated peer ceiling to `WsManager.emit_to`, which owns
+ exact serialized-envelope enforcement before buffering or dispatch. The
+ namespace dispatcher also asks the manager to constrain the final merged
+ acknowledgement against the limit stored on that live connection. That stored
+ ceiling is authoritative for direct emits and broadcasts from every handler,
+ not only connector-plugin call sites.
- Use `RepairableException` for errors an agent may be able to fix.
- This directory is a file-documented DOX profile: every direct `*.py` helper module must have a same-directory `*.py.dox.md` file named by appending `.dox.md` to the full Python filename.
- The `*.py.dox.md` file owns helper purpose, public classes/functions, cross-module contracts, persistence or side effects, path/security assumptions, important dependencies, and verification guidance.
diff --git a/plugins/_a0_connector/AGENTS.md b/plugins/_a0_connector/AGENTS.md
index 5c146ef8b..21221e9b3 100644
--- a/plugins/_a0_connector/AGENTS.md
+++ b/plugins/_a0_connector/AGENTS.md
@@ -21,6 +21,14 @@
execution metadata enables `code_execution_remote`, and supported enabled
Computer Use that does not need re-arming enables `computer_use_remote`.
- Do not bypass WebSocket authentication or leak connector session data.
+- HTTP capabilities and `connector_hello` advertise
+ `capabilities.ws_max_payload_bytes`. Store the peer ceiling per authenticated
+ SID, remove it on disconnect, and use the 4 MiB legacy floor when absent or
+ invalid. Every connector event sent to that SID must pass the ceiling to the
+ shared WebSocket manager; oversize becomes a structured
+ `PAYLOAD_TOO_LARGE` error and never a transport disconnect. Mirror the same
+ limit into the manager's live connection state so Socket.IO acknowledgements
+ are constrained after their final result envelope is assembled.
- Advertise Launcher gateways additively through HTTP capability
`launcher_gateway` and WebSocket feature `launcher_gateway_control`. Older
ordinary CLI clients retain their existing protocol fields and behavior; do
@@ -47,9 +55,23 @@
Computer Use approval belong only to attached or detached A0 Launcher chrome.
Keep the authenticated gateway HTTP/WebSocket protocol available for the
Launcher and connector runtime without adding a Core WebUI surface.
-- File operation results may arrive as chunked JSON/base64
- `connector_file_op_result` frames; resolve the pending file operation only
- after all chunks for the `op_id` are assembled.
+- HTTP capabilities and `connector_hello` advertise `transfer_protocol=1`.
+ Eligible large file, exec, Computer Use, browser, and gateway requests/results
+ use one symmetric start, ordered 64 KiB chunk, end, and abort contract with
+ declared size and SHA-256. Bound each receive by the local ceiling, four
+ concurrent transfers per SID, a 30-second idle timeout, and disk spooling
+ above 1 MiB. Resolve a pending operation only after exact size, order, hash,
+ JSON object shape, and operation ID all verify. Missing capability and legacy
+ file chunks fail once with a structured error and do not disconnect the SID.
+- Associate transfer state with the operation's existing context. Pause, reset,
+ and delete abort matching transfers; disconnect aborts all SID-owned state.
+ Mark outbound loops before emitting abort so raw payloads and pending futures
+ are released promptly even when the peer disappears mid-frame.
+- `text_editor_remote` is a bounded text control plane. Core must reject write
+ and patch content over 256 KiB before creating a pending WebSocket operation;
+ the CLI independently enforces the same ceiling. Reads return at most 2,000
+ lines or 256 KiB with continuation metadata and reject binary-looking files.
+ Prompts must direct complete or binary transfer to authenticated HTTP.
- Host browser status metadata may advertise `available_browsers` entries with browser ids, labels, CDP endpoints, status, and enabled state; keep older CLI payloads without those fields compatible.
- Model preset definitions exposed through v1 are global; project arguments select scope but never create project-owned definitions. Model switcher state reports the effective main, utility, and embedding models and preserves embedding-change notifications.
- Computer Use receipts describe transport success unless the connector returns explicit effect evidence. Linux target-bound typing requires a verified active/focused `window_id`; window activation uses focus, never a press action on an application or window node. Do not retry an identical failed Computer Use call.