Esta página es una traducción de la documentación en inglés. Los comandos, identificadores y ejemplos no cambian. Runtime 7.24.4 · SDK 2.6.7. Original en inglés

Transporte gRPC y del SDK nativo

Estado: Activo Alcance: contrato de transporte nativo de escritorio Última revisión: 2026-09-02 Responsable: SDK de ax-code

AX Code expone ahora un contrato de transporte opcional con forma de gRPC para aplicaciones de interfaz de escritorio y nativas. El contrato es deliberadamente más estrecho que el árbol completo de rutas HTTP/OpenAPI: se centra en las capacidades headless del entorno de ejecución que una interfaz necesita para sentirse nativa, y mantiene HTTP/OpenAPI disponible internamente para compatibilidad, diagnósticos y clientes generados.

Recomendación

Usa el transporte gRPC/nativo como límite preferido para las aplicaciones de escritorio de primera parte. Mantén HTTP/SSE activado como respaldo y superficie de depuración.

Por qué no eliminar HTTP

Eliminar HTTP/OpenAPI del entorno de ejecución quitaría la vía de compatibilidad más inspeccionable y portable. El SDK de JavaScript no debe exponer subcaminos de cliente o servidor HTTP como superficies de soporte de primera parte, pero el puente HTTP interno sigue siendo útil para diagnósticos, el arranque existente del backend headless y los flujos de clientes generados. Los controles actuales del servidor HTTP incluyen la vinculación obligatoria solo a loopback, credenciales Basic Auth generadas en las ayudas de backend gestionadas por el SDK, comprobaciones de origen en las solicitudes mutantes del navegador, validación de directorios, límites de tasa de solicitudes y documentación OpenAPI en vivo solo en loopback.

El transporte no es la fuente dominante de latencia en los turnos normales del agente. Las llamadas al LLM, los comandos de shell, la E/S de archivos, la indexación, el arranque de LSP y la ejecución de herramientas suelen ser más caros que el JSON de localhost. gRPC sigue siendo útil para una interfaz de escritorio porque aporta un contrato de API nativa más limpio, plazos, metadatos, flujo del servidor y una vía hacia transportes de socket Unix o de tubería con nombre, sin arrastrar una API orientada al navegador al shell de la aplicación.

Forma del contrato

El contrato neutro respecto al lenguaje vive en packages/sdk/proto/ax_code/v1/headless.proto. El paquete JSR también contiene ese proto como activo. Los hosts de TypeScript lo localizan con resolveAxCodeGrpcProtoUrl(); los generadores que no son de JavaScript deben usar el contrato canónico del repositorio.

La fachada de TypeScript vive en @defai-digital/ax-code-sdk/grpc y cubre:

• salud y preparación del ciclo de vida
• ingesta de registros de la aplicación y controles de desecho y reinicio de instancia para la gestión del ciclo de vida del host nativo
• creación de sesión
• prompt, comando, shell, aborto, respuesta de permiso y respuesta de pregunta
• instantáneas de arranque de la interfaz para proveedores, sesiones, permisos, preguntas, ruta, VCS, LSP, MCP, formateador y estado de comandos
• lista de sesiones, detalle, historial de mensajes, detalle de mensaje, hijos, objetivo, tarea, diff, bifurcación, compartir y resumir
• descubrimiento de la interfaz y navegación del espacio de trabajo para agentes, habilidades, proyectos, ruta, VCS, comandos, árbol, contenido y estado de archivos, búsqueda de texto, archivos y símbolos, y esquemas de herramientas
• contexto del proyecto, plantillas de contexto, actualización y borrado de la memoria en caché, y diagnósticos del plan pendiente del motor de depuración
• operaciones de lista, respuesta y rechazo de permisos y preguntas pendientes para flujos de interfaz supervisados
• proveedor, configuración, autenticación con clave de API y ajustes OAuth del proveedor para las pantallas de ajustes de la interfaz
• controles de ajuste del entorno de ejecución para el modo autónomo, el modo de aislamiento y el enrutado inteligente de LLM
• estado de MCP, descubrimiento de recursos, gestión dinámica de servidores, OAuth y controles de conexión y desconexión
• estado de LSP y del formateador para pantallas de diagnósticos y de ajustes
• gestión de terminales PTY y flujo bidireccional del terminal
• evidencia de sesión para la interfaz de revisión y depuración
• operaciones de la cola de tareas
• operaciones de tareas programadas
• plantillas de flujo, ejecuciones de flujo, resúmenes del panel, casos de evaluación, rutinas de flujo y artefactos de ejecución
• eventos del entorno de ejecución transmitidos por el servidor

El proto usa cargas JSON estructuradas para los cuerpos de comando y las cargas de flujo y de tarea. Eso mantiene estable el transporte mientras los esquemas del entorno de ejecución de AX Code siguen evolucionando con rapidez.

@defai-digital/ax-code-sdk/grpc también exporta AX_CODE_GRPC_METHOD_DESCRIPTORS, listAxCodeGrpcMethods(), getAxCodeGrpcMethodDescriptor(), assertAxCodeGrpcMethodSupported(), listMissingAxCodeGrpcNativeHandlers() y assertAxCodeGrpcNativeHandlers(). Los hosts nativos deben usar estos descriptores y las comprobaciones de cobertura como catálogo canónico de métodos al construir mapas de manejadores, enlaces de servicio gRPC, listas de permitidos de preload o puertas de arranque. Cada descriptor incluye el nombre del método, la ruta de método plenamente cualificada, el tipo de flujo, los nombres de los mensajes proto de solicitud y respuesta, el dominio de la interfaz, la disponibilidad del puente HTTP y la estabilidad actual. Esto mantiene explícito el límite del transporte nativo sin exponer ni reflejar el árbol completo de rutas HTTP.

Uso de TypeScript

Usa el backend headless gRPC gestionado por el SDK cuando el host aún necesita internamente el entorno de ejecución HTTP existente. Mantiene el puente HTTP dentro del proceso del host y devuelve solo el cliente gRPC más el manejador de ciclo de vida:

import {
  createAxCodeGrpcClientFromNativeBridge,
  resolveAxCodeGrpcProtoUrl,
  startAxCodeGrpcHeadlessBackend,
} from "@defai-digital/ax-code-sdk/grpc"

const backend = await startAxCodeGrpcHeadlessBackend({ directory: "/workspace/app" })
try {
  const client = backend.client

  const session = await client.createSession({ title: "GUI session" })
  const messages = await client.session.messages((session as { id: string }).id, { limit: 50 })
  const skills = await client.app.skills()
  const readme = await client.file.read("README.md")
  const authMethods = await client.provider.auth()
  const bootstrap = await client.bootstrap.load({
    include: { sessions: true, providers: true, providerList: true, path: true, vcs: true },
  })
  const terminal = (await client.pty.create({ title: "GUI shell" })) as { id: string }
  const protoUrl = resolveAxCodeGrpcProtoUrl()

  await client.sendPrompt((session as { id: string }).id, {
    parts: [{ type: "text", text: "Review this workspace" }],
  })

  for await (const event of client.subscribeEvents({ sessionID: (session as { id: string }).id })) {
    if (event.type === "server.heartbeat") continue
    // Project event into GUI state.
  }
} finally {
  await backend.close()
}

Usa un puente IPC nativo cuando el host de escritorio es dueño del límite privilegiado del entorno de ejecución mediante preload de Electron, comandos de Tauri u otro límite de structured-clone. Las llamadas IPC omiten de forma intencionada AbortSignal y mantienen el flujo de entrada bidireccional fuera de la carga de la llamada, para que el objeto de la llamada pueda cruzar limpiamente los límites de renderizador y host:

const client = createAxCodeGrpcClientFromNativeIpc({
  unary(call) {
    return window.axCodeNative.unary(call)
  },
  serverStream(call) {
    return window.axCodeNative.serverStream(call)
  },
  bidiStream(call, input) {
    return window.axCodeNative.bidiStream(call, input)
  },
})

Usa createAxCodeGrpcClientFromNativeBridge() solo cuando ambos lados están en el mismo ámbito de JavaScript y pueden pasar con seguridad AbortSignal e iterables asíncronos directamente en el objeto de la llamada.

Si el host expone suscripciones de estilo push, usa createAxCodeGrpcNativeIpcBridgeFromChannels() o createAxCodeGrpcNativeIpcStream() para adaptar las devoluciones de llamada del host a los flujos AsyncIterable que espera el SDK gRPC. Esas ayudas sirven para oyentes de eventos de Tauri, devoluciones de llamada de preload de Electron y otros sistemas IPC que devuelven una función de cancelación de suscripción en lugar de un generador asíncrono de JavaScript.

Los hosts nativos también pueden exponer un mapa de manejadores en lugar de escribir a mano un conmutador de métodos. Es útil para comandos Rust/Tauri, API de preload de Electron o un servidor gRPC local real que quiera enlazar las operaciones del entorno de ejecución de AX Code método a método. Usa los descriptores de método para validar que cada dominio esperado está cubierto antes de entregar el puente al código del renderizador:

import {
  AX_CODE_GRPC_METHOD,
  assertAxCodeGrpcNativeHandlers,
  createAxCodeGrpcNativeBridgeFromHandlers,
  listAxCodeGrpcMethods,
} from "@defai-digital/ax-code-sdk/grpc"

const handlers = {
  unary: {
    [AX_CODE_GRPC_METHOD.GetSession](request, options) {
      return runtime.getSession(request.sessionID, options)
    },
  },
  serverStream: {
    [AX_CODE_GRPC_METHOD.SubscribeEvents](_request, options) {
      return runtime.events(options)
    },
  },
  bidiStream: {
    [AX_CODE_GRPC_METHOD.ConnectPty](request, input, options) {
      return runtime.connectPty(request.id, input, options)
    },
  },
}

const mcpMethods = listAxCodeGrpcMethods({ domain: "mcp" })
const streamingMethods = listAxCodeGrpcMethods({ kind: "serverStream" })
const ptyDescriptor = listAxCodeGrpcMethods({ kind: "bidiStream" })[0]
// ptyDescriptor.requestType === "PtyClientEvent"
// ptyDescriptor.responseType === "PtyServerEvent"

assertAxCodeGrpcNativeHandlers(handlers, {
  methods: [AX_CODE_GRPC_METHOD.GetSession, AX_CODE_GRPC_METHOD.SubscribeEvents, AX_CODE_GRPC_METHOD.ConnectPty],
})

const bridge = createAxCodeGrpcNativeBridgeFromHandlers(handlers, {
  requireHandlers: {
    methods: [AX_CODE_GRPC_METHOD.GetSession, AX_CODE_GRPC_METHOD.SubscribeEvents, AX_CODE_GRPC_METHOD.ConnectPty],
  },
})

bootstrap.load() es deliberadamente una instantánea orientada a la interfaz, no una copia uno a uno de cada ruta HTTP. Usa include para solicitar solo el estado que necesita la vista actual. Las subsolicitudes fallidas se informan en errors mientras los campos exitosos se siguen devolviendo, así que un subsistema opcional ausente no impide que se abra el shell de escritorio.

El flujo de eventos acepta filtros opcionales types y sessionID. Los transportes nativos deben aplicar esos filtros en el lado del servidor. El puente de compatibilidad HTTP aplica los mismos filtros en el lado del cliente sobre la ruta SSE existente, para que el código de la interfaz pueda conservar una forma de suscripción mientras se implementa el servidor nativo.

startAxCodeGrpcHeadlessBackend() es el respaldo temporal preferido cuando el host sigue iniciando ax-code serve internamente. No devuelve la URL HTTP ni la cabecera de autorización, así que el código del renderizador puede escribirse contra la fachada gRPC y más tarde pasar a un transporte gRPC nativo real sin reescribir la API pública.

Los hosts de escritorio basados en Node pueden exponer un endpoint gRPC HTTP/2 real desde el mismo puente nativo con @defai-digital/ax-code-sdk/grpc/node. Esto es para procesos de host privilegiados, no para código del renderizador:

import { createAxCodeGrpcNativeBridgeFromHandlers, AX_CODE_GRPC_METHOD } from "@defai-digital/ax-code-sdk/grpc"
import { startAxCodeGrpcNodeHttp2Server } from "@defai-digital/ax-code-sdk/grpc/node"

const bridge = createAxCodeGrpcNativeBridgeFromHandlers({
  unary: {
    [AX_CODE_GRPC_METHOD.Health]() {
      return { status: "SERVING" }
    },
  },
  serverStream: {
    [AX_CODE_GRPC_METHOD.SubscribeEvents](request) {
      return runtime.subscribeEvents(request)
    },
  },
})

const server = await startAxCodeGrpcNodeHttp2Server({ bridge, host: "127.0.0.1" })
try {
  // Native clients can generate from ax_code/v1/headless.proto and connect to server.url.
} finally {
  await server.close()
}

El flujo PTY se modela como un flujo bidireccional de gRPC. El puente HTTP adapta ese flujo a la ruta WebSocket existente por compatibilidad; los hosts de interfaz nativos deben implementarlo sobre su transporte local gRPC, de socket Unix o de tubería con nombre, en lugar de exponer la ruta WebSocket al código del renderizador.

Cuando haya un transporte gRPC real, proporciónalo a createAxCodeGrpcClient({ transport }). El cliente de alto nivel sigue siendo el mismo.

Postura de seguridad

Para las aplicaciones de escritorio, prefiere este orden:

1. SDK en proceso cuando la interfaz es TypeScript y puede cargar el entorno de ejecución con seguridad.
2. Transporte gRPC/nativo local sobre loopback, socket Unix o tubería con nombre.
3. Puente headless HTTP/SSE con credenciales Basic Auth de un solo uso generadas.
4. No expongas AX Code por HTTP de red.

El puente de compatibilidad HTTP de gRPC y las ayudas de backend HTTP gestionadas por el SDK aceptan solo endpoints loopback literales. Las opciones heredadas allowRemoteHttpBridge y allowNetworkBind se conservan por compatibilidad del código fuente, pero no eluden la política de solo local. Mantén /doc limitado al servidor loopback.

El puente de compatibilidad HTTP rechaza de forma predeterminada las actualizaciones WebSocket de origen cruzado. Añade un origen a la lista explícita de permitidos CORS del servidor solo cuando ese origen del navegador forme parte del shell de confianza de la aplicación.

No expongas la API HTTP completa, el WebSocket PTY ni la documentación OpenAPI a WebView arbitrarios. Si se usa un WebView, mantenlo como renderizador y enruta las operaciones privilegiadas a través del host nativo usando la fachada gRPC/nativa.