Plugins¶

Plugins are the tools agents can call. Each plugin is a named collection of kernel functions. Add plugin names to an agent's Plugins list to make them available.

Plugins:
  - FileSystem
  - Shell
  - Git
  - Search

Plugin names are case-insensitive.

FileSystem¶

Read, write, and navigate the local filesystem.

Function	Parameters	Description
`read_file`	`path`	Read a text file. Returns up to 80,000 characters. Rejects binary files.
`write_file`	`path`, `content`	Create or overwrite a file. Creates parent directories automatically.
`list_files`	`directory`, `pattern` (default `"*"`)	List files matching a glob pattern. Returns up to 500 results.
`delete_file`	`path`	Delete a file if it exists.

Tip: When FileSystemSandboxPath is configured, all paths are resolved to canonical form and rejected if they fall outside the sandbox root. See Security.

Shell¶

Execute shell commands and scripts.

Function	Parameters	Description
`shell_run`	`command`, `workingDirectory` (optional), `timeoutSeconds` (default 60)	Run a shell command. Supports pipes, redirects, and chained commands. Captures stdout, stderr, and exit code.
`shell_run_script`	`script`, `workingDirectory` (optional), `timeoutSeconds` (default 120)	Write a multi-line script to a temp file and execute it. Useful for complex multi-command workflows.
`shell_get_env`	`name`	Return an environment variable value (empty string if not set).
`shell_which`	`program`	Return the full path of a program (equivalent to `which` / `where`).
`shell_get_working_directory`	—	Return the effective working directory. Returns the sandbox root if a sandbox is configured.

The shell used is /bin/bash on Unix and cmd on Windows. The shell binary is located from common system paths at startup.

sudo protection: sudo is always blocked. Any command or script containing sudo (including after pipes, &&, ;, or newlines) is rejected before execution. The denial message instructs the agent to use non-privileged alternatives (pip install --user, pipx, virtualenvs) or, if elevated access is truly required, to tell the user what to run so they can do it themselves.

Shell command approval in --hitl mode: When fuseraft run --hitl is active, every shell_run and shell_run_script call pauses and shows the command for approval before executing. See CLI Reference — Shell command approval.

Security note: When FileSystemSandboxPath is set, the workingDirectory argument is hard-denied if it falls outside the sandbox. The command and script arguments are scanned for absolute paths escaping the sandbox; system binary prefixes (/usr/, /bin/, /opt/, /nix/, etc.) are exempted. Shell scanning is heuristic — for strict containment use CodeExecution (Docker) instead.

Git¶

Read and write a Git repository.

Read operations

Function	Parameters	Description
`git_status`	`repoPath` (default `"."`)	Show working-tree status: staged, unstaged, and untracked files.
`git_diff`	`repoPath`, `staged` (default false), `maxLines` (default 200)	Show a unified diff. Pass `staged: true` for the index diff.
`git_log`	`repoPath`, `count` (default 10), `ref` (optional)	Show recent commit history with hashes, authors, and messages.
`git_show`	`commitRef`, `repoPath`, `maxLines` (default 300)	Show the content and diff of a specific commit.
`git_branch_list`	`repoPath`, `includeRemotes` (default false)	List branches.

Write operations

Function	Parameters	Description
`git_add`	`paths`, `repoPath`	Stage files. Pass `"."` to stage everything.
`git_commit`	`message`, `repoPath`, `stageAll` (default false)	Commit staged changes.
`git_checkout`	`target`, `repoPath`, `createBranch` (default false)	Switch to a branch or restore files.
`git_create_branch`	`branchName`, `repoPath`	Create a new branch from HEAD.
`git_init`	`directory` (optional)	Initialize a new repository.

Http¶

Make HTTP requests to external APIs.

Function	Parameters	Description
`http_get`	`url`, `headers` (JSON, optional), `timeoutSeconds` (default 30), `profile` (optional)	GET request. Returns response body as text.
`http_post`	`url`, `body`, `contentType` (default `"application/json"`), `headers`, `timeoutSeconds`, `profile`	POST request with body.
`http_put`	`url`, `body`, `contentType` (default `"application/json"`), `headers`, `timeoutSeconds`, `profile`	PUT request.
`http_patch`	`url`, `body`, `contentType` (default `"application/json"`), `headers`, `timeoutSeconds`, `profile`	PATCH request. Useful for partial updates (e.g. closing a ticket).
`http_delete`	`url`, `headers`, `timeoutSeconds` (default 30), `profile`	DELETE request.
`http_head`	`url`, `headers`, `timeoutSeconds` (default 30), `profile`	HEAD request. Returns response headers only, no body.

API profiles (`profile` parameter)¶

All HTTP functions accept an optional profile parameter. When provided, the plugin looks up that name in the ApiProfiles config section and applies:

Base URL — if url is a relative path (no http:///https:// scheme), it is prepended with the profile's BaseUrl. Absolute URLs are used as-is.
Default headers — merged with any per-call headers. Per-call headers win on conflicts.
Timeout — the profile's TimeoutSeconds is used when the caller does not supply an explicit timeout (i.e. when timeoutSeconds equals the default of 30).

# config/orchestration.yaml snippet
ApiProfiles:
  snow:
    BaseUrl: "https://mycompany.service-now.com/api/now"
    TimeoutSeconds: 60
    DefaultHeaders:
      Authorization: "Bearer ${SNOW_API_TOKEN}"
      Accept: "application/json"

# Agent can now call:
http_get(url="/table/incident", profile="snow")
# → GET https://mycompany.service-now.com/api/now/table/incident
#   Authorization: Bearer <value of $SNOW_API_TOKEN>

Header values in DefaultHeaders support ${ENV_VAR} token expansion — the token is replaced with the environment variable's value at startup. See Configuration → ApiProfiles for the full reference.

Security note: When HttpAllowedHosts is non-empty, only listed hostnames are permitted. The allowlist is enforced after profile resolution — a profile that resolves to an unlisted host is still denied. Private and loopback addresses (127.x, 10.x, 172.16–31.x, 192.168.x, 169.254.x, IPv6 loopback/link-local) are always blocked regardless of the allowlist.

Json¶

Parse, transform, and query JSON data.

Function	Parameters	Description
`json_format`	`json`	Pretty-print a JSON string with indentation.
`json_minify`	`json`	Strip whitespace to produce compact output.
`json_get`	`json`, `path`	Get a nested value using dot-separated path notation, e.g. `"data.results.0.title"`.
`json_keys`	`json`	Return top-level keys of an object, or the length of an array.
`json_search`	`json`, `keyName`	Find all keys matching a search term (case-insensitive, deep search).
`json_merge`	`baseJson`, `patchJson`	Shallow-merge two JSON objects. Patch fields overwrite base fields.
`json_to_text`	`json`, `depth` (default 0)	Convert JSON to a human-readable summary suitable for feeding into a model prompt.
`json_validate`	`json`	Check whether a string is well-formed JSON.

Search¶

Search the filesystem by name or content.

Function	Parameters	Description
`search_files`	`pattern`, `directory` (default `"."`), `maxResults` (default 100)	Find files by wildcard/glob pattern.
`search_content`	`query`, `directory` (default `"."`), `filePattern` (default `"*"`), `maxResults` (default 100), `caseSensitive` (default false)	Search file contents by regex or plain text (like grep).
`search_symbol`	`symbol`, `directory` (default `"."`), `extension` (default `""`), `maxResults` (default 50)	Find symbol definitions (class, function, interface, variable, etc.) using language-agnostic patterns.

Probe¶

Structured hypothesis testing and assertion utilities. Useful for Tester agents that need to verify behavior with evidence.

Function	Parameters	Description
`probe_code`	`language`, `code`, `directory` (default `"."`), `timeoutSeconds` (default 30)	Execute a code snippet and return stdout/stderr/exit code. Supported languages: `bash`, `python`, `javascript`, `go`, `csharp`, `powershell`, `kiwi`.
`probe_assert_output`	`command`, `expected`, `matchType` (default `"contains"`), `directory`, `timeoutSeconds`	Run a command and assert its output. `matchType`: `contains`, `equals`, `regex`, `exitcode`. Returns PASS or FAIL with evidence.
`probe_compare_outputs`	`commandA`, `commandB`, `directory`, `timeoutSeconds`	Run two commands and return their outputs side-by-side for comparison.
`probe_run_hypothesis`	`hypothesis`, `command`, `expectedObservation`, `setupCommand` (optional), `directory`, `timeoutSeconds`	Given/When/Then structured test.

Plan¶

File-backed work plan stored as .fuseraft-plan.json in the working directory. Useful for agents that need to track progress across multiple steps.

Function	Parameters	Description
`plan_create`	`title`, `steps` (comma-separated), `planPath` (default `.fuseraft-plan.json`)	Create a new plan.
`plan_get`	`planPath`	Return current plan with all steps and their statuses.
`plan_update_step`	`stepIndex`, `status`, `note` (optional), `planPath`	Update a step. Status values: `pending`, `in_progress`, `done`, `blocked`, `skipped`.
`plan_add_step`	`title`, `description` (optional), `planPath`	Append a new step to the plan.
`plan_summary`	`planPath`	Return a compact summary: title, counts by status, next pending step.

CodeExecution¶

Sandboxed code execution via Docker containers. Each run gets a fresh, isolated container with no network access and capped resources.

Requirements: Docker CLI and daemon must be running. Check with the check_docker function.

Function	Parameters	Description
`code_execution_check_docker`	—	Verify Docker is available and the daemon is reachable.
`code_execution_sandbox_run`	`language`, `code`, `timeoutSeconds` (default 30)	Run code in a fresh Docker container. Supported languages: `python`, `node`, `bash`, `go`, `rust`.
`code_execution_repl_start`	`language`	Start a REPL session (Python or Node). Returns a session ID.
`code_execution_repl_exec`	`sessionId`, `code`, `timeoutSeconds`	Execute code in an active REPL session. Variables and functions persist between calls.
`code_execution_repl_reset`	`sessionId`	Clear accumulated code in a REPL session (session stays open).
`code_execution_repl_stop`	`sessionId`	Remove the REPL session and all accumulated state.

Container resource limits: --network none, --memory 256m, --cpus 0.5

Docker images used:

Language	Image
Python	`python:3.12-slim`
Node	`node:20-slim`
Bash	`bash:5.2`
Go	`golang:1.23-alpine`
Rust	`rust:1-slim`

Scratchpad¶

Persistent per-agent key-value store that survives across sessions. Each agent that includes "Scratchpad" in its Plugins list gets an isolated JSON file at ~/.fuseraft/scratchpad/{AgentName}.json. A global scope (~/.fuseraft/scratchpad/global.json) is shared by all agents in the orchestration.

Files are stored outside the project directory so notes persist regardless of which project or config file is used.

Typical usage pattern:

At the start of a resumed session:  scratchpad_read_all()
When you make a key decision:       scratchpad_write("auth_decision", "Use JWT tokens", tags="auth")
When you want to find past notes:   scratchpad_search("auth")
Before ending the session:          scratchpad_write("session_summary", "Completed task X, left Y for next time")

Function	Parameters	Description
`scratchpad_write`	`key`, `value`, `tags` (optional), `scope` (default `"agent"`)	Store or update an entry. Tags are comma-separated keywords.
`scratchpad_read`	`key`, `scope` (default `"agent"`)	Retrieve a single entry by key.
`scratchpad_read_all`	`scope` (default `"agent"`)	Read all entries — call this at session start to restore context.
`scratchpad_search`	`query`, `scope` (default `"agent"`)	Case-insensitive substring search across keys, values, and tags.
`scratchpad_delete`	`key`, `scope` (default `"agent"`)	Remove an entry.

Scope values:

Scope	File	Visibility
`agent` (default)	`~/.fuseraft/scratchpad/{AgentName}.json`	Private to this agent
`global`	`~/.fuseraft/scratchpad/global.json`	Shared by all agents

Config (optional): Override the storage directory in the orchestration config:

Scratchpad:
  BasePath: /custom/path/to/scratchpad

If Scratchpad is omitted, the default path ~/.fuseraft/scratchpad is used.

Note: Unlike other plugins, "Scratchpad" is not shared between agents — each agent gets its own instance backed by its own file. This is handled automatically; no extra configuration is needed.

Chatroom¶

Shared append-only message log for agent-to-agent coordination. All agents that include "Chatroom" in their Plugins list share the same JSONL file, but each agent sends under its own name.

Function	Parameters	Description
`chatroom_send`	`recipient`, `message`	Append a message to the log. `recipient` can be a specific agent name or `"All"` to broadcast.
`chatroom_read`	`count` (default `20`)	Read the most recent `count` messages from the log.

Typical usage:

After completing a task:    chatroom_send("Tester", "Files are written and build passes.")
At the start of your turn:  chatroom_read()
Broadcasting a blocker:     chatroom_send("All", "Blocked on missing dependency — need shell access.")

Config (optional): Override the log path in the orchestration config:

Chatroom:
  Path: .fuseraft/chatroom.jsonl

If Chatroom is omitted, the default path .fuseraft/chatroom.jsonl is used.

Note: Like "Scratchpad", "Chatroom" is instantiated per-agent (so each instance knows the sender's name), but all instances write to the same file so messages are visible across the team.

Changes¶

Read-only view of the session change log written automatically by the orchestrator's ChangeTracker. Records which files were written, which commands ran, and which git commits were made — turn by turn — so downstream agents (Tester, Reviewer) know exactly what happened without having to infer it from the chat history.

Availability: Only registered when ChangeTracking is present in the orchestration config. See Configuration.

Function	Parameters	Description
`changes_read`	—	Return the full session change log: every agent turn that wrote files, ran commands, or made git commits.
`changes_read_latest`	`count` (default `1`)	Return the `count` most-recent change entries. Use this before deciding what to test or review.