Skip to content

Agent Zero AI framework

feat(a0-connector): lazy-load remote tool guidance

Alessandro7c71185f1649
diff --git a/plugins/_a0_connector/extensions/python/_functions/extensions/python/system_prompt/_11_tools_prompt/build_prompt/end/_70_include_remote_tool_stubs.py b/plugins/_a0_connector/extensions/python/_functions/extensions/python/system_prompt/_11_tools_prompt/build_prompt/end/_70_include_remote_tool_stubs.py
new file mode 100644
index 000000000..4f437c5c4
--- /dev/null
+++ b/plugins/_a0_connector/extensions/python/_functions/extensions/python/system_prompt/_11_tools_prompt/build_prompt/end/_70_include_remote_tool_stubs.py
@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from helpers.extension import Extension
+
+from plugins._a0_connector.helpers.ws_runtime import (
+ computer_use_metadata_for_sid,
+ remote_exec_metadata_for_sid,
+ remote_file_metadata_for_sid,
+ subscribed_sids_for_context,
+)
+
+
+@dataclass(frozen=True)
+class RemoteFileCapability:
+ available: bool
+ write_enabled: bool = False
+ access_mode: str = "Unknown"
+ advertised: bool = False
+
+
+class IncludeRemoteToolStubs(Extension):
+ def execute(self, data: dict[str, Any] = {}, **kwargs: Any) -> None:
+ if not self.agent:
+ return
+
+ result = data.get("result")
+ if not isinstance(result, str):
+ return
+
+ context_id = str(getattr(self.agent.context, "id", "") or "").strip()
+ if not context_id:
+ return
+
+ stubs: list[str] = []
+ file_capability = _remote_file_capability(context_id)
+
+ if file_capability.available:
+ stubs.append(
+ self.agent.read_prompt(
+ "agent.connector_tool.text_editor_remote.md",
+ access_mode=file_capability.access_mode,
+ write_guidance=_file_write_guidance(file_capability),
+ )
+ )
+
+ if _remote_exec_available(context_id):
+ stubs.append(
+ self.agent.read_prompt(
+ "agent.connector_tool.code_execution_remote.md",
+ access_mode=file_capability.access_mode,
+ write_runtime_note=_exec_write_runtime_note(file_capability),
+ )
+ )
+
+ computer_use = _computer_use_capability(context_id)
+ if computer_use:
+ stubs.append(
+ self.agent.read_prompt(
+ "agent.connector_tool.computer_use_remote.md",
+ backend=computer_use["backend"],
+ trust_mode=computer_use["trust_mode"],
+ features=computer_use["features"],
+ )
+ )
+
+ if not stubs:
+ return
+
+ data["result"] = (
+ result.rstrip()
+ + "\n\n"
+ + "\n\n".join(stub.strip() for stub in stubs if stub.strip())
+ )
+
+
+def _subscribed_sids(context_id: str) -> list[str]:
+ return sorted(subscribed_sids_for_context(context_id))
+
+
+def _remote_file_capability(context_id: str) -> RemoteFileCapability:
+ saw_advertised = False
+ saw_enabled = False
+ saw_write_enabled = False
+
+ for sid in _subscribed_sids(context_id):
+ metadata = remote_file_metadata_for_sid(sid)
+ if not metadata:
+ continue
+ saw_advertised = True
+ if not metadata.get("enabled", True):
+ continue
+ saw_enabled = True
+ if metadata.get("write_enabled"):
+ saw_write_enabled = True
+
+ if not saw_enabled:
+ return RemoteFileCapability(
+ available=False,
+ access_mode="Disabled" if saw_advertised else "Unknown",
+ advertised=saw_advertised,
+ )
+
+ return RemoteFileCapability(
+ available=True,
+ write_enabled=saw_write_enabled,
+ access_mode="Read&Write" if saw_write_enabled else "Read only",
+ advertised=True,
+ )
+
+
+def _remote_exec_available(context_id: str) -> bool:
+ for sid in _subscribed_sids(context_id):
+ metadata = remote_exec_metadata_for_sid(sid)
+ if metadata and metadata.get("enabled"):
+ return True
+ return False
+
+
+def _computer_use_capability(context_id: str) -> dict[str, str] | None:
+ for sid in _subscribed_sids(context_id):
+ metadata = computer_use_metadata_for_sid(sid)
+ if not metadata or not metadata.get("supported") or not metadata.get("enabled"):
+ continue
+
+ backend_id = str(metadata.get("backend_id") or "").strip() or "unknown"
+ backend_family = str(metadata.get("backend_family") or "").strip()
+ backend = backend_id if not backend_family else f"{backend_id}/{backend_family}"
+ trust_mode = str(metadata.get("trust_mode") or "").strip() or "unknown"
+ features_value = metadata.get("features")
+ if isinstance(features_value, (list, tuple)):
+ features = ", ".join(
+ str(item).strip() for item in features_value if str(item).strip()
+ )
+ else:
+ features = ""
+
+ return {
+ "backend": backend,
+ "trust_mode": trust_mode,
+ "features": features or "none advertised",
+ }
+
+ return None
+
+
+def _file_write_guidance(capability: RemoteFileCapability) -> str:
+ if capability.write_enabled:
+ return "Writes and patches are currently available."
+ return (
+ "Writes and patches are disabled until the user switches the CLI to "
+ "Read&Write with F3."
+ )
+
+
+def _exec_write_runtime_note(capability: RemoteFileCapability) -> str:
+ if capability.write_enabled:
+ return "Mutating runtimes are currently available because local access is Read&Write."
+ if capability.available:
+ return (
+ "Mutating runtimes are disabled until the user switches the CLI to "
+ "Read&Write with F3; use output/reset only for existing sessions."
+ )
+ if capability.advertised:
+ return (
+ "The CLI advertises remote file access as disabled; mutating runtimes "
+ "are unavailable until local file access is enabled."
+ )
+ return (
+ "The CLI did not advertise a file access mode; prefer non-mutating "
+ "inspection until access is clear."
+ )
diff --git a/plugins/_a0_connector/extensions/python/message_loop_prompts_after/_77_include_computer_use_remote.py b/plugins/_a0_connector/extensions/python/message_loop_prompts_after/_77_include_computer_use_remote.py
deleted file mode 100644
index 240e9a089..000000000
--- a/plugins/_a0_connector/extensions/python/message_loop_prompts_after/_77_include_computer_use_remote.py
+++ /dev/null
@@ -1,50 +0,0 @@
-from __future__ import annotations
-
-from agent import LoopData
-from helpers.extension import Extension
-
-from plugins._a0_connector.helpers.ws_runtime import (
- computer_use_metadata_for_sid,
- select_computer_use_target_sid,
-)
-
-
-class IncludeComputerUseRemote(Extension):
- async def execute(self, loop_data: LoopData = LoopData(), **kwargs):
- if not self.agent:
- return
-
- context_id = getattr(self.agent.context, "id", "")
- if not context_id:
- return
-
- sid = select_computer_use_target_sid(context_id)
- if not sid:
- return
-
- metadata = computer_use_metadata_for_sid(sid)
- if not metadata or not metadata.get("supported") or not metadata.get("enabled"):
- return
-
- backend_id = str(metadata.get("backend_id") or "").strip() or "unknown"
- backend_family = str(metadata.get("backend_family") or "").strip()
- backend = backend_id if not backend_family else f"{backend_id}/{backend_family}"
- trust_mode = str(metadata.get("trust_mode") or "").strip() or "unknown"
- support_reason = str(metadata.get("support_reason") or "").strip() or "No support details available."
-
- features_value = metadata.get("features")
- if isinstance(features_value, (list, tuple)):
- features = ", ".join(str(item).strip() for item in features_value if str(item).strip())
- else:
- features = ""
- if not features:
- features = "none advertised"
-
- prompt = self.agent.read_prompt(
- "agent.extras.computer_use_remote.md",
- backend=backend,
- trust_mode=trust_mode,
- features=features,
- support_reason=support_reason,
- )
- loop_data.extras_temporary["computer_use_remote"] = prompt
diff --git a/plugins/_a0_connector/extensions/python/message_loop_prompts_after/_78_include_code_execution_remote.py b/plugins/_a0_connector/extensions/python/message_loop_prompts_after/_78_include_code_execution_remote.py
deleted file mode 100644
index 72ceb6174..000000000
--- a/plugins/_a0_connector/extensions/python/message_loop_prompts_after/_78_include_code_execution_remote.py
+++ /dev/null
@@ -1,127 +0,0 @@
-from __future__ import annotations
-
-from agent import LoopData
-from helpers.extension import Extension
-
-from plugins._a0_connector.helpers.exec_config import build_exec_config
-from plugins._a0_connector.helpers.ws_runtime import (
- remote_file_metadata_for_sid,
- select_remote_exec_target_sid,
-)
-
-
-def _format_timeouts(payload: dict[str, int]) -> str:
- return ", ".join(f"{key}={value}" for key, value in payload.items()) or "none"
-
-
-def _format_patterns(value: object) -> str:
- if isinstance(value, (list, tuple)):
- items = [str(item).strip() for item in value if str(item).strip()]
- else:
- items = []
- return ", ".join(items) or "none"
-
-
-class IncludeCodeExecutionRemote(Extension):
- async def execute(self, loop_data: LoopData = LoopData(), **kwargs):
- if not self.agent:
- return
-
- context_id = getattr(self.agent.context, "id", "")
- if not context_id:
- return
-
- sid = select_remote_exec_target_sid(context_id, require_writes=False)
- if not sid:
- return
-
- metadata = remote_file_metadata_for_sid(sid)
- if metadata is None:
- access_mode = "Read&Write (legacy/unknown)"
- write_runtime_guidance = (
- "- `runtime=terminal`, `python`, `nodejs`, and `input` are expected to be "
- "available, but this CLI did not advertise an explicit F3 access mode.\n"
- "- Use shell syntax that matches the remote host (for example, PowerShell on "
- "Windows)."
- )
- write_runtime_examples = """```json
-{
- "tool_name": "code_execution_remote",
- "tool_args": {
- "runtime": "terminal",
- "session": 0,
- "code": "pwd"
- }
-}
-```
-
-```json
-{
- "tool_name": "code_execution_remote",
- "tool_args": {
- "runtime": "python",
- "session": 0,
- "code": "import os\\nprint(os.getcwd())"
- }
-}
-```"""
- elif metadata.get("write_enabled"):
- access_mode = "Read&Write"
- write_runtime_guidance = (
- "- `runtime=terminal`, `python`, `nodejs`, and `input` may modify files on "
- "the remote CLI machine. Use them only when shell-backed execution is the "
- "right tool for the job.\n"
- "- Use shell syntax that matches the remote host (for example, PowerShell on "
- "Windows)."
- )
- write_runtime_examples = """```json
-{
- "tool_name": "code_execution_remote",
- "tool_args": {
- "runtime": "terminal",
- "session": 0,
- "code": "pwd"
- }
-}
-```
-
-```json
-{
- "tool_name": "code_execution_remote",
- "tool_args": {
- "runtime": "python",
- "session": 0,
- "code": "import os\\nprint(os.getcwd())"
- }
-}
-```"""
- else:
- access_mode = "Read only"
- write_runtime_guidance = (
- "- `runtime=terminal`, `python`, `nodejs`, and `input` are disabled while "
- "local access is Read only. Press F3 to switch the host machine to Read&Write "
- "before starting new shell-backed work that could modify files."
- )
- write_runtime_examples = ""
-
- exec_config = build_exec_config(agent=self.agent)
- code_exec_timeouts = exec_config.get("code_exec_timeouts")
- output_timeouts = exec_config.get("output_timeouts")
- prompt_patterns = exec_config.get("prompt_patterns")
- dialog_patterns = exec_config.get("dialog_patterns")
-
- prompt = self.agent.read_prompt(
- "agent.extras.code_execution_remote.md",
- access_mode=access_mode,
- write_runtime_guidance=write_runtime_guidance,
- write_runtime_examples=write_runtime_examples,
- code_exec_timeouts=_format_timeouts(
- code_exec_timeouts if isinstance(code_exec_timeouts, dict) else {}
- ),
- output_timeouts=_format_timeouts(
- output_timeouts if isinstance(output_timeouts, dict) else {}
- ),
- prompt_patterns=_format_patterns(prompt_patterns),
- dialog_patterns=_format_patterns(dialog_patterns),
- )
- loop_data.extras_temporary["code_execution_remote"] = prompt
diff --git a/plugins/_a0_connector/extensions/python/message_loop_prompts_after/_79_include_text_editor_remote.py b/plugins/_a0_connector/extensions/python/message_loop_prompts_after/_79_include_text_editor_remote.py
deleted file mode 100644
index 0c9cecf2e..000000000
--- a/plugins/_a0_connector/extensions/python/message_loop_prompts_after/_79_include_text_editor_remote.py
+++ /dev/null
@@ -1,120 +0,0 @@
-from __future__ import annotations
-
-from agent import LoopData
-from helpers.extension import Extension
-
-from plugins._a0_connector.helpers.ws_runtime import (
- remote_file_metadata_for_sid,
- select_remote_file_target_sid,
-)
-
-
-class IncludeTextEditorRemote(Extension):
- async def execute(self, loop_data: LoopData = LoopData(), **kwargs):
- if not self.agent:
- return
-
- context_id = getattr(self.agent.context, "id", "")
- if not context_id:
- return
-
- sid = select_remote_file_target_sid(context_id)
- if not sid:
- return
-
- metadata = remote_file_metadata_for_sid(sid)
- if metadata is None:
- access_mode = "Read&Write (legacy/unknown)"
- write_guidance = (
- "- Writes and patches are expected to be available, but this CLI did not "
- "advertise an explicit F3 access mode.\n"
- "- Prefer `patch_text` for context-anchored edits when supported."
- )
- write_examples = """```json
-{
- "tool_name": "text_editor_remote",
- "tool_args": {
- "op": "write",
- "path": "/path/on/remote/machine/file.py",
- "content": "import os\\nprint('hello')\\n"
- }
-}
-```
-
-```json
-{
- "tool_name": "text_editor_remote",
- "tool_args": {
- "op": "patch",
- "path": "/path/on/remote/machine/file.py",
- "patch_text": "*** Begin Patch\\n*** Update File: /path/on/remote/machine/file.py\\n@@ def main():\\n+ setup()\\n*** End Patch"
- }
-}
-```"""
- elif metadata.get("write_enabled"):
- access_mode = "Read&Write"
- write_guidance = (
- "- Use `write` only when replacing or creating the full file is the right operation.\n"
- "- Use `patch` with `patch_text` for context-anchored edits, especially after inserts/deletes or when line numbers may have shifted.\n"
- "- Use `patch` with `edits` only for surgical line-range edits based on the latest remote read.\n"
- "- Freshness-aware line patching may reject stale edits. If a line patch requires a reread, read the file again and then retry with updated ranges."
- )
- write_examples = """```json
-{
- "tool_name": "text_editor_remote",
- "tool_args": {
- "op": "write",
- "path": "/path/on/remote/machine/file.py",
- "content": "import os\\nprint('hello')\\n"
- }
-}
-```
-
-```json
-{
- "tool_name": "text_editor_remote",
- "tool_args": {
- "op": "patch",
- "path": "/path/on/remote/machine/file.py",
- "patch_text": "*** Begin Patch\\n*** Update File: /path/on/remote/machine/file.py\\n@@ def main():\\n+ setup()\\n*** End Patch"
- }
-}
-```
-
-```json
-{
- "tool_name": "text_editor_remote",
- "tool_args": {
- "op": "patch",
- "path": "/path/on/remote/machine/file.py",
- "patch_text": "*** Begin Patch\\n*** Update File: /path/on/remote/machine/file.py\\n@@ def main():\\n- old_helper()\\n+ new_helper()\\n*** End Patch"
- }
-}
-```
-
-```json
-{
- "tool_name": "text_editor_remote",
- "tool_args": {
- "op": "patch",
- "path": "/path/on/remote/machine/file.py",
- "edits": [
- {"from": 5, "to": 5, "content": " if x == 2:\\n"}
- ]
- }
-}
-```"""
- else:
- access_mode = "Read only"
- write_guidance = (
- "- Writes and patches are disabled in this CLI session. Press F3 to switch the host machine to Read&Write before attempting `write` or `patch`."
- )
- write_examples = ""
-
- prompt = self.agent.read_prompt(
- "agent.extras.text_editor_remote.md",
- access_mode=access_mode,
- write_guidance=write_guidance,
- write_examples=write_examples,
- )
- loop_data.extras_temporary["text_editor_remote"] = prompt
diff --git a/plugins/_a0_connector/prompts/agent.connector_tool.code_execution_remote.md b/plugins/_a0_connector/prompts/agent.connector_tool.code_execution_remote.md
new file mode 100644
index 000000000..4c94d5f30
--- /dev/null
+++ b/plugins/_a0_connector/prompts/agent.connector_tool.code_execution_remote.md
@@ -0,0 +1,27 @@
+# code_execution_remote tool
+
+Runs shell-backed execution on the machine where the subscribed A0 CLI is running.
+Load `a0-cli-remote-workflows` before using this tool for nontrivial local project work.
+
+Current local access mode: `{{access_mode}}`
+
+## Requirements
+- A CLI client is subscribed to this chat and advertises remote execution.
+- Paths and shell syntax are evaluated on the CLI host, not inside Agent Zero.
+- {{write_runtime_note}}
+
+## Arguments
+- `runtime`: one of `terminal`, `python`, `nodejs`, `output`, `reset`
+- `runtime=input` is a temporary deprecated compatibility alias for sending one line of
+ keyboard input into a running shell session
+- `session`: integer session id (default `0`)
+
+Runtime-specific fields:
+- `terminal`, `python`, `nodejs`: require `code`
+- `input`: requires `keyboard` (or `code` as fallback)
+- `reset`: optional `reason`
+
+## Notes
+- Reuse `session` when continuing a workflow.
+- Use `output` to poll a running session and `reset` for a stuck session.
+- If the CLI returns a disabled/no-client error, ask the user to enable or reconnect the CLI instead of falling back to server-side execution.
diff --git a/plugins/_a0_connector/prompts/agent.connector_tool.computer_use_remote.md b/plugins/_a0_connector/prompts/agent.connector_tool.computer_use_remote.md
new file mode 100644
index 000000000..70e65d249
--- /dev/null
+++ b/plugins/_a0_connector/prompts/agent.connector_tool.computer_use_remote.md
@@ -0,0 +1,27 @@
+# computer_use_remote tool
+
+Controls the subscribed A0 CLI host machine as a local desktop target.
+Load `computer-use-remote` before using this tool.
+
+## Requirements
+- A CLI client is subscribed to this chat and advertises enabled local computer use.
+- Backend: `{{backend}}`
+- Trust mode: `{{trust_mode}}`
+- Features: `{{features}}`
+
+## Arguments
+- `action`: one of `start_session`, `status`, `capture`, `move`, `click`, `scroll`, `key`, `type`, `stop_session`
+- `session_id`: optional for actions after `start_session`
+
+Action-specific fields:
+- `move`: `x`, `y` normalized to `[0,1]`
+- `click`: optional `x`, `y`, plus optional `button` (`left`, `right`, `middle`) and `count`
+- `scroll`: `dx`, `dy`
+- `key`: `key` or `keys`
+- `type`: `text`, optional `submit` boolean
+
+## Runtime Notes
+- Use `start_session` before interactive actions. `status` only inspects state.
+- Successful interactive actions attach a fresh screenshot; base decisions on the latest capture.
+- Prefer keyboard/accessibility routes before pointer actions.
+- Coordinates are normalized global screen coordinates.
diff --git a/plugins/_a0_connector/prompts/agent.connector_tool.text_editor_remote.md b/plugins/_a0_connector/prompts/agent.connector_tool.text_editor_remote.md
new file mode 100644
index 000000000..367354196
--- /dev/null
+++ b/plugins/_a0_connector/prompts/agent.connector_tool.text_editor_remote.md
@@ -0,0 +1,21 @@
+# text_editor_remote tool
+
+Reads, writes, and patches files on the machine where the subscribed A0 CLI is running.
+This is different from server-side file tools. Load `a0-cli-remote-workflows` before using it for edits.
+
+Current access mode: `{{access_mode}}`
+
+## Requirements
+- A CLI client is subscribed to this chat and advertises remote file access.
+- Paths are evaluated on the CLI host filesystem, not the Agent Zero server.
+- {{write_guidance}}
+
+## Operations
+- `read`: optional `line_from`, `line_to`
+- `write`: requires `content`
+- `patch`: requires either `patch_text` or `edits`
+
+## Notes
+- Prefer `read` before line-number edits.
+- 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.
diff --git a/plugins/_a0_connector/prompts/agent.extras.code_execution_remote.md b/plugins/_a0_connector/prompts/agent.extras.code_execution_remote.md
deleted file mode 100644
index 992343c9e..000000000
--- a/plugins/_a0_connector/prompts/agent.extras.code_execution_remote.md
+++ /dev/null
@@ -1,45 +0,0 @@
-## code_execution_remote guidance
-
-Remote code execution is currently available in this context through the connected CLI.
-Current local access mode: `{{access_mode}}`
-
-Execution config:
-- code execution timeouts: `{{code_exec_timeouts}}`
-- output polling timeouts: `{{output_timeouts}}`
-- prompt patterns: `{{prompt_patterns}}`
-- dialog patterns: `{{dialog_patterns}}`
-
-- Use this tool for shell-backed execution on the remote CLI machine, not on the Agent Zero server.
-- Session ids are frontend-local and persistent across calls. Reuse the same `session` when continuing a workflow.
-- Use `runtime=terminal` for shell commands, `runtime=python` for Python snippets, and `runtime=nodejs` for Node.js snippets.
-- Use `runtime=output` to poll a running session after a prior call returned before the shell settled.
-- Use `runtime=reset` when a session is stuck or you need a clean shell.
-- `runtime=input` is only a deprecated compatibility alias for sending one line of keyboard input into a running shell session.
-- Frontend execution may still be locally disabled in the CLI session. If so, expect a structured `{ok: false}` error instead of a fallback runtime.
-- Prefer concise, self-checking commands. For multi-step work, inspect output and continue in the same session instead of restarting from scratch.
-{{write_runtime_guidance}}
-
-Examples:
-
-```json
-{
- "tool_name": "code_execution_remote",
- "tool_args": {
- "runtime": "output",
- "session": 0
- }
-}
-```
-
-```json
-{
- "tool_name": "code_execution_remote",
- "tool_args": {
- "runtime": "reset",
- "session": 0,
- "reason": "Start a clean shell for the next step."
- }
-}
-```
-
-{{write_runtime_examples}}
diff --git a/plugins/_a0_connector/prompts/agent.extras.computer_use_remote.md b/plugins/_a0_connector/prompts/agent.extras.computer_use_remote.md
deleted file mode 100644
index 9b4c67cd9..000000000
--- a/plugins/_a0_connector/prompts/agent.extras.computer_use_remote.md
+++ /dev/null
@@ -1,29 +0,0 @@
-## computer_use_remote guidance
-
-Computer use is currently available in this context.
-Backend: `{{backend}}`
-Trust mode: `{{trust_mode}}`
-Features: `{{features}}`
-Support note: `{{support_reason}}`
-
-- Use this for local desktop and native UI tasks on the connected machine.
-- If the task is browser-only and the user is flexible, prefer the direct `browser` tool because it is usually more reliable and token-efficient than screenshot-driven desktop control.
-- Use `start_session` before interactive desktop actions. `status` is for inspection; `stop_session` ends the session.
-- Base every decision on the latest screenshot or a definitive tool result, not memory.
-- The current action API uses normalized global screen coordinates. Do not assume window IDs, element indices, background-safe input, or semantic click targets unless the advertised features explicitly say they exist.
-- If features include `real-cursor-may-move` or `focus-risk`, expect pointer actions to affect the visible desktop state; prefer keyboard/accessibility routes even more strongly.
-- Successful `start_session`, `move`, `click`, `scroll`, `key`, and `type` calls already attach a fresh screenshot.
-- Each attached screenshot includes a `capture id`; treat the latest attached capture as authoritative and ignore superseded capture references.
-- If an attached screenshot looks unchanged after a state-changing action, use one explicit `capture` to verify before repeating the same action.
-- Use `capture` only when you need a screen refresh without taking another action.
-- Prefer accessibility and semantic UI paths first: application shortcuts, command palettes, menu accelerators, address/search bars, focus traversal, selection shortcuts, and other keyboard-accessible controls.
-- Prefer `key` and `type` over pointer actions whenever there is a plausible keyboard or accessibility path. Use `tab`, `shift+tab`, arrow keys, hotkeys, text search, and submit keys before reaching for the mouse.
-- For viewport movement, try keyboard scrolling first: `page_down`, `page_up`, `space`, `shift+space`, arrow keys, `home`, or `end`. Use `scroll` when the desired scrollable region is already active or a keyboard route cannot target it; prefer `scroll` over click-dragging or clicking scrollbars.
-- Treat `move` and `click` as last-resort actions for controls that cannot be reached or activated reliably through accessibility, hotkeys, keyboard navigation, or browser/app-native tooling.
-- Before clicking, make sure the latest screenshot makes the target unambiguous and that a keyboard/accessibility route has already been tried or ruled out. Use one deliberate click, then reassess from the fresh screenshot.
-- Treat menus and popups as transient UI. If a click dismisses one without visible progress, treat that attempt as failed and switch to a non-pointer strategy.
-- If the same approach has already failed twice without visible progress, stop repeating it and try a different strategy.
-- For browser work done through this tool, only claim success when the page content area visibly shows the expected destination or result.
-- Use `type(..., submit=true)` only for navigation-style entry such as an address bar or command box. For ordinary text fields, type first and send `enter` separately only if needed.
-- In `free_run`, do not expect a fresh approval prompt. If silent restore is no longer valid, expect `COMPUTER_USE_REARM_REQUIRED`.
-- Treat user interventions as high-priority control signals. If the user says `stop`, `pause`, `abort`, `hold`, `don't continue`, or equivalent, stop using computer-use tools until the user explicitly resumes.
diff --git a/plugins/_a0_connector/prompts/agent.extras.text_editor_remote.md b/plugins/_a0_connector/prompts/agent.extras.text_editor_remote.md
deleted file mode 100644
index 4c1149d8e..000000000
--- a/plugins/_a0_connector/prompts/agent.extras.text_editor_remote.md
+++ /dev/null
@@ -1,29 +0,0 @@
-## text_editor_remote guidance
-
-Remote file editing is currently available in this context through the connected CLI.
-Current access mode: `{{access_mode}}`
-
-- Use `text_editor_remote` when the user asks you to edit files on their local machine while connected via the CLI.
-- Paths are evaluated on the remote CLI machine's filesystem, not on the Agent Zero server.
-- Prefer `patch_text` for edits that can be located by surrounding code context.
-- For `patch_text` inserts, use one `@@ existing line` anchor followed directly by `+new line`.
-- For `patch_text` replacements, use `@@ before target` then `-old`/`+new`, or `@@ old target` then the same `-old`/`+new`.
-- Do not repeat the same old line as both context and deletion in one replacement hunk.
-- Prefer `read` before line-number `edits` so you have current line numbers and freshness metadata.
-- `read` is always the safest first step for inspecting the local file.
-{{write_guidance}}
-
-Examples:
-
-```json
-{
- "tool_name": "text_editor_remote",
- "tool_args": {
- "op": "read",
- "path": "/path/on/remote/machine/file.py",
- "line_from": 1,
- "line_to": 50
- }
-}
-```
-{{write_examples}}
diff --git a/plugins/_a0_connector/prompts/agent.system.tool.code_execution_remote.md b/plugins/_a0_connector/prompts/agent.system.tool.code_execution_remote.md
deleted file mode 100644
index 9e7823439..000000000
--- a/plugins/_a0_connector/prompts/agent.system.tool.code_execution_remote.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# code_execution_remote tool
-
-This tool runs shell-backed execution on the **remote machine where the CLI is running**.
-Detailed usage guidance is injected separately only when the current context has a
-subscribed CLI, so the base system prompt stays small when remote execution is not in play.
-
-## Requirements
-- A CLI client must be connected to this context via the shared `/ws` namespace.
-- The CLI client must support `connector_exec_op`.
-- Frontend execution may be locally disabled in the CLI session; in that case the result is
- a structured `{ok: false}` error and no fallback runtime is used.
-- Mutating runtimes (`terminal`, `python`, `nodejs`, and `input`) also require the CLI
- session to advertise local access mode `Read&Write` via F3. `output` and `reset` can
- still be used for existing sessions while the CLI is in `Read only`.
-
-## Arguments
-- `runtime`: one of `terminal`, `python`, `nodejs`, `output`, `reset`
-- `runtime=input` is a temporary deprecated compatibility alias for sending one line of
- keyboard input into a running shell session
-- `session`: integer session id (default `0`)
-
-Runtime-specific fields:
-- `terminal`, `python`, `nodejs`: require `code`
-- `input`: requires `keyboard` (or `code` as fallback)
-- `reset`: optional `reason`
-
-## Notes
-- Session state is frontend-local and shell-backed.
-- `output` is for long-running operations where a prior call returned control before the
- shell reached a prompt.
-- Use shell syntax that matches the remote host (for example, PowerShell on Windows).
-- The transport uses `connector_exec_op` and `connector_exec_op_result` with shared `op_id`.
diff --git a/plugins/_a0_connector/prompts/agent.system.tool.computer_use_remote.md b/plugins/_a0_connector/prompts/agent.system.tool.computer_use_remote.md
deleted file mode 100644
index 78800f8b9..000000000
--- a/plugins/_a0_connector/prompts/agent.system.tool.computer_use_remote.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# computer_use_remote tool
-
-Use the connected CLI host machine as a local desktop target.
-
-This tool is only usable when the current context has a subscribed CLI with enabled local computer use.
-Detailed operating guidance is injected separately only when that condition is true, so the base system prompt stays small when computer use is not in play.
-
-## Requirements
-- A CLI client must be connected to this context via the shared `/ws` namespace.
-- The CLI must advertise `computer_use_remote` support and local computer use must be enabled there.
-
-## Arguments
-- `action`: one of `start_session`, `status`, `capture`, `move`, `click`, `scroll`, `key`, `type`, `stop_session`
-- `session_id`: optional for actions after `start_session`
-
-Action-specific fields:
-- `move`: `x`, `y` normalized to `[0,1]`
-- `click`: optional `x`, `y`, plus optional `button` (`left`, `right`, `middle`) and `count`
-- `scroll`: `dx`, `dy`
-- `key`: `key` or `keys`
-- `type`: `text`, optional `submit` boolean
-
-## Runtime Notes
-- The current action API uses normalized global screen coordinates; do not assume window IDs, element indices, background-safe input, or semantic click targets unless runtime guidance explicitly advertises them.
-- Successful `start_session`, `move`, `click`, `scroll`, `key`, and `type` calls automatically attach a fresh screenshot.
-- Attached screenshots include a `capture id`; use the latest capture as the coordinate basis.
-- If the attached screenshot appears unchanged after a state-changing action, verify once with `capture` before repeating the same action.
-- `status` reports the current computer-use state without starting a session.
-- Prefer accessibility, semantic UI controls, hotkeys, focus traversal, and other keyboard paths before pointer actions.
-- For viewport movement, prefer keyboard scrolling first; use `scroll` when a wheel-style scroll is the most reliable way to move an already-focused viewport or pane.
-- Use `move` and `click` only as a last resort when no reliable accessibility or keyboard route is available and the latest screenshot makes the target unambiguous.
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
deleted file mode 100644
index cad385810..000000000
--- a/plugins/_a0_connector/prompts/agent.system.tool.text_editor_remote.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# text_editor_remote tool
-
-This tool allows you to read, write, and patch files on the **remote machine where the CLI is running**.
-This is different from `text_editor` which operates on the Agent Zero server's filesystem.
-Detailed usage guidance is injected separately only when the current context has a
-subscribed CLI, so the base system prompt stays small when remote editing is not in play.
-
-## Requirements
-- A CLI client must be connected to this context via the shared `/ws` namespace.
-- The CLI client must have enabled remote file editing support.
-
-## Operations
-- `read`: optional `line_from`, `line_to`
-- `write`: requires `content`
-- `patch`: requires either `patch_text` or `edits`
-
-## Notes
-- Paths are evaluated on the **remote machine's filesystem**, not the Agent Zero server.
-- The transport uses `connector_file_op` and `connector_file_op_result` with a shared `op_id`.
-- `patch_text` uses context chunks and does not require fresh line numbers.
-- `patch_text` line rules: `@@ existing line` anchors the hunk; `+new` inserts after the anchor when there are no context or delete lines; `-old` then `+new` replaces the next matching old line after the anchor, or the anchor line itself when `@@` is the old target line.
-- For replacements, do not repeat the same old line as both a space-context line and a `-old` line.
-- Every non-header content line in `patch_text` must start with exactly one prefix: space for kept context, `+` for added content, or `-` for removed content. Do not emit raw unprefixed content lines.
-- Do not stack multiple `@@` lines for one insert. Use one anchor, then the `+` lines to insert.
-- `edits` uses 1-based line ranges and may require rereading after line-count changes.
diff --git a/plugins/_a0_connector/skills/a0-cli-remote-workflows/SKILL.md b/plugins/_a0_connector/skills/a0-cli-remote-workflows/SKILL.md
new file mode 100644
index 000000000..5b57d75db
--- /dev/null
+++ b/plugins/_a0_connector/skills/a0-cli-remote-workflows/SKILL.md
@@ -0,0 +1,64 @@
+---
+name: a0-cli-remote-workflows
+description: Guide safe use of A0 CLI remote shell execution and remote file editing on the connected host machine. Load before using code_execution_remote or text_editor_remote for local project work through the CLI connector.
+version: 1.0.0
+author: Agent Zero Team
+tags: ["agent-zero", "a0", "cli", "connector", "remote-execution", "remote-files"]
+trigger_patterns:
+ - "code_execution_remote"
+ - "text_editor_remote"
+ - "remote file editing"
+ - "remote shell execution"
+ - "edit my local files through a0 cli"
+ - "run commands on the cli host"
+allowed_tools:
+ - code_execution_remote
+ - text_editor_remote
+---
+
+# A0 CLI Remote Workflows
+
+## Boundary
+
+Use `code_execution_remote` and `text_editor_remote` only for work on the machine where A0 CLI is running. These paths, shells, runtimes, and files belong to the CLI host, not the Agent Zero server or Docker container.
+
+If the task belongs inside Agent Zero's own runtime, use the normal server-side tools instead.
+
+## Access Modes
+
+- Read only: inspect files and poll/reset existing execution sessions. Do not attempt writes or mutating shell work until the user switches the CLI to Read&Write with F3.
+- Read&Write: shell-backed execution, writes, and patches may modify the CLI host. Keep changes narrow and intentional.
+- Execution may also be disabled locally in the CLI. If a remote tool returns a structured disabled/no-client error, explain the required CLI toggle instead of falling back to the server filesystem.
+
+## Remote Execution
+
+- Use `runtime=terminal` for shell commands, `runtime=python` for Python snippets, and `runtime=nodejs` for Node.js snippets.
+- Reuse the same integer `session` while continuing a workflow; session state is local to the CLI frontend.
+- Use `runtime=output` when a previous command is still running or returned before the shell reached a prompt.
+- Use `runtime=reset` when a session is stuck or a clean shell is safer.
+- Treat `runtime=input` as deprecated compatibility for sending one line to a running shell.
+- Match the remote host shell syntax. A Windows CLI may need PowerShell syntax even when Agent Zero runs on Linux.
+
+## Remote File Editing
+
+- Start with `read` when inspecting a file or preparing line-based edits.
+- Use `write` only when replacing or creating the whole file is truly the right operation.
+- Prefer `patch` with `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.
+
+## Patch Text Rules
+
+- `patch_text` supports update hunks for one file.
+- Use one `@@ existing line` anchor, then `+new line` entries for insertion.
+- For replacement, use `@@ before target` followed by `-old` and `+new`, or use `@@ old target` followed by the same replacement pair.
+- Do not repeat the same old line as both context and deletion in one hunk.
+- Every non-header content line must begin with exactly one prefix: space for context, `+` for additions, or `-` for removals.
+- Do not stack multiple `@@` anchors for one insert.
+
+## Failure Handling
+
+- If no CLI is connected or subscribed, ask the user to connect A0 CLI to this chat.
+- If writes are blocked, tell the user to switch local access to Read&Write with F3.
+- If execution is disabled, tell the user to enable remote execution in the CLI.
+- If a request times out or the CLI disconnects, poll once if a session may still be running; otherwise summarize the failure and wait for reconnection.
diff --git a/skills/computer-use-remote/SKILL.md b/skills/computer-use-remote/SKILL.md
index 4b545ebf0..c31b76dc7 100644
--- a/skills/computer-use-remote/SKILL.md
+++ b/skills/computer-use-remote/SKILL.md
@@ -1,7 +1,7 @@
---
name: computer-use-remote
description: Detailed operating guide for using computer_use_remote on the connected local machine. Load this skill before using computer_use_remote for desktop control, screenshots, menus, browser chrome, or other native UI tasks.
-version: 1.0.0
+version: 1.1.0
author: Agent Zero Team
tags: ["computer-use", "desktop", "local-ui", "screenshots", "native-ui"]
trigger_patterns:
@@ -23,27 +23,38 @@ allowed_tools:
Load this skill before using `computer_use_remote` for local desktop and native UI tasks on the connected machine.
-For ordinary website browsing, search, form filling, and web downloads, prefer the direct `browser` tool instead. If the user is flexible and the task is browser-only, guide them toward browser tools because they are usually more reliable and token-efficient than screenshot-driven computer use.
+If the task is browser-only and the user is flexible, prefer direct browser tooling because it is usually more reliable and token-efficient than screenshot-driven desktop control.
## Core Loop
1. Call `start_session` first.
2. Decide from the latest screenshot, not from memory.
3. Interactive actions (`move`, `click`, `scroll`, `key`, `type`) already attach a fresh screenshot after they run.
-4. Use `capture` only when you need another screenshot without taking an action.
+4. Use `status` for state without starting a session.
+5. Use `capture` only when you need another screenshot without taking an action.
## Operating Rules
- Only the latest screenshot or a definitive tool result counts as evidence.
-- Prefer keyboard actions over pointer actions whenever a reliable keyboard path exists.
+- The current API uses normalized global screen coordinates; do not assume window ids, element indexes, background-safe input, or semantic click targets unless the runtime explicitly advertises them.
+- Prefer accessibility and semantic UI paths first: shortcuts, command palettes, menu accelerators, address/search bars, focus traversal, and other keyboard-accessible controls.
+- Prefer `key` and `type` over pointer actions whenever a reliable keyboard path exists.
- When a menu or popup is open, treat it as the active UI and prefer keyboard navigation over clicking small transient rows by coordinate.
- If a click dismisses a menu or popup without producing the expected next UI, treat that attempt as failed.
- If the same approach has already failed twice without visible progress, switch strategy instead of repeating it.
- Do not infer focus or task completion from chat logs, sidebars, tool summaries, or status text.
- For browser-navigation tasks done through this tool, only claim success if the browser content area visibly shows the destination page or result.
+- If the attached screenshot appears unchanged after a state-changing action, use one explicit `capture` to verify before repeating the same action.
- Use `type(..., submit=true)` only for URL or navigation-style entry where Enter should fire immediately after typing.
- Do not use `submit=true` for ordinary text fields. Type first, then send `enter` separately if needed.
+## Pointer And Scrolling
+
+- Try keyboard scrolling first: `page_down`, `page_up`, `space`, `shift+space`, arrows, `home`, or `end`.
+- Use `scroll` when the desired pane is already active or keyboard scrolling cannot target it.
+- Treat `move` and `click` as last-resort actions for controls that cannot be reached through keyboard, accessibility, browser, or app-native tooling.
+- Before clicking, make sure the latest screenshot makes the target unambiguous. Use one deliberate click, then reassess from the fresh screenshot.
+
## Control Signals
- Treat user interventions as high-priority control signals.
diff --git a/tests/test_a0_connector_prompt_gating.py b/tests/test_a0_connector_prompt_gating.py
new file mode 100644
index 000000000..ee544a983
--- /dev/null
+++ b/tests/test_a0_connector_prompt_gating.py
@@ -0,0 +1,217 @@
+import importlib.util
+import sys
+import uuid
+from pathlib import Path
+
+import yaml
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+ sys.path.insert(0, str(PROJECT_ROOT))
+
+
+def _restore_real_helpers_package() -> None:
+ helpers_module = sys.modules.get("helpers")
+ if helpers_module is None or getattr(helpers_module, "__file__", ""):
+ return
+
+ for name in list(sys.modules):
+ if name == "helpers" or name.startswith("helpers."):
+ del sys.modules[name]
+
+
+_restore_real_helpers_package()
+
+from plugins._a0_connector.helpers import ws_runtime
+
+
+PROMPT_ROOT = PROJECT_ROOT / "plugins" / "_a0_connector" / "prompts"
+GATE_PATH = (
+ PROJECT_ROOT
+ / "plugins"
+ / "_a0_connector"
+ / "extensions"
+ / "python"
+ / "_functions"
+ / "extensions"
+ / "python"
+ / "system_prompt"
+ / "_11_tools_prompt"
+ / "build_prompt"
+ / "end"
+ / "_70_include_remote_tool_stubs.py"
+)
+
+
+def _load_gate_class():
+ spec = importlib.util.spec_from_file_location(
+ "test_a0_connector_remote_tool_gate",
+ GATE_PATH,
+ )
+ module = importlib.util.module_from_spec(spec)
+ assert spec and spec.loader
+ sys.modules[spec.name] = module
+ spec.loader.exec_module(module)
+ return module.IncludeRemoteToolStubs
+
+
+IncludeRemoteToolStubs = _load_gate_class()
+
+
+class FakeContext:
+ def __init__(self, context_id: str):
+ self.id = context_id
+
+
+class FakeAgent:
+ def __init__(self, context_id: str):
+ self.context = FakeContext(context_id)
+
+ def read_prompt(self, file: str, **kwargs) -> str:
+ text = (PROMPT_ROOT / file).read_text(encoding="utf-8")
+ for key, value in kwargs.items():
+ text = text.replace("{{" + key + "}}", str(value))
+ return text
+
+
+def _context_id() -> str:
+ return f"ctx-{uuid.uuid4()}"
+
+
+def _sid() -> str:
+ return f"sid-{uuid.uuid4()}"
+
+
+def _parse_skill_frontmatter(path: Path) -> dict:
+ text = path.read_text(encoding="utf-8")
+ assert text.startswith("---")
+ return yaml.safe_load(text.split("---", 2)[1]) or {}
+
+
+def _apply_gate(context_id: str) -> str:
+ data = {"result": "## available tools\nbase_tool"}
+ IncludeRemoteToolStubs(agent=FakeAgent(context_id)).execute(data=data)
+ return data["result"]
+
+
+def _subscribe(
+ context_id: str,
+ *,
+ remote_files: dict | None = None,
+ remote_exec: dict | None = None,
+ computer_use: dict | None = None,
+) -> str:
+ sid = _sid()
+ ws_runtime.register_sid(sid)
+ ws_runtime.subscribe_sid_to_context(sid, context_id)
+ if remote_files is not None:
+ ws_runtime.store_sid_remote_file_metadata(sid, remote_files)
+ if remote_exec is not None:
+ ws_runtime.store_sid_remote_exec_metadata(sid, remote_exec)
+ if computer_use is not None:
+ ws_runtime.store_sid_computer_use_metadata(sid, computer_use)
+ return sid
+
+
+def test_remote_tool_stubs_absent_without_subscribed_cli():
+ prompt = _apply_gate(_context_id())
+
+ assert "text_editor_remote tool" not in prompt
+ assert "code_execution_remote tool" not in prompt
+ assert "computer_use_remote tool" not in prompt
+
+
+def test_file_only_cli_adds_text_editor_stub():
+ context_id = _context_id()
+ sid = _subscribe(
+ context_id,
+ remote_files={"enabled": True, "write_enabled": True},
+ )
+ try:
+ prompt = _apply_gate(context_id)
+ finally:
+ ws_runtime.unregister_sid(sid)
+
+ assert "text_editor_remote tool" in prompt
+ assert "Current access mode: `Read&Write`" in prompt
+ assert "code_execution_remote tool" not in prompt
+ assert "computer_use_remote tool" not in prompt
+
+
+def test_exec_enabled_cli_adds_execution_stub():
+ context_id = _context_id()
+ sid = _subscribe(
+ context_id,
+ remote_exec={"enabled": True},
+ )
+ try:
+ prompt = _apply_gate(context_id)
+ finally:
+ ws_runtime.unregister_sid(sid)
+
+ assert "code_execution_remote tool" in prompt
+ assert "text_editor_remote tool" not in prompt
+ assert "computer_use_remote tool" not in prompt
+
+
+def test_read_only_mode_marks_mutating_operations_disabled():
+ context_id = _context_id()
+ sid = _subscribe(
+ context_id,
+ remote_files={"enabled": True, "write_enabled": False, "mode": "read_only"},
+ remote_exec={"enabled": True},
+ )
+ try:
+ prompt = _apply_gate(context_id)
+ finally:
+ ws_runtime.unregister_sid(sid)
+
+ assert "text_editor_remote tool" in prompt
+ assert "code_execution_remote tool" in prompt
+ assert "Current access mode: `Read only`" in prompt
+ assert "Writes and patches are disabled" in prompt
+ assert "Mutating runtimes are disabled" in prompt
+
+
+def test_computer_use_enabled_cli_adds_computer_stub():
+ context_id = _context_id()
+ sid = _subscribe(
+ context_id,
+ computer_use={
+ "supported": True,
+ "enabled": True,
+ "trust_mode": "ask",
+ "backend_id": "local",
+ "backend_family": "desktop",
+ "features": ["screenshots", "keyboard"],
+ },
+ )
+ try:
+ prompt = _apply_gate(context_id)
+ finally:
+ ws_runtime.unregister_sid(sid)
+
+ assert "computer_use_remote tool" in prompt
+ assert "Backend: `local/desktop`" in prompt
+ assert "Features: `screenshots, keyboard`" in prompt
+ assert "text_editor_remote tool" not in prompt
+ assert "code_execution_remote tool" not in prompt
+
+
+def test_remote_workflow_skills_parse():
+ connector_skill = _parse_skill_frontmatter(
+ PROJECT_ROOT
+ / "plugins"
+ / "_a0_connector"
+ / "skills"
+ / "a0-cli-remote-workflows"
+ / "SKILL.md"
+ )
+ computer_skill = _parse_skill_frontmatter(
+ PROJECT_ROOT / "skills" / "computer-use-remote" / "SKILL.md"
+ )
+
+ assert connector_skill["name"] == "a0-cli-remote-workflows"
+ assert connector_skill["description"]
+ assert computer_skill["name"] == "computer-use-remote"
+ assert computer_skill["description"]
diff --git a/tests/test_default_prompt_budget.py b/tests/test_default_prompt_budget.py
index 02fe4d289..4d9ff1cb6 100644
--- a/tests/test_default_prompt_budget.py
+++ b/tests/test_default_prompt_budget.py
@@ -55,6 +55,9 @@ async def test_default_agent0_prompt_budget_and_guardrails():
assert '"tool_name": "code_execution_tool"' in system_text
assert '"tool_name": "memory_load"' in system_text
assert "informative but tight" in system_text
+ assert "# code_execution_remote tool" not in system_text
+ assert "# text_editor_remote tool" not in system_text
+ assert "# computer_use_remote tool" not in system_text
def test_a0_small_profile_removed_and_prompt_text_generic():