Metadata-Version: 2.4
Name: ai-monitor-agent
Version: 0.3.2
Summary: Install and run the AI Monitor Agent skill and local dashboard.
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: uvicorn[standard]<1,>=0.30
Requires-Dist: pydantic<3,>=2.8
Dynamic: license-file

# AI Agent Factory (AI Monitor Agent)

Skill e monitor local para Claude Code, Codex e Grok. A distribuição é feita como pacote Python: instala-se pelo PyPI e, em seguida, registra-se a skill nos assistentes disponíveis no usuário atual.

A página principal é uma **fábrica visual**: cada sessão do Claude Code (e cada subagente) é um robô numa linha de produção, animado conforme eventos reais recebidos em tempo real por WebSocket.

> O monitor não inicia tarefas de IA por conta própria. O conector do Claude Code está implementado via hooks oficiais; Codex e Grok ainda não têm conector (só via SDK).

## Instalação como plugin do Claude Code (recomendado)

O plugin traz a skill e os hooks; o pacote PyPI fornece só o servidor.

```text
claude plugin marketplace add <owner>/<repo-no-github>
claude plugin install ai-monitor-agent@ai-monitor-agent-marketplace
python -m pip install "ai-monitor-agent>=0.3.1"
python -m ai_monitor_agent.cli install --runtime-only
```

O `install` adiciona a pasta do comando ao PATH do usuário: a partir do próximo terminal, `ai-monitor-agent start|status|stop` funciona em qualquer pasta. No Windows, use `py` em vez de `python` se necessário.

Depois, numa sessão: `/ai-monitor-agent:ai-monitor-agent`. Para desligar a monitorização, desative o plugin em `/plugin`. Não combine com `ai-monitor-agent install` sem `--runtime-only`, ou os eventos chegam em dobro (`ai-monitor-agent uninstall-hooks` resolve).

## Requisitos

- Python 3.11 ou superior.
- Acesso à Internet para baixar o pacote e suas dependências.

## Instalação pelo PyPI

Quando o pacote estiver publicado:

```bash
python -m pip install ai-monitor-agent
python -m ai_monitor_agent.cli install
```

No Windows:

```powershell
py -m pip install ai-monitor-agent
py -m ai_monitor_agent.cli install
```

Para uma instalação isolada, use `pipx install ai-monitor-agent` e depois `ai-monitor-agent install`.

## Instalação local durante o desenvolvimento

Na raiz deste repositório, instale o pacote e suas dependências diretamente:

```bash
python -m pip install .
python -m ai_monitor_agent.cli install
```

No Windows:

```powershell
py -m pip install .
py -m ai_monitor_agent.cli install
```

O comando `install` instala também os **hooks HTTP do Claude Code** em `~/.claude/settings.json` (fusão que preserva os seus hooks; backup em `settings.json.bak`). Para os remover: `ai-monitor-agent uninstall-hooks`.

O comando `install` copia a skill para os diretórios pessoais do Claude Code (`~/.claude/skills/ai-monitor-agent/`) e dos assistentes compatíveis com o diretório padrão de skills (`~/.agents/skills/ai-monitor-agent/`). Reinicie o aplicativo de IA após a instalação se a skill não aparecer.

## Utilização

Inicie o monitor dentro do repositório que deseja acompanhar:

```bash
ai-monitor-agent start
```

Ou invoque a skill no assistente:

- Claude Code: `/ai-monitor-agent`
- Codex: `$ai-monitor-agent`
- Grok: `/ai-monitor-agent`

Para verificar ou encerrar:

```bash
ai-monitor-agent status
ai-monitor-agent stop
```

A página é criada em `<raiz-do-repositório>/agents-monitor/index.html`; a raiz é identificada pelo Git. Fora de um repositório Git, é usado o diretório atual. O servidor tenta usar a porta `6999` e escolhe outra porta livre se necessário — mas os hooks apontam para `6999` (ou `FACTORY_PORT` no momento do `install`), por isso a CLI avisa se a porta mudou. O painel atualiza em tempo real via WebSocket.

## Fábrica visual

- **Linhas** agrupam agentes por sessão (sessão + subagentes), projeto, plataforma ou estado; **Entrada** mostra pedidos em curso e **Expedição** os concluídos/falhados.
- Estados: repouso, a iniciar, a trabalhar, a pensar, à espera, precisa de aprovação, bloqueado, erro, concluído, offline — sempre com ícone + texto, não só cor. Uma ferramenta em execução mostra há quanto tempo corre; só se o modelo ficar 10 min sem qualquer evento aparece "Sem eventos há…". Interromper com Esc põe o agente "À espera".
- Toda tarefa aberta mostra progresso e ETA. Se o agente os reportar (SDK), são usados e marcados "reportado"; senão o Core estima pelo histórico (duração mediana e nº de ferramentas de tarefas concluídas semelhantes) e marca "(est.)" com a origem. O Claude Code não expõe progresso real, por isso as sessões dele são sempre estimadas; a estimativa nunca passa de 95% antes do fim do turno.
- Clique num robô para ver identidade, atividade, eventos completos (entrada/saída das ferramentas), comandos suportados e histórico.
- Pesquisa, filtros, zoom (Ctrl+roda), arrastar, colapsar linhas, vista em lista, "Reduzir movimento" (respeita `prefers-reduced-motion`).
- **Emergency Stop** bloqueia novos comandos e a entrega de instruções em fila; não interrompe processos já em curso.

## Conector Claude Code

Hooks usados: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `Notification`, `SubagentStart`, `SubagentStop`, `Stop`, `StopFailure`, `SessionEnd`, `PreCompact` (testado com Claude Code 2.1.224). Falhas de ligação são não-bloqueantes: com o monitor parado o Claude Code continua normal.

- **Instruções**: `send_instruction` é entregue no próximo hook da sessão (como contexto após uma ferramenta/pedido, ou continuando o turno no `Stop`).
- **Não suportado**: pausar, retomar, cancelar, aprovar remotamente, deep link para a sessão.
- **Privacidade**: são guardados localmente (SQLite em `~/.ai-agent-factory/data`) o texto dos pedidos, entradas e saídas das ferramentas (truncados a ~4 KB) e a última mensagem de cada turno. Nada sai da máquina.

O runtime, o banco de dados e os logs ficam em `~/.ai-agent-factory/`.

## Desenvolvimento e publicação

Execute os testes:

```bash
python -m unittest discover -s test
```

Para construir o pacote localmente, use `python -m pip install build` e `python -m build`. A publicação no PyPI requer uma conta PyPI e deve ser feita por um mantenedor autorizado. Publicado em https://pypi.org/project/ai-monitor-agent/.

## API

- `GET /health` — estado do serviço
- `POST /api/v1/agents`, `GET /api/v1/agents` — registar/listar agentes
- `POST /api/v1/tasks`, `GET /api/v1/tasks` — criar/listar tarefas
- `POST /api/v1/events`, `GET /api/v1/events` — publicar/listar eventos
- `POST /api/v1/commands`, `GET /api/v1/commands?agent_id=` — enfileirar/listar comandos (rejeita comandos fora das capacidades do agente)
- `GET|POST /api/v1/emergency-stop` — estado / ativar-desativar
- `POST /api/v1/connectors/claude-code/hook` — receção de hooks do Claude Code
- `GET /api/v1/events?agent_id=` — eventos de um agente
- `GET /api/v1/commands/pending/{agent_id}` — consultar comandos
- `POST /api/v1/commands/{command_id}/ack` — confirmar comando
- `WS /ws` — atualizações em tempo real

## Segurança e limitações

O serviço escuta apenas em `127.0.0.1` e não tem autenticação. Não o exponha à Internet ou a redes não confiáveis. Os comandos enviados pela API são apenas enfileirados; um conector compatível precisaria buscá-los e executá-los. A skill não coleta prompts e o monitor não fica executando chamadas aos modelos em segundo plano.
