Compatibilidade do SDK e da CLI

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

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

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
  

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

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:

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:

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

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

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

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

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:

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

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