このページは英語版ドキュメントの翻訳です。コマンド、識別子、例はそのままです。ランタイム 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 呼び出し、シェルコマンド、ファイル I/O、索引付け、LSP 起動、ツール実行は、通常 localhost の JSON より高価です。gRPC はそれでもデスクトップ GUI に有用です。よりきれいなネイティブ API 契約、期限、メタデータ、サーバーストリーミング、そしてブラウザ向け API をアプリシェルへ引きずり込まずに Unix ソケットや名前付きパイプ転送へ進む経路を提供するためです。

契約の形

言語中立の契約は packages/sdk/proto/ax_code/v1/headless.proto にあります。JSR パッケージにも、その proto がアセットとして含まれます。TypeScript ホストは resolveAxCodeGrpcProtoUrl() でそれを見つけます。非 JavaScript の生成器は、正規リポジトリの契約を使うべきです。

TypeScript ファサードは @defai-digital/ax-code-sdk/grpc にあり、次を扱います。

• 健全性とライフサイクルの準備
• アプリログの取り込みと、ネイティブホストのライフサイクル管理のためのインスタンス破棄と再起動の制御
• セッション作成
• プロンプト、コマンド、シェル、中止、権限の返信、質問の返信
• プロバイダー、セッション、権限、質問、パス、VCS、LSP、MCP、フォーマッター、コマンド状態のための GUI ブートストラップスナップショット
• セッション一覧、詳細、メッセージ履歴、メッセージ詳細、子、ゴール、todo、差分、フォーク、共有、要約の操作
• エージェント、スキル、プロジェクト、パス、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 サービスバインダー、プリロード許可リスト、起動ゲートを作るとき、これらの記述子と網羅確認を正規のメソッドカタログとして使うべきです。各記述子には、メソッド名、完全修飾メソッドパス、ストリーム種別、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 プリロード、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 と async iterable を直接安全に渡せるときだけ使います。

ホストがプッシュ型の購読を公開するときは、createAxCodeGrpcNativeIpcBridgeFromChannels() または createAxCodeGrpcNativeIpcStream() を使い、ホストのコールバックを gRPC SDK が期待する AsyncIterable ストリームへ適合させます。これらのヘルパーは、JavaScript の async generator ではなく解除関数を返す Tauri イベントリスナー、Electron プリロードコールバック、その他の IPC システムに有用です。

ネイティブホストは、メソッドの switch を手書きする代わりにハンドラーマップを公開することもできます。これは Rust/Tauri コマンド、Electron プリロード 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 コードは 1 つの購読形を保てます。

startAxCodeGrpcHeadlessBackend() は、ホストが内部でまだ ax-code serve を起動するときの好ましい一時フォールバックです。HTTP URL や認可ヘッダーを返さないため、レンダラーコードは gRPC ファサードに対して書け、後で公開 API を書き直さずに実際のネイティブ gRPC 転送へ移せます。

Node ベースのデスクトップホストは、同じネイティブブリッジから実際の HTTP/2 gRPC エンドポイントを @defai-digital/ax-code-sdk/grpc/node で公開できます。これは特権ホストプロセス向けであり、レンダラーコード向けではありません。

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/ネイティブファサードを使ってネイティブホスト経由でルーティングしてください。