Diese Seite ist eine Übersetzung der englischen Dokumentation. Befehle, Bezeichner und Beispiele bleiben unverändert. Runtime 7.24.4 · SDK 2.6.7. Englische Fassung

gRPC- und nativer SDK-Transport

Status: Aktiv Umfang: Transportvertrag für Desktop und nativ Zuletzt geprüft: 2026-09-02 Verantwortlich: AX-Code-SDK

AX Code stellt jetzt einen optionalen, gRPC-förmigen Transportvertrag für Desktop- und native GUI-Apps bereit. Der Vertrag ist absichtlich enger als der volle Routenbaum von HTTP/OpenAPI: Er konzentriert sich auf die Headless-Laufzeitfähigkeiten, die eine GUI braucht, um sich nativ anzufühlen, und hält HTTP/OpenAPI intern für Kompatibilität, Diagnosen und erzeugte Clients verfügbar.

Empfehlung

Verwenden Sie den Transport gRPC/nativ als bevorzugte Grenze für eigene Desktop-Apps. Lassen Sie HTTP/SSE als Rückfall und Debug-Oberfläche aktiv.

Warum HTTP nicht entfernen

HTTP/OpenAPI aus der Laufzeit zu entfernen würde den am besten prüfbaren und portabelsten Kompatibilitätspfad entfernen. Das JavaScript-SDK sollte Teilpfade von HTTP-Client und Server nicht als eigene Unterstützungsoberflächen freigeben, aber die interne HTTP-Brücke bleibt nützlich für Diagnosen, den vorhandenen Headless-Backend-Start und Abläufe erzeugter Clients. Aktuelle Steuerungen des HTTP-Servers umfassen erzwungenes Binden nur an Loopback, erzeugte Basic-Auth-Zugangsdaten in SDK-verwalteten Backend-Hilfen, Origin-Prüfungen bei mutierenden Browseranfragen, Verzeichnisvalidierung, Anfrageratengrenzen und nur lokale live OpenAPI-Dokumentation.

Der Transport ist für normale Agentenrunden nicht die beherrschende Latenzquelle. LLM-Aufrufe, Shell-Befehle, Datei-E/A, Indizierung, LSP-Start und Toolausführung sind meist teurer als localhost-JSON. gRPC bleibt für eine Desktop-GUI nützlich, weil es einen klareren nativen API-Vertrag, Fristen, Metadaten, Server-Streaming und einen Weg zu Unix-Socket- oder Named-Pipe-Transporten bietet, ohne eine browserorientierte API in die App-Hülle zu ziehen.

Vertragsform

Der sprachneutrale Vertrag liegt unter packages/sdk/proto/ax_code/v1/headless.proto. Das JSR-Paket enthält dieses Proto auch als Asset. TypeScript-Hosts finden es mit resolveAxCodeGrpcProtoUrl(). Generatoren außerhalb von JavaScript sollten den kanonischen Repository-Vertrag verwenden.

Die TypeScript-Fassade liegt unter @defai-digital/ax-code-sdk/grpc und deckt ab:

• Gesundheit und Bereitschaft des Lebenszyklus
• Aufnahme von App-Protokollen und Steuerungen zum Freigeben und Neustarten der Instanz für die Lebenszyklusverwaltung des nativen Hosts
• Erzeugung von Sitzungen
• Prompt, Befehl, Shell, Abbruch, Berechtigungsantwort und Frageantwort
• GUI-Bootstrap-Schnappschüsse für Anbieter, Sitzungen, Berechtigungen, Fragen, Pfad, VCS, LSP, MCP, Formatierer und Befehlszustand
• Sitzungsliste, Detail, Nachrichtenhistorie, Nachrichtendetail, Kinder, Ziel, Todo, Diff, Fork, Teilen und Zusammenfassen
• GUI-Entdeckung und Workspace-Navigation für Agenten, Skills, Projekte, Pfad, VCS, Befehle, Dateibaum, Inhalt und Status, Suche nach Text, Datei und Symbol sowie Tool-Schemata
• Projektkontext, Kontextvorlagen, Aktualisieren und Leeren des zwischengespeicherten Speichers sowie Diagnosen ausstehender Pläne der Debug-Engine
• Auflisten, Beantworten und Ablehnen ausstehender Berechtigungen und Fragen für beaufsichtigte GUI-Abläufe
• Einstellungen für Anbieter, Konfiguration, API-Schlüssel-Auth und Anbieter-OAuth für GUI-Einstellungsbildschirme
• Laufzeiteinstellungen für autonomen Modus, Isolationsmodus und intelligentes LLM-Routing
• MCP-Status, Ressourcenentdeckung, dynamische Serververwaltung, OAuth sowie Verbinden und Trennen
• LSP- und Formatiererstatus für Diagnosen und Einstellungsbildschirme
• PTY-Terminalverwaltung und bidirektionales Terminal-Streaming
• Sitzungsnachweise für Prüf- und Debug-Oberflächen
• Operationen der Aufgabenwarteschlange
• Operationen geplanter Aufgaben
• Ablaufvorlagen, Abläufe, Dashboard-Zusammenfassungen, Auswertungsfälle, Ablaufroutinen und Laufartefakte
• vom Server gestreamte Laufzeitereignisse

Das Proto verwendet strukturierte JSON-Nutzlasten für Befehlskörper und Nutzlasten von Ablauf und Aufgabe. Das hält den Transport stabil, während sich die Laufzeitschemata von AX Code schnell weiterentwickeln.

@defai-digital/ax-code-sdk/grpc exportiert außerdem AX_CODE_GRPC_METHOD_DESCRIPTORS, listAxCodeGrpcMethods(), getAxCodeGrpcMethodDescriptor(), assertAxCodeGrpcMethodSupported(), listMissingAxCodeGrpcNativeHandlers() und assertAxCodeGrpcNativeHandlers(). Native Hosts sollten diese Deskriptoren und Abdeckungsprüfungen als kanonischen Methodenkatalog verwenden, wenn sie Handler-Zuordnungen, gRPC-Dienstbinder, Preload-Zulassungslisten oder Startschranken bauen. Jeder Deskriptor enthält den Methodennamen, den voll qualifizierten Methodenpfad, die Stromart, die Proto-Namen von Anfrage und Antwort, die GUI-Domäne, die Verfügbarkeit der HTTP-Brücke und die aktuelle Stabilität. Das hält die native Transportgrenze ausdrücklich, ohne den vollen HTTP-Routenbaum freizugeben oder zu spiegeln.

Verwendung in TypeScript

Verwenden Sie das SDK-verwaltete gRPC-Headless-Backend, wenn der Host die vorhandene HTTP-Laufzeit intern noch braucht. Es hält die HTTP-Brücke im Hostprozess und gibt nur den gRPC-Client plus das Lebenszyklus-Handle zurück:

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

Verwenden Sie eine native IPC-Brücke, wenn der Desktop-Host die privilegierte Laufzeitgrenze über Electron-Preload, Tauri-Befehle oder eine andere Grenze mit strukturiertem Klonen besitzt. IPC-Aufrufe lassen AbortSignal absichtlich weg und halten den bidirektionalen Eingabestrom außerhalb der Aufrufnutzlast, damit das Aufrufobjekt Renderer- und Hostgrenzen sauber überqueren kann:

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

Verwenden Sie createAxCodeGrpcClientFromNativeBridge() nur, wenn beide Seiten in derselben JavaScript-Umgebung sind und AbortSignal sowie asynchrone Iterierbare direkt im Aufrufobjekt übergeben können.

Wenn der Host Push-Abonnements bereitstellt, verwenden Sie createAxCodeGrpcNativeIpcBridgeFromChannels() oder createAxCodeGrpcNativeIpcStream(), um Host-Rückrufe an die AsyncIterable-Ströme anzupassen, die das gRPC-SDK erwartet. Diese Hilfen sind nützlich für Tauri-Ereignislistener, Electron-Preload-Rückrufe und andere IPC-Systeme, die eine Abmeldefunktion statt eines JavaScript-Async-Generators zurückgeben.

Native Hosts können auch eine Handler-Zuordnung bereitstellen, statt einen Methodenschalter von Hand zu schreiben. Das ist nützlich für Rust- oder Tauri-Befehle, Electron-Preload-APIs oder einen echten lokalen gRPC-Server, der Laufzeitoperationen von AX Code Methode für Methode binden will. Verwenden Sie die Methodendeskriptoren, um zu prüfen, dass jede erwartete Domäne abgedeckt ist, bevor Sie die Brücke an Renderer-Code übergeben:

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() ist absichtlich ein GUI-orientierter Schnappschuss und keine eins-zu-eins-Kopie jeder HTTP-Route. Verwenden Sie include, um nur den Zustand anzufordern, den die aktuelle Ansicht braucht. Fehlgeschlagene Teilanfragen werden in errors gemeldet, während erfolgreiche Felder weiterhin zurückgegeben werden, sodass ein fehlendes optionales Subsystem die Desktop-Hülle nicht am Öffnen hindert.

Ereignis-Streaming akzeptiert optionale Filter types und sessionID. Native Transporte sollten diese Filter serverseitig anwenden. Die HTTP-Kompatibilitätsbrücke wendet dieselben Filter clientseitig über die vorhandene SSE-Route an, damit GUI-Code eine Abonnementform behalten kann, während der native Server umgesetzt wird.

startAxCodeGrpcHeadlessBackend() ist der bevorzugte vorübergehende Rückfall, wenn der Host ax-code serve intern noch startet. Es gibt weder die HTTP-URL noch den Autorisierungsheader zurück, daher kann Renderer-Code gegen die gRPC-Fassade geschrieben und später ohne Umschreiben der öffentlichen API auf einen echten nativen gRPC-Transport verschoben werden.

Node-basierte Desktop-Hosts können aus derselben nativen Brücke einen echten HTTP/2-gRPC-Endpunkt mit @defai-digital/ax-code-sdk/grpc/node bereitstellen. Das gilt für privilegierte Hostprozesse, nicht für Renderer-Code:

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

PTY-Streaming ist als bidirektionaler gRPC-Strom modelliert. Die HTTP-Brücke passt diesen Strom an die vorhandene WebSocket-Route an, zur Kompatibilität. Native GUI-Hosts sollten ihn über ihren lokalen gRPC-, Unix-Socket- oder Named-Pipe-Transport umsetzen, statt die WebSocket-Route an Renderer-Code freizugeben.

Wenn ein echter gRPC-Transport verfügbar ist, übergeben Sie ihn an createAxCodeGrpcClient({ transport }). Der Client höherer Ebene bleibt derselbe.

Sicherheitslage

Bevorzugen Sie für Desktop-Apps diese Reihenfolge:

1. SDK im Prozess, wenn die GUI TypeScript ist und die Laufzeit sicher laden kann.
2. Lokaler Transport gRPC/nativ über Loopback, Unix-Socket oder Named Pipe.
3. HTTP/SSE-Headless-Brücke mit erzeugten einmaligen Basic-Auth-Zugangsdaten.
4. Geben Sie AX Code nicht über Netzwerk-HTTP frei.

Die gRPC-HTTP-Kompatibilitätsbrücke und SDK-verwaltete HTTP-Backend-Hilfen akzeptieren nur literale Loopback-Endpunkte. Die älteren Optionen allowRemoteHttpBridge und allowNetworkBind bleiben aus Quellkompatibilität, umgehen die Nur-lokal-Richtlinie aber nicht. Halten Sie /doc auf den Loopback-Server begrenzt.

Die HTTP-Kompatibilitätsbrücke lehnt Cross-Origin-WebSocket-Upgrades standardmäßig ab. Fügen Sie einen Origin nur dann der ausdrücklichen CORS-Zulassungsliste des Servers hinzu, wenn dieser Browser-Origin Teil der vertrauenswürdigen App-Hülle ist.

Geben Sie die volle HTTP-API, den PTY-WebSocket oder die OpenAPI-Dokumentation nicht an beliebige WebViews frei. Wenn eine WebView verwendet wird, halten Sie sie als Renderer und leiten Sie privilegierte Operationen über den nativen Host mit der Fassade gRPC/nativ.