---
id: AGD-0073
ticket: studio-dev-embedded-terminal
title: Terminal embutido no DEV do Studio
status: open
created: 2026-09-29
resolved:
decision:
tags: [studio, dev, terminal]
---

## Pain

Domain owner: `studio`

O desenvolvedor precisa alternar entre Studio e um terminal externo para executar ferramentas e conversar com um agente de código. Um terminal embutido no DEV, iniciado na raiz do projeto, pode manter execução do agente, concessão de controle e observação do runtime no mesmo ambiente.

## Context

Owner: `studio`, subdomínio workspace DEV, apresentação e lifecycle de processos locais. Worker: Agenda Worker.

O usuário pediu uma agenda separada e aberta para explorar um terminal semelhante ao terminal embutido do IntelliJ. Esta discussão se relaciona à DSC-0070 (conexão MCP persistente), mas não condiciona sua entrega nem amplia implicitamente seu escopo.

Studio usa JavaFX, com API/Core independentes da UI e adaptadores de infraestrutura para processos externos. O terminal hospedaria o cliente externo do agente; o MCP continuaria sendo o canal para os serviços autorizados do Studio. A escolha de modelo, login e conversa continuaria pertencendo ao cliente externo.

Aplicações interativas precisam de emulação de terminal e PTY, incluindo cursor, sequências ANSI, redimensionamento e sinais. Apenas capturar stdout em uma área de texto não atende ao uso proposto. JediTerm/Pty4J são candidatos a avaliar; a integração Swing/JavaFX e o empacotamento por plataforma ainda não foram validados neste repositório.

## Open Questions

- [ ] Qual layout no DEV preserva a visibilidade de concessão/revogação e da observação do runtime: painel inferior, lateral ou aba?
- [ ] Uma sessão por projeto atende à primeira entrega ou múltiplas abas são necessárias?
- [ ] Quais SOs e arquiteturas entram no primeiro aceite?
- [ ] Qual componente oferece compatibilidade suficiente com a interface interativa do Codex, teclado, Unicode, clipboard e redimensionamento?
- [ ] Como selecionar shell e carregar PATH/ambiente quando Studio é iniciado pelo launcher gráfico?
- [ ] Qual lifecycle ao sair do DEV, fechar o projeto e encerrar Studio? Recomenda-se preservar sessão ao trocar de workspace e explicitar encerramento de processos ao fechar projeto.
- [ ] O primeiro fluxo apenas abre shell ou também oferece ação explícita para iniciar um cliente de agente instalado?
- [ ] Como apresentar a independência entre terminal e controle MCP? Revogar autoridade do Studio não interrompe automaticamente shell ou escritas externas.

## Options

### Option A - Componente de terminal JVM existente e PTY

- **Approach:** avaliar JediTerm/Pty4J, integrando apresentação ao JavaFX e mantendo supervisão de processos em infraestrutura.
- **Pro:** reutiliza emulação e integração com processos locais existentes; evita implementar protocolo de terminal.
- **Con:** exige validar interop Swing/JavaFX, foco, atalhos, renderização e bibliotecas nativas por plataforma.
- **Maintainability:** acompanhar dependências, licenças e compatibilidade; manter contratos do Studio livres de tipos dessas bibliotecas.

### Option B - Terminal renderizado em WebView com PTY local

- **Approach:** avaliar um emulador de terminal web embutido, conectado por um adapter ao processo local.
- **Pro:** alternativa de apresentação sem interop Swing; permite avaliar componentes web existentes.
- **Con:** acrescenta engine web e bridge de eventos/bytes, com custo de foco, clipboard e distribuição; compatibilidade e enquadramento arquitetural precisam de avaliação explícita.
- **Maintainability:** adiciona dependências e integração JVM/JavaScript. Não pressupõe autorização para servidor HTTP adicional ou substituição da UI JavaFX.

### Option C - Atalho para terminal externo na raiz do projeto

- **Approach:** Studio abre o terminal do sistema no diretório correto.
- **Pro:** menor superfície de emulação e preserva preferências do usuário.
- **Con:** mantém troca de janelas e não entrega o terminal embutido solicitado.
- **Maintainability:** integração de lançamento específica por SO; alternativa de comparação ou fallback, não equivalente ao objetivo.

## Tradeoffs

Reutilizar um componente reduz esforço inicial, mas não elimina validação de teclado, seleção, clipboard, fontes, escala e interfaces de tela inteira. Uma primeira versão útil parece de complexidade moderada; paridade com uma IDE madura é um escopo bem maior. Nenhum prazo está estabelecido sem validar integração e plataformas.

Manter sessões entre trocas de workspace favorece continuidade, mas exige separar lifecycle do processo e lifecycle do painel visual. Encerrar Studio pode interromper o agente hospedado e operações no shell; esse comportamento precisa ser claro e diferente de apenas revogar acesso aos serviços MCP.

## Recommendation

Explorar a opção A primeiro, sem selecionar biblioteca definitivamente. Propor como primeiro escopo uma sessão por projeto dentro do DEV, shell configurável com padrão do sistema, cwd inicial na raiz do projeto, copiar/colar, scrollback limitado, redimensionamento, sinais e encerramento controlado.

Conservar o cliente do agente como programa externo hospedado no terminal, consumindo a integração MCP discutida na DSC-0070. Abrir o terminal não concede autoridade nem instala/inicia um agente sem ação explícita do usuário. Não ampliar a proposta para chat próprio, gestão de modelos ou credenciais de provedores.

## Discussion

### Evidências necessárias para uma futura decision

- Abrir shell na raiz correta, inclusive caminhos com espaços, e localizar executáveis no ambiente da aplicação empacotada.
- Executar Codex interativamente e verificar foco, atalhos, Unicode, paste, scroll e resize sem corromper a tela.
- Trocar de workspace e voltar sem perder a sessão, caso esse lifecycle seja aceito.
- Definir tratamento de Ctrl+C, término do shell, processos filhos, fechamento de projeto e fechamento do Studio.
- Validar independência de autoridade: terminal disponível não representa grant; revogação MCP não é encerramento de shell.
- Verificar distribuição dos componentes nativos e cobertura por SO/arquitetura escolhidos.

### Referências e possíveis alvos de propagação

- DSC-0070 / [AGD-0072](../../lessons/DSC-0070-studio-persistent-mcp-connector/LSN-0077-integrated-mcp-stable-setup-and-ephemeral-access.md): configuração MCP do projeto, descoberta e conector oficial.
- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md`: localização e comportamento visual.
- `docs/specs/studio/9. Studio Core and Adapter Architecture Specification.md`: contratos neutros, adaptadores e lifecycle.
- `docs/specs/studio/10. DEV and Automation Specification.md`: composição do DEV e separação de autoridade.
- `docs/specs/studio/8. Project-Local Studio State Specification.md`: somente se houver configurações/restauração a definir; não presumir persistência de processos, conteúdo de terminal ou tarefas.
- Candidatos técnicos: https://github.com/JetBrains/jediterm e https://github.com/JetBrains/pty4j, consultados na discussão inicial; seleção requer avaliação específica.

Os caminhos documentais refletem a árvore atual. Esta agenda não altera specs ou código.

## Resolution

Aberta a pedido do usuário. Nenhuma biblioteca, arquitetura final ou implementação foi aprovada.

## Next Step

Retomar quando o terminal for priorizado: fechar UX, lifecycle e plataformas, avaliar os candidatos e reunir evidências de compatibilidade. Depois convergir para uma decision própria, mantendo a DSC-0070 independente.
