Halaman ini diterjemahkan dari dokumentasi bahasa Inggris. Perintah, pengenal, dan contoh tidak diubah. Runtime 7.24.4 · SDK 2.6.7. Sumber bahasa Inggris

Transport gRPC dan SDK bawaan

Status: Aktif Cakupan: kontrak transport bawaan desktop Terakhir ditinjau: 2026-09-02 Pemilik: sdk ax-code

AX Code kini mengekspos kontrak transport berbentuk gRPC opsional untuk aplikasi desktop dan GUI bawaan. Kontrak ini sengaja lebih sempit daripada pohon rute HTTP/OpenAPI penuh: ia berfokus pada kemampuan runtime tanpa interaksi yang dibutuhkan GUI agar terasa bawaan, sambil menjaga HTTP/OpenAPI tersedia secara internal untuk kompatibilitas, diagnostik, dan klien yang dihasilkan.

Rekomendasi

Pakai transport gRPC/bawaan sebagai batas yang diutamakan untuk aplikasi desktop pihak pertama. Biarkan HTTP/SSE aktif sebagai cadangan dan permukaan debug.

Mengapa tidak menghapus HTTP

Menghapus HTTP/OpenAPI dari runtime akan menghapus jalur kompatibilitas yang paling dapat diperiksa dan paling portabel. SDK JavaScript tidak boleh mengekspos subjalur klien/server HTTP sebagai permukaan dukungan pihak pertama, tetapi jembatan HTTP internal tetap berguna untuk diagnostik, mulai backend tanpa interaksi yang sudah ada, dan alur kerja klien yang dihasilkan. Kendali server HTTP saat ini mencakup pengikatan hanya-loopback yang ditegakkan, kredensial Basic Auth yang dihasilkan pada pembantu backend terkelola SDK, pemeriksaan origin pada permintaan peramban yang mengubah, validasi direktori, batas laju permintaan, dan dokumen OpenAPI langsung yang hanya loopback.

Transport bukan sumber latensi dominan untuk giliran agen biasa. Panggilan LLM, perintah shell, IO berkas, pengindeksan, mulai LSP, dan eksekusi alat biasanya lebih mahal daripada JSON localhost. gRPC tetap berguna untuk GUI desktop karena menyediakan kontrak API bawaan yang lebih bersih, batas waktu, metadata, aliran server, dan jalur ke transport soket Unix atau named-pipe tanpa menyeret API berorientasi peramban ke shell aplikasi.

Bentuk kontrak

Kontrak netral bahasa berada di packages/sdk/proto/ax_code/v1/headless.proto. Paket JSR juga berisi proto itu sebagai aset. Host TypeScript menemukannya dengan resolveAxCodeGrpcProtoUrl(); generator non-JavaScript harus memakai kontrak repositori kanonis.

Fasad TypeScript berada di @defai-digital/ax-code-sdk/grpc dan mencakup:

• kesiapan kesehatan dan siklus hidup
• penyerapan log aplikasi serta kendali buang/mulai ulang instans untuk pengelolaan siklus hidup host bawaan
• pembuatan sesi
• prompt, perintah, shell, pengguguran, balasan izin, dan balasan pertanyaan
• cuplikan bootstrap GUI untuk penyedia, sesi, izin, pertanyaan, jalur, VCS, LSP, MCP, pemformat, dan keadaan perintah
• operasi daftar sesi, detail, riwayat pesan, detail pesan, anak, tujuan, todo, diff, cabang, bagikan, dan ringkas
• penemuan GUI dan navigasi ruang kerja untuk agen, skill, proyek, jalur, VCS, perintah, pohon/konten/status berkas, pencarian teks/berkas/simbol, dan skema alat
• konteks proyek, templat konteks, segarkan/bersihkan memori ter-cache, dan diagnostik rencana tertunda mesin debug
• operasi daftar/balas/tolak izin dan pertanyaan tertunda untuk alur GUI yang diawasi
• pengaturan penyedia, konfigurasi, autentikasi kunci API, dan OAuth penyedia untuk layar pengaturan GUI
• kendali pengaturan runtime untuk mode otonom, mode isolasi, dan perutean LLM cerdas
• status MCP, penemuan sumber daya, pengelolaan server dinamis, OAuth, sambungkan, dan putuskan
• status LSP dan pemformat untuk layar diagnostik dan pengaturan
• pengelolaan terminal PTY dan aliran terminal dua arah
• bukti sesi untuk UI tinjauan/debug
• operasi antrean tugas
• operasi tugas terjadwal
• templat alur kerja, jalankan alur kerja, ringkasan dasbor, kasus eval, rutinitas alur kerja, dan artefak jalankan
• peristiwa runtime yang dialirkan server

Proto memakai muatan JSON terstruktur untuk isi perintah dan muatan alur kerja/tugas. Itu menjaga transport tetap stabil sementara skema runtime AX Code terus berkembang cepat.

@defai-digital/ax-code-sdk/grpc juga mengekspor AX_CODE_GRPC_METHOD_DESCRIPTORS, listAxCodeGrpcMethods(), getAxCodeGrpcMethodDescriptor(), assertAxCodeGrpcMethodSupported(), listMissingAxCodeGrpcNativeHandlers(), dan assertAxCodeGrpcNativeHandlers(). Host bawaan harus memakai deskriptor dan pemeriksaan cakupan ini sebagai katalog metode kanonis saat membangun peta penangan, pengikat layanan gRPC, daftar izin preload, atau gerbang mulai. Setiap deskriptor mencakup nama metode, jalur metode yang sepenuhnya terkualifikasi, jenis aliran, nama pesan permintaan dan respons proto, domain GUI, ketersediaan jembatan HTTP, dan stabilitas saat ini. Ini menjaga batas transport bawaan tetap eksplisit tanpa mengekspos atau mencerminkan pohon rute HTTP penuh.

Pemakaian TypeScript

Pakai backend tanpa interaksi gRPC terkelola SDK bila host masih membutuhkan runtime HTTP yang ada secara internal. Ia menjaga jembatan HTTP di dalam proses host dan hanya mengembalikan klien gRPC plus handle siklus hidup:

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

Pakai jembatan IPC bawaan bila host desktop memiliki batas runtime istimewa melalui preload Electron, perintah Tauri, atau batas structured-clone lain. Panggilan IPC sengaja menghilangkan AbortSignal dan menjaga aliran masukan dua arah di luar muatan panggilan agar objek panggilan dapat menyeberangi batas perender/host dengan bersih:

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

Pakai createAxCodeGrpcClientFromNativeBridge() hanya bila kedua sisi berada di realm JavaScript yang sama dan dapat meneruskan AbortSignal serta iterable asinkron secara langsung dalam objek panggilan dengan aman.

Jika host mengekspos langganan bergaya dorong, pakai createAxCodeGrpcNativeIpcBridgeFromChannels() atau createAxCodeGrpcNativeIpcStream() untuk menyesuaikan callback host menjadi aliran AsyncIterable yang diharapkan SDK gRPC. Pembantu itu berguna untuk pendengar peristiwa Tauri, callback preload Electron, dan sistem IPC lain yang mengembalikan fungsi berhenti-langganan alih-alih generator asinkron JavaScript.

Host bawaan juga dapat mengekspos peta penangan alih-alih menulis sakelar metode secara manual. Ini berguna untuk perintah Rust/Tauri, API preload Electron, atau server gRPC lokal sungguhan yang ingin mengikat operasi runtime AX Code metode demi metode. Pakai deskriptor metode untuk memvalidasi bahwa setiap domain yang diharapkan tercakup sebelum menyerahkan jembatan ke kode perender:

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() sengaja berupa cuplikan berorientasi GUI, bukan salinan satu-lawan-satu setiap rute HTTP. Pakai include untuk meminta hanya keadaan yang dibutuhkan tampilan saat ini. Subpermintaan yang gagal dilaporkan di errors sementara bidang yang berhasil tetap dikembalikan, jadi subsistem opsional yang hilang tidak memblokir shell desktop untuk terbuka.

Aliran peristiwa menerima filter types dan sessionID opsional. Transport bawaan harus menerapkan filter itu di sisi server. Jembatan kompatibilitas HTTP menerapkan filter yang sama di sisi klien di atas rute SSE yang ada agar kode GUI dapat mempertahankan satu bentuk langganan sementara server bawaan sedang diimplementasikan.

startAxCodeGrpcHeadlessBackend() adalah cadangan sementara yang diutamakan bila host masih memulai ax-code serve secara internal. Ia tidak mengembalikan URL HTTP atau header otorisasi, jadi kode perender dapat ditulis terhadap fasad gRPC dan kemudian dipindahkan ke transport gRPC bawaan sungguhan tanpa penulisan ulang API publik.

Host desktop berbasis Node dapat mengekspos titik akhir gRPC HTTP/2 sungguhan dari jembatan bawaan yang sama dengan @defai-digital/ax-code-sdk/grpc/node. Ini untuk proses host istimewa, bukan kode perender:

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

Aliran PTY dimodelkan sebagai aliran dua arah gRPC. Jembatan HTTP menyesuaikan aliran itu ke rute WebSocket yang ada demi kompatibilitas; host GUI bawaan harus mengimplementasikannya di atas transport gRPC lokal, soket Unix, atau named-pipe mereka alih-alih mengekspos rute WebSocket ke kode perender.

Bila transport gRPC sungguhan tersedia, berikan ke createAxCodeGrpcClient({ transport }). Klien tingkat tinggi tetap sama.

Postur keamanan

Untuk aplikasi desktop, utamakan urutan ini:

1. SDK dalam proses bila GUI adalah TypeScript dan dapat memuat runtime dengan aman.
2. Transport gRPC/bawaan lokal melalui loopback, soket Unix, atau named pipe.
3. Jembatan tanpa interaksi HTTP/SSE dengan kredensial Basic Auth sekali pakai yang dihasilkan.
4. Jangan mengekspos AX Code melalui HTTP jaringan.

Jembatan kompatibilitas HTTP gRPC dan pembantu backend HTTP terkelola SDK hanya menerima titik akhir loopback harfiah. Opsi lama allowRemoteHttpBridge dan allowNetworkBind dipertahankan untuk kompatibilitas sumber tetapi tidak melewati kebijakan hanya-lokal. Jaga /doc terbatas pada server loopback.

Jembatan kompatibilitas HTTP menolak peningkatan WebSocket lintas origin secara bawaan. Tambahkan origin ke daftar izin CORS server yang eksplisit hanya bila origin peramban itu bagian dari shell aplikasi tepercaya.

Jangan mengekspos API HTTP penuh, WebSocket PTY, atau dokumen OpenAPI ke WebView sembarang. Jika WebView dipakai, jaga sebagai perender dan arahkan operasi istimewa melalui host bawaan memakai fasad gRPC/bawaan.