Terminal no Kavor: execução visível para humano e agente

Um Terminal é um shell real no Canvas. Você continua digitando comandos, acompanhando logs e operando ferramentas conhecidas; o Kavor acrescenta contexto, observabilidade e colaboração ao redor dessa sessão.

O objetivo não é esconder execução atrás de um botão. É permitir que humano e CodingAgent trabalhem no mesmo ambiente visível, cada um sob limites claros.

Ver imagem em tamanho original

O que o Terminal possui

Cada Terminal possui sua própria sessão, shell e histórico de tela retido pelo Node. Abrir mais de um Terminal é útil quando as responsabilidades são distintas: aplicação, testes, banco, logs ou uma máquina remota já aberta por você.

O processo continua sendo um processo de shell. O Kavor não converte texto exibido em sucesso, não transforma todo comando em uma tarefa persistida e não presume que uma ferramenta terminou apenas porque imprimiu uma mensagem otimista.

O que ele faz sozinho

Sem Connections, o Terminal já mantém o shell dentro do Workspace e evita quebrar o fluxo para alternar entre janelas externas. Você pode executar comandos interativos, observar processos longos e manter sessões diferentes no mesmo Canvas.

Connections acrescentam participantes e fontes canônicas sem substituir o shell.

O que ele ganha no grafo

O Terminal aceita quatro pares diretos:

Um CodingAgent não precisa estar diretamente ligado ao Terminal quando ambos já pertencem ao mesmo componente alcançável. A Connection direta, porém, é onde um Guardrail terminal_read_only pode declarar e impor que aquele agente somente observe.

Assistência sem disputar o teclado

O Terminal é uma superfície compartilhada com prioridade para o humano. Um CodingAgent não deve despejar um comando sobre texto que você ainda está digitando. Quando a entrada não está segura, a operação aguarda ou retorna uma condição que precisa ser tratada, em vez de corromper sua linha.

Para trabalho iniciado pelo agente, o Kavor correlaciona o comando com seu acompanhamento. O agente pode esperar por aquele resultado, cancelar a execução correspondente ou consultar o estado visível. Para uma sessão já existente, ele escolhe a visão adequada: tela atual, tail limitado ou buffer completo.

Essa distinção importa. Ler a tela responde “o que o humano vê agora?”. Ler um tail ajuda com logs recentes. O buffer completo serve para uma investigação que realmente precisa do histórico, sem transformar toda interação num dump automático de contexto.

Use Files e Specifications sem copiar caminhos

Connections com File ou Specification recebem um nome de variável de ambiente. O valor é o caminho absoluto canônico da fonte, nunca seu conteúdo.

Exemplos:

node "$IMPORT_SCRIPT" --input "$SOURCE_FILE"

markdownlint "$SPECIFICATION_FILE"

As variáveis são aplicadas quando a sessão do Terminal inicia. Se uma Connection ou seu parâmetro mudar com o shell aberto, a nova configuração aguarda o reinício daquela sessão. TERM e COLORTERM são reservadas pelo emulador.

Use nomes que expressem responsabilidade, como CHECK_SQL, SPECIFICATION_FILE ou IMPORT_SCRIPT. Uma variável genérica como FILE perde significado quando o grafo cresce.

Cole arquivos e imagens na entrada da sessão

Você pode usar um arquivo ou uma captura de tela sem digitar seu caminho manualmente. A colagem no Terminal e na superfície de terminal de um CodingAgent insere uma referência ao arquivo, preparada para a sessão — não o conteúdo binário dentro da linha de comando.

1. Copie um arquivo pelo gerenciador de arquivos do sistema, ou uma imagem PNG/JPEG para o clipboard.
2. Dê foco à entrada de uma sessão aberta no Terminal ou CodingAgent.
3. Use a ação Paste do menu de contexto ou o atalho de colagem da superfície.
4. Confira o caminho inserido e complete o comando ou pedido antes de enviá-lo.

Por exemplo, copie uma captura de um formulário com erro e cole na entrada do CodingAgent. Depois, peça:

Use a imagem referenciada para comparar o formulário com a implementação. Reproduza o problema no WebBrowser conectado e descreva a diferença observada antes de alterar código.

O Kavor disponibiliza a referência; a capacidade de interpretar a imagem depende do provider. Colar uma imagem não é o mesmo que renderizá-la inline no Terminal nem garante que o harness a tenha analisado.

Quando o clipboard contém a própria imagem, o Kavor salva uma cópia local no perfil do aplicativo e insere o caminho desse arquivo. Imagens maiores que 20 MB não são aceitas. Quando contém referências a arquivos existentes, usa esses caminhos. Sem arquivos ou imagens, o texto continua sendo colado como texto.

Essa ação não cria um File no Canvas, não cria uma Connection e não fornece uma variável de ambiente. Para um recurso que deve permanecer explícito no grafo, use File; para um caminho fornecido ao shell por Connection, use o procedimento da seção anterior. Confira conteúdo sensível antes de enviá-lo ao provider.

Também é importante o foco: atalhos dentro de um Terminal, editor ou página pertencem àquela superfície. Para copiar ou mover Nodes, dê foco ao Canvas e siga o procedimento de grafos.

Três padrões úteis

Implementação acompanhada de evidência

Conecte Specification, CodingAgent e Terminal. O agente executa apenas as verificações relevantes, preserva a saída necessária e registra o resultado como output. Você acompanha o mesmo shell e pode intervir.

Diagnóstico de uma aplicação em execução

Mantenha a aplicação em um Terminal e os testes ou consultas em outro. Um CodingAgent alcançável consulta a tela ou o tail necessário, formula uma hipótese e executa um comando delimitado. Logs continuam visíveis para você; a investigação não vira uma caixa-preta.

Operação remota supervisionada

Você abre uma sessão SSH no Terminal. Um CodingAgent pode ajudar a interpretar estado e sugerir ou executar comandos quando autorizado. O Kavor não vira um serviço remoto: credenciais, conexão, shell e supervisão continuam na sessão que você abriu.

Um grafo prático

Specification — Maintainer — Reviewer
                     │
                  Terminal
                     │
              File: check.sql

O Maintainer usa a Specification como contrato, o File como fonte explícita e o Terminal para executar a verificação. O Reviewer avalia resultado e evidências. A Connection File + Terminal fornece CHECK_SQL; o shell pode usá-la sem copiar um caminho manualmente.

Um pedido inicial melhor

Diagnostique a falha usando somente o contexto alcançável. Leia primeiro a tela atual do Terminal. Execute um comando por vez, explique o que ele discrimina e preserve a saída necessária para o Reviewer. Não interrompa um processo iniciado por mim e pare antes de qualquer ação destrutiva ou que amplie o escopo da Specification.

Para monitoramento:

Acompanhe somente o tail necessário deste Terminal. Avise quando houver evidência nova; não trate ausência de novas linhas como sucesso e não deixe um watcher iniciado apenas para sua investigação rodando depois de concluir.

Exemplo: investigue uma falha sem reiniciar tudo

Uma aplicação web roda no Terminal App, mas um formulário não conclui o envio. Mantenha esse processo aberto e use outro Terminal, Checks, para as verificações. Conecte o CodingAgent aos recursos necessários e peça:

Observe a tela atual do Terminal App e reproduza o erro no WebBrowser conectado. Correlacione o horário da ação com os logs. Não reinicie o servidor nem interrompa meu processo. Use o Terminal Checks se precisar de um comando separado e registre o que cada verificação confirmou ou descartou.

Se o projeto for Node.js, uma verificação simples no Terminal Checks pode confirmar o ambiente:

node --version

Para investigar a aplicação, o agente deve escolher os comandos reais do projeto depois de consultar seus scripts e convenções. Um comando genérico copiado de outra stack não comprova nada sobre a falha.

O resultado esperado é uma relação entre ação, saída observada e causa demonstrada ou hipótese delimitada. Por exemplo: “o request chegou ao servidor, mas retornou erro de validação” é mais útil do que “o servidor parece ruim”. Depois de uma correção autorizada, repita o mesmo caminho para comparar os resultados.

Acompanhar um processo que você iniciou

Você também pode iniciar um build e pedir ao CodingAgent para acompanhar apenas a saída relevante:

Acompanhe o build neste Terminal. Use a saída recente e consulte mais histórico apenas quando necessário. Informe o resultado que conseguir observar e as mensagens que justificam sua conclusão. Não envie comandos nem encerre o processo enquanto ele estiver executando.

O pedido coordena a colaboração; um Guardrail terminal_read_only pode restringir as operações do Kavor à observação. Você continua usando o shell, enquanto o agente ajuda a interpretar o estado visível.

Guardrail de somente leitura

terminal_read_only mantém inspeção e bloqueia operações que alterariam a sessão, o processo ou a entrada naquela Connection direta. É útil para um Reviewer que precisa ler evidências, mas não deve executar correções.

O Guardrail pertence ao par. Ele não transforma o Terminal inteiro numa superfície globalmente somente leitura e não substitui as permissões do sistema operacional.

Limites que importam

• Saída de Terminal não é prova automática de que um efeito externo ocorreu corretamente.
• Um CodingAgent não deve interferir em entrada humana inacabada.
• Comandos destrutivos continuam exigindo escopo exato e autorização adequada.
• Uma variável fornecida por Connection contém um caminho, não conteúdo ou segredo.
• Alterações nessas variáveis exigem reiniciar a sessão do Terminal para entrar no ambiente.
• Schedule entrega apenas a uma sessão aberta. Na inicialização, o Kavor pode restaurar um Terminal marcado para permanecer aberto quando ele é alvo de um Trigger em execução, mas não recupera automaticamente comandos perdidos enquanto o aplicativo estava fechado.
• Um processo iniciado para investigação deve ser encerrado quando não precisa permanecer para o humano.
• Vários Terminals ajudam quando representam responsabilidades reais; duplicá-los sem propósito apenas fragmenta o estado operacional.

Antes de delegar um comando

Confirme:

• este é o Terminal correto para a responsabilidade?
• existe entrada humana em andamento?
• o comando é delimitado e reversível quando necessário?
• o agente sabe qual saída constitui evidência?
• o buffer necessário é tela, tail ou histórico completo?
• Files e Specifications usam nomes de variável compreensíveis?
• o Reviewer deve observar sob terminal_read_only?
• está claro quando interromper, esperar ou pedir sua decisão?

O Terminal ganha valor no grafo quando execução permanece real, contexto fica explícito e supervisão não desaparece.

Consulte a matriz de Connections, aprenda como CodingAgents enxergam e constroem o Canvas ou configure Schedule para comandos e prompts.