Referência do agente do Zas: ferramentas MCP e erros

Tudo que o servidor MCP zas-agent expõe, numa página só.


Pacote	`zas-agent` no npm
Nome no registro MCP	`io.github.soke1556/zas-agent`
Transporte	stdio
Runtime	Node.js 22 ou mais novo
Código	github.com/soke1556/zas-agent, MIT

Comandos

zas-agent [--profile <nome>]              serve as ferramentas MCP por stdio
zas-agent pair [--profile <nome>]         pareia este agente com uma conta do Zas
               [--kind claude_code|codex|other] [--host <nome>] [--no-open]
zas-agent telemetry [on|off]              diz o que esta máquina reporta, ou muda
zas-agent --version

Sem comando ele serve as ferramentas MCP, que é para isso que um harness o inicia.

Ferramentas

channel aceita o nome ou o id de um canal. Um nome precisa bater com exatamente um canal liberado. Com uma liberação só, todas as ferramentas que aceitam channel podem omitir, menos zas_list_items e zas_get_item, que sempre nomeiam o canal delas.

`zas_status`

Diz se a máquina está pareada e lista os canais para onde o agente pode mandar ou que ele pode ler. Também imprime a versão do pacote, o perfil e o estado da telemetria. Sem argumentos.

`zas_pair`

Pareia esta máquina com uma conta do Zas. A primeira chamada devolve uma URL para você abrir; uma chamada seguinte diz se você aprovou. Num perfil já pareado, a aprovação substitui o agente anterior.

Argumento	Tipo	Notas
`code`	string, opcional	O código que a página mostra quando o navegador não conseguiu alcançar a máquina.

`zas_send_file`

Manda um arquivo da máquina para um canal liberado. Devolve o id do item, ou um id de trabalho quando a subida passa de um minuto.

Argumento	Tipo	Notas
`path`	string, obrigatório	Caminho absoluto ou relativo do arquivo.
`channel`	string, opcional	Nome ou id. Opcional com uma liberação só.
`title`	string, opcional	Rótulo do item. Por padrão, o nome do arquivo.
`expires_in_days`	inteiro, opcional	Quantos dias inteiros o item vive, mínimo 1. Omitido, ele usa a vida normal da conta.

Um canal em modo Direto recusa esta ferramenta com direct_mode. Ali vai zas_send_direct.

Ela manda qualquer arquivo que o processo consiga ler, segredos incluídos. Veja Recomendações.

`zas_send_note`

Manda uma nota: texto simples, ou um trecho de código com a linguagem.

Argumento	Tipo	Notas
`text`	string, obrigatório	O corpo da nota.
`channel`	string, opcional	Nome ou id. Opcional com uma liberação só.
`title`	string, opcional	Rótulo. Por padrão, a primeira linha.
`lang`	string, opcional	Linguagem para o realce, por exemplo `ts` ou `py`.
`secret`	boolean, opcional	Cobre o corpo até quem recebe abrir.
`expires_in_days`	inteiro, opcional	Quantos dias inteiros o item vive, mínimo 1.

`expires_in_days`

As duas ferramentas de envio aceitam, e ele só encurta a vida de um item. Um pedido mais longo do que o plano dá é respondido com o número do plano em vez de recusado, então pedir 100 dias dá cinco. O piso é um dia inteiro, porque o anel conta dias inteiros. Vale a pena para saída que amanhã já está velha: um log de build, uma rodada de testes, o print de uma correção.

`zas_send_direct`

Manda um arquivo pelo Direto: uma transferência ao vivo, de aparelho para aparelho, para um canal liberado que está em modo Direto. Nada é guardado. Alguém precisa apertar Receber em outro aparelho dentro de dez minutos. A chamada espera um minuto e depois devolve um id de trabalho para consultar com zas_jobs.

Argumento	Tipo	Notas
`path`	string, obrigatório	Caminho absoluto ou relativo do arquivo.
`channel`	string, opcional	Nome ou id. Opcional com uma liberação só.

Um canal que não está em modo Direto recusa esta ferramenta com not_direct_mode.

`zas_receive_direct`

Recebe nesta máquina um arquivo mandado pelo Direto. Espera a oferta, pega e escreve o arquivo em disco. Só num canal em modo Direto, e só com uma liberação que inclua leitura, porque escreve na máquina.

Argumento	Tipo	Notas
`channel`	string, opcional	Nome ou id. Opcional com uma liberação só.
`dest`	string, opcional	Onde escrever o arquivo. Um diretório significa “dentro dele”. Por padrão, um diretório temporário novo.

Nunca sobrescreve um arquivo existente. Esperar uma oferta pode levar dez minutos, então a chamada devolve um id de trabalho depois de um minuto.

`zas_send_direct_fallback`

Quando um trabalho de zas_send_direct falhou em voo, entrega o mesmo arquivo pela via confiável. O Zas cifra o arquivo nesta máquina e guarda só essa cópia cifrada por até 24 horas; ela não usa nada do seu espaço, e o aparelho que já pegou a oferta pode baixar depois.

Argumento	Tipo	Notas
`job`	string, obrigatório	O id de trabalho que reportou o envio pelo Direto que falhou.

Isso deixa de ser Direto: os bytes cifrados passam pelo armazenamento. A descrição da ferramenta manda o modelo perguntar antes, porque a decisão é sua.

`zas_receive_direct_fallback`

Quando um trabalho de zas_receive_direct falhou em voo, baixa a cópia cifrada que quem mandou escolheu guardar. Só funciona se essa pessoa escolheu a via confiável para aquela transferência. O arquivo é decifrado nesta máquina e escrito no mesmo destino.

Argumento	Tipo	Notas
`job`	string, obrigatório	O id de trabalho que reportou o recebimento que falhou.

`zas_list_items`

Lista os itens mais recentes de um canal. Precisa de uma liberação com leitura.

Argumento	Tipo	Notas
`channel`	string, obrigatório	Nome ou id.
`limit`	inteiro, opcional	De 1 a 50. Por padrão, 20.

`zas_get_item`

Traz um item. Uma nota volta como texto; um arquivo é escrito em disco.

Argumento	Tipo	Notas
`channel`	string, obrigatório	Nome ou id.
`id`	string, obrigatório	Id do item, como `zas_list_items` reporta.
`dest`	string, opcional	Onde escrever o arquivo. Um diretório significa “dentro dele”. Por padrão, um diretório temporário novo.

Nunca sobrescreve um arquivo existente. Um nome ocupado ganha um sufixo, e o caminho que volta é o que foi realmente escrito.

`zas_jobs`

Lista os envios e as transferências pelo Direto que este servidor começou, do mais novo para o mais velho, com a fase que cada um alcançou e como terminou. Um job_id de um envio longo é resgatado aqui, e um trabalho terminado guarda o resultado.

Códigos de erro

O agente responde com um conjunto fechado. Qualquer coisa vinda de uma rota que não esteja nesse conjunto vira upload_failed ou network, então um texto cru do servidor, ou um stack trace, nunca chega a um terminal.

Pareamento e identidade

Código	O que significa
`not_paired`	Esta máquina ainda não está pareada.
`identity_corrupt`	O arquivo de identidade em disco está danificado.
`agent_revoked`	O dono revogou este agente.
`agent_forbidden`	Isso só o dono da conta pode fazer.
`pairing_expired`	O pareamento expirou. Pareie de novo.
`pairing_cancelled`	O dono cancelou o pareamento.
`pairing_not_approved`	Ninguém aprovou este pareamento ainda.
`pairing_claimed`	Este pareamento já foi reclamado.
`claim_mismatch`	O código não bate.
`agent_limit`	A conta não comporta outro agente.
`grant_limit`	O plano permite menos canais por agente do que este pareamento libera.
`feature_disabled`	Os agentes não estão ligados para esta conta.
`sign_in_failed`	O Zas não aceitou esta sessão de agente.
`bad_signature`	O Zas recusou a assinatura deste agente. Pareie de novo.
`missing_token`	Falta o token de sessão. Pareie de novo.

Canais e liberações

Código	O que significa
`grant_missing`	Este agente não tem acesso a esse canal.
`send_forbidden`	Este agente não pode mandar para esse canal.
`read_forbidden`	Este agente não pode ler esse canal.
`direct_mode`	Esse canal está em modo Direto. Use `zas_send_direct`.
`not_direct_mode`	Esse canal não está em modo Direto. Use `zas_send_file`.
`key_stale`	A chave do canal mudou. Abra o Zas para atualizar.

Mandar e ler

Código	O que significa
`quota_exceeded`	A conta chegou ao limite de armazenamento.
`rate_limited`	Envios demais seguidos.
`file_too_big`	O arquivo passa do limite do plano.
`duplicate`	Esse item já está no canal.
`not_found`	Esse item não está no canal.
`not_yours`	Esse item não foi mandado por este agente. Ele só pode mudar os dele.
`stale`	Esse item mudou enquanto este agente trabalhava nele. Leia de novo e tente outra vez.
`not_a_note`	Esse item é um arquivo, não uma nota. Só o título pode mudar; para os bytes, use `zas_replace_file`.
`not_a_file`	Esse item é uma nota, não um arquivo. Use `zas_edit_item`.
`item_shared`	Esse item tem um link público. O dono tira o link primeiro.
`invalid_cap`	Esse arquivo não está mais disponível.
`write_failed`	Não deu para salvar o arquivo no destino.
`upload_failed`	A subida falhou.
`oprf_failed`	O Zas respondeu errado enquanto preparava o arquivo.

Direto

Código	O que significa
`not_claimed`	Ninguém recebeu o arquivo em dez minutos. A oferta foi retirada.
`no_offer`	Ninguém ofereceu um arquivo pelo Direto enquanto esta chamada esperava.
`offer_taken`	Outro aparelho recebeu esse arquivo primeiro.
`direct_cancelled`	A oferta foi cancelada do outro lado.
`direct_failed`	A transferência pelo Direto falhou em voo. Uma ferramenta de resgate ainda pode entregar.
`direct_not_failed`	Esse trabalho não é uma transferência pelo Direto que falhou em voo.
`file_changed`	O arquivo mudou depois da oferta pelo Direto. Mande de novo.
`webrtc_unavailable`	Não deu para carregar o motor WebRTC (`node-datachannel`) nesta máquina.
`fallback_unavailable`	A via confiável não está disponível agora.

O resto

Código	O que significa
`network`	Não dá para alcançar o Zas.
`internal`	Algo falhou dentro do agente.

Arquivos em disco

Um diretório por perfil, então uma máquina pode ter um agente do Claude Code e um do Codex sem que nenhum leia as chaves do outro.

Sistema	Caminho
macOS, Linux	`~/.zas/agent/PERFIL/`
Windows	`%USERPROFILE%\.zas\agent\PERFIL\`

Arquivo	O que tem
`identity.json`	O uid do agente, o do dono, o nome e os dois pares de chaves. Guarde como uma chave privada, ou apague e pareie de novo.
`pending.json`	Um pareamento não reclamado. Some quando ele completa, expira ou é cancelado.
`grants.json`	Um cache de um minuto dos canais do agente e das chaves seladas. O nome do canal continua cifrado aqui. Descartável.
`fingerprints.json`	Hashes do que um envio idêntico produziu nos últimos dez minutos, para uma repetição responder sem tocar a rede. Só hashes, nunca um título. Descartável.

Um arquivo vive um nível acima, em ~/.zas/agent/, porque é uma decisão sobre a máquina e não sobre uma identidade:

Arquivo	O que tem
`settings.json`	A decisão de telemetria desta máquina, e se o aviso inicial já foi mostrado. Descartável.

Cada arquivo é escrito num temporário e renomeado, então uma queda no meio da escrita não deixa meio arquivo. No macOS e no Linux o diretório é criado 0700 e cada arquivo 0600. No Windows esses bits não fazem nada: os arquivos ficam com as permissões do perfil de usuário onde vivem, e o pacote não define outras.

Apagar o diretório faz a máquina esquecer o agente. Não revoga. Isso é em Configurações → Agentes → Revogar.

Telemetria

O agente reporta o funil de pareamento e um evento agent.tool_call por chamada, para o Zas ver quais ferramentas funcionam e quais falham. Vem ligada e imprime um aviso na primeira vez. O que ela nunca manda: nomes de arquivo, títulos, corpos de notas, nomes de canal, caminhos nem conteúdo. Três formas de desligar, na ordem em que são lidas:

Interruptor	Efeito
`ZAS_AGENT_TELEMETRY=off`	Desligada para este processo. `on` força ligada.
`DO_NOT_TRACK=1`	Desligada. O interruptor comum entre produtos, respeitado só para desligar.
`zas-agent telemetry off`	Desligada para esta máquina, lembrado em `settings.json`.

zas-agent telemetry sem valor imprime o estado atual e qual dos três decidiu. zas_status imprime a mesma linha.

Ajustes

Ajuste	Padrão	O que muda
`--profile NOME`	`claude-code`	Qual diretório de identidade este processo usa. Letras, dígitos, `.`, `_` e `-`, até 64, e não pode começar com ponto.
`--kind`	pelo nome do perfil	O harness mostrado na aprovação: `claude_code`, `codex` ou `other`.
`--host NOME`	o hostname da máquina	O host mostrado na aprovação.
`--no-open`	desligado	Não abrir o navegador ao parear. O link é impresso do mesmo jeito.
`ZAS_NO_OPEN`	sem valor	O mesmo que `--no-open`.
`ZAS_AGENT_HOME`	`~/.zas/agent`	Onde ficam os diretórios de perfil.
`ZAS_AGENT_TELEMETRY`	sem valor	`off` ou `on`, para este processo.
`DO_NOT_TRACK`	sem valor	`1` desliga a telemetria.
`ZAS_WEB_BASE`	`https://zas.red`	O app web para onde a URL de pareamento aponta.
`ZAS_API_BASE`	`https://zas.red/api`	A API.

Só --profile, ZAS_AGENT_HOME e os interruptores de telemetria valem a pena na mão. O resto existe para apontar o pacote a um ambiente de teste.

Números

	Valor
Agentes, plano grátis	5, revogados incluídos
Canais por agente, plano grátis	5, contando os que ele já teve
Agentes, sem conta	Nenhum
Agentes por membro, padrão numa organização	2, faixa de 0 a 10
Canais por agente, numa organização	Sem teto; o alcance é governado pela participação no canal
Teto duro, qualquer conta	10
Maior arquivo guardado	O limite do seu plano, 50 MB no grátis
Maior arquivo que o agente lê	5 GiB
Maior transferência pelo Direto	O limite do seu plano, 10 GB no grátis
Vida mais curta que um agente pode pedir	1 dia
Vida do token de sessão	1 hora, assinado de novo sozinho
O pareamento espera a aprovação	10 minutos
Um pareamento aprovado espera ser reclamado	5 minutos

Por onde seguir

Conectar um agente

Pareamento, comandos do harness e o que fazer quando falha.

Limites

Cada limite que o Zas aplica, agentes incluídos.

FAQ

Respostas curtas para as perguntas de sempre.

Recomendações

Bons hábitos, e o aviso sobre segredos.

⌘I

Começar

Como o Zas funciona

Usar o Zas

Agentes

Conta

Referência

Referência do agente do Zas: ferramentas MCP e erros

Comandos

Ferramentas

`zas_status`

`zas_pair`

`zas_send_file`

`zas_send_note`

`expires_in_days`

`zas_send_direct`

`zas_receive_direct`

`zas_send_direct_fallback`

`zas_receive_direct_fallback`

`zas_list_items`

`zas_get_item`

`zas_jobs`

Códigos de erro

Pareamento e identidade

Canais e liberações

Mandar e ler

Direto

O resto

Arquivos em disco

Telemetria

Ajustes

Números

Por onde seguir

Conectar um agente

Limites

FAQ

Recomendações

​Comandos

​Ferramentas

​zas_status

​zas_pair

​zas_send_file

​zas_send_note

​expires_in_days

​zas_send_direct

​zas_receive_direct

​zas_send_direct_fallback

​zas_receive_direct_fallback

​zas_list_items

​zas_get_item

​zas_jobs

​Códigos de erro

​Pareamento e identidade

​Canais e liberações

​Mandar e ler

​Direto

​O resto

​Arquivos em disco

​Telemetria

​Ajustes

​Números

​Por onde seguir

Conectar um agente

Limites

FAQ

Recomendações

Comandos

Ferramentas

`zas_status`

`zas_pair`

`zas_send_file`

`zas_send_note`

`expires_in_days`

`zas_send_direct`

`zas_receive_direct`

`zas_send_direct_fallback`

`zas_receive_direct_fallback`

`zas_list_items`

`zas_get_item`

`zas_jobs`

Códigos de erro

Pareamento e identidade

Canais e liberações

Mandar e ler

Direto

O resto

Arquivos em disco

Telemetria

Ajustes

Números

Por onde seguir