Tool memory_forget not found. Available tools: \n## available tools
use ONLY the tools listed below. match names exactly. do NOT invent tool names.
### a2a_chat
chat with a remote FastA2A-compatible agent; remote context is preserved automatically per `agent_url`
args: `agent_url`, `message`, optional `attachments[]`, optional `reset`
- `agent_url`: base url, accepts `host:port`, `http://host:port`, or a full `/a2a` url
- `message`: text to send to the remote agent
- `attachments[]`: optional absolute uris or paths to send with the message
- `reset`: json boolean; use `true` to start a fresh conversation with the same `agent_url`
do not send `context_id`; the tool handles that internally
example:
~~~json
{
  "thoughts": ["I need to ask a remote agent and keep the session for follow-up."],
  "headline": "Contacting remote FastA2A agent",
  "tool_name": "a2a_chat",
  "tool_args": {
    "agent_url": "http://weather.example.com:8000/a2a",
    "message": "What's the forecast for Berlin today?",
    "attachments": [],
    "reset": false
  }
}
~~~


### behaviour_adjustment
exact tool name uses british spelling: `behaviour_adjustment`
update persistent behavioral rules
arg: `adjustments` text describing what to add or remove


### browser_agent
subordinate browser worker for web tasks
args: `message`, `reset`
- give clear task-oriented instructions, credentials, and a stop condition
- `reset=true` starts a new browser session; `false` continues the current one
- when continuing, refer to open pages instead of restarting
downloads go to `/a0/tmp/downloads`


### call_subordinate
delegate research or complex subtasks to a specialized agent.
args: `message`, optional `profile`, `reset`
- `profile`: optional prompt profile name for the subordinate; leave empty for the default profile
- `reset`: use json boolean `true` for the first message or when changing profile; use `false` to continue
- `message`: define role, goal, and the concrete task
example:
~~~json
{
  "thoughts": ["Need focused external research before I continue."],
  "headline": "Delegating research subtask",
  "tool_name": "call_subordinate",
  "tool_args": {
    "profile": "researcher",
    "message": "Research Italy AI trends and return key findings.",
    "reset": true
  }
}
~~~
reuse long subordinate output with `§§include(path)` instead of rewriting it

available profiles:
{'agent0': {'title': 'Agent 0', 'description': 'Main agent of the system communicating directly with the user.', 'context': ''}, 'default': {'title': 'Default', 'description': 'Default prompt file templates. Should be inherited and overriden by specialized prompt profiles.', 'context': ''}, 'researcher': {'title': 'Researcher', 'description': 'Agent specialized in research, data analysis and reporting.', 'context': 'Use this agent for information gathering, data analysis, topic research, and generating comprehensive reports.'}, 'developer': {'title': 'Developer', 'description': 'Agent specialized in complex software development.', 'context': 'Use this agent for software development tasks, including writing code, debugging, refactoring, and architectural design.'}, 'hacker': {'title': 'Hacker', 'description': 'Agent specialized in cyber security and penetration testing.', 'context': 'Use this agent for cybersecurity tasks such as penetration testing, vulnerability analysis, and security auditing.'}}



### code_execution_tool
run terminal, python, or nodejs commands
args:
- `runtime`: `terminal`, `python`, `nodejs`, or `output`
- `code`: command or script code
- `session`: terminal session id; default `0`
- `reset`: kill a session before running; `true` or `false`
rules:
- place the command or script in `code`
- use `runtime=output` to poll running work
- use `input` for interactive terminal prompts
- if a session is stuck, call again with the same `session` and `reset=true`
- check dependencies before running code
- replace placeholder or demo data with real values before execution
- use `print()` or `console.log()` when you need explicit output
- do not interleave other tools while waiting
- ignore framework `[SYSTEM: ...]` info in output
examples:
1 terminal command
~~~json
{
    "thoughts": [
        "Need to do...",
        "Need to install...",
    ],
    "headline": "Installing zip package via terminal",
    "tool_name": "code_execution_tool",
    "tool_args": {
        "runtime": "terminal",
        "session": 0,
        "reset": false,
        "code": "apt-get install zip",
    }
}
~~~

2 execute python code

~~~json
{
    "thoughts": [
        "Need to do...",
        "I can use...",
        "Then I can...",
    ],
    "headline": "Executing Python code to check current directory",
    "tool_name": "code_execution_tool",
    "tool_args": {
        "runtime": "python",
        "session": 0,
        "reset": false,
        "code": "import os\nprint(os.getcwd())",
    }
}
~~~

3 execute nodejs code

~~~json
{
    "thoughts": [
        "Need to do...",
        "I can use...",
        "Then I can...",
    ],
    "headline": "Executing Javascript code to check current directory",
    "tool_name": "code_execution_tool",
    "tool_args": {
        "runtime": "nodejs",
        "session": 0,
        "reset": false,
        "code": "console.log(process.cwd());",
    }
}
~~~

4 wait for output with long-running scripts
~~~json
{
    "thoughts": [
        "Waiting for program to finish...",
    ],
    "headline": "Waiting for long-running program to complete",
    "tool_name": "code_execution_tool",
    "tool_args": {
        "runtime": "output",
        "session": 0,
    }
}
~~~

2 python snippet
~~~json
{
  "thoughts": ["A short Python check is faster than using the shell."],
  "headline": "Running Python snippet",
  "tool_name": "code_execution_tool",
  "tool_args": {
    "runtime": "python",
    "session": 0,
    "reset": false,
    "code": "import os\nprint(os.getcwd())"
  }
}
~~~

3 wait for running output
~~~json
{
  "thoughts": ["The previous command is still running, so I should poll for output."],
  "headline": "Waiting for command output",
  "tool_name": "code_execution_tool",
  "tool_args": {
    "runtime": "output",
    "session": 0
  }
}
~~~


# code_execution_remote tool

This tool runs shell-backed execution on the **remote machine where the CLI is running**.
It converges onto Agent Zero Core's persistent local-shell model, so the frontend session
can execute terminal commands and shell-launched `python` / `nodejs` snippets while keeping
session ids stable across calls.

## 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.

## 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`

## Usage

### Execute a terminal command
```json
{
  "tool_name": "code_execution_remote",
  "tool_args": {
    "runtime": "terminal",
    "session": 0,
    "code": "pwd && ls -la"
  }
}
```

### Execute Python through the shell-backed runtime
```json
{
  "tool_name": "code_execution_remote",
  "tool_args": {
    "runtime": "python",
    "session": 0,
    "code": "import os\nprint(os.getcwd())"
  }
}
```

### Execute Node.js through the shell-backed runtime
```json
{
  "tool_name": "code_execution_remote",
  "tool_args": {
    "runtime": "nodejs",
    "session": 0,
    "code": "console.log(process.cwd())"
  }
}
```

### Poll output from a running session
```json
{
  "tool_name": "code_execution_remote",
  "tool_args": {
    "runtime": "output",
    "session": 0
  }
}
```

### Send keyboard input to a running session
```json
{
  "tool_name": "code_execution_remote",
  "tool_args": {
    "runtime": "input",
    "session": 0,
    "keyboard": "yes"
  }
}
```

### Reset a session
```json
{
  "tool_name": "code_execution_remote",
  "tool_args": {
    "runtime": "reset",
    "session": 0,
    "reason": "stuck process"
  }
}
```

## 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.
- The transport uses `connector_exec_op` and `connector_exec_op_result` with shared `op_id`.


### document_query
read local or remote documents or answer questions about them
args:
- `document`: url path or list of them
- `queries`: optional list of questions
- `query`: optional single-question alias
- without `query` or `queries` it returns document content
- `document` accepts one path/url or a list for cross-document comparison
- for local files use full paths; for web documents use full urls
examples:
1 read a document
~~~json
{
  "thoughts": ["I need the full contents of the report before answering."],
  "headline": "Loading report contents",
  "tool_name": "document_query",
  "tool_args": {
    "document": "https://example.com/report.pdf"
  }
}
~~~

2 compare documents with questions
~~~json
{
  "thoughts": ["I need targeted answers across two documents."],
  "headline": "Comparing two documents",
  "tool_name": "document_query",
  "tool_args": {
    "document": [
      "https://example.com/report-one.pdf",
      "/path/to/report-two.pdf"
    ],
    "queries": [
      "Compare the main conclusions.",
      "What changed between the two versions?"
    ]
  }
}
~~~


### input:
use keyboard arg for terminal program input
use session arg for terminal session number
answer dialogues enter passwords etc
not for browser
usage:
~~~json
{
    "thoughts": [
        "The program asks for Y/N...",
    ],
    "headline": "Responding to terminal program prompt",
    "tool_name": "input",
    "tool_args": {
        "keyboard": "Y",
        "session": 0
    }
}
~~~


## memory tools
use when durable recall or storage is useful
- `memory_load`: args `query`, optional `threshold`, `limit`, `filter`
- `memory_save`: args `text`, optional `area` and metadata kwargs
- `memory_delete`: arg `ids` comma-separated ids
- `memory_forget`: args `query`, optional `threshold`, `filter`

notes:
- `threshold` is similarity from `0` to `1`
- `filter` is a metadata expression (e.g. `area=='main'`)
- confirm destructive changes when accuracy matters

example:
~~~json
{
  "thoughts": ["I should search memory for relevant prior guidance."],
  "headline": "Loading related memories",
  "tool_name": "memory_load",
  "tool_args": {
    "query": "tool argument format",
    "threshold": 0.7,
    "limit": 3
  }
}
~~~


### notify_user
send an out-of-band notification without ending the current task
args: `message`, optional `title`, `detail`, `type`, `priority`, `timeout`
types: `info`, `success`, `warning`, `error`, `progress`
use for progress or alerts, not as the final answer


### response:
final answer to user
ends task processing use only when done or no task active
put result in text arg
always use markdown formatting headers bold text lists
full message is automatically markdown do not wrap ~~~markdown
default to balanced, concise answers: informative but tight, not terse and not verbose.
prefer using tables
focus nice structured output key selling point
output full file paths not only names to be clickable
images shown with ![alt](img:///path/to/image.png) show images when possible when relevant also output full path
all math and variables wrap with latex notation delimiters <latex>x = ...</latex>, use only single line latex do formatting in markdown instead
speech: text and lists are spoken, tables and code blocks not, therefore use tables for files and technicals, use text and lists for plain english, do not include technical details in lists


usage:
~~~json
{
    "thoughts": [
        "...",
    ],
    "headline": "Explaining why...",
    "tool_name": "response",
    "tool_args": {
        "text": "Answer to the user",
    }
}
~~~

for long existing text, use `§§include(path)` instead of rewriting


### scheduler
manage saved tasks and schedules
rules:
- before `scheduler:create_*` or `scheduler:run_task`, inspect existing tasks with `scheduler:find_task_by_name` or `scheduler:list_tasks`
- do not manually run a task just because it is scheduled or planned unless user asks to run now
- do not create recursive task prompts that schedule more tasks
methods:
- `scheduler:list_tasks`: optional `state[]`, `type[]`, `next_run_within`, `next_run_after`
- `scheduler:find_task_by_name`: `name`
- `scheduler:show_task`: `uuid`
- `scheduler:run_task`: `uuid`, optional `context`
- `scheduler:delete_task`: `uuid`
- `scheduler:create_scheduled_task`: `name`, `system_prompt`, `prompt`, optional `attachments[]`, `schedule{minute,hour,day,month,weekday}`, optional `dedicated_context`
- `scheduler:create_adhoc_task`: `name`, `system_prompt`, `prompt`, optional `attachments[]`, optional `dedicated_context`
- `scheduler:create_planned_task`: `name`, `system_prompt`, `prompt`, optional `attachments[]`, `plan[]` iso datetimes like `2025-04-29T18:25:00`, optional `dedicated_context`
- `scheduler:wait_for_task`: `uuid`; works for dedicated-context tasks
example:
~~~json
{
  "thoughts": ["I should check for an existing task before I create or run anything."],
  "headline": "Looking up scheduled task",
  "tool_name": "scheduler:find_task_by_name",
  "tool_args": {
    "name": "daily backup"
  }
}
~~~


### search_engine
find live news, prices, and other real-time web data
arg: `query` (text search query)
returns urls, titles, and descriptions
example:
~~~json
{
  "thoughts": ["I need current information rather than relying on memory."],
  "headline": "Searching the web",
  "tool_name": "search_engine",
  "tool_args": {
    "query": "latest LiteLLM release notes"
  }
}
~~~


### skills_tool
use skills only when relevant
workflow:
- `skills_tool:search`: find candidate skills by keywords or trigger phrases from the current task
- `skills_tool:list`: discover available skills
- `skills_tool:load`: load one skill by `skill_name`
after loading a skill, follow its instructions and use referenced files or scripts with other tools
reload a skill if its instructions are no longer in context
example:
~~~json
{
  "thoughts": ["The user's request sounds like a skill trigger phrase, so I should search first."],
  "headline": "Searching for relevant skill",
  "tool_name": "skills_tool:search",
  "tool_args": {
    "query": "set up a0 cli connector"
  }
}
~~~


### text_editor
file read write patch with numbered lines
not code execution rejects binary
terminal (grep find sed) advance search/replace

#### text_editor:read
read file with numbered lines
args path line_from line_to (inclusive optional)
no range → first 200 lines
long lines cropped output may trim by token limit
read surrounding context before patching
usage:
~~~json
{
    ...
    "tool_name": "text_editor:read",
    "tool_args": {
        "path": "/path/file.py",
        "line_from": 1,
        "line_to": 50
    }
}
~~~

#### text_editor:write
create/overwrite file auto-creates dirs
args path content
usage:
~~~json
{
    ...
    "tool_name": "text_editor:write",
    "tool_args": {
        "path": "/path/file.py",
        "content": "import os\nprint('hello')\n"
    }
}
~~~

#### text_editor:patch
line edits on existing file
args path edits [{from to content}]
from to inclusive \n in content
{from:2 to:2 content:"x\n"} replace line
{from:1 to:3 content:"x\n"} replace range
{from:2 to:2} delete (no content)
{from:2 content:"x\n"} insert before (omit to)
use original line numbers from read 
dont adjust for shifts no overlapping edits
ensure valid syntax in content (all braces brackets tags closed)
only replace exact lines needed dont include surrounding unchanged lines
re-read when insert delete or N≠M replace else patch again ok
large changes write over multiple patches
usage:
~~~json
{
    ...
    "tool_name": "text_editor:patch",
    "tool_args": {
        "path": "/path/file.py",
        "edits": [
            {"from": 1, "content": "import sys\n"},
            {"from": 5, "to": 5, "content": "    if x == 2:\n"}
        ]
    }
}
~~~


# 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.

Use `text_editor_remote` when the user asks you to edit files on their local machine while connected via the CLI.

## 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 a file
```json
{
  "tool_name": "text_editor_remote",
  "tool_args": {
    "op": "read",
    "path": "/path/on/remote/machine/file.py",
    "line_from": 1,
    "line_to": 50
  }
}
```
Returns file content with line numbers. `line_from` and `line_to` are optional.

### Write a file
```json
{
  "tool_name": "text_editor_remote",
  "tool_args": {
    "op": "write",
    "path": "/path/on/remote/machine/file.py",
    "content": "import os\nprint('hello')\n"
  }
}
```
Creates or overwrites the file on the remote machine.

### Patch a file
```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"}
    ]
  }
}
```
Applies line-range patches to the file. Use the same format as the standard `text_editor:patch` tool.

## Notes
- Always read the file first before patching to get current line numbers.
- Paths are evaluated on the **remote machine's filesystem**, not the Agent Zero server.
- If no CLI is connected, the tool will return an error message.
- The transport uses `connector_file_op` and `connector_file_op_result` with a shared `op_id`.


### wait
pause until a duration or timestamp
args: any of `seconds`, `minutes`, `hours`, `days`, or `until` iso timestamp
use only when waiting is actually part of the task



## multimodal vision tools

### vision_load
load images into the model for visual reasoning
args: `paths` list of absolute image paths
rules:
- load all relevant images in one call when comparing screenshots or pages
- use when the task depends on screenshots, diagrams, scanned documents, charts, or photos
- only bitmaps are supported; convert other formats first if needed
- the tool result includes loaded/skipped image totals and the corresponding path lists
example:
```json
{
  "thoughts": [
    "I need to inspect the screenshot before answering."
  ],
  "headline": "Loading screenshot for visual analysis",
  "tool_name": "vision_load",
  "tool_args": {
    "paths": ["/path/to/screenshot.png"]
  }
}
```