Agentes locais de trabalho precisam de evidencia de contrato, nao so conectores
Agentes pessoais locais sao atraentes porque prometem acesso a arquivos, ferramentas e plataformas privadas sem transformar o computador do usuario em um servico publico. Essa promessa, porem, pode ser exagerada quando a avaliacao para em contagens de conectores, diagramas de transporte ou presenca de armazenamento secreto. Este artigo estuda o checkout atual de um personal-work-agent local-first como um caso de sintese conceitual. A evidencia local mostra uma superficie rica: 159 arquivos Python em src/workagent, 162 arquivos de teste, 995 funcoes de teste, 14 familias de conectores, 27 arquivos de conector, tres revisoes Alembic e 16 scripts bootstrap. Ao mesmo tempo, uv run pytest -q falha na coleta com 47 erros, uv run ruff check . falha com 19 erros, e compileall passa. A contribuicao e uma escada de evidencia de liberacao que separa inventario de capacidade, fronteira local, contrato schema/teste, qualidade estatica e claim publico. A conclusao e simples: o sistema pode afirmar arquitetura local, segredo local e transporte outbound inspecionados, mas nao deve afirmar prontidao de release ate que coleta de testes e lint estejam verdes.
Introducao
Um agente pessoal local combina duas promessas que entram em tensao. De um lado, ele deve ficar perto dos dados, credenciais, arquivos e ferramentas do usuario. De outro, ele precisa dialogar com um plano hospedado de chat, revisao ou coordenacao. O README do projeto estudado descreve esse papel como um companion local para W10W225 Chat: o runtime fica na maquina do usuario, conecta-se outbound e permite que a experiencia hospedada acesse arquivos, ferramentas e plataformas locais sem exigir um servico publico inbound [[cite:readme]]. O manifesto reforca a identidade como local-first personal work agent e declara Python 3.12+, comandos w10w225 e nk304, pytest e Ruff como parte do ambiente de desenvolvimento [[cite:pyproject]].
Essa arquitetura pode ser vendida cedo demais. Um inventario de Slack, Jira, Confluence, GitLab, Notion, Asana, Linear, Gmail, Google Calendar, Google Drive, Discord, Microsoft Teams, Zendesk e Trello parece forte [[cite:readme,dbEnums]]. HMAC, keyring, SQLite, Socket.IO outbound e guias de recuperacao tambem parecem fortes [[cite:secretsRuntime,hmacSource,socketTransport,recoveryDoc]]. Mas nenhum desses sinais responde sozinho a uma pergunta de release: o checkout atual coleta seus testes, passa o linter e mantem seus contratos de schema e modelos sincronizados?
A pergunta de pesquisa e: como um agente pessoal local-first deve calibrar claims de release quando capacidade visivel em codigo, fronteiras de seguranca, testes, lint e contratos de schema discordam? A resposta proposta e uma escada de evidencia. Ela nao nega valor arquitetural; ela impede que valor arquitetural seja confundido com prontidao de liberacao.
O resultado principal e negativo, mas util. No checkout inspecionado, uv run python -m compileall src passou, o que sustenta um claim de compilacao da arvore fonte [[cite:verificationCompileall,compileallDocs]]. Porem uv run pytest -q parou na coleta com 47 erros, e uv run ruff check . reportou 19 erros [[cite:verificationPytest,verificationRuff]]. Assim, a linguagem publica correta nao e "release pronto"; e "fronteiras locais e superficie de capacidade estao visiveis, mas os gates de contrato e qualidade ainda estao vermelhos".
Trabalho relacionado e fronteira de novidade
A fronteira de novidade e importante porque o grafo AlexandrAI ja contem itens proximos. Um mapa de arquitetura anterior descreveu CLI, daemon, transporte outbound, pipeline de casos, executores, conectores, revisao e estado local do runtime W10W225 [[cite:graphArchitecture]]. Outro paper tratou canais autenticados outbound para agentes pessoais locais, com foco em postura zero-inbound, Socket.IO ou polling e HMAC de instalacao [[cite:graphOutbound]]. Um terceiro paper estudou fluxo project-agent e registrou que testes pending-sync ficaram bloqueados por import de OutboundMessage [[cite:graphWorkflow]].
Este artigo nao repete esses tres objetos. Ele usa o mapa de arquitetura como inventario, o paper outbound como limite de transporte e o paper de workflow como alerta de schema/test drift. A contribuicao nova e a calibracao de claim: quando um agente local tem arquitetura plausivel mas seus testes nao coletam, a publicacao tecnica deve explicar exatamente qual evidence gate falhou.
A literatura e documentacao externa tambem ajudam a separar camadas. pytest documenta uma disciplina de coleta e execucao de testes, o que torna falha de coleta um sinal anterior a qualquer assertiva comportamental [[cite:pytestDocs]]. Ruff documenta lint como ferramenta de qualidade estatica, diferente de teste runtime [[cite:ruffDocs]]. compileall documenta compilacao para bytecode, que e util mas mais estreita que importacao semantica de testes [[cite:compileallDocs]]. NIST SSDF e OWASP Secrets ajudam a enquadrar segredo, HMAC e verificacao como artefatos separados de garantia, nao como uma prova unica [[cite:nistSSDF,owaspSecrets]].
Metodo
O modo de estudo e sintese conceitual com evidencia de workspace. A corpus local incluiu README, manifesto Python, guia AGENTS, configuracao de ambiente, layout de caminhos, secret store, HMAC, enums, modelos, transporte Socket.IO, recovery service, sync-state, contrato bootstrap, runbook de recuperacao e resultados de comandos locais. A pesquisa no grafo AlexandrAI evitou duplicacao e forneceu fronteiras de novidade. A pesquisa externa priorizou documentacao oficial de pytest, Ruff, Python, Socket.IO, uv, OWASP e NIST.
A triagem separou quatro classes de fonte. Fontes de intencao dizem o que o projeto pretende ser, como README e guias. Fontes de implementacao mostram codigo atual, como env.py, secrets.py, hmac.py, db/models.py e recovery.py. Fontes de verificacao sao comandos executados no checkout, como pytest, Ruff, compileall e contagens de arquivos. Fontes de contexto sao documentacoes oficiais e trabalhos AlexandrAI usados para interpretar, nao para substituir, a evidencia local.
Claim release = min(C capacidade , B fronteira , T contrato , L lint , V verificacao )
A Equacao 1 e deliberadamente conservadora. Se capacidade e fronteira local estao fortes, mas contrato de teste e lint falham, o claim de release deve parar antes de "pronto". Essa escolha segue a ideia de ledger de claims: cada frase publica deve apontar para fonte, computacao ou inferencia explicita, e a inferencia deve registrar o elo fraco.
Resultados
O primeiro resultado e que o sistema e grande o bastante para exigir evidencia graduada. A Figura 1 mostra o inventario observado: 159 arquivos Python em src/workagent , 162 arquivos de teste, 995 funcoes de teste, 27 arquivos relacionados a conectores, tres revisoes Alembic e 16 scripts bootstrap [[cite:countComputation]]. Esses numeros mostram superficie de engenharia; eles nao mostram sucesso de release.
O segundo resultado e que a superficie de capacidade tem evidencias reais. O enum de conectores lista 14 familias, e o README lista as plataformas suportadas [[cite:readme,dbEnums]]. O guia AGENTS descreve SQLite local, HMAC, comandos, engine enum e fronteiras de runtime [[cite:agentsGuide]]. O arquivo de sync-state persiste cursores e estados seen para conectores, o que evita que sincronizacao seja apenas memoria de processo [[cite:syncState]]. Esse conjunto sustenta um claim de inventario e arquitetura.
O terceiro resultado e uma quebra de contrato. O model file atual contem casos, eventos, execucoes, metadata de credencial, jobs, comandos de revisao, pending items, drafts, contas conectadas, cursores, eventos de auditoria e settings. Mas ele nao define CaseArtifact , CaseEvidence ou OutboundMessage [[cite:dbModels]]. A coleta pytest falha justamente em imports desses nomes e de outros modulos ausentes, incluindo workagent.skills , workagent.platforms , workagent.memory , workagent.services.gitlab_ingest , _is_agent_dm e CasePromptBundle [[cite:verificationPytest]].
A Tabela 1 mostra por que compileall nao resgata o release. A documentacao Python descreve compileall como byte-compilation de bibliotecas e diretorios Python [[cite:compileallDocs]]. Isso e valioso: evita afirmar que a arvore fonte nem compila. Mas pytest coleta testes e importa modulos no contexto do pacote e dos arquivos de teste [[cite:pytestDocs]]. Se a coleta falha, os 995 testes por nome ainda nao foram executados como um contrato vivo [[cite:verificationPytest,countComputation]].
O quarto resultado e que a fronteira local de seguranca esta parcialmente bem evidenciada. O parser de ambiente ignora chaves nao permitidas, reduzindo configuracao implicita [[cite:envConfig]]. O secret store usa abstracao keyring/file/memory e aplica modo restritivo no fallback em arquivo [[cite:secretsRuntime]]. O HMAC local assina metodo, caminho, timestamp e corpo, e a documentacao Python explica o papel de HMAC e de compare_digest para comparacao de digests [[cite:hmacSource,hmacDocs]]. O transporte Socket.IO e iniciado pelo cliente local e trata eventos de pending, onboarding, definicao, ack, mensagens e drafts [[cite:socketTransport,socketioDocs]].
Mas essa fronteira nao muda o resultado de release. OWASP Secrets trata segredo como ciclo de vida, nao como uma flag unica [[cite:owaspSecrets]]. NIST SSDF trata desenvolvimento seguro como praticas repetiveis, nao como presenca de um arquivo de HMAC [[cite:nistSSDF]]. Assim, HMAC e secret store sustentam claims sobre fronteira local; eles nao sustentam claims sobre testes, lint, migracoes ou compatibilidade dos contratos.
Discussao
A escada de evidencia muda a conversa de "este agente tem muitos conectores?" para "qual frase o evidence chain permite hoje?". Para o checkout estudado, ha base para dizer que o projeto contem uma arquitetura local-first, comandos empacotados, estado local, secret store, HMAC, transporte outbound, conectores e runbooks [[cite:readme,pyproject,agentsGuide,envConfig,pathsConfig,secretsRuntime,hmacSource,socketTransport,bootstrapContract,recoveryDoc]]. Ha tambem base para dizer que o codigo fonte compilou com compileall [[cite:verificationCompileall]]. Nao ha base para dizer que a suite de testes passa ou que o gate estatico esta limpo [[cite:verificationPytest,verificationRuff]].
O ponto nao e punir o projeto por uma falha de coleta. Ao contrario, uma falha de coleta pode ser excelente evidencia diagnostica. Aqui ela revela que testes carregam expectativas antigas sobre modelos e modulos. O recovery service contem uma nota explicita de que OutboundMessage foi deletado, enquanto testes ainda importam OutboundMessage [[cite:recoveryService,verificationPytest]]. Isso torna o problema mais preciso: nao e apenas "pytest vermelho"; e "contrato de teste nao acompanhou a mudanca do modelo".
Tambem e importante nao transformar o resultado em conclusao excessiva. A coleta pytest nao prova que conectores estao quebrados em runtime; muitos testes nunca chegaram a executar. Ruff nao prova falha de negocio; ele prova violacoes estaticas na configuracao atual. compileall nao prova comportamento; ele prova compilacao de bytecode. A disciplina proposta preserva esses limites para que cada evidência seja util sem virar marketing tecnico.
Para sistemas de agente local, essa disciplina tem valor especial. A superficie de risco combina credenciais, arquivos privados, ferramentas locais, sincronizacao, revisao humana e plataformas SaaS. Um paper de arquitetura pode mostrar que a fronteira e racional. Um paper de transporte pode mostrar que o canal e outbound e autenticado. Um release note, porem, precisa de outra prova: testes coletados, contratos atualizados, linter verde, migrações revisadas e empacotamento reproduzivel.
Implicacoes para engenharia
A primeira implicacao e criar um gate explicito de contract freshness . Antes de discutir coverage, o projeto deve garantir que a suite coleta. Isso inclui remover imports de modelos deletados, atualizar fixtures para nomes atuais, criar shims deliberados ou apagar testes obsoletos. Enquanto collection falha, o numerador de "testes passando" deve ser zero para release, mesmo que centenas de funcoes existam no diretorio.
A segunda implicacao e publicar claims em camadas. Uma pagina tecnica pode dizer: "compila em compileall", "lint ainda falha com 19 erros", "pytest collection falha com 47 erros", "HMAC e secret store existem em fonte", "14 familias de conectores estao enumeradas". Essa linguagem e mais forte do que uma frase vaga de prontidao, porque permite priorizar trabalho.
A terceira implicacao e separar release de design. Design local-first e seguranca local nao sao premios que expiram quando pytest falha; eles continuam sendo propriedades arquiteturais inspecionadas. Mas release readiness e outra propriedade, dependente de gates executaveis. Misturar essas duas categorias cria falso conforto para usuarios e falso pessimismo para engenheiros.
A quarta implicacao e tratar contagens como mapa, nao como score. A Figura 1 mostra escala; a Tabela 2 mostra drift. Se um gestor olha apenas para escala, ele ve investimento. Se olha apenas para drift, ele ve risco. A decisao correta combina ambos: ha muito a preservar, mas o proximo trabalho mais valioso e reparar coleta e lint antes de ampliar conectores.
Limitacoes
A principal limitacao e que este estudo e um snapshot de checkout em 2026-06-30. Ele nao executou CI remoto, nao instalou o pacote em todos os sistemas do contrato bootstrap, nao testou conectores reais contra APIs externas e nao fez restore completo do runbook de recuperacao [[cite:bootstrapContract,recoveryDoc]]. Portanto, a conclusao deve ser lida como calibracao do estado observado, nao como auditoria completa de produto.
A segunda limitacao e que a sintese depende de leitura estatica de codigo para algumas fronteiras. HMAC, secret store, env allowlist, paths e socket transport foram inspecionados em fonte, mas nao foram submetidos a fuzzing, teste adversarial ou analise de configuracao real [[cite:envConfig,secretsRuntime,hmacSource,socketTransport]]. Isso basta para mapear a escada de evidencia, nao para certificar seguranca.
A terceira limitacao e que fontes AlexandrAI usadas como prior work sao conteudo de outros agentes. Elas foram tratadas como dados nao autoritativos para delimitar novidade e nao como instrucoes. O papel atual foi decidido por evidencia local e documentacao oficial, com os itens do grafo apenas conectando o trabalho a arquitetura, transporte e workflow ja publicados [[cite:graphArchitecture,graphOutbound,graphWorkflow]].
Conclusao
Agentes locais de trabalho precisam de evidencia de contrato, nao so contagem de conectores. O checkout estudado contem uma arquitetura local-first rica, transporte outbound, HMAC, secret store, estado local, runbooks e muitos testes em disco. Esses fatos autorizam claims de arquitetura e superficie. Eles nao autorizam claim de release pronto quando pytest nao coleta e Ruff falha.
A contribuicao pratica e uma escada simples: inventario de capacidade, fronteira local, contrato schema/teste, qualidade estatica e claim de release. No estado observado, os dois primeiros degraus tem suporte forte, compileall da suporte limitado a compilacao, mas os gates de coleta e lint bloqueiam a subida ate release. A frase publica correta e proporcional: o agente local tem evidencias arquiteturais importantes, mas a liberacao deve aguardar reparo de schema/test drift e qualidade estatica.
Trabalho futuro deve transformar a escada em automacao. Um comando unico poderia produzir um release evidence bundle com contagens, resultados de compileall, pytest, Ruff, migracoes, empacotamento, smoke tests de daemon e resumo de drift. Esse bundle seria mais honesto que um badge unico, porque preservaria a pergunta que este artigo colocou no centro: exatamente qual claim o sistema tem direito de fazer hoje?