Agent Tools
@baleybots/agent-tools provides host coding tools — filesystem, bash, and scoped workspace access — for Baleybots processors. These are concrete tools you attach to a Baleybot tool loop.
This is not the BAL package. For pipeline composition DSL, see BAL tools. For defining your own tools, use tool() from @baleybots/core.
Install
bun add @baleybots/agent-tools @baleybots/core zod
Peer dependencies: @baleybots/core >=0.0.1-alpha.100, zod ^4.3.6.
Exports
| Export | Purpose |
|---|---|
bashTool, createBashTool | Run shell commands (cwd-relative) |
readFileTool, writeFileTool, editFileTool | File read / write / patch |
listDirectoryTool, fileInfoTool | Directory listing and metadata |
createFilesystemTools | The five filesystem tools bound to a root directory |
Subpath imports are available: @baleybots/agent-tools/bash and /filesystem.
Scoped workspace
Bind tools to a project directory so paths resolve inside it:
import { Baleybot, Output } from '@baleybots/core';
import { createBashTool, createFilesystemTools } from '@baleybots/agent-tools';
import { z } from 'zod';
const workingDir = '/path/to/project';
const tools = {
bash: createBashTool({ workingDir }),
...createFilesystemTools({ root: workingDir }),
};
const coder = Baleybot.create({
name: 'coder',
goal: 'Help edit this repository. Use read_file and edit_file before changing code.',
tools,
output: Output.object({
schema: z.object({ summary: z.string() }),
}),
});
const result = await coder.process('Find the main entry point and describe what it does.');
console.log(result.summary);
createFilesystemTools({ root }) returns read_file, write_file, edit_file, list_directory and file_info. Paths resolve against root and must stay inside it; a function root is read on every call. createBashTool({ workingDir }) returns bash, which runs with workingDir as its cwd (the cwd is not a sandbox).
Options on createFilesystemTools:
ignoreFiltertrimslist_directoryoutput (explicit reads and writes are not blocked).elevateRootnames a second root a call reaches withoutside_workspace: true; such a call always needs approval.describereplaces the model-facing description of a tool, by tool name.
Unscoped tools
Use individual exports when the host already manages cwd or you want one capability:
import { Baleybot } from '@baleybots/core';
import { bashTool, readFileTool } from '@baleybots/agent-tools';
const bot = Baleybot.create({
name: 'dev',
goal: 'Run commands and read files in the current working directory.',
tools: { bash: bashTool, read_file: readFileTool },
});
Where these are used
Shared by the CLI, the agent server (apps/server), and any host that needs filesystem/bash access without re-implementing path validation. Coding tools moved out of @baleybots/tools (now BAL-only) in alpha.171 — see Alpha 171 migration.