Symbi Shell — Orquestração Interativa de Agentes¶

Status: Beta. O symbi shell é utilizável no dia a dia, mas a superfície de comandos, atalhos de teclado e formatos de persistência ainda podem mudar entre versões menores. Reporte issues em thirdkeyai/symbiont com o rótulo shell.

O symbi shell é uma interface de terminal baseada em ratatui para construir, orquestrar e operar agentes Symbiont. Ele se apoia no mesmo runtime que symbi up e symbi run, mas o expõe como uma sessão interativa com autoria conversacional, orquestração ao vivo e attach remoto.

Quando usar o shell¶

O shell é o ponto de entrada padrão para autoria. Os comandos não interativos são melhores em CI, jobs cron e pipelines de deploy.

Iniciando¶

symbi shell                    # inicia uma sessão nova
symbi shell --list-sessions    # mostra as sessões salvas e sai
symbi shell --resume <id>      # reabre uma sessão por UUID

--resume aceita tanto um UUID quanto um nome de snapshot salvo anteriormente com /snapshot.

Layout¶

O guia da branch de contenção descreve o novo fluxo de aprovação. Os turnos do orquestrador local e de frota agora exigem auditoria protegida, e as ferramentas de arquivo/comando usam o limite de contêiner selecionado. Configure montagens explícitas de workspace conforme descrito em workspace de shell governado. Os demais caminhos de runtime e do DSL canônico seguem em andamento.

O shell usa uma viewport inline que compartilha o terminal com o scrollback existente. De cima para baixo, você verá:

• Barra lateral de estrutura do projeto (alternável) — árvore de arquivos do projeto atual, destacando agentes, políticas e ferramentas.
• Linha do tempo de trace — cartões coloridos por fase ORGA para Observe, Reason, Gate e Act, transmitidos em tempo real durante chamadas ao LLM.
• Cartão do agente — os metadados, políticas e invocações recentes do agente atualmente selecionado.
• Linha de entrada — digite /command ou prosa livre. @mention traz caminhos e agentes via autocompletar fuzzy.

O destaque de sintaxe cobre o DSL do Symbiont, Cedar e manifestos ToolClad via gramáticas tree-sitter.

Sob o Zellij, o shell avisa que o scrollback acima da viewport inline pode não ser renderizado. Use um terminal nativo ou o tmux para fidelidade completa; atualmente não existe flag --full-screen.

Atalhos de teclado¶

Revisando ações retidas¶

Abra /gate ou pressione Ctrl+G. Selecione com ↑/↓ e então pressione Enter para abrir a requisição JSON escapada completa. Use ↑/↓ ou Page Up/Down para inspecionar argumentos longos. Pressione a para aprovar ou d para negar a requisição revisada. Esc volta para a lista e, em seguida, fecha o painel. Pressionar a em uma linha da lista pede primeiro uma revisão.

A seleção acompanha o ID da requisição entre atualizações. Alterações, expiração, remoção ou uma leitura de fila malsucedida invalidam a revisão. O painel mantém a resolução pendente até receber o resultado; um timeout reporta um desfecho desconhecido. Mudanças de conexão descartam revisões antigas e aguardam qualquer resolução pendente. Uma fila local configurada tem precedência sobre uma API de runtime conectada. Veja ciclo de vida de aprovação.

Catálogo de comandos¶

Os comandos são agrupados por propósito. Todo comando aceita help / --help / -h para imprimir um breve resumo de uso sem despachar para o orquestrador.

Autoria¶

Os comandos de autoria gravam em disco apenas após a validação passar. Violações de restrição são explicadas na linha do tempo de trace com erros precisos de linha.

Orquestração¶

Operações¶

Ferramentas e skills¶

Agendamento¶

/cron exige um attach remoto (ver abaixo). Os resultados do disparo mostram o UUID da invocação, o comando exato de repetição e o estado enfileirado/salvo/em andamento/não resolvido. Resultados salvos incluem uma prévia limitada da saída, os tokens reportados, o orçamento disponível/reservado/incerto e a referência do journal protegido. O histórico retém os detalhes completos. Guarde o UUID: omiti-lo solicita um novo trabalho. Uma resposta perdida não comprova falha; use o comando de repetição exibido ou inspecione /cron history <job-id> após reiniciar o shell. Efeitos desconhecidos exigem reconciliação. Veja recuperação de cron.

Canais¶

O gerenciamento de canais requer um attach remoto quando direcionado a um runtime implantado.

Segredos¶

Os segredos são criptografados em repouso com SYMBIONT_MASTER_KEY e escopados por agente.

Deploy (Beta)¶

Status: Beta. A stack de deploy é de agente único na edição OSS. Deploys multi-agente e gerenciados estão no roadmap.

/deploy lê o agente ativo e a configuração do projeto e produz um artefato de deploy reprodutível. Para topologias multi-agente, implante o coordenador e cada worker separadamente e conecte-os com mensagens entre instâncias (ver Arquitetura do Runtime).

Attach remoto¶

Use https:// para qualquer destino remoto ou de produção — o canal de attach transporta tokens de autenticação e tráfego de operações, portanto HTTP em texto plano só é apropriado para desenvolvimento local. O atalho local usa por padrão http://localhost:8080, e URLs fornecidas sem um esquema explícito recebem o prefixo http:// para preservar a ergonomia do desenvolvimento em loopback; para todo o resto, passe uma URL completa https://....

Uma vez conectado, /cron, /channels, /agents, /audit e a maioria dos comandos de operações agem no runtime remoto em vez do local. /secrets permanece local — segredos remotos ficam no armazenamento do runtime remoto.

Gerenciamento de sessão¶

As sessões são armazenadas em .symbi/sessions/<uuid>/. O shell dispara compactação automática quando o contexto ultrapassa o orçamento configurado.

Controles de sessão¶

Modo DSL¶

Pressione /dsl para alternar a linha de entrada para o modo DSL. No modo DSL, o shell analisa e avalia a entrada contra o interpretador DSL em processo, com autocompletar e erros apoiados por tree-sitter, sem rotear pelo orquestrador. Alterne de volta com /dsl novamente.

Restrições e validação¶

Os comandos de autoria aplicam um pipeline de validação local:

1. Os artefatos gerados são analisados contra a gramática do DSL Symbiont, Cedar ou ToolClad, conforme apropriado.
2. Um carregador de restrições verifica o resultado contra restrições em nível de projeto (por exemplo, capacidades proibidas, políticas obrigatórias).
3. Apenas após ambas as etapas terem sucesso o artefato é gravado em disco.

O LLM orquestrador pode ver os efeitos do arquivo de restrições através de erros de validação, mas não pode modificar o próprio arquivo — é o mesmo modelo de confiança usado pelo pipeline symbi tools validate.

Ressalvas Beta¶

As partes do shell a seguir ainda estão em desenvolvimento ativo e podem mudar sem janela de depreciação:

• /branch e /copy (ramificação de sessão) são comandos reservados e atualmente imprimem um stub "planejado para uma versão futura".
• /deploy cloudrun e /deploy aws são apenas de agente único.
• O formato de snapshot e o layout de .symbi/sessions/ podem mudar entre versões menores; use /export se precisar de transcripts duráveis.
• Heurísticas de autocompletar fuzzy e o layout da linha do tempo de trace são ajustados com base em feedback e podem mudar.

Se você precisa de uma superfície estável hoje, prefira symbi up, symbi run e a API HTTP — esses são cobertos pelas garantias de compatibilidade em SECURITY.md.

Veja também¶

• Introducao — instalação e symbi init
• Guia DSL — referência da linguagem de definição de agentes
• ToolClad — contratos declarativos de ferramentas
• Agendamento — motor cron e roteamento de entregas
• Modelo de seguranca — limites de confiança e aplicação de políticas