Terminal Session Manager

Terminal Session Manager minimalista, modular e orientado a agentes. O sistema mantém sessões de terminal persistentes independentemente do agente que as iniciou, gerencia execução de jobs, preserva histórico ordenado de eventos e opera dispositivos cadastrados sem expor credenciais em texto puro.

Este repositório implementa a arquitetura incremental descrita em spec.md.

Etapa 0 — Contrato e Esqueleto

Nesta etapa inicial foi construído o esqueleto executável e os contratos fundamentais de domínio, sem acoplamento a integrações de rede ou bibliotecas externas no núcleo:

• Modelos de Domínio:

  • Session e SessionStatus (created, running, waiting, completed, failed, closed, lost) com máquina de estados e validação estrita de transições.

  • Job e JobStatus (created, running, completed, failed, cancelled, timeout) com controle de ciclo de vida, códigos de saída e timestamps.

  • Device, DeviceType e ConnectionMethod para catálogo de inventário e parametrização segura de conexões.

  • CredentialRef e CredentialType com garantia estrutural de não armazenar nem vazar segredos ao agente ou histórico.

  • Event e EventType (stdin, stdout, stderr, state_change, system) com suporte a ordenação estrita (sequence, timestamp) e flags para mascaramento de dados sensíveis.

• Interfaces e Contratos (typing.Protocol):

  • SessionRepository, JobRepository, EventRepository (persistência).

  • TerminalTransport (adaptadores de transporte/PTY).

  • DeviceRepository (catálogo de dispositivos).

  • CredentialResolver (resolução interna de segredos para adaptadores).

• Erros de Domínio:

  • DomainError, InvalidStateTransitionError, InvalidStateError, EntityNotFoundError, SessionNotFoundError, JobNotFoundError, DeviceNotFoundError, CredentialNotFoundError e ValidationError.

Related MCP server: termcp

Etapa 1 — Sessão Local Mínima

Implementa um adaptador concreto de terminal/processo local e um orquestrador de sessão conectado ao ciclo de vida de Session:

• LocalProcessTransport (transports/local_process.py):

  • Implementa o protocolo TerminalTransport sobre subprocessos do sistema operacional.

  • Leitura não-bloqueante multithread com suporte a timeout real e isolamento cross-platform (Windows e Linux).

  • Operações de open, read, write, resize e close com liberação limpa de recursos.

• LocalSession (services/local_session.py):

  • Orquestra sessões de terminal acopladas a transportes via injeção de dependências (pluggable).

  • Sincroniza o ciclo de vida da entidade Session (CREATED -> RUNNING -> COMPLETED / FAILED / CLOSED) com o estado real do transporte.

  • Métodos de conveniência como read_text() e write().

Etapa 2 — Persistência e Histórico

Implementa persistência durável em SQLite (sqlite3 da biblioteca padrão) para sessões, jobs e histórico sequencial de eventos:

• Repositórios SQLite (persistence/sqlite.py):

  • SqliteSessionRepository: CRUD e upsert de metadados e ciclo de vida de sessões.

  • SqliteJobRepository: CRUD e vinculação de jobs com comandos e resultados.

  • SqliteEventRepository: persistência com unicidade estrita (session_id, sequence), ordenação e paginação por cursor (since_sequence, limit).

• Histórico e Proteção de Segredos (services/local_session.py):

  • Emissão e persistência automática de eventos STDIN, STDOUT, STDERR e STATE_CHANGE.

  • Suporte a write(..., is_sensitive=True) registrando eventos com is_masked=True e payload mascarado "[REDACTED]", impedindo vazamento de segredos para a base durável.

  • Recuperação completa de estado e histórico após reinício do serviço.

Etapa 3 — Jobs Assíncronos

Implementa execução, espera, cancelamento e monitoramento de jobs desacoplados da conexão contínua do cliente:

• Serviço de Jobs (JobService em services/job_service.py):

  • Submissão não-bloqueante (submit_job) com execução em thread dedicada e subprocesso isolado.

  • Vínculo a session_id e persistência contínua de eventos (STATE_CHANGE, STDIN, STDOUT, STDERR).

  • Espera com bloqueio sincronizado (wait_job) e cancelamento forçado com terminação de processo (cancel_job).

  • Controle de timeout por job com transição para TIMEOUT e encerramento de processo.

  • Reconciliação em reinício (recover_orphaned_jobs): jobs interrompidos por crash/reinício do serviço são detectados e marcados como FAILED, garantindo que nenhuma falha seja silenciosa.

Etapa 4 — Dispositivos e Credenciais

Implementa o catálogo persistente de dispositivos e a resolução segura de credenciais:

• Catálogo de Dispositivos (persistence/sqlite.py e services/device_service.py):

  • SqliteDeviceRepository: persistência durável de metadados não-secretos no SQLite (devices), com garantia de unicidade de nome/nickname e exclusão lógica (is_deleted).

  • DeviceService: gerenciamento completo de ciclo de vida (criação, consulta, atualização, desativação e remoção lógica) e resolução interna de dados de conexão (resolve_connection).

• Resolução Segura e Proteção em Repouso (services/credential_store.py):

  • ProtectedLocalCredentialStore: armazenamento local cifrado em SQLite (credential_secrets) usando derivação de chaves PBKDF2-HMAC-SHA256, cifra de fluxo autenticada e tags HMAC contra adulteração, mantendo zero dependências externas no runtime e nunca persistindo segredos em texto puro.

  • DelegatingCredentialResolver: resolução com delegação a provedores externos (ExternalCredentialProvider) e fallback local.

  • ResolvedConnection: objeto de trânsito em memória estrita, ocultando segredos em representações (__repr__) e inacessível a agentes.

• Integração à Sessão e Mascaramento de Saídas (services/local_session.py):

  • Associação injetável da resolução de dispositivo no fluxo de LocalSession.

  • Mascaramento dinâmico em saídas de terminal: qualquer eco ou saída contendo o segredo resolvido é redigido para [REDACTED] antes da persistência de eventos no histórico.

Etapa 5 — API HTTP

Expõe por HTTP os serviços essenciais do Terminal Session Manager através de uma arquitetura leve, minimalista e sem dependências externas:

• Coordenação de Sessões (SessionService em services/session_service.py):

  • Gerencia instâncias de sessões interativas em memória (LocalSession), integrando-as com SqliteSessionRepository, EventRepository e DeviceService.

  • Suporte à escrita (write_session) e leitura mascarada (read_session).

• Servidor HTTP e Roteador (APIServer e TSMRequestHandler em api/):

  • Servidor multi-threaded baseado em http.server.ThreadingHTTPServer da biblioteca padrão do Python.

  • Autenticação local configurável via Bearer token (Authorization: Bearer <token>) ou X-API-Key.

  • Mapeamento uniforme e sanitizado de exceções de domínio para códigos HTTP (400, 401, 404, 409, 500).

  • Endpoints Disponíveis:

    • POST /sessions: Cria e inicia nova sessão.

    • GET /sessions: Lista todas as sessões cadastradas.

    • GET /sessions/{id}: Consulta metadados da sessão.

    • POST /sessions/{id}/write: Escreve dados na sessão ativa (com flag is_sensitive).

    • POST /sessions/{id}/read: Lê dados do canal de saída da sessão.

    • POST /sessions/{id}/close: Encerra o canal de transporte da sessão.

    • GET /sessions/{id}/events?since_sequence=...&limit=...: Consulta paginada do histórico por cursor sequencial.

    • POST /sessions/{id}/jobs e POST /jobs: Submete um job assíncrono.

    • GET /jobs/{id}: Consulta status, exit_code e saídas do job.

    • GET /sessions/{id}/jobs: Lista jobs associados a uma sessão.

    • POST /jobs/{id}/wait: Aguarda conclusão com timeout.

    • POST /jobs/{id}/cancel: Cancela execução de um job em andamento.

    • POST /devices: Cadastra novo dispositivo no catálogo.

    • GET /devices: Lista dispositivos registrados (?only_active=true).

    • GET /devices/{id_or_name}: Consulta detalhes do dispositivo.

    • PATCH /devices/{id}: Atualiza parâmetros do dispositivo.

    • POST /devices/{id}/deactivate: Desativa logicamente um dispositivo.

    • GET /devices/{id_or_name}/resolve: Resolve parâmetros de conexão por nickname sem expor segredos (has_credential: true/false).

Etapa 6 — MCP com FastMCP

Expõe as capacidades essenciais do Terminal Session Manager para agentes de inteligência artificial através do protocolo Model Context Protocol (MCP), utilizando a biblioteca FastMCP:

• Servidor FastMCP (terminal_session_manager.mcp.server):

  • Execução via transporte padrão stdio, compatível com Claude Desktop, Cursor, Antigravity e clientes MCP em geral.

  • Reutiliza diretamente as instâncias de domínio (SessionService, JobService, DeviceService, SqliteEventRepository), garantindo paridade total com a API HTTP.

• Ferramentas MCP Expostas (17 Tools):

  • Sessões: create_session, get_session, list_sessions, write_session, read_session, close_session.

  • Histórico de Eventos: get_events (paginação por cursor com since_sequence e limit).

  • Jobs em Segundo Plano: submit_job, get_job, list_jobs, wait_job, cancel_job.

  • Catálogo e Resolução de Dispositivos: list_devices, get_device, resolve_device.

  • Transferência SCP: scp_upload, scp_download.

• Terminal Local Nativo (Sem Cadastro Prévio):

  • Para abrir uma sessão interativa no computador local onde o TSM roda, não é necessário cadastrar nenhum dispositivo. Omitir device_identifier ao chamar create_session (ou enviar POST /sessions com {"name": "local"}) dispara diretamente o LocalProcessTransport nativo do SO (cmd.exe no Windows ou /bin/sh no Linux/macOS). O catálogo de dispositivos é destinado a conexões remotas SSH.

• Garantias de Segurança:

  • resolve_device resolve internamente parâmetros de conexão, validando existência e atividade do dispositivo, indicando has_credential: true/false, mas omite estritamente segredos, senhas e chaves privadas da resposta ao agente.

• Configuração em Clientes MCP:

Adicione a configuração abaixo ao seu cliente MCP (por exemplo, claude_desktop_config.json ou arquivo de settings do IDE):

{
  "mcpServers": {
    "terminal-session-manager": {
      "command": "uv",
      "args": [
        "--directory",
        "d:/Projetos/TerminalPersistente",
        "run",
        "terminal-session-manager-mcp"
      ],
      "env": {
        "TSM_DB_PATH": ".tsm/tsm.db"
      }
    }
  }
}

Etapa 7 — Configuração e Endurecimento

Consolida a configuração centralizada, ciclo de vida operacional, reconciliação de recursos órfãos e rotação de credenciais protegidas:

• Configuração Centralizada (config.yml e config.py):

  • Carregamento declarativo via config.yml com defaults seguros para servidor, armazenamento, sessões, jobs e limites de eventos.

  • Sobrescrita estrita via variáveis de ambiente com prefixo TSM_:

    • TSM_CONFIG_PATH: Caminho alternativo para o arquivo de configuração.

    • TSM_SERVER_HOST: Endereço de escuta da API (padrão: 127.0.0.1).

    • TSM_SERVER_PORT: Porta TCP da API HTTP (padrão: 8000).

    • TSM_API_TOKEN: Token de autenticação da API HTTP.

    • TSM_DB_PATH: Caminho do banco SQLite (padrão: .tsm/tsm.db).

    • TSM_MASTER_KEY: Chave mestra criptográfica para proteção em repouso.

    • TSM_REQUIRE_AUTH: Obrigatoriedade de autenticação HTTP (true/false).

  • Validação Antecipada na Inicialização: Portas inválidas, timeouts nulos ou negativos, limites invertidos ou ativação de require_auth sem token informado levantam ConfigurationError imediato e abortam a execução com erro claro.

  • Segredos Fora do YAML: Nenhuma credencial ou chave secreta é persistida em texto puro no arquivo config.yml.

• Endurecimento de Ciclo de Vida e Reconciliação (app.py):

  • TSMApplication: Container central que injeta a mesma configuração e banco entre API, MCP e serviços.

  • startup(): Executa reconciliação de recursos interrompidos:

    • Jobs em execução durante falhas/reinícios são marcados como FAILED.

    • Sessões ativas em banco sem processo no runtime são marcadas como LOST.

  • shutdown(): Encerramento gracioso que fecha todas as sessões ativas (close_all()), cancela processos em segundo plano e fecha conexões SQLite de maneira determinística.

• Segurança e Rotação do Armazenamento de Credenciais:

  • rotate_master_key(new_master_key): Re-criptografa todas as credenciais sob uma nova chave mestra em transação atômica única no SQLite.

  • rotate_credential(ref_id, new_secret): Atualiza o segredo de uma credencial gerando novo sal, nonce e tag de autenticação HMAC.

  • Restrição de permissões de arquivo em sistemas POSIX (0o600 para banco e 0o700 para diretório).

Requisitos

• Python >= 3.11

• uv (gerenciador de dependências e ambientes)

Instalação

Clone o repositório e sincronize o ambiente virtual com uv:

uv sync

Execução

O utilitário CLI unificado terminal-session-manager oferece controle sobre todos os serviços e operações:

# Validar arquivo de configuração e banco de dados
uv run terminal-session-manager validate

# Iniciar o servidor HTTP REST API (com documentação Swagger em /docs)
uv run terminal-session-manager api

# Iniciar o servidor MCP (transporte stdio para Claude Desktop / Cursor / Antigravity)
uv run terminal-session-manager mcp

# Exibir status e visão geral
uv run terminal-session-manager status

# Ponto de entrada direto do MCP
uv run terminal-session-manager-mcp

# Gerenciador interativo de dispositivos (SSH, chaves, diagnóstico e transferências SCP)
uv run python scripts/manage_devices.py

# Verificar versão instalada
uv run terminal-session-manager --version

Etapa 8 — Transporte SSH

Implementa conexão e execução remota SSH para dispositivos cadastrados, reutilizando o contrato TerminalTransport, LocalSession, DeviceService, CredentialResolver, JobService, API HTTP e FastMCP:

• Adaptador SSH Pluggable (SSHTransport em transports/ssh.py):

  • Implementa o protocolo TerminalTransport (open, read, read_stderr, write, resize, close, is_alive, exit_code) utilizando paramiko>=3.5.0.

  • Suporte a autenticação por senha ou chave privada (RSA, Ed25519, ECDSA) a partir de dados resolvidos em memória pelo DeviceService / ProtectedLocalCredentialStore.

  • Modo interativo (invoke_shell com PTY) para sessões de terminal contínuas e modo de execução de comando (exec_command) para jobs remotos.

  • Verificação estrita de host keys contra known_hosts (paramiko.RejectPolicy), rejeitando silenciosamente qualquer host não confiável por padrão em modo seguro.

• Integração de Sessões e Jobs Remotos:

  • ConnectionMethod.SSH: Dispositivos registrados com método SSH têm o transporte SSHTransport instanciado automaticamente ao criar a sessão ou submeter um job informando apenas o nickname do dispositivo.

  • Mascaramento garantido: senhas e tokens resolvidos são proativamente censurados ([REDACTED]) no histórico de eventos persistidos no SQLite.

  • Falhas de rede, recusa de chave de host e erros de autenticação resultam em estados previsíveis (FAILED) sem vazar credenciais em mensagens de erro ou logs.

Etapa 9 — Transferência SCP

Implementa suporte modular a transferências seguras de arquivos entre o host TSM e dispositivos SSH remotos, utilizando a biblioteca scp>=0.15.0 integrada à infraestrutura existente:

• Serviço Modular (SCPService em services/scp_service.py):

  • Desacoplado de TerminalTransport, tratando transferências de arquivos com semântica dedicada.

  • Suporta operações de upload (local -> remoto) e download (remoto -> local).

  • Cada transferência é registrada e gerenciada como um Job assíncrono persistente no SQLite, emitindo eventos de auditoria sequenciados (STATE_CHANGE, STDOUT, STDERR).

  • Suporta cancelamento limpo (cancel_transfer) e timeouts de transferência com transição de status determinística (JobStatus.CANCELLED, JobStatus.TIMEOUT).

  • Verificação estrita de known_hosts e strict_host_key_checking, validação de integridade de caminhos locais e remotos e sanitização de segredos em qualquer saída ou erro.

• Endpoints na API HTTP REST:

  • POST /scp/upload: Dispara transferência de envio de arquivo local para destino remoto.

  • POST /scp/download: Dispara transferência de recebimento de arquivo remoto para storage local.

# Exemplo de Upload via cURL (retorna HTTP 202 com os metadados do Job)
curl -X POST http://127.0.0.1:8000/scp/upload \
  -H "Content-Type: application/json" \
  -d '{
    "device": "maclinux",
    "local_path": "C:/dados/config.yml",
    "remote_path": "/tmp/config.yml",
    "timeout": 30.0
  }'

# Exemplo de Download via cURL
curl -X POST http://127.0.0.1:8000/scp/download \
  -H "Content-Type: application/json" \
  -d '{
    "device": "maclinux",
    "remote_path": "/etc/os-release",
    "local_path": "C:/dados/os-release.txt",
    "timeout": 30.0
  }'

# Acompanhar conclusão do Job de transferência
curl http://127.0.0.1:8000/jobs/{job_id}

• Ferramentas FastMCP para Agentes (17 Tools):

  • scp_upload e scp_download: Permitem a agentes LLM enviar e baixar arquivos em máquinas remotas informando apenas o nickname do dispositivo (ex: maclinux).

• Gerenciador Interativo (scripts/manage_devices.py):

  • Opção 9) Transferência e teste de arquivos SCP (Upload / Download) no menu interativo para transferir arquivos e executar teste rápido de conectividade SCP sem precisar escrever código.

Testes

A suíte de testes automatizados valida modelos, transportes locais e SSH, transferências SCP, persistência durável, ciclo de vida de jobs, catálogo e resolução de dispositivos, autenticação e documentação OpenAPI:

uv run pytest -v

Todos os 150 testes são autossuficientes e executam sem qualquer dependência de hardware externo, portas de rede abertas ou servidores SSH físicos (utilizando mocks de cliente Paramiko e SCPClient).

Estrutura do Projeto

.
├── pyproject.toml                         # Configuração uv e dependências
├── README.md                              # Documentação de uso e instalação
├── help.md                                # Guia operacional completo
├── skill.md                               # Especificação das ferramentas FastMCP para agentes
├── spec.md                                # Especificação completa do produto
├── scripts/
│   └── manage_devices.py                  # Gerenciador CLI interativo (CRUD, SSH, chaves, SCP)
├── reports/
│   ├── 01-contrato-e-esqueleto.md         # Relatório da Etapa 0
│   ├── 02-sessao-local.md                 # Relatório da Etapa 1
│   ├── 03-persistencia-e-historico.md     # Relatório da Etapa 2
│   ├── 04-jobs-assincronos.md             # Relatório da Etapa 3
│   ├── 05-catalogo-dispositivos.md        # Relatório da Etapa 4
│   ├── 06-api-http.md                     # Relatório da Etapa 5
│   ├── 07-mcp.md                          # Relatório da Etapa 6
│   ├── 08-transporte-ssh.md               # Relatório da Etapa 8
│   └── 09-scp.md                          # Relatório da Etapa 9 (Transferência SCP)
├── src/
│   └── terminal_session_manager/
│       ├── __init__.py                    # Exportações públicas de domínio
│       ├── errors.py                      # Exceções de domínio e transporte
│       ├── main.py                        # Ponto de entrada CLI
│       ├── api/                           # API HTTP REST e OpenAPI
│       │   ├── handler.py                 # Handlers HTTP (/sessions, /jobs, /devices, /scp)
│       │   ├── openapi.py                 # Esquemas e especificação OpenAPI
│       │   └── server.py                  # Servidor HTTP multithread com autenticação
│       ├── mcp/                           # Servidor FastMCP
│       │   └── server.py                  # 17 ferramentas MCP para agentes LLM
│       ├── models/                        # Entidades e máquinas de estado
│       │   ├── credential.py              # CredentialRef, CredentialType
│       │   ├── device.py                  # Device, DeviceType, ConnectionMethod
│       │   ├── event.py                   # Event, EventType
│       │   ├── job.py                     # Job, JobStatus, JOB_TRANSITIONS
│       │   └── session.py                 # Session, SessionStatus, SESSION_TRANSITIONS
│       ├── transports/                    # Adaptadores de transporte
│       │   ├── local_process.py           # LocalProcessTransport (subprocess + non-blocking queue)
│       │   └── ssh.py                     # SSHTransport (Paramiko SSH interativo e comando)
│       ├── services/                      # Orquestradores de domínio
│       │   ├── device_service.py          # DeviceService (catálogo e resolução de dispositivos)
│       │   ├── job_service.py             # JobService (execução assíncrona em background)
│       │   ├── local_session.py           # LocalSession controller
│       │   └── scp_service.py             # SCPService (upload/download assíncrono via SCP)
│       └── persistence/                   # Repositórios duráveis (SQLite)
│           ├── sqlite.py                  # SqliteStorage, Repositories
│           └── protected_store.py         # ProtectedLocalCredentialStore (cofre criptografado)
└── tests/
    ├── test_contracts.py                  # Verificação dos protocolos em memória
    ├── test_device_and_credential.py      # Testes de Device e CredentialRef
    ├── test_event.py                      # Testes de Event e ordenação estrita
    ├── test_job.py                        # Testes de Job e transições de ciclo de vida
    ├── test_job_service.py                # Testes de JobService assíncrono
    ├── test_local_session.py              # Testes do controlador LocalSession
    ├── test_local_transport.py            # Testes do adaptador LocalProcessTransport
    ├── test_ssh_transport.py              # Testes do adaptador SSHTransport
    ├── test_scp_service.py                # Testes do serviço SCPService
    ├── test_api_devices.py                # Testes de API HTTP para dispositivos
    ├── test_api_scp.py                    # Testes de API HTTP e MCP para SCP
    ├── test_persistence_lifecycle.py      # Testes de reinício, saída volumosa e segredos
    ├── test_session.py                    # Testes de Session e máquina de estados
    └── test_sqlite_persistence.py         # Testes dos repositórios SQLite