Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Transporte gRPC e do SDK nativo

Status: Ativo Escopo: contrato de transporte nativo de desktop Última revisão: 2026-09-02 Responsável: SDK do ax-code

O AX Code agora expõe um contrato de transporte opcional no formato gRPC para aplicativos de desktop e GUIs nativas. O contrato é de propósito mais estreito que a árvore completa de rotas HTTP/OpenAPI: ele se concentra nas capacidades de runtime sem interface de que uma GUI precisa para parecer nativa, e mantém HTTP/OpenAPI disponível internamente para compatibilidade, diagnóstico e clientes gerados.

Recomendação

Use o transporte gRPC/nativo como limite preferido para aplicativos de desktop de primeira parte. Mantenha HTTP/SSE ativado como contingência e superfície de depuração.

Por que não remover o HTTP

Remover HTTP/OpenAPI do runtime retiraria o caminho de compatibilidade mais inspecionável e portátil. O SDK JavaScript não deve expor subcaminhos de cliente e servidor HTTP como superfícies de suporte de primeira parte, mas a ponte HTTP interna continua útil para diagnóstico, inicialização existente do backend sem interface e fluxos de cliente gerado. Os controles atuais do servidor HTTP incluem vinculação obrigatória somente a loopback, credenciais Basic Auth geradas nos auxiliares de backend administrados pelo SDK, verificação de origem em pedidos mutáveis do navegador, validação de diretório, limites de taxa de pedidos e documentação OpenAPI ao vivo somente em loopback.

O transporte não é a fonte dominante de latência em turnos normais de agente. Chamadas de LLM, comandos de shell, entrada e saída de arquivo, indexação, inicialização do LSP e execução de ferramentas costumam custar mais que JSON em localhost. O gRPC ainda é útil para uma GUI de desktop porque oferece um contrato de API nativa mais limpo, prazos, metadados, streaming de servidor e um caminho para transportes de socket Unix ou named pipe sem arrastar uma API orientada a navegador para dentro do shell do aplicativo.

Forma do contrato

O contrato neutro em relação à linguagem fica em packages/sdk/proto/ax_code/v1/headless.proto. O pacote JSR também contém esse proto como ativo. Hosts TypeScript o localizam com resolveAxCodeGrpcProtoUrl(); geradores fora de JavaScript devem usar o contrato canônico do repositório.

A fachada TypeScript fica em @defai-digital/ax-code-sdk/grpc e cobre:

• prontidão de saúde e de ciclo de vida
• ingestão de log do aplicativo e controles de descarte e reinício de instância para a gestão do ciclo de vida do host nativo
• criação de sessão
• prompt, comando, shell, interrupção, resposta de permissão e resposta de pergunta
• instantâneos de inicialização da GUI para provedores, sessões, permissões, perguntas, caminho, VCS, LSP, MCP, formatador e estado de comando
• lista de sessões, detalhe, histórico de mensagens, detalhe de mensagem, filhos, meta, todo, diff, bifurcação, compartilhamento e operações de resumo
• descoberta da GUI e navegação do espaço de trabalho para agentes, habilidades, projetos, caminho, VCS, comandos, árvore, conteúdo e status de arquivo, busca de texto, arquivo e símbolo, e esquemas de ferramenta
• contexto de projeto, modelos de contexto, atualização e limpeza de memória em cache e diagnóstico de plano pendente do engine de depuração
• operações de lista, resposta e rejeição de permissões e perguntas pendentes para fluxos de GUI supervisionados
• provedor, configuração, autenticação por chave de API e ajustes de OAuth do provedor para telas de configuração da GUI
• controles de ajuste de runtime para modo autônomo, modo de isolamento e roteamento inteligente de LLM
• status de MCP, descoberta de recursos, gestão dinâmica de servidor, OAuth, conexão e desconexão
• status de LSP e de formatador para diagnóstico e telas de configuração
• gestão de terminal PTY e streaming bidirecional de terminal
• evidência de sessão para a interface de revisão e depuração
• operações da fila de tarefas
• operações de tarefas agendadas
• modelos de fluxo de trabalho, execuções de fluxo, resumos de painel, casos de avaliação, rotinas de fluxo e artefatos de execução
• eventos de runtime transmitidos pelo servidor

O proto usa cargas JSON estruturadas para corpos de comando e cargas de fluxo de trabalho e de tarefa. Isso mantém o transporte estável enquanto os esquemas de runtime do AX Code continuam a evoluir depressa.

@defai-digital/ax-code-sdk/grpc também exporta AX_CODE_GRPC_METHOD_DESCRIPTORS, listAxCodeGrpcMethods(), getAxCodeGrpcMethodDescriptor(), assertAxCodeGrpcMethodSupported(), listMissingAxCodeGrpcNativeHandlers() e assertAxCodeGrpcNativeHandlers(). Hosts nativos devem usar estes descritores e verificações de cobertura como o catálogo canônico de métodos ao montar mapas de handlers, binders de serviço gRPC, listas de permissão de preload ou gates de inicialização. Cada descritor inclui o nome do método, o caminho totalmente qualificado do método, o tipo de fluxo, os nomes das mensagens proto de pedido e de resposta, o domínio da GUI, a disponibilidade da ponte HTTP e a estabilidade atual. Isso mantém explícito o limite do transporte nativo sem expor nem espelhar a árvore completa de rotas HTTP.

Uso em TypeScript

Use o backend gRPC sem interface administrado pelo SDK quando o host ainda precisa do runtime HTTP existente internamente. Ele mantém a ponte HTTP dentro do processo do host e devolve apenas o cliente gRPC mais o identificador 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()
}

Use uma ponte IPC nativa quando o host de desktop é dono do limite privilegiado do runtime por meio do preload do Electron, de comandos Tauri ou de outro limite de structured clone. As chamadas IPC omitem de propósito AbortSignal e mantêm o fluxo de entrada bidirecional fora da carga da chamada, para que o objeto da chamada atravesse os limites entre renderer e host com limpeza:

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

Use createAxCodeGrpcClientFromNativeBridge() apenas quando os dois lados estão no mesmo realm JavaScript e podem passar com segurança AbortSignal e iteráveis assíncronos diretamente no objeto da chamada.

Se o host expõe assinaturas no estilo push, use createAxCodeGrpcNativeIpcBridgeFromChannels() ou createAxCodeGrpcNativeIpcStream() para adaptar callbacks do host aos fluxos AsyncIterable esperados pelo SDK gRPC. Esses auxiliares servem para ouvintes de evento do Tauri, callbacks de preload do Electron e outros sistemas IPC que devolvem uma função de cancelamento de assinatura em vez de um gerador assíncrono JavaScript.

Hosts nativos também podem expor um mapa de handlers em vez de escrever à mão um switch de métodos. Isso é útil para comandos Rust/Tauri, APIs de preload do Electron ou um servidor gRPC local real que queira vincular as operações de runtime do AX Code método a método. Use os descritores de método para validar que cada domínio esperado está coberto antes de entregar a ponte ao código do renderer:

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() é de propósito um instantâneo orientado à GUI, e não uma cópia um para um de cada rota HTTP. Use include para pedir apenas o estado de que a vista atual precisa. Subpedidos com falha aparecem em errors, e os campos bem-sucedidos ainda são devolvidos, de modo que um subsistema opcional ausente não impede a abertura do shell de desktop.

O streaming de eventos aceita filtros opcionais types e sessionID. Transportes nativos devem aplicar esses filtros no servidor. A ponte de compatibilidade HTTP aplica os mesmos filtros no cliente sobre a rota SSE existente, para que o código da GUI mantenha uma única forma de assinatura enquanto o servidor nativo é implementado.

startAxCodeGrpcHeadlessBackend() é a contingência temporária preferida quando o host ainda inicia ax-code serve internamente. Ele não devolve a URL HTTP nem o cabeçalho de autorização, de modo que o código do renderer pode ser escrito contra a fachada gRPC e depois movido para um transporte gRPC nativo real sem reescrever a API pública.

Hosts de desktop baseados em Node podem expor um endpoint gRPC HTTP/2 real a partir da mesma ponte nativa com @defai-digital/ax-code-sdk/grpc/node. Isso é para processos de host privilegiados, não para código de renderer:

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

O streaming de PTY é modelado como um fluxo bidirecional gRPC. A ponte HTTP adapta esse fluxo à rota WebSocket existente para compatibilidade; hosts de GUI nativa devem implementá-lo sobre o transporte gRPC local, socket Unix ou named pipe, em vez de expor a rota WebSocket ao código do renderer.

Quando um transporte gRPC real está disponível, entregue-o a createAxCodeGrpcClient({ transport }). O cliente de alto nível permanece o mesmo.

Postura de segurança

Para aplicativos de desktop, prefira esta ordem:

1. SDK no processo quando a GUI é TypeScript e pode carregar o runtime com segurança.
2. Transporte gRPC/nativo local sobre loopback, socket Unix ou named pipe.
3. Ponte sem interface HTTP/SSE com credenciais Basic Auth de uso único geradas.
4. Não exponha o AX Code por HTTP de rede.

A ponte de compatibilidade HTTP do gRPC e os auxiliares de backend HTTP administrados pelo SDK aceitam apenas endpoints de loopback literais. As opções legadas allowRemoteHttpBridge e allowNetworkBind permanecem para compatibilidade de código-fonte, mas não contornam a política somente local. Mantenha /doc limitado ao servidor de loopback.

A ponte de compatibilidade HTTP rejeita por padrão upgrades WebSocket de outra origem. Acrescente uma origem à lista de permissão CORS explícita do servidor apenas quando essa origem do navegador faz parte do shell confiável do aplicativo.

Não exponha a API HTTP completa, o WebSocket de PTY nem a documentação OpenAPI a WebViews arbitrárias. Se um WebView for usado, mantenha-o como renderer e encaminhe operações privilegiadas pelo host nativo usando a fachada gRPC/nativa.