chore: add docs
This commit is contained in:
Joe Fleming
233
docs/API.md
Normal file
233
docs/API.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# 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`:
|
||||
|
||||
```typescript
|
||||
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:
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
class MessageBus {
|
||||
publishInbound(msg: InboundMessage): void;
|
||||
consumeInbound(): Promise<InboundMessage>;
|
||||
publishOutbound(msg: OutboundMessage): void;
|
||||
consumeOutbound(): Promise<OutboundMessage>;
|
||||
}
|
||||
```
|
||||
|
||||
### InboundMessage
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
type OutboundMessage = {
|
||||
channel: string;
|
||||
chatId: string;
|
||||
content: string | null;
|
||||
metadata: Record<string, unknown>;
|
||||
media?: string[];
|
||||
};
|
||||
```
|
||||
|
||||
### LLMProvider
|
||||
|
||||
```typescript
|
||||
class LLMProvider {
|
||||
defaultModel: string;
|
||||
chat(opts: ChatOptions): Promise<{ response: LLMResponse; responseMessages: ModelMessage[] }>;
|
||||
chatWithRetry(opts: ChatOptions): Promise<{ response: LLMResponse; responseMessages: ModelMessage[] }>;
|
||||
}
|
||||
```
|
||||
|
||||
### Session
|
||||
|
||||
```typescript
|
||||
class Session {
|
||||
key: string;
|
||||
messages: SessionMessage[];
|
||||
createdAt: string;
|
||||
updatedAt: string;
|
||||
lastConsolidated: number;
|
||||
getHistory(maxMessages?: number): SessionMessage[];
|
||||
clear(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### CronService
|
||||
|
||||
```typescript
|
||||
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;
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user