FileAgent

FTP para agentes: um filesystem virtual compartilhado, cada arquivo endereçado e verificado por SHA-256, com metadados extraídos no upload.

Agentes no mesmo FILEAGENT_DATA_DIR (stdio) ou no mesmo servidor HTTP vêem o mesmo acervo. Nada entra ou sai sem um hash cadastrado (ftp_register). Esse access_hash é o canal; o SHA-256 do arquivo é a prova de integridade.

Modelo

Conceito	O que é
Access hash	Credencial cadastrada com ftp_register. Sem ela, put/get falham. Cada hash é um canal isolado.
Path	Caminho FTP (/inbox/nota.md) dentro do access_hash.
Blob	Bytes imutáveis. Endereço = sha256(bytes). Toda leitura recalcula o hash.
Metadados	Extraídos do conteúdo: mime, kind, título, idioma, headings, colunas CSV, chaves JSON, dimensões de imagem, hints de PDF.
Documento	Ponteiro mutável atrás do path. Serve checkout/commit entre agentes.
CAS	expected_hash no get/put. Disco adulterado → code=tampered.

agente A                         FileAgent                       agente B
   |-- ftp_register() -----------> |                               |
   |<-- access_hash ---------------|                               |
   |---------------- compartilha access_hash --------------------->|
   |-- ftp_put(/inbox/a.md, hash) >|  sha256 + metadata            |
   |                               |<-- ftp_get(/inbox/a.md, hash)-|

Dois agentes com o mesmo secret em ftp_register obtêm o mesmo access_hash.

Ferramentas FTP

Tool	Uso
ftp_register	Cadastra o hash. Sem isto, put/get são recusados.
ftp_revoke / ftp_hashes	Revoga ou lista hashes deste agente.
ftp_put	Envia. Exige access_hash. Grava SHA-256 + metadados.
ftp_get	Baixa. Exige o mesmo access_hash. Recalcula SHA-256.
ftp_ls	Lista o canal deste hash (conteúdo + metadados).
ftp_stat / ftp_meta	Só metadados (path ou hash).
ftp_verify	Auditoria de integridade.
ftp_find	Busca por path, hash, título, kind, colunas…
ftp_mkdir / ftp_rm / ftp_mv / ftp_cp	Navegação estilo FTP.

doc_* continua para edição colaborativa (lock + doc_commit) do documento ligado ao path.

Recursos: fileagent://fs, fileagent://docs, fileagent://blob/{hash}.

Metadados extraídos

No ftp_put / ftp_stat / ftp_ls:

• sempre: hash, size, mime, kind, filename, extension
• texto / markdown: título, headings, linhas, palavras, idioma (pt/en)
• JSON: validade, tipo, chaves
• CSV: colunas e número de linhas
• PNG / JPEG / GIF: largura e altura
• PDF: versão, title/author se presentes no header

Admin e senha

Só o admin cadastra access_hash. A senha em texto fica apenas no .venv do projeto (fora do git):

• hash: .venv/fileagent_admin.hash (PBKDF2-SHA256)
• senha: .venv/fileagent_admin.password

uv run fileagent --init-admin          # gera se ainda não existir
uv run fileagent --rotate-admin        # nova senha

Painel no navegador: abra / e entre com essa senha para ver todos os arquivos de todos os canais. Sem login, a lista não aparece.

# cadastrar um canal para clientes
curl -sS -X POST http://127.0.0.1:8765/v1/admin/register \
  -H "Content-Type: application/json" \
  -d '{"admin_password":"<senha>","label":"equipe-a"}'

Clientes não cadastram hash. Usam o access_hash devolvido em POST /v1/files ou ftp_put.

Subir no ar

uv run fileagent --http --host 0.0.0.0 --port 8765

• Painel admin (login): http://<host>:8765/
• MCP: http://<host>:8765/mcp
• REST: POST/GET /v1/files com header X-Access-Hash
• Saúde: GET /healthz

Skills

• fileagent-send — agentes que enviam
• fileagent-receive — agentes que listam/baixam

Instalação

cd /Users/naubergois/FileAgent
uv sync --extra dev

Cursor (mesmo store entre agentes)

{
  "mcpServers": {
    "fileagent": {
      "command": "uv",
      "args": ["--directory", "/Users/naubergois/FileAgent", "run", "fileagent"],
      "env": {
        "FILEAGENT_DATA_DIR": "/Users/naubergois/.fileagent",
        "FILEAGENT_AGENT_ID": "cursor",
        "FILEAGENT_OPEN_EDIT": "1"
      }
    }
  }
}

Cada agente: mesmo FILEAGENT_DATA_DIR, FILEAGENT_AGENT_ID distinto.

HTTP

uv run fileagent --http --port 8765

Variáveis

Variável	Default	Função
FILEAGENT_DATA_DIR	~/.fileagent	SQLite + blobs. Mesmo path = mesmo FTP.
FILEAGENT_AGENT_ID	user@host	Quem enviou / editou.
FILEAGENT_OPEN_EDIT	1	Agentes do store editam paths shared.
FILEAGENT_HOST / PORT	127.0.0.1 / 8765	Modo --http.

Paths private só o dono (e grants) enxergam. agent_id é coordenação, não autenticação forte. A segurança do conteúdo é o hash: se os bytes mudarem, a leitura falha.

Produção atual (AWS): https://fileagent.54-204-243-102.sslip.io/ — painel com senha de admin.

Testes

uv run pytest -q