Skip to content

Custom tools are now framework-agnostic #123

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Sewer56 merged 5 commits into from
May 30, 2026
Merged

Custom tools are now framework-agnostic #123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ed896cf
Changed: Add framework-agnostic custom tool registry and API
Sewer56 May 30, 2026
9765f78
Removed: Unused Markdown reference definition for ToolBuildContext
Sewer56 May 30, 2026
79cce7d
Removed: Unused link reference definitions from tools.md
Sewer56 May 30, 2026
1f5a5cd
Removed: Unused Markdown link definitions in README
Sewer56 May 30, 2026
2dbdcba
Changed: Update AgentBuildError # Errors docs for custom-tool materia…
Sewer56 May 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 14 additions & 13 deletions README.MD
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,13 @@ A **CI pipeline**? A **custom product**?
**ReloadedCode** ships the same agent tools as a Rust library.
Shell sandboxing. Default-deny permissions. ~10 MiB footprint.

| | OpenCode | ReloadedCode |
| ------------ | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Language | TypeScript | Rust |
| | OpenCode | ReloadedCode |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Language | TypeScript | Rust |
| Memory | <abbr title="opencode v1.14.21&#10;serve: 305 MiB RSS&#10;TUI: 525 MiB RSS&#10;&#10;v1.4.2&#10;serve: 392 MiB RSS&#10;TUI: 679 MiB RSS">~305 MiB</abbr> | <abbr title="~13 MiB RSS on release build, all providers enabled.&#10; • Code &amp; read-only data: ~6.5 MiB&#10; • Heap (runtime state): ~2.5 MiB&#10; • Shared libraries (glibc, libm): ~2.3 MiB&#10; • Thread stacks: ~0.1 MiB (34 threads)&#10; Private ~2.5 MiB · PSS ~10 MiB.">~13 MiB</abbr> |
| Interface | TUI / Desktop / IDE | Library (headless) |
| Agent format | Markdown + YAML | Similar format |
| Embeddable | HTTP API | Rust crate |
| Interface | TUI / Desktop / IDE | Library (headless) |
| Agent format | Markdown + YAML | Similar format |
| Embeddable | HTTP API | Rust crate |

## Features

Expand Down Expand Up @@ -114,13 +114,14 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {

## Crate Map

| Crate | Version | Description |
| --------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |
| [**reloaded-code-core**](./src/reloaded-code-core/) | 0.2 | Framework-agnostic tool implementations, path resolvers, permissions, system prompt builder |
| [**reloaded-code-agents**](./src/reloaded-code-agents/) | 0.1 | agent markdown loader similar to [OpenCode](https://opencode.ai), typed catalog, runtime builder |
| [**reloaded-code-serdesai**](./src/reloaded-code-serdesai/) | 0.2 | SerdesAI framework integration, tool adapters, 15 provider bridges, task delegation |
| [**reloaded-code-bubblewrap**](./src/reloaded-code-bubblewrap/) | 0.1 | Linux bubblewrap sandbox profiles (Public Bot + Trusted Maintenance) |
| [**reloaded-code-models-dev**](./src/reloaded-code-models-dev/) | 0.1 | models.dev catalog sync with ETag caching and offline fallback |
| Crate | Version | Description |
| ------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |
| [**reloaded-code-core**](./src/reloaded-code-core/) | 0.2 | Framework-agnostic tool implementations, path resolvers, permissions, custom tool registry |
| [**reloaded-code-agents**](./src/reloaded-code-agents/) | 0.1 | agent markdown loader similar to [OpenCode](https://opencode.ai), typed catalog, runtime builder |
| [**reloaded-code-serdesai**](./src/reloaded-code-serdesai/) | 0.2 | SerdesAI framework integration, tool adapters, 15 provider bridges, task delegation |
| [**reloaded-code-bubblewrap**](./src/reloaded-code-bubblewrap/) | 0.1 | Linux bubblewrap sandbox profiles (Public Bot + Trusted Maintenance) |
| [**reloaded-code-models-dev**](./src/reloaded-code-models-dev/) | 0.1 | models.dev catalog sync with ETag caching and offline fallback |
| [**reloaded-code-provider-config**](./src/reloaded-code-provider-config/) | 0.1 | Provider configuration loading and provider catalog overrides |

## Examples

Expand Down
11 changes: 11 additions & 0 deletions docs/src/agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,17 @@ Evaluation uses **last-match-wins**: the final matching rule takes effect.
For the full rule table and examples, see
[Tools > Permission rules](tools.md#permission-rules).

#### Custom tool permissions

Custom tools are referenced in the `permission` map by name, same as built-in tools.
See [Custom tools](tools.md#custom-tools) for registration.

```yaml
permission:
web_search: allow # custom tool
database: deny # custom tool
```

### Model specification

Format: `provider/model-id` or `synthetic/hf:huggingface-model-id`.
Expand Down
10 changes: 10 additions & 0 deletions docs/src/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,14 @@ graph TD
serdesai["reloaded-code-serdesai<br/><i>SerdesAI framework integration</i>"]
bubblewrap["reloaded-code-bubblewrap<br/><i>Linux sandbox profiles</i>"]
modelsdev["reloaded-code-models-dev<br/><i>models.dev catalog sync</i>"]
providerconfig["reloaded-code-provider-config<br/><i>Provider config loading</i>"]

agents --> core
serdesai --> core
serdesai --> agents
serdesai -.->|optional| bubblewrap
modelsdev --> core
providerconfig --> core

classDef default fill:#1C1C1C,stroke:#fa7774,strokeWidth:2px,color:#fff
```
Expand All @@ -32,6 +34,8 @@ The foundation. Contains every tool implementation as a plain function
- **Path resolvers** - control which files tools can access
- **System prompt builder** - generates context-aware tool guidance
- **Permission engine** - last-match-wins rules with wildcard patterns
- **Custom tool registry + catalog** - framework-agnostic `ToolFactory`,
`CustomToolRegistry`, and `ToolCatalogEntry` types
- **Credential resolver** - API key lookup with override support ([details](getting-started.md#credential-management))
- **Model catalog** - compact hash-table-based provider/model lookup

Expand All @@ -46,6 +50,7 @@ Loads agent definitions from markdown files with YAML frontmatter. Provides:
- **AgentLoader** - scans directories for `.md` agent files
- **AgentCatalog** - name-to-config lookup table
- **AgentRuntime** - bundles catalog + defaults + permissions + task settings
- **AgentRuntimeBuilder** - accepts core tool catalogs and custom tool factories

The agent file format mirrors [OpenCode]'s schema - similar enough that many
files are drop-in compatible, but [not identical](migration.md). The most
Expand Down Expand Up @@ -82,6 +87,11 @@ Syncs the online [models.dev](https://models.dev) catalog into a compact
- Offline fallback when network is unavailable
- Cache load in ~0.3 ms

### reloaded-code-provider-config

Loads provider override configuration and turns it into provider catalog entries
that can be merged with or replace the defaults from models.dev.

## Where your code plugs in

There are two integration paths:
Expand Down
32 changes: 32 additions & 0 deletions docs/src/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,38 @@ a Rust project and an LLM API key (e.g. `OPENAI_API_KEY`).
[serdesai-agents](https://github.com/Reloaded-Project/ReloadedCode/blob/main/src/reloaded-code-serdesai/examples/serdesai-agents.rs)
(with agent files). See [Examples](examples.md) for the full list.

## Custom tools

Implement [`ToolContext`] and [`ToolFactory`], then register with the builder:

```rust
struct MyFactory;
impl ToolContext for MyFactory {
fn name(&self) -> &'static str { "my_tool" }
fn context(&self) -> ToolPrompt {
ToolPrompt::Static("Guidance for using my_tool.")
}
}
impl ToolFactory for MyFactory {
fn create(&self, _ctx: &ToolBuildContext) -> Box<dyn Any + Send + Sync> {
todo!("return your tool")
}
}

let runtime = AgentRuntimeBuilder::new()
.custom_tool(MyFactory)
.tools(vec![
ToolCatalogEntry::new("my_tool", ToolCatalogKind::Custom),
])
.build()?;
```

See [Tools > Custom tools](tools.md#custom-tools) for annotated details
and error handling.

[`ToolContext`]: https://docs.rs/reloaded-code-core/latest/reloaded_code_core/trait.ToolContext.html
[`ToolFactory`]: https://docs.rs/reloaded-code-core/latest/reloaded_code_core/trait.ToolFactory.html

## Credential management

`CredentialResolver` resolves API keys by name (e.g. `"OPENAI_API_KEY"`) -
Expand Down
36 changes: 21 additions & 15 deletions docs/src/guides/custom-framework.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,10 @@ pb.track(read_tool);
// pb.track(other_tool);
// pb.track(another_tool);

// For custom tools (e.g. tool factories, framework adapters) where you
// have name + prompt but no instance, use track_entry():
pb.track_entry("my_custom_tool", ToolPrompt::Static("Use my_custom_tool to do X."));

let system_prompt = pb.build();
```

Expand Down Expand Up @@ -143,22 +147,24 @@ let glob = AllowedGlobResolver::new(["/workspace/project"])?

## What you get from core

| Component | What it provides |
| ---------------------------------------------- | ------------------------------------------- |
| `read_file`, `write_file`, `edit_file` | File operations |
| `glob_files`, `grep_search` | Search operations |
| `execute_command`, `execute_command_with_mode` | Shell execution |
| `fetch_url` | URL fetching |
| `read_todos`, `write_todos` | Shared todo state |
| `SystemPromptBuilder` | Context-aware system prompt generation |
| `ToolContext` trait | Tool metadata interface for prompt building |
| `PathResolver` trait | Path security boundary |
| `AllowedPathResolver` | Directory-based sandbox |
| Component | What it provides |
| ---------------------------------------------- | -------------------------------------------------------- |
| `read_file`, `write_file`, `edit_file` | File operations |
| `glob_files`, `grep_search` | Search operations |
| `execute_command`, `execute_command_with_mode` | Shell execution |
| `fetch_url` | URL fetching |
| `read_todos`, `write_todos` | Shared todo state |
| `SystemPromptBuilder` | Context-aware system prompt generation |
| `ToolContext` trait | Tool metadata interface for prompt building |
| `ToolFactory` / `CustomToolRegistry` | Framework-agnostic custom tool creation and lookup |
| `ToolCatalogEntry` / `ToolCatalogKind` | Standard/custom tool catalog for adapters |
| `PathResolver` trait | Path security boundary |
| `AllowedPathResolver` | Directory-based sandbox |
| `AllowedGlobResolver` | Glob-based sandbox (last matching rule takes precedence) |
| `Ruleset` / `Rule` | Permission evaluation engine |
| `CredentialResolver` | API key lookup with overrides |
| `ModelCatalog` | Compact provider/model hash table |
| `ToolError` | Unified error type for all tools |
| `Ruleset` / `Rule` | Permission evaluation engine |
| `CredentialResolver` | API key lookup with overrides |
| `ModelCatalog` | Compact provider/model hash table |
| `ToolError` | Unified error type for all tools |

For the full API reference, see [docs.rs/reloaded-code-core](https://docs.rs/reloaded-code-core).

Expand Down
56 changes: 53 additions & 3 deletions docs/src/tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,58 @@ permission:
| [**todoread**](#todoread-todowrite) | `read_todos` | Read shared todo list state |
| [**todowrite**](#todoread-todowrite) | `write_todos` | Update shared todo list state |
| [**task**](#task) | `TaskInput`/`TaskOutput` | Delegate work to a named sub-agent |
| [**custom**](#custom-tools) | `ToolFactory` | User-defined tool registered by the embedder |

### Custom tools

Custom tools let embedders add non-built-in tools to an agent runtime.

```rust
use reloaded_code_agents::AgentRuntimeBuilder;
use reloaded_code_core::{
ToolBuildContext, ToolCatalogEntry, ToolCatalogKind, ToolContext, ToolFactory,
};
use reloaded_code_core::context::ToolPrompt;
use std::any::Any;

struct WebSearchFactory;

// Name + prompt guidance.
impl ToolContext for WebSearchFactory {
fn name(&self) -> &'static str { "web_search" }
fn context(&self) -> ToolPrompt {
ToolPrompt::Static("Use web_search to find information online.")
}
}

// Build framework-specific tool instance.
impl ToolFactory for WebSearchFactory {
fn create(&self, _ctx: &ToolBuildContext) -> Box<dyn Any + Send + Sync> {
// SerdesAI: return Box::new(Box<dyn serdes_ai::Tool<()>>).
todo!("return your tool")
}
}

let runtime = AgentRuntimeBuilder::new()
// Register factory.
.custom_tool(WebSearchFactory)
// Enable tool in catalog.
.tools(vec![
ToolCatalogEntry::new("web_search", ToolCatalogKind::Custom),
])
.build()?;
```

Rules:

- Factory name must match catalog entry name.
- `ToolContext::context()` adds system-prompt guidance.
- Custom tool names work in agent `permission` maps.
- Missing factory: `AgentBuildError::UnknownCustomTool`.
- Wrong return type: `AgentBuildError::CustomToolDowncastFailed`.

See [reloaded-code-core API docs](https://docs.rs/reloaded-code-core/latest)
for full API details.

### read

Expand Down Expand Up @@ -422,6 +474,4 @@ For a deeper dive into path security, see [Sandboxing](sandboxing.md).
[bubblewrap]: https://github.com/containers/bubblewrap
[create_todo_tools]: https://docs.rs/reloaded-code-serdesai/latest/reloaded_code_serdesai/tools/todo/fn.create_todo_tools.html
[reloaded-code-core]: https://docs.rs/reloaded-code-core
[reloaded-code-serdesai]: https://docs.rs/reloaded-code-serdesai
[Agents]: agents.md
[agent files]: agents.md
[reloaded-code-serdesai]: https://docs.rs/reloaded-code-serdesai
Loading
Loading