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.

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.

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.

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 ativa e não recupera automaticamente comandos perdidos enquanto o Kavor 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.