📦 Skill no OpenHuman hoje
Existe uma confusão histórica. Em versões antigas, skill era um pacote de JavaScript que rodava num runtime QuickJS embarcado. Isso foi removido. Hoje, src/openhuman/skills/ guarda apenas metadados: descobrir, instalar, parsear, injetar referência no prompt.
⚠️ Confusão comum
Não existe mais "rodar meu JavaScript dentro do core". Se você precisa de lógica nova, escreva um tool nativo em Rust via controller registry, ou um MCP server externo. Não tente reviver o QuickJS.
O que sobrou em skills/
ops_create ← criar pacote de skill ops_discover ← achar skills disponíveis ops_install ← instalar metadado ops_parse ← ler manifesto inject ← injetar referências no prompt schemas ← types do controller types ← modelo de dados
🛰️ Agent harness e tool surface
O agent harness é o catálogo dinâmico de ferramentas que o agente "vê" em cada momento. Ele é montado a partir do controller registry, das integrações ativas, e dos servidores MCP conectados.
🔍 O que cada tool no registry tem
- •
tool_idestável (ex.:memory.search,tools.web_search) - •Route (RPC method ou MCP transport)
- •Schemas de input e output
- •Allowed agents — quais agentes podem usar
- •Tags, estado (enabled), health
RPCs de descoberta
openhuman.tool_registry_list ← lista geral openhuman.tool_registry_get ← pega um tool por id
Read-only. Não muda dispatch nem permissão — só descreve.
🔌 MCP — Model Context Protocol
Rodando openhuman-core mcp, o core vira um servidor MCP stdio read-only. Clientes como Claude Desktop, Cursor ou Zed se conectam e ganham acesso à sua memória — sem cloud, sem token.
Tools curadas no MCP
memory.search → openhuman.memory_tree_search memory.recall → openhuman.memory_tree_recall tree.read_chunk → openhuman.memory_tree_get_chunk tree.browse → openhuman.memory_tree_list_chunks tree.top_entities → openhuman.memory_tree_top_entities tree.list_sources → openhuman.memory_tree_list_sources searxng_search* → openhuman.tools_searxng_search (* se SearXNG ligado)
🪪 Provenance por cliente
No initialize, o servidor captura clientInfo.name e normaliza (ex.: "Claude Desktop" → claude-desktop). Tools write-capable usam isso para provenance: writes vêm como mcp:<client>.
Sem clientInfo válido, fallback para o label mcp bare — preserva compatibilidade com clients antigos.
Smoke test rápido
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| openhuman-core mcp
🧰 Tools nativos via controller registry
Este é o caminho oficial para estender o agente: escreva um domínio Rust, registre controllers, e ganhe simultaneamente CLI, JSON-RPC e tool no harness — sem branching adicional em cli.rs ou jsonrpc.rs.
Crie src/openhuman/<dominio>/mod.rs
Adicione mod schemas;. Coloque a lógica em ops.rs, store.rs, types.rs. mod.rs fica leve.
Defina schemas.rs
Exporte all_controller_schemas e all_registered_controllers. Cada handler delega para rpc.rs.
Re-exporte em src/core/all.rs
Nome padronizado: openhuman.<namespace>_<function>. CLI e JSON-RPC descobrem automaticamente.
Teste em isolamento
Unit tests no domínio + JSON-RPC E2E em tests/json_rpc_e2e.rs + UI consome via core_rpc_relay.
✓ O que FAZER
- ✓Subdir dedicado para cada nova feature
- ✓Usar
RpcOutcome<T>em handlers - ✓Logs com prefixo do domínio
- ✓Coverage ≥80% nas linhas alteradas
✗ O que NÃO fazer
- ✗Adicionar
.rssolto emsrc/openhuman/ - ✗Hardcode em
src/core/cli.rsoujsonrpc.rs - ✗Lógica pesada em
mod.rs - ✗Pular E2E ("teste local funcionou")
⏰ Webhooks e cron como gatilhos
Nem todo fluxo nasce de um humano digitando. Os domínios cron e webhooks publicam DomainEvents, e seus subscribers (CronDeliverySubscriber, WebhookRequestSubscriber) disparam o que precisar.
Fluxo de um cron job
[scheduler tick]
↓
[cron domain]
↓ DomainEvent::Cron(CronDue)
[event bus]
↓
[CronDeliverySubscriber]
↓ chama agente / tool / cadeia
[resultado registrado]
⚙️ Configurar na UI
- Cron e webhooks vivem em
/settings/webhooks-triggers - Cada trigger tem nome, schedule (cron expr) ou URL, e ação alvo
- A rota antiga
/webhooksredireciona para a nova
💡 Dica prática
Cron + memory.recall + canal de saída = "todo dia às 8h, me mande as 3 threads mais quentes de ontem no Slack". Receita curta, valor alto.
🚀 Receitas práticas
Padrões prontos que combinam tudo da trilha. Adaptáveis a quase qualquer time. Receita = trigger + tool + memória + canal.
Daily digest no Slack
Trigger: cron 08:00 dias úteis. Tool: memory.recall com "decisões e bloqueios das últimas 24h". Canal: Slack DM.
Triagem de e-mails urgentes
Trigger: subconscious task read-only a cada 15 min. Tool: tree.browse filtrando Gmail. Escalation: card de aprovação se quiser responder algo.
Webhook do GitHub → resumo no Discord
Trigger: webhook em PR open. Tool: tool nativo que lê o diff via TokenJuice. Canal: Discord canal #reviews.
Cursor + memória do OpenHuman
Trigger: você abrindo Cursor. Tool: conectar via MCP (openhuman-core mcp). Resultado: Cursor usa memory.recall nas suas conversas reais.
💡 Dica prática
Comece pequeno. Uma receita que economiza 15 minutos por dia vira hábito. Receitas "perfeitas" que nunca vão para produção não economizam nada.
🧩 Resumo do módulo
Próxima trilha:
Trilha 4 — 🎓 Técnicas Avançadas