이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문

gRPC와 네이티브 SDK 전송

상태: 활성 범위: 데스크톱 네이티브 전송 계약 최종 검토: 2026-09-02 담당: ax-code sdk

AX Code는 이제 데스크톱과 네이티브 GUI 앱을 위한 선택적 gRPC 형태의 전송 계약을 노출합니다. 계약은 전체 HTTP/OpenAPI 경로 트리보다 의도적으로 좁습니다. GUI가 네이티브처럼 느끼게 하는 헤드리스 런타임 기능에 집중하고, HTTP/OpenAPI는 호환, 진단, 생성된 클라이언트를 위해 내부에서 계속 사용할 수 있습니다.

권장

자사 데스크톱 앱의 선호 경계로 gRPC/네이티브 전송을 사용합니다. HTTP/SSE는 폴백과 디버그 표면으로 켜 둡니다.

HTTP를 제거하지 않는 이유

런타임에서 HTTP/OpenAPI를 제거하면 가장 살펴보기 쉽고 옮길 수 있는 호환 경로가 사라집니다. JavaScript SDK는 HTTP 클라이언트/서버 하위 경로를 자사 지원 표면으로 노출하지 않아야 하지만, 내부 HTTP 브리지는 진단, 기존 헤드리스 백엔드 시작, 생성된 클라이언트 작업 흐름에 여전히 유용합니다. 현재 HTTP 서버 제어에는 강제된 루프백 전용 바인딩, SDK가 관리하는 백엔드 도우미의 생성된 Basic Auth 자격 증명, 변경하는 브라우저 요청의 오리진 검사, 디렉터리 검증, 요청 속도 제한, 루프백 전용 실시간 OpenAPI 문서가 포함됩니다.

전송은 일반적인 에이전트 턴의 지배적인 지연 원인이 아닙니다. LLM 호출, 셸 명령, 파일 IO, 색인, LSP 시작, 도구 실행이 보통 localhost JSON보다 더 비쌉니다. gRPC는 더 깨끗한 네이티브 API 계약, 기한, 메타데이터, 서버 스트리밍, 브라우저 지향 API를 앱 셸로 끌어들이지 않고 Unix 소켓이나 명명된 파이프 전송으로 가는 경로를 제공하므로 데스크톱 GUI에 여전히 유용합니다.

계약 형태

언어 중립 계약은 packages/sdk/proto/ax_code/v1/headless.proto에 있습니다. JSR 패키지도 그 proto를 자산으로 담습니다. TypeScript 호스트는 resolveAxCodeGrpcProtoUrl()로 찾습니다. JavaScript가 아닌 생성기는 기준 저장소 계약을 사용해야 합니다.

TypeScript 퍼사드는 @defai-digital/ax-code-sdk/grpc에 있으며 다음을 다룹니다.

• 건강과 수명 주기 준비
• 네이티브 호스트 수명 주기 관리를 위한 앱 로그 수집과 인스턴스 폐기/다시 시작 제어
• 세션 생성
• 프롬프트, 명령, 셸, 중단, 권한 응답, 질문 응답
• 공급자, 세션, 권한, 질문, 경로, VCS, LSP, MCP, 포매터, 명령 상태를 위한 GUI 부트스트랩 스냅샷
• 세션 목록, 세부 정보, 메시지 기록, 메시지 세부 정보, 자식, 목표, 할 일, diff, 포크, 공유, 요약 연산
• 에이전트, 스킬, 프로젝트, 경로, VCS, 명령, 파일 트리/내용/상태, 텍스트/파일/기호 검색, 도구 스키마를 위한 GUI 탐색과 작업 공간 이동
• 프로젝트 컨텍스트, 컨텍스트 템플릿, 캐시된 메모리 새로 고침/지우기, 디버그 엔진의 대기 계획 진단
• 감독되는 GUI 흐름을 위한 대기 권한과 질문의 목록/응답/거부 연산
• GUI 설정 화면을 위한 공급자, 구성, API 키 인증, 공급자 OAuth 설정
• 자율 모드, 격리 모드, 스마트 LLM 라우팅을 위한 런타임 설정 제어
• MCP 상태, 자원 탐색, 동적 서버 관리, OAuth, 연결, 연결 해제 제어
• 진단과 설정 화면을 위한 LSP와 포매터 상태
• PTY 터미널 관리와 양방향 터미널 스트리밍
• 검토/디버그 UI를 위한 세션 증거
• 작업 대기열 연산
• 예약 작업 연산
• 워크플로 템플릿, 워크플로 실행, 대시보드 요약, 평가 사례, 워크플로 루틴, 실행 아티팩트
• 서버가 스트리밍하는 런타임 이벤트

proto는 명령 본문과 워크플로/작업 페이로드에 구조화된 JSON 페이로드를 사용합니다. AX Code 런타임 스키마가 계속 빨리 바뀌는 동안 전송을 안정적으로 유지합니다.

@defai-digital/ax-code-sdk/grpc은 AX_CODE_GRPC_METHOD_DESCRIPTORS, listAxCodeGrpcMethods(), getAxCodeGrpcMethodDescriptor(), assertAxCodeGrpcMethodSupported(), listMissingAxCodeGrpcNativeHandlers(), assertAxCodeGrpcNativeHandlers()도 내보냅니다. 네이티브 호스트는 핸들러 맵, gRPC 서비스 바인더, preload 허용 목록, 시작 게이트를 만들 때 이 설명자와 커버리지 검사를 기준 메서드 카탈로그로 사용해야 합니다. 각 설명자에는 메서드 이름, 완전히 한정된 메서드 경로, 스트림 종류, proto 요청과 응답 메시지 이름, GUI 도메인, HTTP 브리지 가용성, 현재 안정성이 포함됩니다. 이것은 전체 HTTP 경로 트리를 노출하거나 그대로 비추지 않고 네이티브 전송 경계를 명시적으로 유지합니다.

TypeScript 사용

호스트가 내부에서 기존 HTTP 런타임이 여전히 필요할 때는 SDK가 관리하는 gRPC 헤드리스 백엔드를 사용합니다. HTTP 브리지를 호스트 프로세스 안에 두고 gRPC 클라이언트와 수명 주기 핸들만 반환합니다.

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

데스크톱 호스트가 Electron preload, Tauri 명령, 또는 다른 구조화 복제 경계를 통해 특권 런타임 경계를 소유할 때는 네이티브 IPC 브리지를 사용합니다. IPC 호출은 의도적으로 AbortSignal를 생략하고, 호출 객체가 렌더러/호스트 경계를 깨끗하게 건널 수 있도록 양방향 입력 스트림을 호출 페이로드 밖에 둡니다.

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

createAxCodeGrpcClientFromNativeBridge()는 양쪽이 같은 JavaScript 영역에 있고 호출 객체에서 AbortSignal과 비동기 이터러블을 직접 안전하게 전달할 수 있을 때만 사용합니다.

호스트가 푸시 스타일 구독을 노출하면, 호스트 콜백을 gRPC SDK가 기대하는 AsyncIterable 스트림으로 맞추기 위해 createAxCodeGrpcNativeIpcBridgeFromChannels() 또는 createAxCodeGrpcNativeIpcStream()을 사용합니다. 이 도우미는 JavaScript 비동기 생성기 대신 구독 해제 함수를 반환하는 Tauri 이벤트 리스너, Electron preload 콜백, 그 밖의 IPC 시스템에 유용합니다.

네이티브 호스트는 메서드 분기를 손으로 쓰는 대신 핸들러 맵을 노출할 수도 있습니다. Rust/Tauri 명령, Electron preload API, 또는 AX Code 런타임 연산을 메서드별로 묶고 싶은 실제 로컬 gRPC 서버에 유용합니다. 브리지를 렌더러 코드에 넘기기 전에 메서드 설명자로 예상되는 모든 도메인이 다뤄지는지 검증합니다.

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()는 모든 HTTP 경로를 일대일로 복사한 것이 아니라 의도적으로 GUI 지향 스냅샷입니다. 현재 보기에 필요한 상태만 요청하려면 include을 사용합니다. 실패한 하위 요청은 errors에 보고되고 성공한 필드는 여전히 반환되므로, 선택적 하위 시스템이 없어도 데스크톱 셸이 열리는 것을 막지 않습니다.

이벤트 스트리밍은 선택적 types와 sessionID 필터를 받습니다. 네이티브 전송은 그 필터를 서버 쪽에서 적용해야 합니다. HTTP 호환 브리지는 기존 SSE 경로 위에서 같은 필터를 클라이언트 쪽에 적용하므로, 네이티브 서버를 구현하는 동안 GUI 코드가 하나의 구독 형태를 유지할 수 있습니다.

startAxCodeGrpcHeadlessBackend()는 호스트가 내부에서 여전히 ax-code serve를 시작할 때의 선호하는 임시 폴백입니다. HTTP URL이나 권한 헤더를 반환하지 않으므로, 렌더러 코드는 gRPC 퍼사드에 맞춰 쓰고 나중에 공개 API를 다시 쓰지 않고 실제 네이티브 gRPC 전송으로 옮길 수 있습니다.

Node 기반 데스크톱 호스트는 @defai-digital/ax-code-sdk/grpc/node으로 같은 네이티브 브리지에서 실제 HTTP/2 gRPC 엔드포인트를 노출할 수 있습니다. 이것은 렌더러 코드가 아니라 특권 호스트 프로세스를 위한 것입니다.

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 스트리밍은 gRPC 양방향 스트림으로 모델링됩니다. HTTP 브리지는 호환을 위해 그 스트림을 기존 WebSocket 경로에 맞춥니다. 네이티브 GUI 호스트는 WebSocket 경로를 렌더러 코드에 노출하는 대신 로컬 gRPC, Unix 소켓, 명명된 파이프 전송 위에서 구현해야 합니다.

실제 gRPC 전송을 사용할 수 있으면 createAxCodeGrpcClient({ transport })에 제공합니다. 상위 클라이언트는 그대로입니다.

보안 자세

데스크톱 앱에는 이 순서를 선호합니다.

1. GUI가 TypeScript이고 런타임을 안전하게 불러올 수 있으면 프로세스 안 SDK.
2. 루프백, Unix 소켓, 명명된 파이프 위의 로컬 gRPC/네이티브 전송.
3. 생성된 일회용 Basic Auth 자격 증명이 있는 HTTP/SSE 헤드리스 브리지.
4. AX Code를 네트워크 HTTP로 노출하지 않습니다.

gRPC HTTP 호환 브리지와 SDK가 관리하는 HTTP 백엔드 도우미는 리터럴 루프백 엔드포인트만 받습니다. 이전 allowRemoteHttpBridge과 allowNetworkBind 옵션은 소스 호환을 위해 남아 있지만 로컬 전용 정책을 우회하지 않습니다. /doc은 루프백 서버로 제한합니다.

HTTP 호환 브리지는 기본적으로 교차 오리진 WebSocket 업그레이드를 거부합니다. 그 브라우저 오리진이 신뢰하는 앱 셸의 일부일 때만 명시적인 서버 CORS 허용 목록에 오리진을 추가합니다.

전체 HTTP API, PTY WebSocket, OpenAPI 문서를 임의의 WebView에 노출하지 마십시오. WebView를 쓰면 렌더러로 두고, 특권 연산은 gRPC/네이티브 퍼사드를 통해 네이티브 호스트로 라우팅합니다.