Docs

API local

Live activity de deploy tocando junto com a música

Visão geral

O Knobler expõe um servidor HTTP opcional em 127.0.0.1:4477. Ele aceita notificações transitórias, live activities, controle do espelho e perguntas interativas. O servidor escuta somente loopback. As rotas legadas, incluindo /ask, permanecem sem autenticação por compatibilidade. Solicitações de agentes usam um token efêmero de sessão, gravado com modo 0600 (pasta 0700) em ~/Library/Application Support/Knobler/agent-request-token. Cada abertura do app gera um token novo e o grava quando a porta liga de fato — enquanto ela estiver com outro processo, o arquivo continua com o token de quem a tem. Só roda uma instância por vez (a mais nova encerra a anterior), então o arquivo sempre corresponde ao processo que está escutando.

Ligue em Ajustes → Notch → API local. Desligar a opção fecha o listener e remove activities e perguntas pendentes. Se a porta estiver ocupada quando a API sobe, ela tenta de novo sozinha — depois de 1 s, 2 s, 4 s… até uma vez por minuto — até ligar ou até a opção ser desligada.

Segurança: requisições de navegador

Escutar só no loopback não impede que uma página aberta no navegador chame a API. Por isso o servidor recusa com 403 as requisições que só um navegador faria:

curl, scripts e hooks não mandam esses headers e continuam funcionando sem mudança.

Ferramentas rápidas

# notificação
curl -X POST http://127.0.0.1:4477/notify \
  -H 'Content-Type: application/json' \
  -d '{"title":"Deploy finalizado","body":"em produção","app":"Terminal"}'

# live activity determinada; progress aceita 0–1 ou 0–100
curl -X POST http://127.0.0.1:4477/activity \
  -d '{"id":"deploy","title":"Deploy","detail":"rsync","progress":40}'

# encerrar activity
curl -X POST http://127.0.0.1:4477/activity \
  -d '{"id":"deploy","done":true}'

CLI incluído:

tools/knobler notify "Título" ["corpo"] ["app"]
tools/knobler activity <id> <0-100|-> "Título" ["detalhe"]
tools/knobler done <id>
tools/knobler ask "Pergunta?" "Opção A" "Opção B"
tools/knobler agent-request publish '{"id":"perm-1","agent":"claude","kind":"permission","title":"Permissão","summary":"Ler README","source":"terminal","actions":[{"action":"allow"},{"action":"deny"}]}'
tools/knobler agent-request wait perm-1
tools/knobler codex check     # o app-server instalado expõe as aprovações?
tools/knobler codex bridge    # app-server com as aprovações espelhadas no NOB

Referência dos endpoints

POST /notify

Publica um card transitório. title é obrigatório e não pode ser vazio.

{
  "title": "Deploy finalizado",
  "body": "em produção",
  "app": "Terminal",
  "supacodeWorktree": "/projetos/app",
  "supacodeTab": "deploy"
}

supacodeWorktree e supacodeTab são opcionais e permitem focar uma sessão do Supacode quando o card for clicado. Sucesso retorna {"ok":true}; JSON inválido ou sem título retorna 400.

POST /activity

Cria ou atualiza uma activity por id. Se id for omitido, usa default.

{
  "id": "deploy",
  "title": "Deploy",
  "detail": "rsync",
  "progress": 0.4
}

progress é opcional e pode estar em 0…1 ou 0…100; valores são limitados ao intervalo válido. Para atividade indeterminada, omita o campo ou use null. Para remover:

{"id":"deploy","done":true}

Uma activity expira após 30 minutos sem atualização. A activity mais recentemente atualizada é a exibida.

POST /keyboard/lock · POST /keyboard/unlock

Bloqueia o teclado inteiro (teclas, modificadores, mídia) pra limpeza; o notch mostra "Teclado bloqueado — clique para destravar". Sem corpo. Não liga sem Acessibilidade (abre Ajustes › Permissões) nem com campo de senha focado (avisa no notch). O estado é só em memória: sair do app libera o teclado.

curl -X POST http://127.0.0.1:4477/keyboard/lock

POST /dictation/toggle

Liga ou desliga a gravação do ditado, o mesmo que segurar e soltar a ⌥ direita. A primeira chamada começa a gravar; a segunda para e transcreve. Sem corpo. Respeita o toggle de ditado em Ajustes: desligado, não começa a gravar. Como não instala o monitor de teclas, digitar durante a gravação não cancela.

curl -X POST http://127.0.0.1:4477/dictation/toggle

POST /mirror (plugin: espelho)

Liga o espelho no notch do monitor sob o ponteiro ou desliga o espelho em todos os monitores. Com o Espelho desinstalado a rota responde 404 {"ok":false,"error":"plugin não instalado","plugin":"espelho"} — a marca (plugin: X) no título é a fronteira entre rota estável e rota de peça.

{"on":true}
{"on":false}

Sem corpo, on assume true.

POST /ask

Cria uma pergunta interativa. O formato é compatível com AskUserQuestion:

{
  "id": "ask-123",
  "source": "knobler",
  "questions": [
    {
      "question": "Continuar?",
      "header": "Deploy",
      "multiSelect": false,
      "options": [
        {"label":"Sim","description":"Continuar o deploy"},
        {"label":"Não","description":"Parar agora"}
      ]
    }
  ]
}

id e questions não vazios são obrigatórios. Cada pergunta precisa de pelo menos uma opção com label. source é opcional e aparece como contexto no card. O resultado é mostrado no notch e consultado pelo caller em GET /ask/<id>, de preferência em long-poll.

GET /ask/<id>

Retorna o estado da pergunta:

{"answered":false}

Resposta concluída:

{
  "answered": true,
  "answers": {
    "Continuar?": {"labels":["Sim"]}
  }
}

Resposta com texto livre usa text; esse texto vence os labels da mesma pergunta. A resposta é consumida na primeira leitura bem-sucedida. Se o card for cancelado:

{"cancelled":true}

Pergunta desconhecida retorna 404. Perguntas pendentes expiram após 15 minutos.

Long-poll (X-Knobler-Wait)

GET /ask/<id> e GET /agent-requests/<id> aceitam o header X-Knobler-Wait: <segundos>. Com ele, se o estado ainda está pendente, o servidor segura a conexão e responde quando a pergunta ou a solicitação fica final (respondida, cancelada, resolvida, dispensada ou expirada) ou quando o prazo vence, o que vier primeiro. O JSON é o mesmo de um GET comum: prazo vencido devolve {"answered":false} ou {"state":"pending"}, e o estado final continua sendo lido uma única vez.

Por que existe: cada GET abre uma conexão TCP, e o Network.framework grava umas 20 linhas por conexão no log do sistema. Esperar um card com polling a cada 0,3 s enchia o log; com long-poll é uma conexão a cada 25 s.

É header, e não query string, porque o app sem suporte (0.36.0 e anteriores) ignora o header e responde na hora. O cliente mantém o laço de sempre — GET com o header e, se ainda pendente, sleep 0.3 — e funciona com as duas versões. O timeout do cliente precisa cobrir a espera, com folga.

Timeout do cliente não quer dizer API fora. O prazo do servidor corre no relógio que para quando o Mac dorme; o -m do curl (e o AbortSignal.timeout do Node) conta o sono. Um Mac que dorme mais de 5 s no meio da espera estoura o cliente com a pergunta ainda pendente. Trate o timeout (curl sai com 28) com uma leitura sem espera: se ela responde, siga o laço; se não, o app parou de verdade.

while :; do
  rc=0
  state="$(curl -sf -m 30 -H 'X-Knobler-Wait: 25' http://127.0.0.1:4477/ask/ask-123)" || rc=$?
  # 28 = timeout: pode ser só o Mac que dormiu
  [ "$rc" -eq 28 ] && { rc=0; state="$(curl -sf -m 2 http://127.0.0.1:4477/ask/ask-123)" || rc=$?; }
  [ "$rc" -eq 0 ] || break
  case "$state" in *'"answered":true'* | *'"cancelled":true'*) echo "$state"; break ;; esac
  sleep 0.3
done

O CLI (knobler ask, knobler agent-request wait), os hooks do Claude e a ponte do Codex já esperam assim.

POST /ask/<id>/cancel

Cancela uma pergunta pendente. A operação é idempotente e retorna {"ok":true} mesmo quando a pergunta já terminou.

Solicitações de agentes autenticadas

Todas as rotas em /agent-requests exigem Authorization: Bearer <token>. O token muda a cada inicialização do app; use o CLI incluído em vez de copiá-lo para histórico de shell.

POST /agent-requests publica uma solicitação. Campos obrigatórios: id (ASCII seguro para URL), agent (claude ou codex), kind (question ou permission), title, summary, source (terminal, cli ou ide) e entre uma e oito actions. As ações são allow, allowForSession, deny, cancel, ou option/text com value.

{
  "id": "permission-42",
  "agent": "claude",
  "kind": "permission",
  "title": "Ler arquivo",
  "summary": "README.md",
  "source": "terminal",
  "actions": [{"action":"allow"}, {"action":"deny"}]
}

GET /agent-requests/<id> retorna {"state":"pending"} enquanto aguarda (aceita long-poll). Depois retorna uma única vez o estado final e result; a segunda leitura é 404. A ação em result vem no mesmo formato das actions — um objeto, não uma string:

{"id":"permission-42","state":"resolved","result":{"action":{"action":"allow"},"responder":"nob","state":"resolved"}}

POST /agent-requests/<id>/resolve recebe uma ação nesse formato e aceita apenas uma ação oferecida. POST /agent-requests/<id>/dismiss cancela. Resoluções repetidas são no-op: a primeira ação válida vence.

Claude PermissionRequest

O hook do Claude envia tool_name, tool_input, permission_suggestions e session_id ao endpoint como dados, sem executar o conteúdo recebido. allow autoriza apenas a operação atual. allowForSession só está disponível quando Claude forneceu uma sugestão de allow; o hook muda o destino dessas regras para session, portanto não escreve configurações persistentes. Em falha ou timeout da API, ele sai com sucesso e sem JSON para manter o prompt nativo do Claude.

Aprovações do Codex

A ponte tools/codex-agent-bridge.mjs traduz os pedidos de aprovação do app-server do Codex para o mesmo endpoint: allow/allowForSession viram accept/acceptForSession, deny vira decline e cancel interrompe o turno. Emendas de execpolicy e de política de rede não viram botão, porque são regras persistentes. Sem token, sem API ou sem decisão dentro do prazo, a ponte não responde e o Codex mostra a aprovação nativa. Detalhes em agent-requests.md.

GET /status

Retorna diagnóstico do app. O schema é deliberadamente extensível; campos atuais incluem notches, player, visualizerTapped, dictation, ask, agentRequests, micInUse, silenciando, lanMessaging, desempenho e plugins — este último é a lista de ids das peças instaladas (ver plugins.md), pra um script perguntar uma vez em vez de descobrir batendo em rota; campo de peça desligada simplesmente não aparece. silenciando é true quando a notificação que chegar agora vai direto pro histórico em vez de virar card (ver notifications.md). Cada entrada de notches traz também focus: o identificador da seção que o card aberto está mostrando (musica, atividade, pomodoro, shelf, espelho, mensagens, historico, nota, link, anotacao), ou string vazia quando não há seção em foco. A anotação de tela reporta em annotation: axTrusted, tapExists, tapEnabled, isActive, tool, background e lineWidth. O espelho reporta cameraAuth, cameraDevice, mirrorSessionRunning, mirrorUseCount e mirrorFailed — este último é true quando abrir o dispositivo de vídeo falhou. ask e agentRequests trazem pending e waiting — este último conta as conexões em long-poll seguradas agora. desempenho é a última amostra do registro de desempenho (tirada no lançamento e a cada 5 min, nunca mais velha que isso): data, versao, pid, uptime_s, footprint_mb, residente_mb, cpu_s, cpu_pct, threads, notches, displays e janelas — os campos e o histórico de 7 dias estão em troubleshooting.md.

curl -sS http://127.0.0.1:4477/status | jq .
curl -sS http://127.0.0.1:4477/status | jq .desempenho

Use esse endpoint para diagnóstico local, não como contrato de persistência.

Erros e limites

Para problemas, veja troubleshooting.md. Para o fluxo Ask e o ownership do estado, veja architecture.md.