Compatibilidade do SDK e da CLI

Observação

SDK do Copilot está em versão prévia pública no momento. A funcionalidade e a disponibilidade estão sujeitas a alterações.

          SDK do GitHub Copilot comunica-se com CLI do GitHub Copilot através 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	Observações
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	`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
Mensagens
Enviar mensagem	`send()`	Com anexos
Enviar e aguardar	`sendAndWait()`	Bloqueia 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	`getMessages()`	Todos os eventos de sessão
Anular	`abort()`	Cancelar solicitação de disponibilização de versão piloto
Ferramentas
Registrar ferramentas personalizadas	`registerTools()`	Suporte completo ao esquema JSON
Controle de permissão da ferramenta	Gancho `onPreToolUse`	Permitir/negar/perguntar
Modificação do resultado da ferramenta	Gancho `onPostToolUse`	Transformar resultados
Ferramentas disponíveis/excluídas

          `availableTools`, `excludedTools` configuração | Filtrar ferramentas |

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 |

Soluções alternativas

Exportação de sessão

A --share opção não está disponível por meio do SDK. Para solucionar esse problema:

Colete eventos manualmente: Assine eventos de sessão e crie sua própria exportação:

TypeScript

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

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

Use a CLI diretamente para exportações pontuais.

Controle de permissão

O SDK utiliza um modelo de permissões de negação por padrão. Todas as solicitações de permissão (gravações de arquivo, comandos de shell, buscas de URL e outras) 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:

TypeScript

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

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

Acompanhamento de uso de token

Em vez de /usage, assine eventos de uso:

TypeScript

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

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, configure a compactação automática ou acione-a manualmente:

TypeScript

// 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.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

// 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.compaction.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:

TypeScript

// 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();

// 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:

TypeScript

// 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" });

// 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:

Verifique se há alternativas: Muitos recursos têm equivalentes do SDK (consulte soluções alternativas acima).
Use a CLI diretamente: Para operações pontuais, invoque a CLI.
Solicite o recurso: Abra um problema no repositório github/copilot-sdk para solicitar suporte ao protocolo.

Compatibilidade entre versões

Intervalo de protocolos do SDK	Versão do protocolo CLI	Compatibilidade
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.

Você pode verificar versões em runtime:

TypeScript

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

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

Quem pode usar esse recurso?

Neste artigo

Comparação de funcionalidades

Disponível no SDK

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

Soluções alternativas

Exportação de sessão

Controle de permissão

Acompanhamento de uso de token

Compactação de contexto

Gerenciamento de Planos

Direção de mensagem

Limitações de protocolo

Compatibilidade entre versões