dsh-tavily-resilient-search

Pesquisa web em tempo real para o DeepSeek Harness (DSH), através da API
Tavily, com rotação atómica e resiliente de um agrupamento
de credenciais e contingência keyless — sem quebrar o agent loop quando as
chaves atingem limites de taxa (429), esgotam a cota mensal (432/433) ou são
revogadas (401).

Plugin Cordis autónomo: instala-se por manifesto, sem forks do código do
DSH, e sobrevive a hot-reload/unload sem fugas nem escutas órfãs.

O problema que resolve

Numa implementação ingénua, um HTTP 429 ou 432 é propagado como rejeição de
promessa à rotina de turnos: o turno termina abruptamente — ou o modelo conclui,
erradamente, que "a internet deixou de existir". Aqui, a intenção semântica
(pesquisar) está desacoplada da camada física (qual credencial despacha agora):

• erros de saturação/faturação mutam o estado da chave causadora e a chamada
  é reemitida de imediato com o payload intacto, pela próxima credencial
  desimpedida (round-robin);
• quando todo o pool está impedido, ativa-se a contingência keyless
  (X-Tavily-Access-Mode: keyless);
• só quando todas as alternativas de transporte se esgotam é que a ferramenta
  devolve uma conclusão estruturada de aviso — nunca uma exceção que ejetasse
  o processo hospedeiro.

Instalação

dsh plugin --profile web add dsh-tavily-resilient-search

A ativação é automática: o pacote declara dsh.bundle.patch (apenas
dsh.bundle.patch ativa um plugin — um bundle: {} vazio não ativa nada) e o
manifesto cordis.patch.yml entra na camada Bundle da composição.

Defina as credenciais por variáveis de ambiente (nunca em texto simples):

export TAVILY_API_KEY_A="tvly-..."
export TAVILY_API_KEY_B="tvly-..."   # tantas quantas as contas disponíveis
export TAVILY_API_KEY_C="tvly-..."
export TAVILY_API_KEY_D="tvly-..."

Sem nenhuma chave o plugin não rebenta o boot: degrada para o modo
keyless-only (limites muito mais severos) e avisa em voz alta. Estado
legítimo documentado: "ainda não configurado".

Gestão de chaves via interface

Todo o CRUD do pool vive num único sítio: a secção “Tavily Keys” em
Definições (Settings) — contribuída para o slot settings.section pelo
bundle de cliente (client/client.js, formato __ModuleLoader__ medido no
exemplo oficial), estilizada com o design system do DSH.

• CRUD completo num só ecrã: adicionar (C, com Enter), listar com
  estados em cartões (R), editar/substituir (U, Enter guarda, Esc
  cancela), remover (D) e Testar (valida contra a API — 1 crédito).
• Feedback em cada ação: spinner durante o pedido e confirmação ✓/⚠
  imediata — nada de cliques sem resposta.
• Botão “🔑 Tavily Keys” na área lateral só quando não existe chave
  válida (desaparece assim que há credencial utilizável); abre diretamente as
  Definições. Não há ecrã paralelo: a antiga página autónoma responde 410.
• Links úteis no painel: app.tavily.com para obter chaves, documentação e
  onde está o token.

Token administrativo (para abrir o painel): gerado por CSPRNG no primeiro
arranque, guardado em ~/.dsh/dsh-tavily-resilient-search/admin-token.txt
(0600) e impresso uma vez no registo do DSH (logger 'tavily-pool'). Perdeu?
Recarregue com DSH_TAVILY_ADMIN_RESET=1. Também pode definir
DSH_TAVILY_ADMIN_TOKEN.
- Fronteira: origem (socket + Origin) → Host → credencial, por esta
ordem fixa; denegações byte-idênticas (sem oráculo). Predefinição: só
loopback (admin.trustedRemotes / admin.allowedHosts).
- Força bruta: orçamento NIST SP 800-63B-4 (100 falhas → lockout com o
mesmo 401).
- Ações destrutivas (remoção e substituição/edição) exigem nonce de
confirmação, de uso único.
- Auditoria: audit.log apensível (0600, O_NOFOLLOW) com todas as
decisões mutáveis e denegações.
- Chaves removidas que vêm do ambiente regressam no próximo arranque (a
remoção é volátil e o painel avisa); chaves persistidas/removidas pelo painel
são definitivas.
- Sobre um bind público (0.0.0.0) o painel recusa-se a subir (fail-closed,
ruidoso) até admin.allowPublicBind: true — a ferramenta de pesquisa continua
a funcionar em qualquer caso.

Configuração

Sobreponha qualquer campo na camada Profile
($DSH_HOME/profiles//cordis.patch.yml), Home
($DSH_HOME/cordis.patch.yml) ou CLI overlay (dsh --patch ./o.yml). A
resolução é de entrada inteira (whole-entry replace), nunca deep-merge:
aponte sempre ao id do próprio plugin.

Exemplo (camada Bundle, já incluído no pacote):

- insert:
- id: dsh-tavily-resilient-search
name: 'dsh-tavily-resilient-search'
config:
searchDepth: 'basic'
maxResults: 5
includeAnswer: true
timeoutMs: 15000
callTimeoutMs: 120000
securityProfile:
sandbox: 'workspace-write'
approval: 'ask'
apiKeys: !!js >
(() => { try { return [process.env.TAVILY_API_KEY_A, process.env.TAVILY_API_KEY_B, process.env.TAVILY_API_KEY_C, process.env.TAVILY_API_KEY_D].filter(Boolean) } catch { return [] } })()

Regras medidas do manifesto (@deepseek-ai/dsh 0.1.x-rc): a ordem das linhas não
carrega semântica de carga (a ativação é dirigida por inject) e um !!js que
lança na carga impede o boot do DSH para todos os instaladores — a expressão
acima é defensiva e devolve [] em falha.

Ferramenta exposta: web_search

Resultado canónico (forma total, null explícito quando não aplicável):
ok, query, answer, sources[] (title, url, snippet, score),
responseTime, resultsTruncated, keylessFallbackUsed, error, detail,
suggestion. A projeção para o modelo inclui sempre um aviso de
não-confiança sobre o conteúdo web (contenção de injeção indireta).

Comportamento por código HTTP

Máquina de estados do agrupamento

┌──────────────┐  401   ┌──────────┐
┌────────►│    ACTIVE    │───────►│ REVOKED  │ (definitivo)
│         └──────┬───────┘        └──────────┘
│  cooldown      │ 429
│  expirado      ▼
┌─────┴────────┐  ┌──────────────┐
│ (round-robin)│◄─│ RATE_LIMITED │  T = Retry-After ou min(Tmax, T0·2^k) + δ
└──────────────┘  └──────────────┘
▲
│ reposição mensal (1.º dia, UTC)
┌─────┴───────────┐
│ QUOTA_EXHAUSTED │  432/433 → suspensa até à meia-noite UTC do mês seguinte
└─────────────────┘

T₀ = 500 ms, T_max = 60 s, jitter δ ∈ [0, 500) ms contra ressaturação em
bloco. A recuperação é lazy (sem timers): a expiração é aplicada na seleção
seguinte, o que mantém leituras puras e o event loop limpo.

Segurança

Resumo (completo em docs/seguranca.md):

• A conjugação sandbox: danger-full-access + approval: never é recusada no
  load (fail-loud, irrecuperável de propósito). O securityProfile é uma
  atestação obrigatória do operador — configuração ausente também falha alto.
• Canário de segredos por valor: material de credencial é redigido de todo o
  texto de saída e registos (um corpo de resposta malicioso que ecoasse a chave
  do Authorization nunca a propaga); identificação em logs apenas por máscara
  …últimos4.
• Teto volumétrico de 50 KB por invocação: documentos-bomba não saturam a
  janela de contexto (include_raw_content nunca é enviado).
• Conteúdo web é dado não-confiável: a projeção do modelo carrega aviso
  permanente contra injeção indireta de instruções.

API validada por medição (nunca por prosa)

A superfície usada foi lida dos .d.ts dentro dos tarballs npm publicados
(sha256 registado em types/; reverificado por pnpm run check:upstream) e é
travada por um contract test que falha se a API pública divergir. Factos
medidos que corrigem documentação circulante:

Linhas suportadas: @deepseek-ai/dsh-tools ^0.1.1-rc.1 || ^0.1.7-rc.1 (o
drift entre ambas é apenas aditivo) e @deepseek-ai/cordis ~4.0.4. Nota: o
dist-tag latest dos subpacotes dsh-* aponta para a publicação mais antiga —
a linha viva é next.

Desenvolvimento

pnpm install
pnpm run gate          # lint + typecheck + build + test + check:tarball
pnpm run check:upstream # reverifica tarballs/sha256 pela rede (Q-1)

Testes em quatro camadas (node:test + tsx, determinísticos — relógio e RNG
injetados, sem sleeps):

Empacotamento e publicação

Publica-se pré-compilado (dist/), sem scripts de build na instalação do
consumidor (risgo de cadeia de suprimentos). files é uma allowlist: dist/,
cordis.patch.yml, README.md, LICENSE, CHANGELOG.md. O gate de release é
pnpm run gate && publint && attw --pack . && node scripts/check-tarball.mjs
(este último inspeciona o tarball real). Notas de versão via
changesets; em 0.x, um minor é
breaking. Releases em CI usam trusted publishing (OIDC) — configurar uma vez
no console do npm para este repositório.

Licença

MIT