Cette page est traduite de la documentation anglaise. Les commandes, identifiants et exemples sont inchangés. Runtime 7.24.4 · SDK 2.6.7. Source anglaise

Transport gRPC et SDK natif

Statut : Actif Portée : contrat de transport natif pour le bureau Dernière revue : 2026-09-02 Responsable : sdk ax-code

AX Code expose désormais un contrat de transport facultatif de forme gRPC pour les applications de bureau et les interfaces natives. Le contrat est volontairement plus étroit que l’arbre complet des routes HTTP/OpenAPI : il se concentre sur les capacités du runtime sans interface dont une interface graphique a besoin pour sembler native, tout en gardant HTTP/OpenAPI disponible en interne pour la compatibilité, le diagnostic et les clients générés.

Recommandation

Utilisez le transport gRPC/natif comme frontière préférée pour les applications de bureau de première partie. Gardez HTTP/SSE activé comme repli et surface de débogage.

Pourquoi ne pas retirer HTTP

Retirer HTTP/OpenAPI du runtime supprimerait le chemin de compatibilité le plus inspectable et le plus portable. Le SDK JavaScript ne doit pas exposer les sous-chemins client ou serveur HTTP comme surfaces de prise en charge de première partie, mais le pont HTTP interne reste utile pour le diagnostic, le démarrage existant du moteur sans interface et les flux de clients générés. Les contrôles actuels du serveur HTTP comprennent une liaison forcée à la boucle locale seulement, des identifiants Basic Auth générés dans les assistants de moteur gérés par le SDK, des contrôles d’origine sur les requêtes mutantes du navigateur, la validation des répertoires, des limites de débit de requêtes et une documentation OpenAPI en direct limitée à la boucle locale.

Le transport n’est pas la source de latence dominante pour les tours d’agent ordinaires. Les appels LLM, les commandes shell, les entrées-sorties de fichiers, l’indexation, le démarrage LSP et l’exécution des outils sont en général plus coûteux que le JSON sur localhost. gRPC reste utile pour une interface graphique de bureau parce qu’il fournit un contrat d’API native plus net, des échéances, des métadonnées, un flux serveur et un chemin vers des transports par socket Unix ou tube nommé, sans entraîner une API orientée navigateur dans l’enveloppe de l’application.

Forme du contrat

Le contrat neutre vis-à-vis du langage se trouve dans packages/sdk/proto/ax_code/v1/headless.proto. Le paquet JSR contient aussi ce proto comme ressource. Les hôtes TypeScript le localisent avec resolveAxCodeGrpcProtoUrl() ; les générateurs hors JavaScript doivent utiliser le contrat canonique du dépôt.

La façade TypeScript se trouve dans @defai-digital/ax-code-sdk/grpc et couvre :

• la santé et la disponibilité du cycle de vie
• l’ingestion des journaux d’application et les contrôles de destruction ou de redémarrage d’instance pour la gestion du cycle de vie de l’hôte natif
• la création de session
• l’invite, la commande, le shell, l’abandon, la réponse de permission et la réponse de question
• les instantanés d’amorçage de l’interface pour les fournisseurs, les sessions, les permissions, les questions, le chemin, VCS, LSP, MCP, le formateur et l’état des commandes
• la liste des sessions, le détail, l’historique des messages, le détail d’un message, les enfants, l’objectif, les tâches, le diff, la fourche, le partage et les opérations de résumé
• la découverte pour l’interface et la navigation dans l’espace de travail pour les agents, les skills, les projets, le chemin, VCS, les commandes, l’arbre, le contenu et l’état des fichiers, la recherche de texte, de fichiers et de symboles, et les schémas d’outils
• le contexte de projet, les modèles de contexte, le rafraîchissement et l’effacement de la mémoire en cache, et le diagnostic du plan en attente du moteur de débogage
• les opérations de liste, de réponse et de rejet des permissions et questions en attente pour les flux d’interface supervisés
• les réglages de fournisseur, de configuration, d’authentification par clé d’API et OAuth de fournisseur pour les écrans de réglages
• les contrôles de réglages d’exécution pour le mode autonome, le mode d’isolation et le routage LLM intelligent
• l’état MCP, la découverte de ressources, la gestion dynamique des serveurs, OAuth, et les contrôles de connexion et de déconnexion
• l’état LSP et du formateur pour les écrans de diagnostic et de réglages
• la gestion de terminal PTY et le flux bidirectionnel du terminal
• les preuves de session pour l’interface de revue et de débogage
• les opérations de file de tâches
• les opérations de tâches planifiées
• les modèles de flux de travail, les exécutions de flux, les résumés de tableau de bord, les cas d’évaluation, les routines de flux et les artefacts d’exécution
• les événements d’exécution diffusés par le serveur

Le proto utilise des charges JSON structurées pour les corps de commandes et les charges de flux de travail et de tâches. Cela garde le transport stable pendant que les schémas du runtime AX Code continuent d’évoluer vite.

@defai-digital/ax-code-sdk/grpc exporte aussi AX_CODE_GRPC_METHOD_DESCRIPTORS, listAxCodeGrpcMethods(), getAxCodeGrpcMethodDescriptor(), assertAxCodeGrpcMethodSupported(), listMissingAxCodeGrpcNativeHandlers() et assertAxCodeGrpcNativeHandlers(). Les hôtes natifs doivent utiliser ces descripteurs et ces contrôles de couverture comme catalogue canonique de méthodes lorsqu’ils construisent des cartes de gestionnaires, des lieurs de service gRPC, des listes d’autorisation de préchargement ou des portes de démarrage. Chaque descripteur inclut le nom de méthode, le chemin de méthode pleinement qualifié, le genre de flux, les noms des messages proto de requête et de réponse, le domaine d’interface, la disponibilité du pont HTTP et la stabilité actuelle. Cela garde explicite la frontière du transport natif sans exposer ni refléter l’arbre complet des routes HTTP.

Utilisation de TypeScript

Utilisez le moteur gRPC sans interface géré par le SDK lorsque l’hôte a encore besoin du runtime HTTP existant en interne. Il garde le pont HTTP dans le processus hôte et ne renvoie que le client gRPC plus la poignée de cycle de vie :

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

Utilisez un pont IPC natif lorsque l’hôte de bureau possède la frontière d’exécution privilégiée par le préchargement Electron, les commandes Tauri ou une autre frontière de clone structuré. Les appels IPC omettent volontairement AbortSignal et gardent le flux d’entrée bidirectionnel hors de la charge d’appel, afin que l’objet d’appel puisse traverser proprement les frontières entre rendu et hôte :

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

Utilisez createAxCodeGrpcClientFromNativeBridge() seulement lorsque les deux côtés sont dans le même domaine JavaScript et peuvent transmettre sans risque AbortSignal et des itérables asynchrones directement dans l’objet d’appel.

Si l’hôte expose des abonnements de style poussé, utilisez createAxCodeGrpcNativeIpcBridgeFromChannels() ou createAxCodeGrpcNativeIpcStream() pour adapter les rappels de l’hôte aux flux AsyncIterable attendus par le SDK gRPC. Ces assistants sont utiles pour les écouteurs d’événements Tauri, les rappels de préchargement Electron et les autres systèmes IPC qui renvoient une fonction de désabonnement plutôt qu’un générateur asynchrone JavaScript.

Les hôtes natifs peuvent aussi exposer une carte de gestionnaires au lieu d’écrire à la main un aiguillage de méthodes. C’est utile pour les commandes Rust/Tauri, les API de préchargement Electron, ou un véritable serveur gRPC local qui veut lier les opérations du runtime AX Code méthode par méthode. Utilisez les descripteurs de méthodes pour valider que chaque domaine attendu est couvert avant de remettre le pont au code de rendu :

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() est volontairement un instantané orienté interface plutôt qu’une copie une à une de chaque route HTTP. Utilisez include pour ne demander que l’état nécessaire à la vue courante. Les sous-requêtes échouées sont signalées dans errors tandis que les champs réussis sont encore renvoyés, afin qu’un sous-système facultatif manquant n’empêche pas l’enveloppe de bureau de s’ouvrir.

Le flux d’événements accepte les filtres facultatifs types et sessionID. Les transports natifs doivent appliquer ces filtres côté serveur. Le pont de compatibilité HTTP applique les mêmes filtres côté client sur la route SSE existante, afin que le code d’interface puisse garder une seule forme d’abonnement pendant que le serveur natif est mis en œuvre.

startAxCodeGrpcHeadlessBackend() est le repli temporaire préféré lorsque l’hôte démarre encore ax-code serve en interne. Il ne renvoie ni l’URL HTTP ni l’en-tête d’autorisation, afin que le code de rendu puisse être écrit contre la façade gRPC puis déplacé plus tard vers un véritable transport gRPC natif sans réécriture d’API publique.

Les hôtes de bureau fondés sur Node peuvent exposer un véritable point de terminaison gRPC HTTP/2 depuis le même pont natif avec @defai-digital/ax-code-sdk/grpc/node. Cela concerne les processus hôtes privilégiés, pas le code de rendu :

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

Le flux PTY est modélisé comme un flux bidirectionnel gRPC. Le pont HTTP adapte ce flux à la route WebSocket existante pour la compatibilité ; les hôtes d’interface natifs doivent le mettre en œuvre sur leur transport gRPC local, socket Unix ou tube nommé, au lieu d’exposer la route WebSocket au code de rendu.

Lorsqu’un véritable transport gRPC est disponible, fournissez-le à createAxCodeGrpcClient({ transport }). Le client de haut niveau reste le même.

Posture de sécurité

Pour les applications de bureau, préférez cet ordre :

1. SDK dans le processus lorsque l’interface est en TypeScript et peut charger le runtime sans risque.
2. Transport gRPC/natif local sur boucle locale, socket Unix ou tube nommé.
3. Pont sans interface HTTP/SSE avec des identifiants Basic Auth à usage unique générés.
4. N’exposez pas AX Code sur HTTP réseau.

Le pont de compatibilité HTTP de gRPC et les assistants de moteur HTTP gérés par le SDK n’acceptent que des points de terminaison de boucle locale littéraux. Les options héritées allowRemoteHttpBridge et allowNetworkBind sont conservées pour la compatibilité des sources, mais ne contournent pas la politique locale seulement. Gardez /doc limité au serveur de boucle locale.

Le pont de compatibilité HTTP rejette par défaut les mises à niveau WebSocket d’origine croisée. N’ajoutez une origine à la liste d’autorisation CORS explicite du serveur que lorsque cette origine de navigateur fait partie de l’enveloppe d’application de confiance.

N’exposez pas l’API HTTP complète, le WebSocket PTY ni la documentation OpenAPI à des WebView arbitraires. Si un WebView est utilisé, gardez-le comme rendu et acheminez les opérations privilégiées à travers l’hôte natif en utilisant la façade gRPC/native.