Otto Bridge

Companion local do Otto para:

• reivindicar um codigo de pareamento gerado pela web
• armazenar o device_token do dispositivo
• manter um WebSocket persistente com o backend
• executar jobs locais com executor proprio do Otto no macOS, mock ou clawd-cursor

Guia de uso

Para um passo a passo de instalacao, pareamento, uso, desconexao e desinstalacao, veja USER_GUIDE.md.

Para o estado atual da arquitetura, capacidades entregues, limitacoes e roadmap do Otto Bridge, veja leg3ndy-ai-backend/docs/OTTO_BRIDGE_ARCHITECTURE.md.

Distribuicao

Fluxo recomendado agora:

1. publicar como pacote npm privado/publico para time interno e beta testers
2. validar pareamento, atualizacao e telemetria em ambiente real
3. depois empacotar em .dmg/.pkg no macOS e .msi no Windows

O pacote ja esta estruturado para install via CLI:

npm install -g @leg3ndy/otto-bridge
otto-bridge status
otto-bridge version

Enquanto o pacote nao estiver publicado, voce pode gerar um tarball local:

npm pack
npm install -g ./leg3ndy-otto-bridge-0.7.4.tgz

No 0.7.4, playwright segue como dependencia obrigatoria no otto-bridge. O primeiro npm install -g @leg3ndy/otto-bridge pode demorar mais porque instala o browser persistente usado pelo WhatsApp Web e pelos fluxos web em background do bridge.

No macOS, o 0.7.4 usa o provider macos-helper, um helper WKWebView sem Dock para o WhatsApp Web. O helper sobe com user-agent de Chrome moderno para evitar o bloqueio do WhatsApp ao detectar Safari/WebKit. O runtime antigo com Chromium/Playwright fica disponivel apenas como override explicito via OTTO_BRIDGE_WHATSAPP_RUNTIME_PROVIDER=embedded-playwright.

Publicacao

Checklist de release:

npm whoami
npm install
npm run release:check
npm publish --access public

O publish exige permissao no scope @leg3ndy.

Se o seu npm local estiver com cache travado por permissao, rode com cache temporario:

npm_config_cache=/tmp/otto-npm-cache npm run release:check
npm_config_cache=/tmp/otto-npm-cache npm publish --access public

Comandos

Listar ajuda

otto-bridge help
otto-bridge --help

Parear o dispositivo

otto-bridge pair --api http://localhost:8000 --code ABC123

Opcoes suportadas:

• --name: nome amigavel do dispositivo
• --timeout-seconds: limite de espera pela aprovacao web
• --poll-interval-ms: intervalo de polling do claim
• --executor: native-macos, mock ou clawd-cursor
• --clawd-url: base URL da API local do clawd-cursor
• --clawd-poll-interval-ms: polling do status/logs do clawd-cursor

No macOS, o caminho recomendado agora e o executor nativo do Otto Bridge. Se nenhum --executor for informado, o pair usa native-macos por padrao no Mac.

Rodar o bridge

otto-bridge run

Se o executor estiver salvo no config.json, o run usa essa configuracao por padrao.

Para forcar o executor nativo no macOS sem reparar:

otto-bridge run --executor native-macos

O adapter clawd-cursor continua disponivel como override opcional:

otto-bridge run --executor clawd-cursor --clawd-url http://127.0.0.1:3847

WhatsApp Web em background

Fluxo recomendado no 0.7.4:

otto-bridge extensions --install whatsappweb
otto-bridge extensions --setup whatsappweb
otto-bridge extensions --status whatsappweb

O setup agora abre o login do WhatsApp Web no helper/background browser do proprio bridge. Depois do QR code, o Otto usa a sessao local em background, sem depender de aba visivel no Safari.

Contrato do 0.7.4:

• otto-bridge extensions --setup whatsappweb: autentica a sessao uma vez
• otto-bridge run: mantem o browser persistente do WhatsApp vivo em background enquanto o runtime estiver ativo, sem depender de uma aba aberta no Safari
• ao parar o otto-bridge run: o browser em background e desligado, mas a sessao local fica lembrada para o proximo boot

Handoff rapido do 0.7.4

Ja fechado no codigo:

• provider macos-helper dockless no macOS como runtime padrao do WhatsApp
• user-agent do helper ajustado para evitar bloqueio do WhatsApp por detecao de Safari/WebKit
• resultado final dos device_job agora e persistido como contexto mais forte para o proximo turno do Otto
• prompt bridge-aware no chat normal para ajudar o Otto a responder com base no que realmente aconteceu no device

Ainda precisa reteste em campo:

• fluxo completo do WhatsApp no helper macos-helper
• confirmacao de que o helper realmente passa do gate de compatibilidade do WhatsApp
• perguntas de follow-up como o que voce mandou? depois de uma acao local de mensagem

Ver estado local

otto-bridge status

Ver versao instalada

otto-bridge version
otto-bridge --version

Atualizar o pacote

Atualizacao automatica via npm:

otto-bridge update

Para apenas ver qual comando sera executado:

otto-bridge update --dry-run

Para instalar manualmente:

npm install -g @leg3ndy/otto-bridge@latest

Remover pareamento local

otto-bridge unpair

Variaveis de ambiente

• OTTO_API_BASE_URL
• OTTO_BRIDGE_HOME
• OTTO_BRIDGE_NAME
• OTTO_BRIDGE_EXECUTOR
• OTTO_CLAWD_BASE_URL
• OTTO_CLAWD_POLL_INTERVAL_MS

Payload esperado para jobs desktop

Os executores locais do Otto Bridge procuram a tarefa em uma destas chaves, nessa ordem:

• task
• prompt
• instruction
• instructions
• message

O executor nativo do macOS tambem aceita payload estruturado em actions[], por exemplo:

{
  "job_type": "desktop_actions",
  "payload": {
    "actions": [
      { "type": "open_app", "app": "Safari" },
      { "type": "open_url", "url": "https://www.youtube.com", "app": "Safari" }
    ]
  }
}

Exemplo:

{
  "job_type": "desktop_task",
  "payload": {
    "task": "Abra o Safari e pesquise Otto AI"
  }
}