Agent Zero AI framework
Document connector payload contracts
Alessandro697f3ea4768e
diff --git a/helpers/AGENTS.md b/helpers/AGENTS.mdindex 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.mdindex 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 enabledComputer 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`. Olderordinary 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 theLauncher 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.