Compatibilidade do SDK e da CLI

Overview

O SDK do Copilot se comunica com a CLI por meio do protocolo JSON-RPC. Os recursos devem ser explicitamente expostos por meio desse protocolo para estarem disponíveis no SDK. Muitos recursos interativos da CLI são específicos do terminal e não estão disponíveis programaticamente.

Comparação de funcionalidades

✅ Disponível no SDK

Característica	Método SDK	Notes
Gerenciamento de Sessão
Criar sessão	`createSession()`	Suporte completo à configuração
Retomar sessão	`resumeSession()`	Com espaços de trabalho de sessão infinitos
Desconectar sessão	`disconnect()`	Liberar recursos na memória
Destruir sessão (preterida)	`destroy()`	Use `disconnect()` em vez disso
Excluir sessão	`deleteSession()`	Remover do armazenamento
Listar sessões	`listSessions()`	Todas as sessões armazenadas
Obter a última sessão	`getLastSessionId()`	Para retomar rapidamente
Obter sessão em primeiro plano	`getForegroundSessionId()`	Coordenação de várias sessões
Configurar sessão em primeiro plano	`setForegroundSessionId()`	Coordenação de várias sessões
Messaging
Enviar mensagem	`send()`	Com anexos
Enviar e aguardar	`sendAndWait()`	Blocos até a conclusão
Direção (modo imediato)	`send({ mode: "immediate" })`	Injetar no meio da rotação sem anular
Fila (modo de enfileiramento)	`send({ mode: "enqueue" })`	Buffer para processamento sequencial (padrão)
Anexos de arquivo	`send({ attachments: [{ type: "file", path }] })`	Imagens codificadas automaticamente e redimensionadas
Anexos de diretório	`send({ attachments: [{ type: "directory", path }] })`	Anexar contexto de diretório
Obter histórico	`getEvents()`	Todos os eventos de sessão
Abortar	`abort()`	Cancelar solicitação em voo
Ferramentas
Registrar ferramentas personalizadas	`registerTools()`	Suporte completo ao esquema JSON
Controle de permissão da ferramenta
`onPreToolUse` Gancho	Permitir/negar/perguntar
Modificação do resultado da ferramenta
`onPostToolUse` Gancho	Transformar resultados
Ferramentas disponíveis/excluídas
`availableTools`, `excludedTools` configuração	Filtrar ferramentas
Modelos
Listar modelos	`listModels()`	Com funcionalidades, cobrança, política
Definir modelo (na criação)
`model` na configuração da sessão	Por sessão
Modelo de Switch (durante a sessão)	`session.setModel()`	Também via `session.rpc.model.switchTo()`
Obter o modelo atual	`session.rpc.model.getCurrent()`	Consultar o modelo ativo
Esforço de raciocínio
`reasoningEffort` Configuração	Para modelos com suporte
Modo de agente
Obter o modo atual	`session.rpc.mode.get()`	Retorna o modo atual
Configurar modo	`session.rpc.mode.set()`	Alternar entre os modos
Gerenciamento de Planos
Plano de leitura	`session.rpc.plan.read()`	Obter o conteúdo e o caminho de plan.md
Plano de atualização	`session.rpc.plan.update()`	Escrever conteúdo do plan.md
Excluir plano	`session.rpc.plan.delete()`	Remover plan.md
Arquivos do Workspace.
Listar arquivos do espaço de trabalho	`session.rpc.workspace.listFiles()`	Arquivos na área de trabalho da sessão
Ler arquivo de espaço de trabalho	`session.rpc.workspace.readFile()`	Ler o conteúdo do arquivo
Criar arquivo de workspace	`session.rpc.workspace.createFile()`	Criar arquivo no workspace
Autenticação
Obter o status de autenticação	`getAuthStatus()`	Verificar o estado de logon
Usar token
Opção `gitHubToken`	Autenticação programática
Conectividade
Ping	`client.ping()`	Verificação de saúde com carimbo de data e hora do servidor
Obter o status do servidor	`client.getStatus()`	Informações sobre a versão do protocolo e o servidor
Servidores MCP
Servidores locais/stdio
`mcpServers` Configuração	Criar processos
HTTP/SSE remoto
`mcpServers` Configuração	Conectar-se a serviços
Hooks
Uso de pré-ferramenta	`onPreToolUse`	Permissão, modificar args
Após o uso da ferramenta (sucesso)	`onPostToolUse`	Modificar resultados
Após o uso da ferramenta (falha)	`onPostToolUseFailure`	Monitorar chamadas de ferramentas com falha, injetar orientações para nova tentativa
Solicitação do usuário	`onUserPromptSubmitted`	Modificar prompts
Início/término da sessão
`onSessionStart`, `onSessionEnd`	Ciclo de vida com origem/motivo
Tratamento de erros	`onErrorOccurred`	Manipulação personalizada
Eventos
Todos os eventos de sessão
`on()`, `once()`	Mais de 40 tipos de evento
Streaming	`streaming: true`	Eventos delta
Configuração da Sessão
Agentes personalizados
`customAgents` Configuração	Definir agentes especializados
Mensagem do sistema
`systemMessage` Configuração	Acrescentar ou substituir
Provedor personalizado
`provider` Configuração	Suporte ao BYOK
Sessões infinitas
`infiniteSessions` Configuração	Compactação automática
Manipulador de permissões	`onPermissionRequest`	Aprovar/negar solicitações
Manipulador de entrada do usuário	`onUserInputRequest`	Manipular ask_user
Habilidades
`skillDirectories` Configuração	Habilidades personalizadas
Habilidades desabilitadas
`disabledSkills` Configuração	Desabilitar habilidades específicas
Diretório de configuração
`configDir` Configuração	Sobrescrever a localização de config padrão
Nome do cliente
`clientName` Configuração	Identificar o aplicativo no User-Agent
Diretório de trabalho
`workingDirectory` Configuração	Definir o cwd da sessão
Experimental
Gerenciamento de agentes	`session.rpc.agent.*`	Listar, selecionar, deselecionar, obter o agente atual
Modo de frota	`session.rpc.fleet.start()`	Execução paralela de sub-agente; ver Modo de frota
Compactação manual	`session.rpc.history.compact()`	Acionar compactação sob demanda
Truncamento de histórico	`session.rpc.history.truncate()`	Remover eventos de um ponto em diante
Bifurcação de sessão	`server.rpc.sessions.fork()`	Criar uma bifurcação de uma sessão a partir de um ponto do histórico

❌ Não disponível no SDK (somente CLI)

Característica	Comando/opção da CLI	Reason
Exportação de sessão
Exportar para arquivo
`--share`, `/share`	Não está no protocolo
Exportar como gist
`--share-gist`, `/share gist`	Não está no protocolo
Interface do usuário interativa
Comandos de barra
`/help`, `/clear`, `/exit`, etc.	Somente TUI
Caixa de diálogo seletor de agente	`/agent`	Interface do usuário interativa
Caixa de diálogo do modo Diff	`/diff`	Interface do usuário interativa
Caixa de diálogo de feedback	`/feedback`	Interface do usuário interativa
Seletor de tema	`/theme`	Interface do usuário do terminal
Seletor de modelo	`/model`	Interface do usuário interativa (use o SDK `setModel()` em vez disso)
Copiar para a área de transferência	`/copy`	Específico do terminal
Gerenciamento de contexto	`/context`	Interface do usuário interativa
Pesquisa & Histórico
Pesquisa profunda	`/research`	Fluxo de trabalho TUI com pesquisa na Web
Ferramentas de histórico de sessão	`/chronicle`	Reunião de pé, dicas, melhorar, reindexar
Recursos do terminal
Saída de cor	`--no-color`	Específico do terminal
Modo de leitor de tela	`--screen-reader`	Accessibility
Renderização de difusão avançada	`--plain-diff`	Renderização de terminal
Faixa de inicialização	`--banner`	Elemento visual
Modo de transmissão	`/streamer-mode`	Modo de exibição TUI
Buffer de tela alternativo
`--alt-screen`, `--no-alt-screen`	Renderização de terminal
Suporte ao mouse
`--mouse`, `--no-mouse`	Entrada do terminal
Atalhos de caminho/permissão
Permitir todos os caminhos	`--allow-all-paths`	Usar o manipulador de permissões
Permitir todas as URLs	`--allow-all-urls`	Usar o manipulador de permissões
Permitir todas as permissões
`--yolo`, `--allow-all`, `/allow-all`	Usar o manipulador de permissões
Permissões granulares de ferramenta
`--allow-tool`, `--deny-tool`	Usar o gancho `onPreToolUse`
Controle de acesso à URL
`--allow-url`, `--deny-url`	Usar o manipulador de permissões
Redefinir ferramentas permitidas	`/reset-allowed-tools`	Comando TUI
Gerenciamento de Diretório
Adicionar diretório
`/add-dir`, `--add-dir`	Configurar na sessão
Listar diretórios	`/list-dirs`	Comando TUI
Alterar diretório	`/cwd`	Comando TUI
Gerenciamento de Plug-in/MCP
Comandos de plugin	`/plugin`	Gerenciamento interativo
Gerenciamento de servidor MCP	`/mcp`	Interface do usuário interativa
Gestão de Contas
Fluxo de logon
`/login`, `copilot auth login`	Fluxo do dispositivo OAuth
Sair
`/logout`, `copilot auth logout`	CLI direta
Informações do usuário	`/user`	Comando TUI
Operações de sessão
Limpar conversa	`/clear`	Somente TUI
Visão em planta	`/plan`	Somente TUI (use o SDK `session.rpc.plan.*` em vez disso)
Gerenciamento de sessão
`/session`, `/resume`, `/rename`	Fluxo de trabalho TUI
Modo de gerenciamento de frota (interativo)	`/fleet`	Somente TUI (use o SDK `session.rpc.fleet.start()` em vez disso)
Gerenciamento de habilidades
Gerenciar habilidades	`/skills`	Interface do usuário interativa
Gerenciamento de Tarefas
Exibir tarefas em segundo plano	`/tasks`	Comando TUI
Uso e Estatísticas
Uso de token	`/usage`	Assinar eventos de uso
Revisão de código
Revisar alterações	`/review`	Comando TUI
Delegação
Delegar ao PR	`/delegate`	Fluxo de trabalho TUI
Instalação do terminal
Integração do Shell	`/terminal-setup`	Específico do shell
Desenvolvimento
Alternar funcionalidade experimental
`/experimental`, `--experimental`	Sinalizador de runtime
Controle de instruções personalizadas	`--no-custom-instructions`	Sinalizador da CLI
Diagnosticar sessão	`/diagnose`	Comando TUI
Exibir/gerenciar instruções	`/instructions`	Comando TUI
Coletar logs de depuração	`/collect-debug-logs`	Ferramenta de diagnóstico
Reindexar espaço de trabalho	`/reindex`	Comando TUI
Integração de IDE	`/ide`	Fluxo de trabalho específico do IDE
Modo não interativo
Modo de prompt
`-p`, `--prompt`	Execução de tiro único
Prompt interativo
`-i`, `--interactive`	Execução automática e depois interativa
Saída silenciosa
`-s`, `--silent`	Amigável ao script
Continuar sessão	`--continue`	Retomar o mais recente
Seleção do agente	`--agent <agent>`	Sinalizador da CLI

Soluções alternativas

Modo de frota

O modo de frota está disponível por meio de session.rpc.fleet.start() para aplicativos com SDK que desejam que o runtime acione subagentes em paralelo para atingir um objetivo mais amplo. Use-o quando subtarefas independentes puderem ser executadas simultaneamente e, em seguida, ser resumidas pela sessão principal. Para obter um guia completo, consulte Modo de frota.

Exportação de sessão

A --share opção não está disponível por meio do SDK. Soluções alternativas:

Coletar eventos manualmente – assine eventos de sessão e crie sua própria exportação:

const events: SessionEvent[] = [];
session.on((event) => events.push(event));
// ... after conversation ...
const messages = await session.getEvents();
// Format as markdown yourself

Use a CLI diretamente para exportação - Execute a CLI com --share para exportações pontuais.

Controle de permissão

O SDK usa um modelo de permissões que nega por padrão. Todas as solicitações de permissão (gravações de arquivo, comandos de shell, buscas de URL etc.) são negadas, a menos que seu aplicativo forneça um onPermissionRequest manipulador.

Em vez de --allow-all-paths ou --yolo, use o manipulador de permissões:

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

Acompanhamento de uso de token

Em vez de /usage, assine eventos de uso:

session.on("assistant.usage", (event) => {
  console.log("Tokens used:", {
    input: event.data.inputTokens,
    output: event.data.outputTokens,
  });
});

Compactação de contexto

Em vez de /compact, configurar a compactação automática ou acioná-la manualmente:

// Automatic compaction via config
const session = await client.createSession({
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // Start background compaction at 80% context utilization
    bufferExhaustionThreshold: 0.95,      // Block and compact at 95% context utilization
  },
});

// Manual compaction (experimental)
const result = await session.rpc.history.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

Observação

Os limites são taxas de utilização de contexto (0,0-1,0), não contagens absolutas de token.

Gerenciamento de Planos

Ler e escrever planos de sessão de forma programática:

// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
  console.log(plan.content);
}

// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });

// Delete the plan
await session.rpc.plan.delete();

Direção de mensagem

Injetar uma mensagem no turno atual do LLM sem interromper.

// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });

// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });

Limitações de protocolo

O SDK só pode acessar recursos expostos por meio do protocolo JSON-RPC da CLI. Se você precisar de um recurso da CLI que não esteja disponível:

Verificar se há alternativas – muitos recursos têm equivalentes do SDK (confira as soluções alternativas acima)
Usar a CLI diretamente – para operações pontuais, invoque a CLI
Solicitar o recurso – Abrir um problema para solicitar suporte ao protocolo

Compatibilidade entre versões

Intervalo do protocolo do SDK	Versão do protocolo CLI	Compatibility
v2–v3	v3	Suporte completo
v2–v3	v2	Suportado por adaptadores automáticos v2

O SDK negocia versões de protocolo com a CLI na inicialização. O SDK dá suporte às versões de protocolo 2 a 3. Ao se conectar a um servidor CLI v2, o SDK adapta automaticamente as mensagens tool.call e permission.request ao modelo de evento v3, sem necessidade de alterar o código.

Verifique as versões em tempo de execução:

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);

Neste artigo