Skip to content

Agent Zero AI framework

Bound remote connector tool payloads

Alessandro76f905e07a39
diff --git a/plugins/_a0_connector/prompts/agent.system.tool.text_editor_remote.md b/plugins/_a0_connector/prompts/agent.system.tool.text_editor_remote.md
index 0c2b0341f..9ab45adc7 100644
--- a/plugins/_a0_connector/prompts/agent.system.tool.text_editor_remote.md
+++ b/plugins/_a0_connector/prompts/agent.system.tool.text_editor_remote.md
@@ -23,6 +23,13 @@ report that to the user instead of falling back to server-side file tools.
- For simple "change X to Y" requests, prefer exact replace with `old_text` and `new_text`; `old_text` must match one exact current span.
- Prefer `patch_text` for context-anchored changes and `edits` only for fresh, surgical line ranges.
- If freshness checks reject a line patch, reread the file and retry with updated ranges.
+- Reads are text previews capped at 2,000 lines and 256 KiB. When the result says
+ it was truncated, continue from its `next_line` only if another bounded text
+ slice is sufficient.
+- Write and patch content is capped at 256 KiB. For a complete large file or any
+ binary file, use the authenticated CLI/Core HTTP upload or download path; do
+ not retry it through this WebSocket tool. If no HTTP-facing action is available
+ in the current task, ask the user to attach/upload the file through A0 CLI.
- Relative paths are relative to the CLI host filesystem. Do not rewrite them to
`/a0/usr/workdir`; that path belongs to the Agent Zero server/Docker side.
diff --git a/plugins/_a0_connector/skills/host-file-editing/SKILL.md b/plugins/_a0_connector/skills/host-file-editing/SKILL.md
index 27e6d6e08..d417f52c2 100644
--- a/plugins/_a0_connector/skills/host-file-editing/SKILL.md
+++ b/plugins/_a0_connector/skills/host-file-editing/SKILL.md
@@ -24,6 +24,11 @@ If the task belongs inside Agent Zero's own runtime, use the normal server-side
- Use `patch_text` for context-anchored edits, especially after inserts/deletes or when line numbers may have shifted.
- Use `patch` with `edits` only for small line-range edits based on the latest remote read.
- If freshness-aware line patching rejects an edit as stale, reread the file and retry with updated ranges.
+- Treat reads as bounded text previews (2,000 lines / 256 KiB). Follow
+ `next_line` for another small slice; use the authenticated HTTP transfer path
+ for complete large files and binary data.
+- Keep each write or patch payload within 256 KiB. Do not split a binary file
+ into text-editor calls.
## Patch Text Rules
@@ -40,3 +45,6 @@ If the task belongs inside Agent Zero's own runtime, use the normal server-side
- If no CLI is connected, ask the user to connect A0 CLI to this Agent Zero instance.
- If writes are blocked, tell the user to switch local file access to Read&Write with F3.
- If a request times out or the CLI disconnects, summarize the failure and wait for reconnection.
+- If the tool rejects binary or oversized content, use the CLI/Core HTTP
+ upload/download path when the workflow exposes it; otherwise ask the user to
+ attach or upload the file through A0 CLI.
diff --git a/plugins/_a0_connector/tools/code_execution_remote.py b/plugins/_a0_connector/tools/code_execution_remote.py
index 00457d6c7..aaeb80101 100644
--- a/plugins/_a0_connector/tools/code_execution_remote.py
+++ b/plugins/_a0_connector/tools/code_execution_remote.py
@@ -6,12 +6,16 @@ import uuid
from typing import Any
from helpers.tool import Response, Tool
-from helpers.ws import NAMESPACE
-from helpers.ws_manager import ConnectionNotFoundError, get_shared_ws_manager
+from helpers.ws_manager import (
+ ConnectionNotFoundError,
+ WsPayloadTooLargeError,
+ get_shared_ws_manager,
+)
from plugins._a0_connector.helpers.exec_config import build_exec_config
from plugins._a0_connector.helpers.ws_runtime import (
clear_pending_exec_op,
+ emit_connector_event,
remote_exec_metadata_for_sid,
remote_file_metadata_for_sid,
remote_tool_sids_for_context,
@@ -210,14 +214,17 @@ class CodeExecutionRemote(Tool):
)
try:
- await get_shared_ws_manager().emit_to(
- NAMESPACE,
+ await emit_connector_event(
sid,
EXEC_OP_EVENT,
payload,
handler_id=f"{self.__class__.__module__}.{self.__class__.__name__}",
+ manager=get_shared_ws_manager(),
)
result = await asyncio.wait_for(future, timeout=wait_timeout)
+ except WsPayloadTooLargeError as exc:
+ clear_pending_exec_op(op_id)
+ return Response(message=str(exc), break_loop=False)
except ConnectionNotFoundError:
clear_pending_exec_op(op_id)
return Response(
diff --git a/plugins/_a0_connector/tools/computer_use_remote.py b/plugins/_a0_connector/tools/computer_use_remote.py
index c0ea899e4..72efcae53 100644
--- a/plugins/_a0_connector/tools/computer_use_remote.py
+++ b/plugins/_a0_connector/tools/computer_use_remote.py
@@ -9,12 +9,12 @@ from typing import Any
from helpers import chat_media, history, media_artifacts
from helpers.print_style import PrintStyle
from helpers.tool import Response, Tool
-from helpers.ws import NAMESPACE
from helpers.ws_manager import ConnectionNotFoundError, get_shared_ws_manager
from plugins._a0_connector.helpers.ws_runtime import (
clear_pending_computer_use_op,
computer_use_metadata_for_sid,
+ emit_connector_event,
select_computer_use_target_sid,
store_pending_computer_use_op,
)
@@ -203,12 +203,12 @@ class ComputerUseRemote(Tool):
)
try:
- await get_shared_ws_manager().emit_to(
- NAMESPACE,
+ await emit_connector_event(
sid,
COMPUTER_USE_OP_EVENT,
payload,
handler_id=f"{self.__class__.__module__}.{self.__class__.__name__}",
+ manager=get_shared_ws_manager(),
)
result = await asyncio.wait_for(future, timeout=COMPUTER_USE_OP_TIMEOUT)
finally:
diff --git a/plugins/_a0_connector/tools/text_editor_remote.py b/plugins/_a0_connector/tools/text_editor_remote.py
index 1db409c66..d99ddd6c2 100644
--- a/plugins/_a0_connector/tools/text_editor_remote.py
+++ b/plugins/_a0_connector/tools/text_editor_remote.py
@@ -6,8 +6,11 @@ import uuid
from typing import Any
from helpers.tool import Response, Tool
-from helpers.ws import NAMESPACE
-from helpers.ws_manager import ConnectionNotFoundError, get_shared_ws_manager
+from helpers.ws_manager import (
+ ConnectionNotFoundError,
+ WsPayloadTooLargeError,
+ get_shared_ws_manager,
+)
from plugins._a0_connector.helpers.text_editor_freshness import (
apply_patch_post_state,
@@ -18,6 +21,8 @@ from plugins._a0_connector.helpers.text_editor_freshness import (
)
from plugins._a0_connector.helpers.ws_runtime import (
clear_pending_file_op,
+ emit_connector_event,
+ payload_too_large_result,
remote_file_metadata_for_sid,
remote_tool_sids_for_context,
select_remote_file_target_sid,
@@ -31,12 +36,30 @@ from plugins._text_editor.helpers.patch_request import (
FILE_OP_TIMEOUT = 30.0
FILE_OP_EVENT = "connector_file_op"
+REMOTE_FILE_TEXT_MAX_BYTES = 256 * 1024
UNSUPPORTED_FRESHNESS_ERROR = (
"text_editor_remote: the connected CLI is too old for freshness-aware patching. "
"Upgrade the CLI and try again."
)
+def _modification_payload_bytes(op: str, payload: dict[str, Any]) -> int:
+ if op == "write":
+ return len(str(payload.get("content", "")).encode("utf-8"))
+ if op != "patch":
+ return 0
+ if payload.get("patch_text") is not None:
+ return len(str(payload["patch_text"]).encode("utf-8"))
+ edits = payload.get("edits")
+ if not isinstance(edits, list):
+ return 0
+ return sum(
+ len(str(edit.get("content")).encode("utf-8"))
+ for edit in edits
+ if isinstance(edit, dict) and edit.get("content") is not None
+ )
+
+
class TextEditorRemote(Tool):
"""Send file-editing operations to the connected CLI machine."""
@@ -172,6 +195,24 @@ class TextEditorRemote(Tool):
path: str,
**payload_extra: Any,
) -> dict[str, Any]:
+ actual_bytes = _modification_payload_bytes(op, payload_extra)
+ if actual_bytes > REMOTE_FILE_TEXT_MAX_BYTES:
+ return {
+ "ok": False,
+ "code": "PAYLOAD_TOO_LARGE",
+ "error": (
+ f"text_editor_remote limits write and patch content to "
+ f"{REMOTE_FILE_TEXT_MAX_BYTES} bytes; received {actual_bytes}. "
+ "Use the authenticated HTTP bulk transfer path instead."
+ ),
+ "details": {
+ "type": "payload_too_large",
+ "actual_bytes": actual_bytes,
+ "limit_bytes": REMOTE_FILE_TEXT_MAX_BYTES,
+ "alternative": "http_bulk_transfer",
+ },
+ }
+
context_id = self.agent.context.id
require_writes = op in {"write", "patch"}
candidates = remote_tool_sids_for_context(context_id)
@@ -224,14 +265,17 @@ class TextEditorRemote(Tool):
)
try:
- await get_shared_ws_manager().emit_to(
- NAMESPACE,
+ await emit_connector_event(
sid,
FILE_OP_EVENT,
payload,
handler_id=f"{self.__class__.__module__}.{self.__class__.__name__}",
+ manager=get_shared_ws_manager(),
)
result = await asyncio.wait_for(future, timeout=FILE_OP_TIMEOUT)
+ except WsPayloadTooLargeError as exc:
+ clear_pending_file_op(op_id)
+ return payload_too_large_result(exc, op_id=op_id)
except ConnectionNotFoundError:
clear_pending_file_op(op_id)
return {
@@ -332,7 +376,19 @@ class TextEditorRemote(Tool):
if op == "read":
content = data.get("content", "")
total_lines = data.get("total_lines", "?")
- return f"{path} {total_lines} lines\n>>>\n{content}\n<<<"
+ message = f"{path} {total_lines} lines\n>>>\n{content}\n<<<"
+ truncation = data.get("truncation")
+ if data.get("truncated") and isinstance(truncation, dict):
+ reason = str(truncation.get("reason") or "configured limit")
+ next_line = truncation.get("next_line")
+ continuation = (
+ f" Continue with line_from={next_line}." if next_line else ""
+ )
+ message += (
+ f"\n[Remote text read truncated by {reason}.{continuation} "
+ "Use HTTP bulk transfer for the complete or binary file.]"
+ )
+ return message
if op == "write":
return data.get("message") or f"{path} written successfully"
if op == "patch":
diff --git a/plugins/_browser/helpers/connector_runtime.py b/plugins/_browser/helpers/connector_runtime.py
index d5f05cb71..0ad061392 100644
--- a/plugins/_browser/helpers/connector_runtime.py
+++ b/plugins/_browser/helpers/connector_runtime.py
@@ -11,11 +11,6 @@ from urllib.parse import urlparse
from helpers import chat_media, media_artifacts
-try:
- from helpers.ws import NAMESPACE
-except Exception:
- NAMESPACE = "/ws"
-
try:
from helpers.ws_manager import ConnectionNotFoundError, get_shared_ws_manager
except Exception:
@@ -27,6 +22,7 @@ except Exception:
from plugins._a0_connector.helpers.ws_runtime import (
clear_pending_browser_op,
+ emit_connector_event,
host_browser_metadata_for_context,
host_browser_metadata_for_sid,
select_host_browser_candidate_sid,
@@ -341,12 +337,12 @@ class ConnectorBrowserRuntime:
context_id=self.context_id,
)
try:
- await get_shared_ws_manager().emit_to(
- NAMESPACE,
+ await emit_connector_event(
sid,
BROWSER_OP_EVENT,
payload,
handler_id=f"{self.__class__.__module__}.{self.__class__.__name__}",
+ manager=get_shared_ws_manager(),
)
response = await asyncio.wait_for(future, timeout=BROWSER_OP_TIMEOUT)
except ConnectionNotFoundError as exc:
diff --git a/tests/test_host_browser_connector.py b/tests/test_host_browser_connector.py
index d7e17bf98..7daf4e218 100644
--- a/tests/test_host_browser_connector.py
+++ b/tests/test_host_browser_connector.py
@@ -397,8 +397,16 @@ def test_connector_runtime_ensures_preparable_host_browser_before_action(monkeyp
emitted: list[dict[str, object]] = []
class FakeWsManager:
- async def emit_to(self, namespace, target_sid, event, payload, handler_id=""):
- del namespace, event, handler_id
+ async def emit_to(
+ self,
+ namespace,
+ target_sid,
+ event,
+ payload,
+ handler_id="",
+ **kwargs,
+ ):
+ del namespace, event, handler_id, kwargs
emitted.append(dict(payload))
assert target_sid == sid
if payload["action"] == "ensure":
diff --git a/tests/test_tool_action_contracts.py b/tests/test_tool_action_contracts.py
index 45defc0fb..0b7b0225c 100644
--- a/tests/test_tool_action_contracts.py
+++ b/tests/test_tool_action_contracts.py
@@ -274,6 +274,10 @@ def _load_computer_use_remote_tool(monkeypatch):
ws_runtime_stub = types.ModuleType("plugins._a0_connector.helpers.ws_runtime")
ws_runtime_stub.clear_pending_computer_use_op = lambda *args, **kwargs: None
ws_runtime_stub.computer_use_metadata_for_sid = lambda *args, **kwargs: {}
+ async def _emit_connector_event(*args, **kwargs):
+ return None
+
+ ws_runtime_stub.emit_connector_event = _emit_connector_event
ws_runtime_stub.select_computer_use_target_sid = lambda *args, **kwargs: "sid"
ws_runtime_stub.store_pending_computer_use_op = lambda *args, **kwargs: None
monkeypatch.setitem(