Compatibilidad del SDK y la CLI

Nota:

          SDK de Copilot actualmente está en versión preliminar pública. La funcionalidad y la disponibilidad están sujetas a cambios.

          SDK de GitHub Copilot se comunica con CLI de GitHub Copilot a través del protocolo JSON-RPC. Las características deben exponerse explícitamente a través de este protocolo para que estén disponibles en el SDK. Muchas características interactivas de la CLI son específicas del terminal y no están disponibles mediante programación.

Comparación de características

Disponible en el SDK

Feature	Método del SDK	Notas

          **Gestión de sesiones** |

| | | Crear sesión | createSession() | Soporte completo de configuración | | Reanudar sesión | resumeSession() | Con áreas de trabajo de sesión infinitas | | Desconectar sesión | disconnect() | Liberar recursos en memoria | | Destruir sesión | destroy() | Use disconnect() en su lugar | | Eliminar sesión | deleteSession() | Quitar del almacenamiento | | Enumerar las sesiones | listSessions() | Todas las sesiones almacenadas | | Obtención de la última sesión | getLastSessionId() | Para un currículum rápido | | Obtener sesión en primer plano | getForegroundSessionId() | Coordinación de varias sesiones | | Establecer sesión en primer plano | setForegroundSessionId() | Coordinación de varias sesiones | | Mensajería | | | | Enviar mensaje | send() | Con datos adjuntos | | Enviar y esperar | sendAndWait() | Bloques hasta completarse | | Dirección (modo inmediato) | send({ mode: "immediate" }) | Inyectar a mitad de giro sin abortar | | Puesta en cola (modo de puesta en cola) | send({ mode: "enqueue" }) | Búfer para el procesamiento secuencial (valor predeterminado) | | Archivos adjuntos | send({ attachments: [{ type: "file", path }] }) | Imágenes codificadas automáticamente y cambiadas de tamaño | | Datos adjuntos de directorio | send({ attachments: [{ type: "directory", path }] }) | Adjuntar contexto de directorio | | Obtener historial | getMessages() | Todos los eventos de sesión | | Abortar | abort() | Cancelar solicitud en curso | | Herramientas | | | | Registro de herramientas personalizadas | registerTools() | Compatibilidad completa con el esquema JSON | | Control de permisos de herramientas | onPreToolUse gancho | Permitir/denegar/preguntar | | Modificación del resultado de la herramienta | onPostToolUse gancho | Transformación de los resultados | | Herramientas disponibles o excluidas | availableTools, excludedTools configuración | Herramientas de filtro | | Modelos | | | | Enumeración de modelos | listModels() | Con funcionalidades, facturación y políticas | | Establecer modelo (en la creación) | model en la configuración de sesión | Por sesión | | Modelo de conmutador (mediados de sesión) | session.setModel() | También a través de session.rpc.model.switchTo() | | Obtención del modelo actual | session.rpc.model.getCurrent() | Consulta del modelo activo | | Esfuerzo de razonamiento | reasoningEffort configuración | Para los modelos admitidos | | Modo de agente | | | | Obtener el modo actual | session.rpc.mode.get() | Devuelve el modo actual. | | Establecer modo | session.rpc.mode.set() | Cambiar entre modos | | Administración de planes | | | | Leer plan | session.rpc.plan.read() | Obtén el contenido y la ruta de acceso de plan.md | | Actualizar plan | session.rpc.plan.update() | Escribir el contenido del archivo plan.md | | Eliminar el plan | session.rpc.plan.delete() | Eliminar plan.md | | Archivos del área de trabajo. | | | | Enumerar archivos del área de trabajo | session.rpc.workspace.listFiles() | Archivos en el área de trabajo de sesión | | Leer el archivo del área de trabajo | session.rpc.workspace.readFile() | Leer el contenido de archivos | | Crear archivo de área de trabajo | session.rpc.workspace.createFile() | Creación de un archivo en el área de trabajo | | Autenticación | | | | Obtención del estado de autenticación | getAuthStatus() | Comprobación del estado de inicio de sesión | | Uso del token | Opción githubToken | Autenticación mediante programación | | Conectividad | | | | Ping | client.ping() | Verificación de salud con marca de tiempo del servidor | | Obtención del estado del servidor | client.getStatus() | Información del servidor y la versión del protocolo | | Servidores MCP | | | | Servidores locales/stdio | mcpServers configuración | Generar procesos | | HTTP/SSE remoto | mcpServers configuración | Conexión a los servicios | | Hooks | | | | Uso previo a la herramienta | onPreToolUse | Permisos para modificar argumentos | | Uso posterior de herramientas | onPostToolUse | Modificación de los resultados | | Indicador de usuario | onUserPromptSubmitted | Modificación de avisos | | Inicio y finalización de la sesión | onSessionStart, onSessionEnd | Ciclo de vida con origen o motivo | | Gestión de errores | onErrorOccurred | Control personalizado | | Eventos | | | | Todos los eventos de sesión | on(), once() | Más de 40 tipos de eventos | | Transmisión en línea | streaming: true | Eventos delta | | Configuración de sesión | | | | Agentes personalizados | customAgents configuración | Definición de agentes especializados | | Mensaje del sistema | systemMessage configuración | Anexar o reemplazar | | Proveedor personalizado | provider configuración | Compatibilidad con BYOK | | Sesiones infinitas | infiniteSessions configuración | Compactación automática | | Controlador de permisos | onPermissionRequest | Aprobar o denegar solicitudes | | Controlador de entrada de usuario | onUserInputRequest | Gestionar ask_user | | Habilidades | skillDirectories configuración | Aptitudes personalizadas | | Aptitudes deshabilitadas | disabledSkills configuración | Deshabilitar habilidades específicas | | Directorio de configuración | configDir configuración | Invalidar la ubicación de configuración predeterminada | | Nombre de cliente | clientName configuración | Identificación de la aplicación en User-Agent | | Directorio de trabajo | workingDirectory configuración | Establecer el cwd de la sesión | | Experimental | | | | Administración de agentes | session.rpc.agent.* | Lista, seleccionar, deseleccionar, obtener agente actual | | Modo flota | session.rpc.fleet.start() | Ejecución paralela de subagentes | | Compactación manual | session.rpc.compaction.compact() | Active la compactación bajo demanda |

No disponible en el SDK (solo la CLI)

Feature	Comando o opción de la CLI	Motivo

          **Exportación de sesión** |

Soluciones alternativas

Exportación de sesión

La --share opción no está disponible a través del SDK. Para solucionar este problema:

        **Recopilar eventos manualmente:** Suscríbase a eventos de sesión y cree su propia exportación:

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 la CLI directamente** para las exportaciones puntuales.

Control de permisos

El SDK usa un modelo de permisos de denegación por defecto. Se deniegan todas las solicitudes de permiso (escrituras de archivos, comandos de shell, capturas de direcciones URL y otras), a menos que la aplicación proporcione un onPermissionRequest controlador.

En lugar de --allow-all-paths o --yolo, use el manejador de permisos.

TypeScript

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

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

Seguimiento del uso de tokens

En lugar de suscribirse a eventos de uso /usage,

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,
  });
});

Compactación de contexto

En lugar de /compact, configure la compactación automática o desencadene 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`);

Nota:

Los umbrales son relaciones de uso de contexto (0,0-1,0), no recuentos absolutos de tokens.

Administración de planes

Leer y escribir planes de sesión mediante programación:

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

Encaminamiento de mensajes

Inserte un mensaje en el turno LLM actual sin interrumpir:

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

Limitaciones del protocolo

El SDK solo puede acceder a las características expuestas a través del protocolo JSON-RPC de la CLI. Si necesita una característica de la CLI que no esté disponible:

        **Buscar alternativas:** Muchas características tienen equivalentes de SDK (consulte [Soluciones alternativas](#workarounds) anteriores).

        **Use la CLI directamente:** Para las operaciones puntuales, invoque la CLI.

        **Solicite la característica:** Abra un problema en el repositorio [github/copilot-sdk](https://github.com/github/copilot-sdk/issues) para solicitar compatibilidad con el protocolo.

Compatibilidad de versiones

Intervalo de protocolos del SDK	Versión del protocolo de la CLI	Compatibility
v2-v3	v3	Soporte completo
v2-v3	v2	Compatible con adaptadores v2 automáticos

El SDK negocia las versiones de protocolo con la CLI al iniciarse. El SDK admite las versiones de protocolo de 2 a 3. Al conectarse a un servidor de CLI v2, el SDK adapta automáticamente los mensajes entre tool.call y permission.request al modelo de eventos v3, sin necesidad de realizar cambios en el código.

Puede comprobar las versiones en tiempo de ejecución:

TypeScript

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

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

¿Quién puede utilizar esta característica?

En este artículo

Comparación de características

Disponible en el SDK

No disponible en el SDK (solo la CLI)

Soluciones alternativas

Exportación de sesión

Control de permisos

Seguimiento del uso de tokens

Compactación de contexto

Administración de planes

Encaminamiento de mensajes

Limitaciones del protocolo

Compatibilidad de versiones