nanobot-ts/docs/API.md

API Reference

This document describes the tool interface exposed to the LLM and the internal APIs for extending nanobot.

Tool Interface

All tools implement the Tool interface from src/agent/tools/base.ts:

interface Tool {
  name: string;                              // Tool identifier
  description: string;                       // LLM-readable description
  parameters: Record<string, unknown>;       // JSON Schema object
  execute(args: Record<string, unknown>): Promise<string>;
}

Built-in Tools

read_file

Read a file from the filesystem.

Parameter	Type	Required	Description
path	string	yes	Absolute or relative file path
offset	number	no	Line number to start from (1-indexed)
limit	number	no	Maximum number of lines to read

Returns: Line-numbered content (e.g., 1: first line\n2: second line)

write_file

Write content to a file, creating parent directories as needed.

Parameter	Type	Required	Description
path	string	yes	File path to write
content	string	yes	Content to write

Returns: Success message or error

edit_file

Replace an exact string in a file.

Parameter	Type	Required	Description
path	string	yes	File path to edit
oldString	string	yes	Exact string to replace
newString	string	yes	Replacement string
replaceAll	boolean	no	Replace all occurrences

Returns: Success message or error if oldString not found

list_dir

List files in a directory.

Parameter	Type	Required	Description
path	string	yes	Directory path
recursive	boolean	no	List recursively

Returns: One file/directory per line, directories suffixed with /

exec

Execute a shell command.

Parameter	Type	Required	Description
command	string	yes	Shell command to execute
timeout	number	no	Timeout in seconds (default: 120)
workdir	string	no	Working directory override

Returns: Combined stdout + stderr

web_search

Search the web using Brave Search API.

Parameter	Type	Required	Description
query	string	yes	Search query
count	number	no	Number of results (default: 10)

Returns: JSON array of { title, url, snippet } objects

web_fetch

Fetch and parse a URL.

Parameter	Type	Required	Description
url	string	yes	URL to fetch
mode	string	no	markdown (default), raw, or html

Returns:

• HTML pages: extracted readable text (via Readability)
• JSON: pretty-printed JSON
• Other: raw text

message

Send a message to the current chat channel.

Parameter	Type	Required	Description
content	string	yes	Message content

Returns: Success confirmation

spawn

Spawn a background subagent for long-running tasks.

Parameter	Type	Required	Description
task	string	yes	Task description for the subagent

Returns: Spawn confirmation with subagent ID

cron

Manage scheduled tasks.

Parameter	Type	Required	Description
action	string	yes	list, add, remove, enable, disable, run, status
id	string	conditional	Job ID (for remove/enable/disable/run)
name	string	conditional	Job name (for add)
message	string	conditional	Task message (for add)
schedule	string	conditional	Schedule expression (for add)
deleteAfterRun	boolean	no	Delete after one execution

Schedule formats:

• every Ns/m/h/d — e.g., every 30m
• at YYYY-MM-DD HH:MM — one-time
• Cron expression — e.g., 0 9 * * 1-5

Returns: Action-specific response (job list, confirmation, status)

Internal APIs

BaseChannel

Extend to create new channel types:

abstract class BaseChannel {
  _bus: MessageBus;
  abstract start(): Promise<void>;
  abstract stop(): void;
  abstract send(chatId: string, content: string, metadata?: Record<string, unknown>): Promise<void>;
  isAllowed(senderId: string, allowFrom: string[]): boolean;
}

MessageBus

class MessageBus {
  publishInbound(msg: InboundMessage): void;
  consumeInbound(): Promise<InboundMessage>;
  publishOutbound(msg: OutboundMessage): void;
  consumeOutbound(): Promise<OutboundMessage>;
}

InboundMessage

type InboundMessage = {
  channel: string;           // 'mattermost', 'cli', 'system'
  senderId: string;          // User identifier
  chatId: string;            // Conversation identifier
  content: string;           // Message text
  metadata: Record<string, unknown>;
  media?: string[];          // Optional media URLs
};

OutboundMessage

type OutboundMessage = {
  channel: string;
  chatId: string;
  content: string | null;
  metadata: Record<string, unknown>;
  media?: string[];
};

LLMProvider

class LLMProvider {
  defaultModel: string;
  chat(opts: ChatOptions): Promise<{ response: LLMResponse; responseMessages: ModelMessage[] }>;
  chatWithRetry(opts: ChatOptions): Promise<{ response: LLMResponse; responseMessages: ModelMessage[] }>;
}

Session

class Session {
  key: string;
  messages: SessionMessage[];
  createdAt: string;
  updatedAt: string;
  lastConsolidated: number;
  getHistory(maxMessages?: number): SessionMessage[];
  clear(): void;
}

CronService

class CronService {
  listJobs(): CronJob[];
  addJob(job: Omit<CronJob, 'state' | 'createdAtMs' | 'updatedAtMs'>): CronJob;
  removeJob(id: string): boolean;
  enableJob(id: string, enabled: boolean): boolean;
  runJob(id: string): Promise<string>;
  status(): string;
  start(): void;
  stop(): void;
}