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.pynew file mode 100644index 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.pydeleted file mode 100644index 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"] = promptdiff --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.pydeleted file mode 100644index 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"] = promptdiff --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.pydeleted file mode 100644index 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"] = promptdiff --git a/plugins/_a0_connector/prompts/agent.connector_tool.code_execution_remote.md b/plugins/_a0_connector/prompts/agent.connector_tool.code_execution_remote.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mdnew file mode 100644index 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.mdindex 4b545ebf0..c31b76dc7 100644--- a/skills/computer-use-remote/SKILL.md+++ b/skills/computer-use-remote/SKILL.md@@ -1,7 +1,7 @@---name: computer-use-remotedescription: 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.0author: Agent Zero Teamtags: ["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 Loop1. 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.pynew file mode 100644index 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.pyindex 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_textassert '"tool_name": "memory_load"' in system_textassert "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_textdef test_a0_small_profile_removed_and_prompt_text_generic():