Tool System

Extensible tool architecture with JSON I/O, agent scoping, and Lua scripting.

Overview

Tools are how agents interact with the world beyond text generation. Each tool accepts JSON input and returns JSON output. Tools are registered in the ToolRegistry and are available to agents based on their per-agent tool allowlist (empty = all tools available).

Built-in Tools

file: Read, write, and edit files with path sandboxing. Default-deny policy — agents can only access paths explicitly allowed in their per-agent allowlist. Supports absolute and relative paths with glob pattern matching.
shell_exec: Execute /bin/sh commands with configurable timeouts and command allow/deny lists. Output is captured and returned as structured JSON (stdout, stderr, exit code).
http: General-purpose HTTP client with SSRF protection. Blocks RFC 1918 addresses, loopback, link-local, and CGNAT ranges to prevent agents from probing internal networks.
web_fetch: URL content extraction. Fetches a URL and converts the response to markdown or plain text. Used for reading web pages without browser automation.
diary: Per-agent encrypted diary access. Write entries, read by date range, search content, list metadata, and export encrypted backups.
social: Proactive social actions across connected platforms. Posts, replies, searches, and profile lookups. Routes to the correct adapter (Bluesky, VK, etc.) based on the platform prefix.

Lua Scripting

Custom tools can be written in Lua 5.4 and registered at runtime via the admin UI. Lua scripts are sandboxed — restricted IO, no os.exit or loadfile, budget-limited execution.

A Lua script registers one or more actions under a single tool name. Each action is a Lua function that receives a JSON params table and returns a JSON result. The LuaToolHandler bridges these to the IToolHandler interface automatically.

Scripts are stored in SQLite via ScriptStore and loaded in a two-phase startup (after the kernel initializes, ensuring all native tools are available to Lua code).

Lua tool example

-- A simple Lua tool that reverses text
function reverse_text(params)
  local text = params.text or ""
  return { result = text:reverse() }
end

-- Register with Animus
animus.register("text_utils", {
  reverse = reverse_text,
})

Tool Security

Default-deny file access with per-agent path allowlists
SSRF protection on HTTP tool (blocks internal network access)
Command allow/deny lists on shell execution
Sandboxed Lua execution with budget limits
Per-agent tool allowlist (agents only see tools they're authorized to use)