scriptoriumadmin/fabro
1
0
Fork 0
mirror of https://github.com/fabro-sh/fabro.git synced 2026-09-07 08:27:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
fabro/docs/public/agents/tools.mdx
fabro-sh-0530[bot] e8f0aceee8
refactor: rationalize server secret scopes (vault-only for optional int… (#401) 
## Summary

Separates Fabro server secrets into two explicit scopes: **bootstrap**
secrets that come from process env or `server.env`, and **optional
integration** secrets that come exclusively from the vault. This makes
secret resolution simple and predictable, and removes all `process env →
server.env` fallback paths for optional integrations such as GitHub App,
Slack, Daytona, Brave Search, and LLM provider keys.

## What changed

**New `ToolSecrets` struct in `fabro-agent`** — Brave Search API key is
now passed explicitly through `SessionOptions.tool_secrets` rather than
read from process env inside the tool. The standalone CLI reads the key
at the CLI boundary (with an explicit
`#[expect(clippy::disallowed_methods)]` annotation); the server will
read it from the vault. The error message changes from
`"BRAVE_SEARCH_API_KEY environment variable is not set"` to
`"BRAVE_SEARCH_API_KEY is not configured"`.

**`VaultCredentialSource::vault_only` constructor in `fabro-auth`** —
Adds a constructor that passes `|_| None` as the env lookup, ensuring
the server LLM credential source never resolves provider keys from
process env.

**GitHub App secrets move to vault in install flows** — Both the CLI
`fabro install github` path and the browser install finish handler now
write `GITHUB_APP_PRIVATE_KEY`, `GITHUB_APP_CLIENT_SECRET`, and
`GITHUB_APP_WEBHOOK_SECRET` to the vault instead of `server.env`.
Switching strategies removes stale secrets from the other strategy's
storage location. The `vault_set` field type changes from `Vec<(String,
String)>` to `Vec<VaultSecretWrite>` to carry per-secret type metadata
(file vs. token).

**`fabro-vault` gains a `fabro-static` dependency** — Needed so the
vault crate can reference canonical env-var names from the shared
registry without a cycle.

**`GH_TOKEN` fallback removed** — `GITHUB_TOKEN` is now read from the
vault only; the changelog and `server-configuration.mdx` note drops
mention of `GH_TOKEN` as an accepted fallback.

**Version bump** — Workspace crates promoted from `0.244.0-nightly.0` to
`0.244.0`.

**Docs** — Internal strategy doc, public admin docs (Docker, Railway,
server-configuration, security, troubleshooting), and integration docs
(GitHub, Slack, Daytona, Brave Search, LiteLLM, tools reference, models)
all updated to reflect vault-only optional secrets and direct users to
`fabro secret set` rather than process env or `server.env`.

### Plan Summary

- **Task 1** (secret registry) — not yet present in this diff;
classification lives in the places that consume it.
- **Task 3–6** (vault-only lookups for GitHub, Slack, Daytona, LLM) —
implemented via `vault_only` constructor, `tool_secrets` threading, and
install-path changes.
- **Task 7** (Brave Search explicit injection) — `ToolSecrets`,
`register_core_tools` wiring, CLI boundary read.
- **Task 8** (install persistence) — GitHub App secrets written to
vault; token strategy writes `GITHUB_TOKEN` to vault and clears app
vault keys; app strategy clears `GITHUB_TOKEN` vault key.
- **Task 9** (docs) — all public and internal docs updated.


### Fabro Details

<details>
<summary>Ran 0 stages in 155m 26s for $60.85</summary>

| Stage | Duration | Cost | Retries |
|---|---|---|---|
| **Total** | **155m 26s** | **$60.85** | **0** |

</details>

<details>
<summary>Ran <code>ImplementPlan.fabro</code> (11 nodes and 14
edges)</summary>

```dot
digraph ImplementPlan {
    graph [
        goal="Implement and simplify",
        model_stylesheet="
            * { model: claude-opus-4-7; }
        "
    ]
    rankdir=LR

    start [shape=Mdiamond, label="Start"]
    exit  [shape=Msquare, label="Exit"]

    toolchain         [label="Toolchain", shape=parallelogram, script="command -v cargo >/dev/null || { curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && sudo ln -sf $HOME/.cargo/bin/* /usr/local/bin/; }; cargo --version 2>&1", max_retries=0]
    preflight_compile [label="Preflight Compile", shape=parallelogram, script="cargo check -q --workspace 2>&1", max_retries=0]
    preflight_lint    [label="Preflight Lint", shape=parallelogram, script="cargo +nightly-2026-04-14 clippy -q --workspace --all-targets -- -D warnings 2>&1", max_retries=0]
    fix_lints         [label="Fix Lints", prompt="The preflight lint step failed. Read the build output from context and fix all clippy lint warnings.", max_visits=3]
    implement         [label="Implement", prompt="Read the plan file referenced in the goal and implement every step. Make all the code changes described in the plan. Use red/green TDD.", model="gpt-55", reasoning_effort="xhigh"]
    simplify_opus     [label="Simplify (Opus)", prompt="@prompts/simplify.md"]
    simplify_gpt      [label="Simplify (GPT-55)", prompt="@prompts/simplify.md", model="gpt-55"]
    verify            [label="Verify", shape=parallelogram, script="git fetch origin main 2>&1 && git merge --no-edit --no-stat origin/main 2>&1 && cargo +nightly-2026-04-14 fmt --all 2>&1 && cargo dev docs refresh 2>&1 && cargo +nightly-2026-04-14 fmt --check --all 2>&1 && { command -v rg >/dev/null 2>&1 || { echo 'rg is required for verify'; exit 127; }; } && ! rg -n 'AuthMode::Disabled|RunAuthMethod|RunSubjectProvenance|\bActorRef\b|\bActorKind\b|AuthenticatedSubject|AuthenticatedService|AuthorizeRunScoped|AuthorizeRunBlob|AuthorizeStageArtifact|AuthorizeCommandLog|auth_method\s*==\s*\"disabled\"' lib/crates apps lib/packages docs/public/api-reference/fabro-api.yaml 2>&1 && cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings 2>&1 && cargo nextest run --workspace --status-level slow --profile ci 2>&1 && cargo dev docs check 2>&1 && bun install --frozen-lockfile 2>&1 && (cd apps/fabro-web && bun run typecheck) 2>&1 && (cd apps/fabro-web && bun run test) 2>&1 && (cd lib/packages/fabro-api-client && bun run typecheck) 2>&1 && cargo dev build -- -p fabro-cli --release 2>&1", goal_gate=true, retry_target="fixup"]
    fixup             [label="Fixup", prompt="The verify step failed. Read the build output from context and fix all format, clippy, Rust test, docs, TypeScript typecheck/test, and build failures.", max_visits=3]

    start -> toolchain
    toolchain -> preflight_compile [condition="outcome=succeeded"]
    toolchain -> exit
    preflight_compile -> preflight_lint [condition="outcome=succeeded"]
    preflight_compile -> exit
    preflight_lint -> implement [condition="outcome=succeeded"]
    preflight_lint -> fix_lints
    fix_lints -> preflight_lint
    implement -> simplify_opus -> simplify_gpt -> verify
    verify -> exit  [condition="outcome=succeeded"]
    verify -> fixup
    fixup -> verify
}

```

</details>

⚒️ Generated with [Fabro](https://fabro.sh)

---------

Co-authored-by: Fabro <noreply@fabro.sh>
Co-authored-by: Bryan Helmkamp <bryan@brynary.com>
2026-05-25 17:26:01 -04:00

287 lines
13 KiB
Text
Raw Permalink Blame History

---
title: "Tools"
description: "Built-in tools for file I/O, shell commands, search, and web access"
---
Every agent in Fabro has access to a set of built-in tools for interacting with the codebase and environment. Tools execute inside the agent's [sandbox](/execution/environments) — whether that's the local machine, a Docker container, or a Daytona VM — so the same tool calls work identically regardless of provider.
<Note>
The tools described on this page apply to the **API backend** (the default). When using the [ACP backend](/core-concepts/agents#acp-backend), the external agent process provides its own tools — Fabro's built-in tools are not used.
</Note>
## Core tools
These tools are registered for every provider profile:
| Tool | Category | Description |
|---|---|---|
| `shell` | shell | Run shell commands via `/bin/bash -c` |
| `read_file` | read | Read file contents with optional offset and limit |
| `write_file` | write | Create or overwrite a file |
| `grep` | read | Search file contents with regex patterns |
| `glob` | read | Find files by name pattern |
| `web_search` | shell | Search the web via Brave Search |
| `web_fetch` | shell | Fetch and optionally summarize a URL |
## Provider-specific tools
Some tools are only available with certain LLM providers:
| Tool | Providers | Description |
|---|---|---|
| `edit_file` | Anthropic, Gemini | Replace a string in a file (find-and-replace) |
| `apply_patch` | OpenAI | Apply a v4a-format patch to modify files |
| `update_plan` | OpenAI | Maintain a multi-step plan for the current task |
| `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList` | Anthropic | Maintain a shared task list for the root agent session |
| `read_many_files` | Gemini | Read multiple files in a single call |
| `list_dir` | Gemini | List directory contents with depth control |
## Tool reference
### shell
Executes a shell command via `/bin/bash -c` in the sandbox's working directory.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `command` | string | yes | The shell command to execute |
| `timeout_ms` | integer | no | Timeout in milliseconds |
| `description` | string | no | Description of what the command does |
The timeout defaults to the provider's configured value (10s for most providers, 120s for Anthropic) and is capped at the maximum (600s / 10 minutes). If the command exceeds the timeout, Fabro kills the process and returns a "Command timed out" message along with any output captured so far.
The output includes the exit code, stdout, and stderr.
### read_file
Reads a file and returns its contents with line numbers.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `file_path` | string | yes | Absolute path to the file |
| `offset` | integer | no | 1-based line number to start reading from |
| `limit` | integer | no | Number of lines to read (default: 2000) |
Output is formatted with line numbers (e.g. ` 1 | fn main() {`), making it easy for agents to reference specific lines when editing.
### write_file
Creates or overwrites a file.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `file_path` | string | yes | Absolute path to the file |
| `content` | string | yes | Content to write |
<Note>
The [read-before-write guardrail](#read-before-write-guardrail) prevents writing to existing files that haven't been read first. Writing to new files is always allowed.
</Note>
### edit_file
Replaces a string in an existing file. Available for Anthropic and Gemini providers.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `file_path` | string | yes | Absolute path to the file |
| `old_string` | string | yes | The string to find |
| `new_string` | string | yes | The replacement string |
| `replace_all` | boolean | no | Replace all occurrences (default: false) |
If `old_string` is not found, the tool returns an error. If multiple occurrences exist and `replace_all` is false, the tool returns an error asking for more context or to set `replace_all`.
The tool reads the file internally before writing, so it satisfies the read-before-write guardrail automatically.
### grep
Searches file contents with a regex pattern, powered by ripgrep in the sandbox.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `pattern` | string | yes | Regex pattern to search for |
| `path` | string | no | Path to search in (default: `.`) |
| `glob_filter` | string | no | Glob pattern to filter which files are searched |
| `case_insensitive` | boolean | no | Case-insensitive search (default: false) |
| `max_results` | integer | no | Maximum number of results |
Results are returned as `file:line:content` lines. Files that appear in grep results are marked as "read" for the [read-before-write guardrail](#read-before-write-guardrail).
### glob
Finds files matching a glob pattern.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `pattern` | string | yes | Glob pattern to match files (e.g. `**/*.rs`) |
| `path` | string | no | Directory to search in (default: working directory) |
Returns matching file paths, one per line.
<Note>
Unlike `grep`, `glob` does **not** mark files as read for the read-before-write guardrail. To modify a file found via glob, the agent must read it first.
</Note>
### web_search
Searches the web using the Brave Search API.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Search query |
| `max_results` | integer | no | Maximum results (default: 5, max: 20) |
Requires `BRAVE_SEARCH_API_KEY` to be configured for the current runtime. Server-backed sessions read it from the server vault (`fabro secret set BRAVE_SEARCH_API_KEY <key>`); standalone local agent runs can pass it from the invoking shell. Returns numbered results with title, URL, and description.
### web_fetch
Fetches content from a URL and optionally summarizes it with an LLM.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `url` | string | yes | URL to fetch (must be `http://` or `https://`) |
| `prompt` | string | no | A question about the page content; returns a concise answer instead of the full page |
| `timeout_ms` | integer | no | Timeout in milliseconds (default: 30000, max: 60000) |
HTML content is automatically converted to Markdown (with script and style tags stripped). Output is capped at 100KB. When a `prompt` is provided and a summarizer model is configured, the fetched content is passed to a lightweight LLM call that returns a concise answer.
### apply_patch
Applies a v4a-format patch to create, update, or delete files. Available for OpenAI providers.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `patch` | string | yes | Patch content in v4a format |
The v4a format uses `*** Begin Patch` / `*** End Patch` delimiters with `*** Add File:`, `*** Delete File:`, and `*** Update File:` operations.
### read_many_files
Reads multiple files in a single tool call. Available for Gemini.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `paths` | string[] | yes | Array of absolute file paths |
Returns each file's contents prefixed with `=== path ===`.
### list_dir
Lists directory contents with optional depth control. Available for Gemini.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `path` | string | yes | Directory path to list |
| `depth` | integer | no | Depth of listing (default: 1) |
Directories are suffixed with `/` in the output.
### update_plan
Maintains the current task plan. Available for OpenAI providers.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `plan` | object[] | yes | Full ordered list of plan steps |
| `plan[].step` | string | yes | Step text; step text must be unique within the plan |
| `plan[].status` | string | yes | `pending`, `in_progress`, or `completed` |
| `explanation` | string | no | Short note explaining why the plan changed |
The submitted list replaces the current plan for that OpenAI session. Fabro reconciles steps by exact step text, emits `todo.created`, `todo.updated`, and `todo.deleted` events for changes, and projects the current list into run state.
### TaskCreate, TaskUpdate, TaskGet, and TaskList
Maintains a shared task list for Anthropic providers. The list is scoped to the root agent session, so sub-agents share the same task projection.
`TaskCreate` creates a task with `subject`, `description`, optional `activeForm`, and optional metadata. `TaskUpdate` changes an existing task by `taskId`; setting `status` to `deleted` removes it from the projection. `TaskGet` returns full details for one task, while `TaskList` returns the current shared task list.
Like `update_plan`, task changes are persisted as `todo.created`, `todo.updated`, and `todo.deleted` events and replay into run state.
When an Anthropic session has not used `TaskCreate` or `TaskUpdate` for ten assistant turns, Fabro may inject a system reminder asking the agent to keep task state current. The reminder is only added when both tools are available and resets after the agent uses either tool.
## Read-before-write guardrail
Fabro wraps every sandbox in a `ReadBeforeWriteSandbox` decorator that tracks which files the agent has seen. The rules are:
1. **Writing to a new file** (one that doesn't exist yet) is always allowed
2. **Writing to an existing file** requires that the agent has previously read it via `read_file` or seen it in `grep` results
3. **Deleting an existing file** follows the same rule as writing
If an agent attempts to write to an existing file it hasn't read, the tool returns an error:
```
Cannot write to 'src/main.rs': file exists but has not been read.
Use read_file to read the file before writing to it.
```
This prevents agents from blindly overwriting files they haven't inspected. The guardrail normalizes paths so that reading `src/main.rs` (relative) and `/workspace/src/main.rs` (absolute) both satisfy the check.
## Tool execution
### Parallel execution
When an LLM returns multiple tool calls in a single response, Fabro can execute them in parallel. Independent tool calls run concurrently, while the results are collected in order. If the agent session is cancelled, pending tool calls return a "Cancelled" error.
### Argument validation
Before executing a tool, Fabro validates the arguments against the tool's JSON Schema. Invalid arguments are rejected with a descriptive error before the tool executor runs.
### Output truncation
Tool output is truncated before being stored in conversation history to prevent context window bloat. Each tool has default limits:
| Tool | Character limit | Truncation mode |
|---|---|---|
| `grep` | 30,000 | Tail (keep end) |
| `glob` | 20,000 | Tail |
| `edit_file` | 10,000 | Tail |
| `apply_patch` | 10,000 | Tail |
| `write_file` | 1,000 | Tail |
| Other tools | No default limit | Head + tail |
Limits can be overridden per-tool via `SessionConfig.tool_output_limits`.
### Error handling
When a tool call fails, the error is returned to the agent as a tool result with an error flag — the agent loop continues. Tool errors do **not** fail the stage. The LLM sees the error message and decides how to respond: retry the call, try an alternative approach, or move on.
Common error cases:
| Error | Cause |
|---|---|
| Unknown tool | The agent called a tool that doesn't exist |
| Argument validation failure | Arguments don't match the tool's JSON Schema |
| File not found | The target file doesn't exist |
| Command timeout | A shell command exceeded its timeout |
| Read-before-write | The agent tried to write to a file it hasn't read (see [guardrail](#read-before-write-guardrail)) |
### Timeouts
Shell commands have two timeout settings:
| Setting | Default | Description |
|---|---|---|
| `default_command_timeout_ms` | 10,000 (120,000 for Anthropic) | Timeout when the agent doesn't specify one |
| `max_command_timeout_ms` | 600,000 (10 minutes) | Hard cap regardless of what the agent requests |
The agent can request a specific timeout via the `timeout_ms` parameter, but it's always capped at the maximum.
## Extending with MCP
Additional tools can be added via [MCP servers](/agents/mcp). MCP tools appear alongside built-in tools in the agent's tool set and follow the same permission and execution model.
## Further reading
<Columns cols={2}>
<Card title="Permissions" icon="lock" href="/agents/permissions">
How permissions control which tools are available.
</Card>
<Card title="Environments" icon="server" href="/execution/environments">
Sandbox providers where tools execute.
</Card>
<Card title="MCP" icon="plug" href="/agents/mcp">
Extend agents with Model Context Protocol servers.
</Card>
<Card title="Sub-agents" icon="users" href="/agents/subagents">
Sub-agents inherit tools from their parent session.
</Card>
</Columns>
Reference in a new issue View git blame Copy permalink