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
createScopedFilesystemTools	All of the above + bash, rooted at a working directory

Subpath imports are available: @baleybots/agent-tools/bash, /filesystem, /scoped.

Scoped workspace

Bind tools to a project directory so paths resolve inside it:

import { Baleybot, Output } from '@baleybots/core';
import { createScopedFilesystemTools } from '@baleybots/agent-tools';
import { z } from 'zod';

const workingDir = '/path/to/project';
const tools = createScopedFilesystemTools(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);

createScopedFilesystemTools returns:

• bash — shell in workingDir
• read_file, write_file, edit_file, list_directory, file_info — paths resolve against workingDir

Optional ignoreFilter trims list_directory output (explicit reads/writes are not blocked).

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, apps/ui, 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.

Related

• Tools — core tool() helper and stopWhen
• BAL tools — declarative pipeline DSL (different package)
• MCP — remote tools from MCP servers