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`:

```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;
}
```