vault-go 0.20.0 → 0.22.0

package/docs/mode-integrations.md

@@ -0,0 +1,74 @@
+# Integrações de modos
+
+O Vault Go implementa três superfícies locais independentes: alertas Telegram,
+CCS Align e taxonomias customizadas. O registro MCP fica em
+`registerModeIntegrations`, separado do servidor principal.
+
+## Telegram
+
+O token do bot nunca é aceito como argumento MCP. Defina
+`VAULT_GO_TELEGRAM_BOT_TOKEN` no ambiente privado do serviço e invoque
+`vault_go_telegram_configure` com o chat e os tipos ou conceitos aprovados.
+A configuração é cifrada pelo armazenamento privado local; status, resources e
+erros não retornam o token. Configurar não envia mensagem. O único envio de teste
+ocorre por uma chamada explícita a `vault_go_telegram_test`.
+
+Depois da persistência de uma observação, o worker envia apenas quando alertas
+estão habilitados e o tipo ou um conceito corresponde aos gatilhos. A mensagem é
+limitada a tipo, título, projeto e ID; narrativa e fatos não são enviados. Uma
+falha do Telegram não repete nem invalida uma memória já persistida.
+
+Ferramentas: `vault_go_telegram_status`, `vault_go_telegram_configure`,
+`vault_go_telegram_disable` e `vault_go_telegram_test`.
+
+## CCS Align
+
+Cada viewer possui `middle.jsonl`, `exclude-marks.json`, `cursor.json` e
+`rules-report.md` sob o diretório privado do Vault. Atualizações usam arquivo
+temporário e rename, deduplicam por UUID e conteúdo e limitam quantidade e
+tamanho. Excluir filtra o cache compilado; não apaga a memória cloud. Restaurar
+remove a marca e requer um novo ciclo para reler a fonte autoritativa.
+
+O ciclo comprova health e consulta `search_index → timeline → observations`.
+O rules check recebe listas limitadas de regras como dados, detecta
+`SHADOW_HOUSE`, `DENY_ALLOW`, `DRIFT` e `CLOCK_HEADER` e acrescenta uma seção ao
+relatório. Ele nunca altera house, project ou seat rules.
+
+Ferramentas: `vault_go_ccs_align_health`, `vault_go_ccs_align_cycle`,
+`vault_go_ccs_align_exclude`, `vault_go_ccs_align_restore` e
+`vault_go_ccs_align_rules_check`.
+
+O writer de awareness do Grok Bot é outra função upstream: ele grava linhas em
+logs mensais de um agente Grok. CCS Align não escreve nesses logs e esta mudança
+não implementa esse writer.
+
+## Taxonomias customizadas
+
+`vault_go_custom_mode_save` valida identificadores, taxonomias e prompts antes
+de gravar. A resolução rejeita pais desconhecidos e ciclos; arrays presentes
+substituem os do pai e prompts são mesclados. O catálogo e a preferência ativa
+ficam cifrados. `vault_go_custom_mode_select` aplica o modo à injeção de contexto
+e à geração local futura. Memórias existentes não são reclassificadas.
+
+Ferramentas adicionais: `vault_go_custom_modes`, `vault_go_custom_mode_get` e
+`vault_go_custom_mode_delete`. O modo base `code` não pode ser sobrescrito ou
+apagado, e um modo com filhos não pode ser removido.
+
+## Auditoria dos workflows
+
+Os 20 nomes em `vault-go://modes` correspondem aos 20 skills publicados no
+snapshot upstream 13.25.2. Um skill é um roteiro executado pelo agente cliente;
+carregá-lo não iniciar um agente em background não é, por si só, uma lacuna.
+Babysit, planejamento, execução, relatórios e os demais roteiros funcionam quando
+o cliente oferece as ferramentas indicadas. Diferenças reais permanecem para
+knowledge-agent (sem sessão conversacional persistente), wowerpoint (sem renderer
+PPTX/PDF embutido) e cloud-sync (cmem.ai não é o Vault cloud).
+
+Após integrar estes módulos, a matriz global deve separar a antiga linha conjunta:
+
+- Telegram: disponível com configuração explícita e gatilhos locais.
+- CCS Align: disponível na variante Vault descrita acima.
+- Modos customizados: disponíveis; atualizar a linha de privacy/capture modes.
+- Grok awareness push: ainda não implementado e distinto de Telegram/CCS Align.
+- Transcript watchers: avaliar separadamente com o trabalho específico de watchers.
+- Workflows: não marcar como parciais apenas porque o agente cliente executa as instruções.

package/docs/parity-deployment-review.md

@@ -0,0 +1,60 @@
+# Revisão e implantação da paridade
+
+Data: 20 de setembro de 2026. Referência: claude-mem 13.25.2, adce0fdf.
+
+## Implementado
+
+Busca sem query obrigatória, offset e ordem por data; timeline com âncora por
+consulta; leitura individual de jobs. Backup v2 paginado e consistente por
+snapshot materializado, privado no cliente, com hash e validação de proprietário
+antes da restauração. O formato cobre preferências e dados de memória; o manifesto
+explicita limites e omissões, sem declarar exportações truncadas como completas.
+
+Conversas com corpora usam o modelo escolhido, fontes numeradas e histórico local
+cifrado por conta/base. Respostas HTTP do corpus têm teto de 8 MiB; o JSON de
+fontes enviado ao modelo tem teto de 16 mil caracteres. Codex Terra/Luna/Sol e
+Claude Haiku foram executados de verdade com fontes sintéticas e citações válidas.
+O schema estrito exige todos os campos e aceita classificação nula.
+
+Telegram, CCS Align, taxonomias herdadas, watchers de Claude/Codex e encadeamento
+de projetos têm ferramentas próprias no MCP. Captura adicional e envio de
+alertas exigem configuração explícita. Caches e destinos de notificações ficam
+vinculados à conta. O Crystal usa o mesmo servidor Vault Go.
+
+AST real cobre os 24 idiomas upstream e HTML; o catálogo informa disponibilidade
+por plataforma. SCSS não tem prebuild Linux ARM64. Awareness do Grok usa logs
+mensais locais, com consentimento e allowlist de agentes.
+
+## Evidências
+
+- Engine 649f5f7 e API fdcc24b enviados a main e implantados no Docker Swarm.
+- Serviços saudáveis; health/readiness, autenticação e contratos testados na API canônica.
+- `deploymentVerified: true`: health, searchIndex, toolUses, feed, knowledgeBases,
+  observerStatus, backup e job aprovados em 20/09/2026. A verificação é dinâmica,
+  privada por conta e válida por cinco minutos; não equivale a verificar
+  credenciais externas, qualidade dos modelos ou entrega Telegram.
+- Backup real: 4.008 registros, 81 páginas, 14.070.751 bytes. Arquivo privado
+  mantido em `~/.memvault/backups/`; conteúdo não foi publicado.
+- Testes de snapshot cobrem alterações/remoções/criações entre páginas, expiração,
+  limites, isolamento entre contas e restauração idempotente.
+- Testes do cliente cobrem mudança de conta durante operações, resposta HTTP
+  excessiva, substituição de lock, redaction, credenciais, MCP e fila de modelos.
+- Auditoria de dependências de produção: zero vulnerabilidades.
+- Crystal: 122 testes, typecheck, gates de qualidade e E2E Electron com 2.359 notas;
+  as sete operações foram exercitadas pelo MCP Vault e servidor Crystal reais.
+
+## Revisão
+
+APROVADO COM RESSALVAS. A revisão multimodelo foi substituída por revisão manual:
+ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN não estavam definidos, impedindo conferir
+os aliases dos três revisores no gateway. Não se presumiu que aliases eram órfãos.
+A revisão manual e uma segunda leitura independente encontraram e corrigiram
+fencing de conta, recuperação de locks, restauração de preferências e limites de
+leitura. As correções têm testes de regressão.
+
+Ressalvas: o servidor gerenciado está `configured:false` até receber uma credencial
+válida; provedores locais selecionados continuam disponíveis com sua autenticação.
+Backup v2 não é o formato SQLite upstream nem uma réplica offline/cmem.ai Pro.
+Restauração é idempotente por página; não é uma única transação entre preferências
+do gateway e todos os dados do engine. Os workflows/skills executam no cliente e
+respeitam as ferramentas e autorizações disponíveis nesse cliente.

package/docs/transcripts-and-context.md

@@ -0,0 +1,75 @@
+# Transcripts persistentes e contexto entre projetos
+
+Vault Go pode capturar transcripts JSONL de Claude Code e Codex enquanto o serviço local está em execução. É uma opção local, desligada por padrão e vinculada à conta Vault. A preferência da conta `automaticCapture` também precisa estar ativada. A geração continua usando o motor/modelo já escolhido; ativar watchers não altera Claude Haiku, Codex ou chaves de providers.
+
+## Ativação
+
+```sh
+vault-go transcripts enable --client claude --workspace /caminho/projeto --consent
+vault-go transcripts enable --client codex --workspace /caminho/projeto --consent
+vault-go local start
+vault-go transcripts status
+```
+
+As raízes padrão são `~/.claude/projects` e `~/.codex/sessions`. Para outro perfil, use `--root /caminho/transcripts`. O workspace e a raiz precisam existir e ser caminhos absolutos. Registre cada workspace separadamente; no máximo 20 pares cliente/workspace. Subdiretórios de um repositório usam sua raiz Git.
+
+Sem `--from-start`, arquivos existentes começam no fim na primeira descoberta. Eventos que chegarem antes dessa primeira leitura podem ser pulados. Arquivos novos, criados depois da ativação, são lidos desde o início. Use `--from-start` na primeira configuração apenas quando quiser importar o histórico. Uma importação histórica pode se sobrepor à captura anterior por hooks sem identificadores comuns; a opção é explícita por esse motivo. Uma troca de conta exige novo consentimento.
+
+```sh
+vault-go transcripts enable --client codex --workspace /projeto --root /export/rollouts --consent --from-start
+vault-go transcripts poll
+vault-go transcripts disable --client codex --workspace /projeto
+```
+
+`poll` executa um lote sem iniciar serviços nem modificar preferências. `disable` devolve imediatamente aos hooks nativos a captura daquele cliente/workspace. Enquanto o watcher estiver habilitado, os hooks nativos continuam injetando contexto, mas deixam a escrita para o transcript, evitando captura dupla na operação normal. Desligar o serviço local mantém o checkpoint para retomada. Para voltar à captura exclusiva por hooks, desative o watcher.
+
+O setup aceita `--watch-transcripts claude|codex --workspace /projeto --consent`, opcionalmente `--transcript-root /raiz` e `--from-start`. Não ativa watchers implicitamente.
+
+## Recuperação e privacidade
+
+- `transcript-watchers.json` guarda o consentimento; `transcript-checkpoints.json` guarda offsets em bytes, identidade dos arquivos e o estado mínimo de chamadas pendentes. Arquivos usam permissão 0600 e gravação atômica. Entradas pendentes são redigidas e limitadas; esse checkpoint não é criptografado.
+- O checkpoint avança depois do evento cloud e da fila durável de geração. Falhas de rede voltam ao mesmo identificador idempotente. Uma perda de confirmação pode repetir o envio HTTP, mas usa a mesma chave na API e na fila/importação. Não há promessa de execução exatamente uma vez do modelo após replay histórico.
+- Um lock por processo impede dois consumidores simultâneos. Reinício, inode novo, truncamento e alteração do prefixo são detectados. Linhas parciais esperam a próxima leitura; UTF-8 usa offsets em bytes. JSON inválido e linhas acima de 256 KB são descartados.
+- Apenas registros cujo `cwd` corresponde ao workspace consentido são enviados. Symlinks encontrados na árvore são ignorados. Trocar conta, credenciais ou consentimento durante uma operação interrompe o lote. Um refresh de credencial pode abortar um lote; a próxima leitura retoma com os mesmos IDs.
+- `<private>` / `<vault-private>` e flags privadas bloqueiam o turno inteiro, incluindo ferramentas e resposta, até o próximo prompt público. Senhas, tokens, chaves e blocos de contexto são redigidos com a política dos hooks. `includeToolResults=false` continua omitindo resultados na API. Ao começar no fim de um arquivo existente, a leitura espera um novo prompt público antes de capturar ferramentas/respostas.
+- Claude: `user`, `assistant`, blocos `text`, `tool_use`, `tool_result`. Codex: `session_meta`, `turn_context`, `response_item.message`, chamadas `function_call` e `custom_tool_call` e seus resultados. `event_msg` duplicados são ignorados; `task_complete.last_agent_message` é fallback para resposta final ausente. Comentários intermediários do Codex não viram resumo. Formatos desconhecidos são ignorados.
+- Chamadas sem resultado ficam pendentes até o resultado chegar. No máximo 16 chamadas pendentes por arquivo, com entrada redigida limitada a 16 KB; excedentes antigos são descartados. Um novo prompt limpa chamadas sem resultado do turno anterior.
+
+Cada lote processa até 200 registros, 32 arquivos e 2 MB; cada arquivo é lido em blocos de até 256 KB. A descoberta visita até 4096 entradas e 1000 arquivos, priorizando diretórios e arquivos recentes. O checkpoint mantém até 1000 arquivos e aproximadamente 4 MB. Árvores que excedam os limites podem deixar arquivos históricos fora da descoberta; selecione uma raiz mais estreita para esses casos. A descoberta não promete uma varredura exaustiva de arquivos arbitrariamente grandes. A fila de geração mantém seus limites próprios.
+
+O worker faz polling a cada cinco segundos. `local serve`, instalação e atualizações usam o mesmo lifecycle; o serviço só se declara ocioso quando nenhuma captura está em execução e espera a captura atual ao fechar. Updates copiam os módulos novos para o runtime, preservando consentimento e checkpoints fora dele. SDK MCP e Zod ficam isolados em `transcript-tools.js`; o worker/hook staged não depende de `node_modules`.
+
+## Cadeia de contexto
+
+```sh
+vault-go context-chain set --workspace /app --roots /biblioteca,/infra --consent
+vault-go context-chain set --workspace /worktree --worktree-parent --consent
+vault-go context-chain status
+vault-go context-chain clear --workspace /app
+```
+
+SessionStart e `vault_go_session_start_context` passam a consultar o projeto primário e os vínculos configurados para aquele workspace. São no máximo cinco projetos, sempre descobertos na lista autenticada da conta e comparados por caminho exato. Projetos inexistentes ou marcados privados são omitidos; a leitura nunca cria projetos. O pai de worktree é resolvido pelo `.git`/`commondir`, sem executar comandos Git, e requer consentimento explícito.
+
+`contextItems` e `contextMaxChars` são orçamentos totais compartilhados entre os projetos, incluindo os pequenos cabeçalhos que identificam cada projeto. Os limites de caracteres e itens não são multiplicados por projeto. Vínculos vivem em `context-chains.json`, com permissão privada e escopo da conta. PreToolUse permanece restrito ao projeto/arquivo em uso.
+
+Isto fornece contexto multi-project em cadeia explícita. Não reproduz o renderer visual/token analytics do claude-mem nem escreve `AGENTS.md` automaticamente. O filtro semântico de memórias e isolamento do tenant continuam pertencendo à API Vault autenticada.
+
+## Ferramentas MCP
+
+| Ferramenta | Operação |
+| --- | --- |
+| `vault_go_transcripts_status` | Consentimento, alvos, última leitura e erro sanitizado |
+| `vault_go_transcripts_configure` | Ativar/desativar; exige `consent=true` para ativar |
+| `vault_go_transcripts_poll` | Processar um lote dos alvos já habilitados |
+| `vault_go_context_chain` | Consultar vínculos da conta |
+| `vault_go_context_chain_configure` | Definir/remover raízes e pai de worktree consentidos |
+
+## Evidência de implementação
+
+A descoberta upstream usou `/tmp/claude-mem-parity-20260919`, especialmente `src/services/transcripts/{processor,config,types}.ts`, `tests/transcripts/processor-codex-context.test.ts`, `tests/transcripts/watcher-start-at-end.test.ts` e o relatório `/tmp/claude-mem-parity-scan.md`. A arquitetura de watcher/runtime foi portada funcionalmente para a fila e a API Vault, sem executar scripts upstream.
+
+Foi consultada somente a estrutura de três arquivos locais por host (tipos e nomes de campos conhecidos, sem conteúdo dos prompts) para confirmar `custom_tool_call/output`, fases `commentary` e metadados Claude/Codex. Fixtures sintéticas em `src/transcript-watchers.test.ts` reproduzem esses formatos, com HTTP local, subprocesso CLI e runtime staged isolado. `src/context-chain.test.ts` verifica consentimento, isolamento, privacidade, limites totais, worktree e integração do hook.
+
+A revisão multimodelo foi substituída por revisão manual porque as variáveis de acesso ao gateway LiteLLM não estão disponíveis neste ambiente; nenhum alias foi chamado ou classificado como órfão sem consulta. A revisão manual conferiu fronteiras de conta/consentimento, parser, checkpoints, exclusão mútua, limites, integração e pacote. Nenhum watcher foi ativado na conta real e o worker instalado não foi alterado por estes testes.
+
+Validação em 2026-09-20, sobre a base `8f08e19341eed95164ee9a77cf178486adeddb0f`: `bun run build` e `bun test src` passaram (169 testes, 1229 assertions). `npm pack --dry-run --json` contém os 12 arquivos `.js`/`.d.ts` novos e esta documentação, sem arquivos de teste. `git diff --check` passou. Veredito manual: aprovado com os limites operacionais declarados acima.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vault-go",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Servidor MCP universal com autenticação e instalação multi-cliente para a plataforma Vault.",
   "type": "module",
   "bin": {
@@ -20,10 +20,18 @@
     }
   },
   "files": [
+    "dist/opencode-plugin.js",
+    "dist/opencode-plugin.d.ts",
+    "dist/knowledge-agent.js",
+    "dist/knowledge-agent.d.ts",
+    "dist/knowledge-tools.js",
+    "dist/knowledge-tools.d.ts",
     "dist/activity.js",
     "dist/activity.d.ts",
     "dist/auth.js",
     "dist/auth.d.ts",
+    "dist/backup.js",
+    "dist/backup.d.ts",
     "dist/callback-page.js",
     "dist/callback-page.d.ts",
     "dist/cli.js",
@@ -34,6 +42,8 @@
     "dist/config.d.ts",
     "dist/context-engines.js",
     "dist/context-engines.d.ts",
+    "dist/crystal-tools.js",
+    "dist/crystal-tools.d.ts",
     "dist/hook-install.js",
     "dist/hook-install.d.ts",
     "dist/hook-queue.js",
@@ -68,6 +78,7 @@
     "dist/server.d.ts",
     "assets/",
     "README.md",
+    "docs/mode-integrations.md",
     "LICENSE",
     "dist/mcp-result.js",
     "dist/mcp-result.d.ts",
@@ -84,7 +95,36 @@
     "dist/update-runner.js",
     "dist/update-runner.d.ts",
     "dist/modes.js",
-    "dist/modes.d.ts"
+    "dist/modes.d.ts",
+    "dist/telegram.js",
+    "dist/telegram.d.ts",
+    "dist/ccs-align.js",
+    "dist/ccs-align.d.ts",
+    "dist/custom-modes.js",
+    "dist/custom-modes.d.ts",
+    "dist/mode-integrations.js",
+    "dist/mode-integrations.d.ts",
+    "dist/transcript-config.js",
+    "dist/transcript-config.d.ts",
+    "dist/transcript-parser.js",
+    "dist/transcript-parser.d.ts",
+    "dist/transcript-watchers.js",
+    "dist/transcript-watchers.d.ts",
+    "dist/transcript-tools.js",
+    "dist/transcript-tools.d.ts",
+    "dist/context-chain.js",
+    "dist/context-chain.d.ts",
+    "docs/transcripts-and-context.md",
+    "dist/capture-privacy.js",
+    "dist/capture-privacy.d.ts",
+    "dist/deployment-verification.js",
+    "dist/deployment-verification.d.ts",
+    "dist/grok-awareness.js",
+    "dist/grok-awareness.d.ts",
+    "dist/awareness-tools.js",
+    "dist/awareness-tools.d.ts",
+    "docs/ast-and-awareness.md",
+    "docs/parity-deployment-review.md"
   ],
   "scripts": {
     "clean": "bun -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
@@ -129,8 +169,28 @@
   "author": "Gutierrez Henrique",
   "license": "MIT",
   "dependencies": {
+    "@ast-grep/lang-bash": "0.0.8",
+    "@ast-grep/lang-c": "0.0.6",
+    "@ast-grep/lang-cpp": "0.0.6",
+    "@ast-grep/lang-go": "0.0.6",
+    "@ast-grep/lang-haskell": "0.0.7",
+    "@ast-grep/lang-java": "0.0.7",
+    "@ast-grep/lang-kotlin": "0.0.7",
+    "@ast-grep/lang-lua": "0.0.7",
+    "@ast-grep/lang-markdown": "0.0.6",
+    "@ast-grep/lang-php": "0.0.7",
+    "@ast-grep/lang-python": "0.0.6",
+    "@ast-grep/lang-ruby": "0.0.7",
+    "@ast-grep/lang-rust": "0.0.7",
+    "@ast-grep/lang-scala": "0.0.7",
+    "@ast-grep/lang-sql": "0.0.8",
+    "@ast-grep/lang-swift": "0.0.8",
+    "@ast-grep/lang-toml": "0.0.9",
+    "@ast-grep/lang-yaml": "0.0.6",
     "@ast-grep/napi": "0.45.3",
     "@modelcontextprotocol/sdk": "1.29.0",
+    "@tree-sitter-grammars/tree-sitter-zig": "1.1.2",
+    "tree-sitter-scss": "1.0.0",
     "zod": "3.25.76"
   },
   "devDependencies": {