Entrada de voz e Web Push

Ambos os recursos vêm desativados por padrão. Você pode ativar um botão de microfone no editor e notificações do navegador que disparam quando um agente estiver aguardando entrada.

Entrada de voz (opcional)

Um botão de microfone no editor e um chave de viva-voz em Configurações → Voz. Toque no botão, fale, e a transcrição vai para a caixa de mensagem para você ler e enviar. Com o modo viva-voz ativo, ela é enviada para você: pelo mesmo caminho protegido de resposta que uma mensagem digitada usa, nunca desviando dele. O microfone é o botão redondo no fim da linha enquanto a caixa estiver vazia; o primeiro caractere digitado o transforma de volta em Enviar. Você dita uma mensagem ou digita uma, havendo assim uma única ação primária em vez de duas disputando a largura do campo.

Enquanto você fala, um gravador cobre todo o compositor, a barra e a caixa, sem adicionar altura, para que a tela acima nunca se mova. OK fica onde o microfone estava e finaliza o áudio. O bin na outra ponta o descarta e ainda cancela enquanto o áudio é transcrito. Depois que você fala, dois segundos de silêncio finalizam o áudio para você; um anel se fecha ao redor de OK para mostrar isso, e falar novamente reinicia a contagem. Antes da primeira palavra, nada o finaliza sozinho.

Não existe até que você configure um provedor. Execute collie stt setup ou configure o Whistle (abaixo). Nenhum botão é desenhado, nenhum áudio sai do celular, nenhuma credencial é mantida, nenhum processo filho é executado. Ausente, não desativado. Quatro provedores:

A configuração é feita via CLI pelo mesmo motivo de pareamento: esta superfície aceita uma credencial, portanto deve ficar no teclado do host. Não há formulário web para chave, endpoint ou comando. Duas exceções não exigem nenhum desses. O Whistle não armazena credenciais, não executa comandos escolhidos por você e não envia áudio para fora do host; portanto, um dispositivo com acesso de escrita pode configurá-lo em Configurações (por que). E em Configurações → Voz → Fala no host, um dispositivo com acesso de escrita pode alternar o host entre o Whistle, a assinatura do ChatGPT (o provedor codex) e Desativado. O ChatGPT só é ativado após o mesmo consentimento exibido pelo terminal e um toque em Aceito (abaixo). Um provedor configurado no terminal com chave ou comando, ou indicado pelo seu ambiente, é exibido ali e nunca alterado pelo aplicativo. Para esses dois, a página mostra os comandos para executar no host, com Copiar e Verificar novamente, e nenhum formulário.

$ bin/collie stt setup
Which speech-to-text provider?
  openai-compatible  any endpoint that speaks POST /audio/transcriptions —
                     the public OpenAI API, or a local whisper.cpp / parakeet.cpp
                     server, which is the zero-egress choice and the one to prefer.
  codex              borrow your own `codex` sign-in. No new key, no new account —
                     and a private endpoint that may break without notice.
  local-cli          run a transcription command already on this machine, such as
                     whisper-cli or muesli-cli. Its stdout is the transcript.
provider [openai-compatible]:
The API base, INCLUDING its version prefix — the provider appends /audio/transcriptions.
  local  http://127.0.0.1:8080/v1     (whisper.cpp / parakeet.cpp — nothing leaves the host)
  cloud  https://api.openai.com/v1    (room audio leaves this machine)
base URL: http://127.0.0.1:8080/v1
The model the endpoint understands. Empty takes Collie's default, gpt-transcribe.
model [gpt-transcribe]: whisper-1
API key [none]:
The language you speak, as a two-letter ISO-639-1 code — en, de, tr, ja.
LEAVE IT EMPTY to let the model detect it, which is what you want if you mix languages in one
sentence. Name one only if short clips keep coming back in a language you did not speak: a few
seconds of accented audio is too little for the model to detect from, and it guesses.
spoken language [auto-detect]: en
✓ speech-to-text configured — /home/you/.local/state/collie/stt.json (owner-only)
  Live immediately — no restart needed. The bridge re-reads this file per request.
  Check it end to end with `collie stt test`.

Cada pergunta acima tem uma flag (--provider · --url · --model · --key · --lang), portanto uma execução de provisionamento não precisa de terminal. Deixar a chave em branco é um modo suportado — um endpoint sem chave é chamado sem nenhum cabeçalho Authorization, em vez de enviar um cabeçalho vazio.

Vale a pena definir o idioma falado apenas para uma falha. Se deixado em branco — o padrão —, o próprio modelo detecta o idioma, que é o que alguém misturando dois idiomas em uma frase precisa. Defina-o se clipes curto continuarem retornando em um idioma que você não falou: poucos segundos de áudio com sotaque são insuficientes para detecção, e o modelo tenta adivinhar. Um código de duas letras ou uma tag regional que o Collie ajusta para você (en-GB → en). Funciona apenas no provedor openai-compatible; o endpoint codex não aceita idioma, e o collie stt status informa isso em vez de deixar você pensar o contrário.

Uma gravação longa ganha um prazo longo. O tempo limite do navegador para um clipe depende do tamanho desse clipe, não de um número fixo — ele presume um uplink estável de 256 kb/s e adiciona o prazo do próprio provedor do bridge por cima, de modo que o máximo de 8 MiB tem direito a pouco menos de seis minutos. Um clipe que o Collie aceitou gravar é um clipe que ele está disposto a esperar. Enquanto o upload está em andamento, o Collie para de consultar e para de escalar o banner de conexão: o seu próprio áudio saturando o uplink de um celular não é uma interrupção, e não deve ser reportado como tal.

Uma gravação para aos cinco minutos. Um host executando o Whistle aceita quatro, porque o celular envia um arquivo WAV, que tem cerca de quatro vezes o tamanho do áudio comprimido. O gravador mostra o limite aplicável.

Funcionou? stt test envia um quinto de segundo de silêncio gerado através do provedor real, uma vez para cada container que um celular consegue gravar:

$ bin/collie stt test
provider: openai-compatible (http://127.0.0.1:8080/v1, model whisper-1, language en)
sending:  0.2 s of generated silence as audio/wav (the setup probe) … ✓ 214 ms
  transcript: (empty) — expected from silence, and the empty answer still proves the pipeline.
sending:  0.2 s of generated silence as audio/webm;codecs=opus (Chrome, Android, Firefox) … ✓ 198 ms
sending:  0.2 s of generated silence as audio/mp4 (Safari, iOS) … ✓ 190 ms

Com o Whistle no host, stt test envia um áudio, um WAV de 16 kHz, e informa que webm e mp4 são ignorados, porque o celular converte a gravação em WAV de 16 kHz antes de enviar a esse provedor.

Uma transcrição vazia é uma aprovação — o silêncio é transcrito como nada, e a comunicação de ida e volta era o que estava sendo testado. Se falhar, o erro indica o tipo (autenticação, endpoint, formato de resposta). Em seguida, recarregue o Collie no celular: um microfone fica ao lado da caixa de mensagem. collie stt status mostra o que está configurado e de onde veio cada configuração (o arquivo ou uma variável de ambiente que tem precedência sobre ele); collie stt off remove stt.json e o botão desaparece novamente, sem necessidade de reiniciar em nenhum dos casos.

Whistle: conversão de fala em texto no seu celular ou no seu host

Whistle é um modelo de fala compacto da Cactus Compute. O arquivo tem 16,9 MB e a licença é Apache-2.0. Ele reconhece inglês, alemão, francês, espanhol, italiano, holandês e polonês, identificando o idioma por conta própria. Não requer conta, chave nem programa adicional. O Collie inclui o motor que o executa, funcionando no Linux, macOS, Windows e NixOS.

O Whistle pode rodar em dois locais. Você escolhe por celular.

Ambos os motores leem o mesmo modelo. O host mantém uma cópia. Um telefone que queira executar o Whistle localmente copia dele do host, nunca da internet. Um trecho leva cerca de um segundo em um telefone recente.

Configure a partir de Configurações. Você precisa de um dispositivo com acesso de gravação (um dispositivo que tenha emparelhado). Um dispositivo somente leitura vê "A device with write access can set this up." e não pode iniciar o download.

Configurações → Voz é uma página com duas páginas abaixo dela:

• —
  Voice coloca o que está em uso primeiro. O card superior é intitulado com o que está configurado: o comando que seu host executa, como whisper-cli com Modelo ggml-base.bin e Seu próprio comando no seu host abaixo dele; o modelo de um serviço de voz, como whisper-large-v3 com Um serviço de voz em api.groq.com; Whistle da Cactus Compute com Modelo ca52876 e Neste telefone ou No seu host; ou Assinatura do ChatGPT (OpenAI) com Pelo Codex no seu host. Se o comando for o wrapper whistle-stt antigo, o card informa isso e oferece Mudar para o Whistle integrado, que abre a voz do host. Em seguida, o status, que informa em que ele se apoia, por exemplo "Pronto. O Whistle ca52876 está neste telefone." ou "Não pronto. A sessão do Codex está encerrada no seu host.", para onde o Áudio vai, e como foi Configurar (a partir de Configurações, por qual dispositivo e quando, ou em um terminal no host). Abaixo do card fica a chave de viva-voz. Todo o resto fica atrás de uma linha, Alterar o funcionamento da voz. Enquanto a voz funciona, essa linha fica fechada a cada visita. Enquanto não funciona (nada configurado, um telefone pausado, uma opção do host que não responde), ela fica aberta, e o card superior traz a única ação: Configurar voz neste telefone, Restaurar ou Corrigir. Aberta, mostra a própria escolha deste telefone, Neste telefone (marcada como Recomendado) ou No seu host (o computador que executa seus agentes), que é mantida por dispositivo. A escolha em uso tem uma borda em negrito, um tom de cor e um selo de Em uso, e alternar entre as duas não move nada na página. Depois, uma linha para o que o host usa, uma linha que abre todas as cinco opções, e uma linha para o modelo. Cada escolha tem um botão de informações que lista cinco fatos sobre ela: para onde o áudio vai, se funciona offline, quanto custa, qual configuração exige, e quão rápida é. Um toque no botão de informações não seleciona nada.
• —
  Voz do host lista as cinco opções do host. O Whistle e seu próprio comando mantêm o áudio em suas máquinas. Um serviço de voz e a assinatura do ChatGPT o enviam para fora do seu host. A opção Desligado fica isolada abaixo deles. Uma alteração aqui se aplica a todos os dispositivos pareados com o host. Uma escolha que envie áudio para mais longe do que a que ela substitui pede confirmação primeiro; um retorno é aplicado com o toque. Cada opção tem Como configurar: passos numerados, os comandos para copiar, e os botões do próprio aplicativo onde ele puder agir. O próximo passo a ser realizado está marcado como Avançar. Ele fica aberto sozinho apenas para a opção em uso quando ela não funciona. A opção em uso também informa o que está configurado, por exemplo "Configurado: whisper-cli, modelo ggml-base.bin".
• —
  Modelo Whistle cita o criador, Cactus Compute, a licença, e traz links para a página do modelo no Hugging Face. Mostra a cópia no host e a cópia neste telefone, cada uma com seu próprio estado.

Para configurar o Whistle:

1. 01
   Em um celular onde a voz ainda não funciona, toque em Configurar voz neste telefone no card superior em Voice. Um toque faz todo o processo: o host baixa o modelo se não o tiver, este celular o copia do host e Neste telefone é selecionado. Uma barra mostra o progresso e indica qual etapa está em execução, "Baixando para o seu host…" ou "Copiando para este celular…". Se uma etapa falhar, o processo para ali, informa o motivo e oferece Tentar novamente. Um dispositivo somente leitura pode copiar, porque copiar é uma leitura, mas não pode solicitar o download ao host. As mesmas duas etapas também estão em Alterar o funcionamento da voz: Configurar (16.9 MB) em um celular sem cópia, ou Copiar para este celular quando o host já possui o modelo.
2. 02
   Ou abra Modelo Whistle e toque em Baixar para o host (16.9 MB). Uma barra mostra o progresso. Se falhar, a página informa o motivo. Toque em Tentar novamente. Quando o modelo estiver disponível, a página lista sua versão (os primeiros sete caracteres da revisão do Hugging Face, um link para essa revisão) e seu tamanho. Detalhes mostra um checksum curto e quando o host fez o download.
3. 03
   Para ditado através do host, abra Voz do host e escolha Whistle no seu host, depois Alterar para todos os dispositivos. Ou abra Como configurar abaixo dele e toque em Usar no host. Se você configurar outro provedor no terminal, com uma chave ou um comando, a página o exibe e não oferece escolha. As etapas do Whistle então começam com collie stt off no host, depois collie stt whistle --host.
4. 04
   Na cópia deste celular, Modelo Whistle informa a versão e oferece Remover deste celular. Também informa se o navegador aceitou manter a cópia ("Mantido") ou se pode apagá-la quando o espaço estiver baixo. Se o host receber mais tarde um modelo mais novo, a cópia informa isso e oferece Update.
5. 05
   Em Voice, abra Alterar o funcionamento da voz e escolha Neste telefone ou No seu host. Neste telefone fica desativado até que o celular tenha uma cópia. No seu host fica desativado enquanto o host não tiver nenhuma opção de voz. A linha abaixo da escolha informa o que o host usa.
6. 06
   Para remover o modelo do host, toque em Remover do host em Modelo Whistle e confirme. Se o Whistle era o mecanismo do host, o reconhecimento de voz no host é interrompido até você baixá-lo novamente.

Quem alterou. Quando um dispositivo pareado altera a opção do host em Settings, o host grava o nome desse dispositivo e a hora. Voice e Voz do host exibem então "Última alteração por Pixel 8", com a hora. Uma alteração no terminal limpa isso.

Ou configure no terminal.

$ bin/collie stt whistle                 # fetch the model once
$ bin/collie stt whistle --host          # also make Whistle this host's engine
$ bin/collie stt whistle --from <path>   # use a copy you already have, same hash check
$ bin/collie stt whistle --remove        # remove the model, and the host engine if it is Whistle
$ bin/collie stt status                  # shows the model line

--host pergunta antes de substituir um provedor que você configurou intencionalmente. --yes responde a essa pergunta para uma execução sem terminal. A pergunta vem antes do download, portanto uma execução recusada não busca nada. --remove não altera um provedor de outro tipo. collie stt off remove o provedor e informa que o modelo permanece. collie doctor avisa quando o modelo no host não for o aceito por esta versão. O mecanismo fica ativo imediatamente, sem reiniciar. Verifique com collie stt test.

O que é baixado e de onde. O host busca whistle.cact de um endereço fixo do Hugging Face, segue o redirecionamento para o CDN correspondente (no máximo cinco, apenas HTTPS e nunca para um endereço local ou privado) e mantém o arquivo somente quando o sha256 for igual ao hash incluído nesta versão. Uma divergência exclui o arquivo e relata ambos os hashes. O download é limitado a 32 MiB e tem um tempo limite de 10 minutos. O arquivo fica na pasta whistle da pasta de estado. O código do mecanismo (cerca de 1 MB) faz parte de cada versão do Collie e vem dos próprios arquivos do Collie.

Nada é baixado por conta própria. Não na instalação, não em uma atualização, não ao escolher um mecanismo. O modelo chega quando alguém toca em Baixar para o host, Configurar ou executa collie stt whistle. Um celular o copia do host quando o proprietário toca em Configurar, Copiar para este celular ou Restaurar, e de nenhum outro lugar. O host envia o modelo para no máximo dois celulares simultaneamente. Um terceiro recebe "tente novamente em um momento".

Limites. O mecanismo do host aceita gravações de até 4 minutos, pois um WAV tem cerca de quatro vezes o tamanho do clipe compactado e o limite de upload permanece em 8 MiB. O gravador exibe esse limite. O mecanismo do celular aceita até 5 minutos. O processo filho do host tem um tempo limite de metade da duração do clipe, no mínimo 60 segundos e no máximo 3 minutos, e no máximo dois clipes rodam no host ao mesmo tempo. Um celular precisa de espaço livre para o modelo (solicita o dobro do tamanho do arquivo) e de uma conexão segura (HTTPS, como tailscale serve fornece).

Quando o celular não consegue processar. Se Neste telefone falhar em um clipe, a tela de voz informa o motivo e oferece Enviar para o host, apenas enquanto o host tiver um provedor de voz funcional. O clipe permanece na memória, no estado de falha, até você tocar em Enviar para o host ou descartá-lo. O Collie nunca o envia sozinho, porque você escolheu um mecanismo cujo objetivo é manter o áudio localmente. Duas falhas do mecanismo em uma mesma sessão desativam Neste telefone até você recarregar o app.

Quando a cópia do telefone não existir mais. O navegador pode limpar a cópia para liberar espaço. A opção permanece neste telefone e o ditado é pausado: Voice informa "Ditado pausado" e oferece Restaurar, que copia o modelo do host novamente. O microfone continua gravando e o clipe permanece no telefone com Enviar para o host, conforme descrito acima. O Collie não muda para o host por conta própria. Para usar o host, escolha No seu host.

Navegadores. Este telefone precisa de um navegador que aplique uma política de segurança própria ao worker de voz. O Chrome no Android foi testado. O WebKit foi testado em uma compilação do WebKit. O Safari no iPhone ainda não foi verificado em um dispositivo. O navegador que não puder executá-lo mostra Neste telefone como desativado com o motivo, e No seu host continua disponível.

Se você usou o wrapper antigo. Versões anteriores desta página mostravam um wrapper de local-cli em torno de um executor nativo, ffmpeg e jq. Essa configuração foi descontinuada, mas nada altera uma configuração existente, e ela continua funcionando. Para migrar para o motor integrado, execute bin/collie stt whistle --host --yes ou execute collie stt off primeiro e depois bin/collie stt whistle --host. Você também pode manter o wrapper. O arquivo de modelo dele não é reutilizado por conta própria. Passe-o com --from <path> para ignorar o download.

A parte de segurança deste motor, e por que a configuração a partir de Configurações é permitida, está em Segurança e ADR 0096.

O suporte a contêineres depende do provedor

O telefone nunca grava em WAV. Ele grava em Opus dentro de um contêiner WebM no Chrome, Android e Firefox, ou em AAC dentro de um contêiner MP4 no Safari e iOS, e envia esses bytes como estão. Um provedor que transcreve WAV ainda pode responder 400 para ambos, e cada ditado falhará com "refused" enquanto stt test parecer normal. É por isso que stt test envia os três clipes: a recusa é detectada na configuração, não no telefone.

Um caso, verificado em 2026-09-01 no POST /v1/audio/transcriptions do OpenRouter:

A solução de contorno é o modelo, não a chave: aponte a mesma chave do OpenRouter para openai/whisper-large-v3-turbo, que aceita todos os quatro.

bin/collie stt setup --provider openai-compatible \
  --url https://openrouter.ai/api/v1 --model openai/whisper-large-v3-turbo --key <key>

Uma transcrição recusada agora informa o status do upstream e o contêiner no qual foi enviada, para que o erro no telefone mostre qual formato o provedor rejeitou. (#148, obrigado @drewbitt)

Egress zero: aponte para o seu próprio engine

O motivo pelo qual openai-compatible é o provedor a ser escolhido: forneça uma URL base local e nenhum áudio ambiente sai do host. Dois engines fornecem um endpoint de transcrição compatível com OpenAI: o server embutido do whisper.cpp e o mudler/parakeet.cpp (MIT). Compile ou instale qualquer um deles seguindo suas próprias instruções, execute-o no loopback e aponte --url para ele:

bin/collie stt setup --provider openai-compatible --url http://127.0.0.1:8080/v1

Essa é toda a integração: o Collie não tem preferência sobre qual engine responde.

O Voxtral da Mistral não precisa de suporte próprio, e nenhum outro serviço que siga este contrato precisa: esse é o objetivo do ponto de integração. O vLLM fornece os modelos Voxtral de pesos abertos em /v1/audio/transcriptions, portanto, uma instância local usa a mesma --url que qualquer outro engine. Os modelos hospedados usam a mesma requisição na base da própria Mistral:

bin/collie stt setup --provider openai-compatible \
  --url https://api.mistral.ai/v1 --model voxtral-mini-latest --key <key> --lang en

O Voxtral Mini Transcribe cobre 13 idiomas e aceita o mesmo campo ISO-639-1 language que o Collie já envia. Teste com collie stt test antes de confiar: "compatível com OpenAI" é uma afirmação que cada endpoint faz por conta própria, e esse verbo existe para verificá-la.

O provedor codex: o que você está aceitando

collie stt setup --provider codex exibe um bloco de consentimento e para até você digitar yes, porque a verdade direta é esta: as gravações vão para um endpoint do ChatGPT não documentado e sem suporte autorizado pelo login do seu, portanto a sua conta do ChatGPT assume o risco de rate-limit e banimento, e isso pode parar de funcionar sem aviso prévio.

O Collie faz requisições a esse endpoint sob seu próprio nome primeiro. Apenas se a identidade honesta for recusada ele recorre aos cabeçalhos da CLI do Codex, e esse fallback é gravado na configuração, em uma palavra que collie stt status lê de volta para você. O Collie nunca lê nem armazena ~/.codex/auth.json; o binário em que você já confia continua sendo o único a manipulá-lo.

Você também pode escolher isso em Configurações. Abra Configurações → Voz → Fala no host em um dispositivo com acesso de gravação. A página mostra o que o host usa no momento. Para a assinatura do ChatGPT, ela também mostra a identidade registrada: honest, ou codex-cli quando o fallback foi necessário. A linha Assinatura do ChatGPT fica aberta apenas quando o codex está instalado no host e conectado com o ChatGPT. O Collie consulta codex login status para verificar. Caso contrário, a linha informa o motivo em uma frase, e Como configurar marca a próxima etapa: instale o Codex no host, conecte-se com codex login e toque em Usar assinatura do ChatGPT. Toque na linha para exibir uma folha com o mesmo termo de consentimento, palavra por palavra, abaixo de uma linha informando que a alteração se aplica a todos os dispositivos emparelhados com o host. Nada é enviado para o host até que você toque em Aceito. Em seguida, o host executa a mesma sondagem de collie stt setup, priorizando a identidade autêntica, e grava a mesma configuração. Se a sondagem falhar, nada será gravado e a folha informará o motivo. Desativado na mesma página remove o provedor. O terminal continua funcionando da mesma forma.

Execute seu próprio comando: o provedor local-cli

local-cli executa um comando de transcrição que você já tem, uma vez por gravação, sem nenhum servidor HTTP intermediário:

bin/collie stt setup --provider local-cli \
  --command /Applications/Muesli.app/Contents/MacOS/muesli-cli --args transcribe
bin/collie stt test

O Collie grava a gravação em um arquivo temporário privado e executa <command> [args…] <file>. O caminho do arquivo é sempre o último argumento. O stdout do comando, sem espaços extras nas pontas, é a transcrição.

Um nome simples é resolvido quando você executa setup, e o caminho completo é salvo. O serviço roda com um PATH curto, portanto um nome que o seu shell encontra pode não ser resolvido lá. Um caminho relativo como ./whisper-cli é recusado.

--args aceita palavras separadas por espaços. Nenhum shell as interpreta, portanto as aspas são mantidas como digitadas. Um argumento com espaço precisa do formato JSON:

bin/collie stt setup --provider local-cli --command whisper-cli \
  --args '["-m", "/srv/my models/ggml-base.bin", "-nt"]'

O que o comando deve fazer:

• —
  Ser um arquivo comum que o seu usuário possa executar. Um symlink para um é aceito, porque o Collie o segue. collie stt setup recusa qualquer outra coisa, e collie stt status informa o erro.
• —
  Sair com status 0 e imprimir a transcrição no stdout. Qualquer outra coisa falha o ditado.
• —
  Terminar em até 60 segundos. O Collie então encerra o comando e cada processo iniciado por ele com SIGKILL.
• —
  Imprimir no máximo 256 KiB no stdout. O Collie encerra o comando assim que ele imprimir mais.
• —
  Não deixar nada em execução. Quando o comando sai, o Collie encerra qualquer processo iniciado por ele que ainda esteja ativo. Um utilitário auxiliar que precisa continuar ativo deve iniciar sua própria sessão, por exemplo com setsid.

No Windows, o Collie encerra toda a árvore de processos do comando nos mesmos momentos e, após uma saída limpa, encerra qualquer processo iniciado pelo comando que ainda esteja rodando. Resta um caso: um processo iniciado por um auxiliar que já saiu pode sobreviver ao comando.

No máximo dois ditados executam o comando ao mesmo tempo. Um terceiro recebe a mesma resposta de "ocupado" que o telefone já conhece, e o Collie não inicia nada para ele.

Um stdout vazio é uma falha no telefone, porque não há nada para colocar no campo. collie stt test conta isso como sucesso, já que seus clipes são silêncio.

Nota. O comando roda com o próprio usuário da bridge, com as permissões desse usuário, uma vez por ditado. Ele não recebe shell, nem stdin, e nenhuma variável de ambiente COLLIE_*. Seu stderr nunca é lido, e o telefone nunca vê a linha de comando ou um caminho, apenas que o comando falhou e seu status de saída.

O arquivo temporário fica em uma pasta que apenas o seu usuário pode abrir, e o Collie a apaga após cada execução. Se a própria bridge foi encerrada no meio da execução, a próxima inicialização da bridge remove essas pastas quando tiverem uma hora de existência. Para onde o áudio vai em seguida depende do comando: um mecanismo local o mantém no host.

O motivo de tudo isso (por que foi recusado duas vezes, o que mudou e por que o ponto de integração funciona assim) está em ADR 0029.

Web Push (opcional)

Desativado por padrão. A configuração exige três etapas. A biblioteca de envio (web-push) é incluída como dependência opcional durante a compilação:

collie push-keys     # 1. generate + write the VAPID keys
collie restart       # 2. Collie reads them at start
#                      3. on your phone: Settings → Alerts

O comando push-keys gera o par de chaves e grava COLLIE_VAPID_PUBLIC e COLLIE_VAPID_PRIVATE com permissão de arquivo 600 no .env ativo, que é ~/.config/collie/.env em uma instalação binária ou no diretório de configuração de plugins do Herdr em uma instalação do Herdr.

Passe uma URI de contato como argumento para definir a claim subject da RFC 8292:

collie push-keys mailto:you@example.com

Em instalações gerenciadas pelo Herdr, ambas as etapas estão disponíveis como ações (herdr plugin action invoke push-keys --plugin herdr.collie e restart). As ações do Herdr não aceitam argumentos posicionais, portanto, definir um subject exige executar o comando diretamente no shell.

Detalhes de manipulação de chaves:

O comando se recusa a sobrescrever chaves existentes, a menos que você passe --force. A substituição de chaves invalida todas as assinaturas atuais, exigindo que cada dispositivo faça uma nova assinatura antes de poder receber notificações novamente. Informar um argumento de subject em uma configuração existente atualiza apenas o endereço de contato e preserva as chaves atuais.

Nota. Em versões do Herdr anteriores a 0.8.0, as ações permanecem fixadas no conjunto armazenado em cache durante a instalação inicial do plugin (ADR 0006). As ações push-keys e push-test não aparecerão até que você execute herdr plugin install. Em vez disso, execute bash scripts/collie-ctl.sh push-keys diretamente. O script wrapper passa o comando diretamente para o binário.

Teste o caminho de entrega em todos os dispositivos inscritos:

collie push-test                     # or: push-test "Title" "Body"

A entrega leva de um a dois segundos. Se o comando relatar que o push está desativado, reinicie o serviço para que ele carregue as chaves geradas. Se relatar que não há dispositivos inscritos, conclua a etapa 3 no navegador do celular.

O Web Push requer um contexto seguro (HTTPS). Isso é fornecido pelo tailscale serve (certificados MagicDNS) ou por um proxy reverso externo terminando TLS (Variante C). Configurações em HTTP simples (COLLIE_SERVE_MODE=http) não possuem um contexto seguro, e o navegador desativa os controles de assinatura em Settings.

O Collie envia notificações quando um agente entra no estado blocked ou done, colocando a mensagem do agente no corpo. Selecionar a notificação leva diretamente para esse agente na UI web.

Quais alertas o Collie envia

Cinco tipos, cada um com sua própria chave em Configurações → Alertas → Notificar quando.

Finished dispara quando um agente passa de working para idle, portanto um agente que você interrompe também conta como finalizado.

A carga da máquina não envia nada até você definir uma regra na página da máquina. A chave desativa todas as regras de uma só vez. Um alerta é enviado a cada vez que um valor sobe e se mantém alto, e um toque abre a visualização de Status dessa máquina. Consulte Máquinas.

Cada dispositivo exibe o título de um alerta em seu próprio idioma, e em inglês em um dispositivo que não abriu o Collie desde a atualização. O corpo permanece como a bridge escreveu.

Cada opção se aplica a toda a bridge. Um push é propagado para todos os dispositivos inscritos, portanto não há nada para configurar por dispositivo.

O aviso de cache também pode ser ativado para um painel por vez, a partir das configurações do próprio painel: abra o painel, toque em ⋮ e depois em Configurações do painel. Esses painéis são listados sob a opção global em Configurações, com um botão Remover em cada um.

Os dois estados se somam em vez de se substituírem. Um painel recebe aviso quando a opção global está ativada ou o painel está nessa lista; portanto, desativar a opção global não silencia um painel que você monitorou manualmente.

Um painel monitorado é alertado uma vez por ciclo ativo. A próxima requisição do agente adia o prazo, e somente então o mesmo painel pode alertar novamente. As horas de silêncio se aplicam: uma bridge em modo soneca não envia nada, e uma soneca que termina dentro da janela ainda alerta. Um painel que já está inativo nunca é alertado, o que inclui um que uma alternância do /model tornou inativo enquanto ainda restava tempo.

COLLIE_CACHE_WARN_SECONDS altera a janela, o padrão é 300 segundos (configure.md).

Nota. Este alerta precisa da leitura do cache de prompts, cobrindo apenas os painéis que exibem uma contagem regressiva de cache: o harness precisa manter uma transcrição que o Collie consiga ler, e o agente precisa ter feito pelo menos uma rodada. A janela em que um painel realmente emite aviso é o valor configurado em segundos ou a metade do tempo de vida do cache desse painel, o que for menor. Um cache de uma hora do Claude mantém a janela completa de 300 segundos. Já um cache de cinco minutos, como Codex, OpenCode, pi e omp, avisa cerca de dois minutos e meio antes de esfriar.

Assinaturas obsoletas podem se acumular com o tempo, pois reinstalações na tela inicial e redefinições do service worker criam novos endpoints sem retornar necessariamente um HTTP 410. O Collie atualiza o registro quando um dispositivo se registra novamente. Você pode visualizar e excluir os endpoints armazenados diretamente:

# one line per device: service, since, user agent, endpoint tail
bin/collie push list
bin/collie push forget <substring>   # or: push forget --all

Pushes de um durable agent

O card de pergunta de um durable agent pode enviar push para o seu telefone, e o Collie limita a quantidade de pushes que um durable agent pode fazer.

O push exibe "Permission needed in" seguido do nome que você deu ao painel. Ele nunca inclui o título atribuído pelo próprio durable agent à pergunta. Um durable agent pode escolher suas palavras: o título (máximo de 60 caracteres) segue o nome do seu painel após dois-pontos, e sua linha (máximo de 120 caracteres) forma o corpo. Essas palavras alteram o conteúdo da mensagem, nunca a frequência de envio.

O resumo diz "A durable agent on {host} is raising many asks", usando o nome da máquina no lugar de host. Em uma crew, ele cita o member. A opção Needs input e o adiamento também retêm o resumo. Um limite nunca oculta uma pergunta: toda pergunta aberta permanece no telefone.

O Collie envia o push de uma pergunta apenas uma vez. Ele memoriza cada uma por máquina, durable agent e chamada de ferramenta; assim, se um durable agent reiniciar e fizer a mesma pergunta, ela aparecerá no telefone sem gerar um segundo push. Uma pergunta é esquecida uma hora após ser concluída. Essa memória fica em durable-asks.json, na pasta de estado. Em uma crew, o lead aplica essas regras e mantém esse arquivo, enquanto o member não envia push para suas próprias perguntas (ADR 0100).