Skip to content

Agent Zero AI framework

Merge websocket transport hardening

Alessandro9e0c44b9849e
diff --cc api/download_work_dir_file.py.dox.md
index f92c584cf,c7feb9cc6..ebb604c60
--- a/api/download_work_dir_file.py.dox.md
+++ b/api/download_work_dir_file.py.dox.md
@@@ -15,9 -15,12 +15,12 @@@
- `get_methods(cls)`
- `async process(self, input: Input, request: Request) -> Output`
- Top-level functions:
+ - `file_size_and_sha256(file_source) -> tuple[int, str]`: Stream a disk file or
+ `BytesIO` source to produce download integrity metadata without loading a disk
+ file into memory.
- `stream_file_download(file_source, download_name, chunk_size=...)`: Create a streaming response for file downloads that shows progress in browser.
- `make_disposition(download_name: str) -> str`
-- `resolve_download_path(path: str) -> str`: Resolve a requested download path and keep it within the runtime base dir.
+- `resolve_download_path(path: str) -> str`: Resolve a requested download path from the File Browser root.
- `async fetch_file(path)`
## Runtime Contracts
@@@ -27,8 -30,8 +30,10 @@@
- `DownloadFile` is an `ApiHandler`.
- `DownloadFile` defines `process(...)`.
- `DownloadFile` defines `get_methods(...)`.
+- The endpoint retains the default authenticated and CSRF-protected browser contract.
+- Download paths use `/` as their root, matching the authenticated File Browser and editor filesystem scope.
+ - Every streamed response carries `Content-Length` and `X-Content-SHA256`; the
+ CLI verifies both before atomically exposing a host destination.
- Observed side-effect areas: filesystem reads, network calls.
- Imported dependency areas include: `api`, `base64`, `flask`, `helpers`, `helpers.api`, `io`, `mimetypes`, `os`, `pathlib`, `urllib.parse`.
diff --cc helpers/ui_server.py
index aa3f3586b,cedaeddc4..751f9e7ef
--- a/helpers/ui_server.py
+++ b/helpers/ui_server.py
@@@ -34,10 -32,7 +34,11 @@@ from helpers.extension import extensibl
from helpers.files import get_abs_path
from helpers.print_style import PrintStyle
from helpers.server_startup import StartupMonitor
+from helpers.ui_bundler import (
+ get_ui_asset_bundle,
+ serialize_ui_asset_bundle,
+)
+ from helpers.ws_limits import A0_WS_MAX_PAYLOAD_BYTES
from helpers import settings as settings_helper
from helpers.ws import register_ws_namespace, validate_ws_origin
from helpers.ws_manager import WsManager, set_shared_ws_manager
diff --cc helpers/ui_server.py.dox.md
index 0af0da6e8,bb63bcef2..8e5ba536b
--- a/helpers/ui_server.py.dox.md
+++ b/helpers/ui_server.py.dox.md
@@@ -32,15 -28,16 +32,16 @@@
- Top-level functions:
- `_positive_int_env(name: str, default: int) -> int`
- `configure_process_environment() -> None`
- - Notable constants/configuration names: `UPLOAD_LIMIT_BYTES`, `SOCKETIO_PING_INTERVAL_SECONDS`, `SOCKETIO_PING_TIMEOUT_SECONDS`, `GZIP_MINIMUM_RESPONSE_BYTES`, `GZIP_COMPRESSION_LEVEL`, `UI_INDEX_ASSET_URL`, `A0_SOCKETIO_PING_INTERVAL_SECONDS`, `A0_SOCKETIO_PING_TIMEOUT_SECONDS`.
-- Notable constants/configuration names: `UPLOAD_LIMIT_BYTES`, `SOCKETIO_PING_INTERVAL_SECONDS`, `SOCKETIO_PING_TIMEOUT_SECONDS`, `A0_SOCKETIO_PING_INTERVAL_SECONDS`, `A0_SOCKETIO_PING_TIMEOUT_SECONDS`, and the shared `A0_WS_MAX_PAYLOAD_BYTES` import.
++- Notable constants/configuration names: `UPLOAD_LIMIT_BYTES`, `SOCKETIO_PING_INTERVAL_SECONDS`, `SOCKETIO_PING_TIMEOUT_SECONDS`, `GZIP_MINIMUM_RESPONSE_BYTES`, `GZIP_COMPRESSION_LEVEL`, `UI_INDEX_ASSET_URL`, `A0_SOCKETIO_PING_INTERVAL_SECONDS`, `A0_SOCKETIO_PING_TIMEOUT_SECONDS`, and the shared `A0_WS_MAX_PAYLOAD_BYTES` import.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Socket.IO heartbeat defaults are intentionally longer than Engine.IO's short defaults so CLI sessions survive long prompt/context work; environment overrides must remain positive integers and fall back to source defaults when invalid.
+ - Engine.IO's inbound buffer ceiling uses the shared WebSocket payload limit from `helpers.ws_limits`.
- Observed side-effect areas: filesystem reads, network calls, subprocess/runtime control, WebSocket state, plugin state, settings/state persistence, secret handling.
-- Imported dependency areas include: `asyncio`, `dataclasses`, `datetime`, `flask`, `helpers`, `helpers.api`, `helpers.extension`, `helpers.files`, `helpers.print_style`, `helpers.server_startup`, `helpers.ws`, `helpers.ws_manager`, `logging`, `os`, `secrets`, `socketio`.
+- Imported dependency areas include: `asyncio`, `dataclasses`, `datetime`, `flask`, `helpers`, `helpers.api`, `helpers.extension`, `helpers.files`, `helpers.print_style`, `helpers.server_startup`, `helpers.ws`, `helpers.ws_manager`, `logging`, `os`, `secrets`, `socketio`, `starlette.middleware.gzip`.
## Key Concepts
diff --cc plugins/_a0_connector/AGENTS.md
index 5dc630a52,21221e9b3..c9f0cf4df
--- a/plugins/_a0_connector/AGENTS.md
+++ b/plugins/_a0_connector/AGENTS.md
@@@ -22,10 -20,15 +22,18 @@@
prompts, remote file metadata enables `text_editor_remote`, F4-enabled remote
execution metadata enables `code_execution_remote`, and supported enabled
Computer Use that does not need re-arming enables `computer_use_remote`.
+- Agent-scoped skill discovery includes this plugin's `skills/` root only when a routed connected socket has connector capability metadata. WebUI-only sockets do not qualify; disabled capabilities still count as a connected CLI. Filter roots on each discovery without mutating cached paths or persisting visibility settings. `setup-a0-cli` lives in root `skills/` and stays discoverable while disconnected.
+- Never re-add a connector prompt that the effective project/profile tool policy
+ blocks.
- 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
@@@ -52,17 -55,26 +60,31 @@@
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.
+- The protected v1 `agent_editor` route delegates to the bundled Agent Editor
+ API and must not define another profile schema or write profile files itself.
+- The protected v1 `agents_list` response uses the shared agent presentation
+ catalog rather than applying connector-specific visibility rules.
- 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.
+- Accepted WebSocket user-message replay metadata may include attachment basenames only; strip paths, query strings, fragments, and bytes before logging them in `kvps`.
## Work Guidance