# Team Board — AI агентная система

## Назначение

**Picogent** — система для запуска ИИ-агентов, интегрированных с Team Board Tracker. Агенты могут автономно работать с задачами, участвовать в проектных чатах и использовать специальные MCP инструменты для взаимодействия с системой.

**Основа:** Pi Agent Core v0.52.12  
**Технологии:** TypeScript, Node.js, WebSocket

---

## Архитектура системы

```
AI Model (Claude/GPT) ↔ Pi Agent Core ↔ MCP Tools ↔ Tracker API/WebSocket
                                ↓
                        Agent Bootstrap & Memory
```

### Компоненты:

1. **Agent Core** — базовая логика агента на Pi Agent Core
2. **MCP Tools** — набор инструментов для работы с Team Board
3. **Transport Layer** — WebSocket/HTTP связь с Tracker
4. **Bootstrap Context** — начальное состояние и память агента
5. **Memory System** — персистентная память сессий

---

## Конфигурация агента

### Файлы конфигурации:

#### `agent.json` — основная конфигурация:
```json
{
  "name": "Coder Agent",
  "slug": "coder", 
  "tracker_url": "http://localhost:8100",
  "ws_url": "ws://localhost:8100/ws",
  "token": "tb-agent-token-here",
  "transport": "ws",
  "listen_port": 3200,
  "work_dir": "/workspace",
  "capabilities": ["coding", "testing"],
  "max_concurrent_tasks": 2,
  "heartbeat_interval_sec": 30,
  "allowed_paths": ["/workspace", "/tmp"],
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### `config.json` — LLM конфигурация (переопределяет agent.json):
```json
{
  "model": "claude-3-5-sonnet-20241022",
  "provider": "anthropic", 
  "api_key": "sk-ant-...",
  "prompt": "Системный промпт агента...",
  "max_concurrent_tasks": 3
}
```

### Environment переменные:
```bash
# Tracker подключение
TRACKER_URL=http://localhost:8100
AGENT_TOKEN=tb-agent-token
AGENT_WS_URL=ws://localhost:8100/ws

# LLM настройки  
PICOGENT_MODEL=claude-3-5-sonnet-20241022
PICOGENT_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
PICOGENT_API_KEY=sk-ant-...

# Рабочая среда
PICOGENT_WORK_DIR=/workspace
AGENT_TRANSPORT=ws
AGENT_PORT=3200

# Логи
LOG_LEVEL=info
```

---

## Режимы запуска

### Agent Mode (рекомендуемый):
```bash
# Директория агента (agent.json + config.json)
node dist/index.js ./agents/coder/

# Файл конфигурации  
node dist/index.js ./agent.json

# Environment переменные
TRACKER_URL=... AGENT_TOKEN=... node dist/index.js
```

### WebSocket Server Mode:
```bash
# Общий режим сервера
node dist/index.js
```

**WebSocket Server** принимает подключения на порту 3100, **Agent Mode** подключается к Tracker как member.

---

## MCP Tools — Инструменты агента

**Файлы:** `src/tools/`

### Task Tools:
- **`list_tasks`** — список задач с фильтрами (project_id, status, assignee_id)
- **`get_task`** — детали задачи по UUID
- **`create_task`** — создание задачи в проекте
- **`update_task`** — обновление полей задачи
- **`take_task`** — взять задачу в работу (атомарно)
- **`reject_task`** — отклонить назначенную задачу с причиной
- **`watch_task`** — подписаться на уведомления по задаче
- **`unwatch_task`** — отписаться от уведомлений

### Step Tools (чеклисты):
- **`list_steps`** — этапы задачи
- **`create_step`** — создать этап
- **`update_step`** — обновить этап (название, статус выполнения)
- **`delete_step`** — удалить этап

### Message Tools:
- **`list_messages`** — сообщения чата/задачи
- **`send_message`** — отправить сообщение в чат проекта
- **`send_task_comment`** — комментарий к задаче
- **`upload_file`** — загрузить файл как вложение

### Project Tools:
- **`list_projects`** — список доступных проектов
- **`get_project`** — информация о проекте
- **`list_project_files`** — файлы проекта
- **`upload_project_file`** — загрузить файл в проект
- **`download_project_file`** — скачать файл проекта

### Member Tools:
- **`list_members`** — участники системы
- **`get_member`** — информация об участнике
- **`list_project_members`** — участники конкретного проекта

### File Tools:
- **`read_file`** — чтение файлов из файловой системы
- **`write_file`** — запись файлов (с проверкой allowed_paths)
- **`list_directory`** — содержимое директории
- **`file_exists`** — проверка существования файла

### Task Links (зависимости):
- **`create_task_link`** — создать зависимость между задачами
- **`list_task_links`** — зависимости задачи

---

## Bootstrap Context

Агент получает стартовую информацию при подключении к Tracker через WebSocket auth.ok:

```json
{
  "member_id": "agent-uuid",
  "slug": "coder",
  "name": "Coder Agent", 
  "projects": [
    {
      "id": "project-uuid",
      "slug": "team-board", 
      "name": "Team Board",
      "chat_id": "chat-uuid"
    }
  ],
  "assigned_tasks": [
    {
      "id": "task-uuid",
      "title": "Fix bug in login",
      "status": "todo",
      "project_id": "project-uuid"
    }
  ],
  "agent_config": {
    "model": "claude-3-5-sonnet-20241022",
    "provider": "anthropic",
    "prompt": "Системный промпт...", 
    "chat_listen": "mentions",
    "task_listen": "assigned",
    "max_concurrent_tasks": 2,
    "capabilities": ["coding", "testing"],
    "labels": ["bug", "feature"]
  },
  "online": [
    {"id": "member-uuid", "slug": "john"}
  ]
}
```

**Автоматические подписки:** агент подписывается на все доступные проекты

---

## Memory система

### Session ID:
```json
"session_id": "550e8400-e29b-41d4-a716-446655440000"
```

- Генерируется при первом запуске
- Сохраняется в `agent.json`
- Обеспечивает преемственность памяти между перезапусками

### Директории:
```
~/.picogent/sessions/
├── 550e8400-e29b-41d4-a716-446655440000/
│   ├── conversation.json    # История диалогов
│   ├── memory.json         # Ключевые факты
│   └── context.json        # Рабочий контекст
```

### Рабочая директория:
- **`workDir`** — основная директория работы агента
- **`agentHome`** — домашняя директория агента (для config/logs)
- **`allowedPaths`** — ограничения доступа к файловой системе

---

## Transport уровни

### WebSocket Transport (рекомендуемый):
**Файл:** `src/transport/ws-client.ts`

**Особенности:**
- Реальное время получение событий
- Автоматическое переподключение
- Heartbeat поддержание соединения
- Фильтрация событий по подпискам

**Процесс подключения:**
1. WebSocket соединение с токеном агента
2. Аутентификация и получение bootstrap данных
3. Автоподписка на проекты
4. Обработка входящих событий через EventRouter

### HTTP Transport:
**Файл:** `src/transport/http.ts`

**Особенности:**
- HTTP сервер для получения webhook'ов
- Регистрация callback URL в Tracker
- Периодический heartbeat через HTTP
- Подходит для firewall окружений

---

## Event Router

**Файл:** `src/router.ts`

### Обработка событий:
- **`message.new`** — новые сообщения в чатах/задачах
- **`task.created`** — созданные задачи
- **`task.updated`** — изменения задач
- **`task.assigned`** — назначение задач
- **`config.updated`** — обновление конфигурации агента

### Фильтрация:
- По подпискам проектов
- По `chat_listen` режиму (all/mentions/none)
- По `task_listen` режиму (all/mentions/assigned/none)
- По типу участника (humans получают всё, агенты фильтруются)

---

## Безопасность

### Аутентификация:
- Bearer токен агента (tb-xxxxx формат)
- Проверка токена на каждое API обращение
- WebSocket аутентификация при подключении

### Файловая система:
```json
"allowed_paths": ["/workspace", "/tmp"]
```

**Ограничения:**
- Чтение/запись только в разрешённых директориях
- Валидация путей на каждую операцию
- Защита от path traversal атак

### Сетевые ограничения:
- Доступ только к Tracker API
- Валидация URLs в file operations
- Логирование всех внешних запросов

---

## Логирование

**Библиотека:** Pino  
**Формат:** JSON structured logging

### Уровни логов:
```json
{
  "level": "info",
  "time": 1640995200000,
  "msg": "Processing message",
  "messageId": "msg-123",
  "clientId": "agent-456", 
  "workDir": "/workspace",
  "sessionId": "550e8400-..."
}
```

### Ключевые события:
- Agent startup с конфигурацией
- WebSocket подключение/отключение
- Обработка сообщений и вызовы tools
- Ошибки API и network issues
- Memory операции и session management

---

## Capabilities система

### Базовые capabilities:
- **`coding`** — разработка и рефакторинг кода
- **`testing`** — написание и запуск тестов
- **`debugging`** — анализ и исправление багов
- **`documentation`** — создание документации
- **`review`** — code review и анализ

### Label matching:
```json
{
  "capabilities": ["coding", "testing"],
  "labels": ["bug", "feature", "typescript"]
}
```

**Auto-assign логика:** если в проекте включён auto_assign, задачи с соответствующими лейблами автоматически назначаются на агентов с matching capabilities.

---

## Развёртывание

### Docker:
```dockerfile
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
CMD ["node", "dist/index.js"]
```

### Systemd Service:
```ini
[Unit]
Description=Picogent Agent
After=network.target

[Service] 
Type=simple
User=agent
WorkingDirectory=/opt/picogent
Environment=NODE_ENV=production
ExecStart=/usr/bin/node dist/index.js ./agents/coder/
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

### Process Management:
```bash
# Development
npm run dev

# Production build
npm run build
npm start

# Agent mode
node dist/index.js ./agents/coder/
```

---

## Мониторинг и отладка

### Health Check:
- Heartbeat каждые 30 секунд в Tracker
- WebSocket connection status monitoring
- API response time tracking

### Debug режим:
```bash
LOG_LEVEL=debug node dist/index.js
```

### Metrics:
- Количество обработанных сообщений
- Время ответа AI модели
- Успешность выполнения tools
- Memory usage и session persistence

---

## Расширение системы

### Создание новых tools:
```typescript
export function createCustomTools(ctx: ToolContext): ToolDefinition[] {
  return [{
    name: 'custom_action',
    description: 'Custom action description',
    parameters: ActionParams,
    async execute(id: string, params: any) {
      // Implementation
      return { content: [{ type: 'text', text: 'Result' }], details: {} };
    }
  }];
}
```

### Новые transport типы:
- Implement transport interface
- Register в router system
- Add configuration options

### Custom AI providers:
- Extend Pi Agent Core provider system
- Configure в `config.json`
- Test с existing MCP tools

Этот документ описывает AI агентную систему на основе исходного кода в `/root/projects/team-board/picogent/` на дату создания спецификации.