docs/TECHNICAL.md

# Agent OS - Documentacao Tecnica

## Visao Geral

Agent OS e um sistema operacional de agentes IA. Uma interface desktop-like (macOS-style) que orquestra multiplos modelos de IA especializados atraves de um modelo gestor central. Cada agente e um "slot" plugavel que pode ser trocado, adicionado ou removido facilmente.

## Arquitetura

```
┌──────────────────────────────────────────────────────────────┐
│                    AGENT OS (Frontend React)                  │
│  ┌─────────┬──────────┬──────────┬────────┬────────┬───────┐ │
│  │ Browser │ Terminal │  Inbox   │Mission │ Agents │Finder │ │
│  │         │          │          │Control │        │       │ │
│  └─────────┴──────────┴──────────┴────────┴────────┴───────┘ │
├──────────────────────────────────────────────────────────────┤
│                    SERVER (Node.js + Express)                 │
│  ┌──────────┬──────────┬──────────┬──────────┬─────────────┐ │
│  │ Browser  │ PM2      │ Supabase │ GitHub   │ SmolAgent   │ │
│  │ Manager  │ API      │ API      │ CLI      │ Daemon      │ │
│  └──────────┴──────────┴──────────┴──────────┴─────────────┘ │
├──────────────────────────────────────────────────────────────┤
│                    CAMADA DE ORQUESTRACAO                     │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │              MODELO GESTOR (Orchestrator)                 │ │
│  │    Recebe tarefa → Classifica → Roteia → Retorna         │ │
│  │    Llama 3.3 70B via HF Inference API (gratis, Pro)      │ │
│  └─────────────┬────────────┬───────────────┬───────────────┘ │
│                │            │               │                 │
│  ┌─────────────┴┐  ┌───────┴──────┐  ┌─────┴──────────────┐ │
│  │ Agent Slot 1 │  │ Agent Slot 2 │  │ Agent Slot N       │ │
│  │ Coding       │  │ SQL/Data     │  │ (plugavel)         │ │
│  │ Opus 4.6 API │  │ 1.5B local   │  │ qualquer modelo    │ │
│  └──────────────┘  └──────────────┘  └────────────────────┘ │
├──────────────────────────────────────────────────────────────┤
│                    MEMORIA CENTRAL                            │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │              Basic Memory (MCP Server)                    │ │
│  │    Markdown files + SQLite + Vector Embeddings            │ │
│  │    Persistente entre sessoes e agentes                    │ │
│  └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
```

## Stack Atual

### Frontend (React + TypeScript + Vite)
- **Desktop**: Interface macOS-style com janelas arrastáveis, dock, menu bar
- **Window Manager**: Zustand store (`useAppStore`) com persist
- **Apps**: Registry plugavel (`appRegistry.ts`)
- **Componentes**: Desktop, Dock, MenuBar, WindowFrame

### Backend (Node.js + Express)
- **Porta**: 3000
- **APIs implementadas**:
  - `/api/browsers/*` - Browser automation via Playwright (criar, navegar, clicar, digitar, screenshot)
  - `/api/pm2/*` - Process manager (listar, restart, stop, logs)
  - `/api/supabase/*` - Supabase CLI proxy (auth, projetos, tabelas, SQL)
  - `/api/github/*` - GitHub CLI proxy (auth, repos, issues, PRs, notificacoes)
  - `/api/smol/chat` - SmolAgent daemon proxy (porta 8082)
  - `/api/launcher/*` - Proxy pro claude-launcher-web (porta 3002)
  - `/ws` - WebSocket para terminal, browser streaming, file watching

### Infra (Vultr - 207.246.65.100)
- **OS**: Ubuntu, 4 CPU, 8GB RAM, sem GPU
- **Processos ativos**:
  - `server.js` (porta 3000) - Frontend + API
  - `smol-daemon.py` (porta 8082) - SmolAgent backend
  - `llama-server` (porta 8080) - Modelo 1.5B local CPU
  - `launcher/server.js` (porta 3002) - Claude launcher
  - `agent-bot` (porta 9090) - Bot auxiliar

## App Registry

O sistema de apps e plugavel. Cada app registrado no `appRegistry.ts`:

| App | ID | Status | Descricao |
|-----|----|--------|-----------|
| Browser | `browser` | Funcional | Web browser com Playwright |
| Terminal | `terminal` | Funcional | Terminal session via launcher |
| Inbox | `inbox` | Placeholder | Task inbox com comments |
| Mission Control | `mission-control` | Placeholder | Kanban board de tarefas |
| Agents | `agents` | Placeholder | Org chart de agentes |
| Finder | `finder` | Placeholder | File browser de workspaces |
| Settings | `settings` | Placeholder | Configuracoes do sistema |

### Interface de um App
```typescript
interface AppRegistryEntry {
  id: string;           // ID unico
  name: string;         // Nome exibido
  icon: string;         // Icone do dock
  description: string;  // Descricao
  component: React.LazyExoticComponent;  // Componente React
  defaultSize: { width, height };
  minSize?: { width, height };
  allowMultiple?: boolean;    // Multiplas instancias
  dockPinned?: boolean;       // Fixado no dock
}
```

## Agent Registry (A IMPLEMENTAR)

Sistema de registro de agentes especializados. Cada agente e um slot plugavel:

```typescript
interface AgentSlot {
  id: string;                  // "coder", "sql", "text", "frontend"
  name: string;                // "Coding Agent"
  description: string;         // "Especializado em..."
  provider: "anthropic" | "openai" | "openrouter" | "huggingface" | "local";
  config: {
    model: string;             // "claude-opus-4-6" ou "agent-os-1b5"
    endpoint?: string;         // URL do endpoint (local ou API)
    apiKey?: string;           // Chave da API
    temperature?: number;
    maxTokens?: number;
  };
  capabilities: string[];     // ["code", "sql", "text", "reasoning"]
  active: boolean;             // Ativado/desativado
}
```

### Agentes Planejados

| Slot | Modelo | Provider | Funcao |
|------|--------|----------|--------|
| **Gestor/Orquestrador** | Llama 3.3 70B | HF Inference API (gratis Pro) | Roteia tarefas, classifica intencao, coordena agentes |
| **Coding** | Claude Opus 4.6 | Anthropic API | Escreve/refatora codigo |
| **SQL/Data** | agent-os-1b5 (custom) | Local llama-server | Queries SQL, Supabase, information_schema |
| **Frontend** | (a definir) | (a definir) | UI/UX, componentes React |
| **Texto** | (a definir) | (a definir) | Criacao de conteudo, copywriting |
| **Pesquisa** | (a definir) | (a definir) | Web search, analise de dados |

### Fluxo de Orquestracao

```
1. Usuario digita mensagem no chat
2. Gestor (Llama 70B) analisa a intencao:
   - "escreve uma funcao que..." → routing: coder
   - "quantas vms ativas..." → routing: sql
   - "cria um texto sobre..." → routing: text
3. Gestor envia pra o agente especializado
4. Agente processa e retorna resultado
5. Gestor formata e entrega ao usuario
6. Memoria Central registra a interacao
```

### Troca de Agentes
O usuario pode a qualquer momento:
- Trocar o modelo de um slot (ex: mudar coder de Opus pra GPT-4)
- Adicionar novo slot
- Desativar um slot
- Escolher manualmente qual agente usar

## Memoria Central: Basic Memory

### O que e
Sistema de memoria persistente baseado em Markdown + SQLite + Vector Embeddings. Opera como MCP Server.

### Arquitetura
```
┌──────────────────────────────────────┐
│          Markdown Files              │
│  - YAML frontmatter (metadata)      │
│  - [category] observations           │
│  - [[wiki-links]] relations          │
├──────────────────────────────────────┤
│          SQLite Index                │
│  - Full-text search                  │
│  - Vector embeddings (FastEmbed)     │
│  - Hybrid search                     │
├──────────────────────────────────────┤
│          MCP Server                  │
│  - memory:// URLs                    │
│  - CRUD de notas                     │
│  - Navegacao semantica               │
│  - Context building                  │
└──────────────────────────────────────┘
```

### Uso no Agent OS
- **Contexto entre sessoes**: Agentes mantem conhecimento entre conversas
- **Knowledge graph**: Relacoes entre entidades (projetos, decisoes, aprendizados)
- **Multi-agente**: Todos os agentes leem/escrevem na mesma memoria
- **Orquestrador documenta**: O gestor registra cada interacao e decisao
- **Humano edita**: Usuario pode editar arquivos Markdown diretamente

### Claude Session Logger
Complementa o Basic Memory registrando automaticamente:
- Sessoes de conversa com Claude
- Ferramentas utilizadas
- Decisoes tomadas
- Erros e solucoes

## Modelos Treinados (Custom)

### agent-os-adapter-1.5b
- **Base**: Qwen 2.5 1.5B Instruct
- **Treino**: LoRA (r=32, alpha=64), 7 epochs, 415 exemplos x4
- **Funcao**: Converter linguagem natural → JSON (SQL, CLI, shell)
- **Deploy**: GGUF Q8 no llama-server (CPU, 1.6GB RAM, ~3s/query)
- **Repos**:
  - Adapter: `devsomosahub/agent-os-adapter-1.5b`
  - Merged: `devsomosahub/agent-os-1b5-merged`

### agent-os-adapter-7b
- **Base**: Qwen 2.5 7B Instruct
- **Treino**: LoRA Q4, mesma config
- **Funcao**: Mesma, mas mais preciso
- **Repos**:
  - Adapter: `devsomosahub/agent-os-adapter-7b`
  - Merged: `devsomosahub/agent-os-7b-merged`

### Limitacao conhecida
Modelos custom inventam nomes de colunas baseados no dataset de treino quando fazem queries diretas. Solucao: fluxo de 2 passos (information_schema primeiro, depois query com colunas reais).

## APIs Externas Utilizadas

| Servico | Uso | Autenticacao |
|---------|-----|-------------|
| HuggingFace (Pro) | Inference API gratis (Llama 70B), treinamento, endpoints | Token HF |
| Anthropic | Claude Opus 4.6 para coding agent | API Key |
| OpenRouter | LLMs alternativos, fallback | API Key |
| Vultr | Servidores (VMs dos boards, server Agent OS) | API Key |
| Supabase | Banco de dados dos projetos (Cloud-Hub, Hubia) | Access Token |
| GitHub | Repos, issues, PRs | gh CLI token |

## Portas do Server (207.246.65.100)

| Porta | Servico | Acesso |
|-------|---------|--------|
| 3000 | Agent OS (frontend + API) | Publico |
| 3002 | Claude Launcher Web | Interno |
| 8080 | llama-server (modelo 1.5B) | Interno |
| 8082 | SmolAgent daemon | Interno |
| 9090 | Agent bot | Interno |

## Proximos Passos

1. **Implementar Agent Registry** - Config JSON de agentes plugaveis
2. **Implementar Orquestrador** - Gestor que roteia entre agentes
3. **Integrar Basic Memory** - MCP Server como memoria central
4. **Integrar Session Logger** - Log automatico de sessoes
5. **Implementar apps Placeholder** - Inbox, Mission Control, Agents, Finder, Settings
6. **Modelo guia/assistente** - Treinar modelo que explica o sistema ao usuario
7. **Dashboard de agentes** - UI para ver/trocar/configurar agentes em tempo real