SDK と CLI の互換性

GitHub Copilot SDK は、JSON-RPC プロトコルを介して GitHub Copilot CLI（コマンドラインインターフェース） と通信します。 SDK で使用できるようにするには、このプロトコルを使用して機能を明示的に公開する必要があります。 多くの対話型 CLI 機能はターミナル固有であり、プログラムでは使用できません。

機能の比較

SDK で使用可能

SDK では使用できません (CLI のみ)

対処方法

セッションのエクスポート

--share オプションは SDK では使用できません。 これを解決するには、次のようにします。

• イベントを手動で収集する: セッション イベントをサブスクライブし、独自のエクスポートを作成します。

  TypeScript

  const events: SessionEvent[] = [];
  session.on((event) => events.push(event));
  // ... after conversation ...
  const messages = await session.getMessages();
  // Format as markdown yourself
  

• 1 回限りのエクスポートには CLI を直接使用します。

アクセス許可の制御

SDK では、既定で拒否アクセス許可モデルが使用されます。 アプリが onPermissionRequest ハンドラーを提供しない限り、すべてのアクセス許可要求 (ファイルの書き込み、シェル コマンド、URL フェッチなど) は拒否されます。

--allow-all-pathsまたは--yoloの代わりに、アクセス許可ハンドラーを使用します。

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

トークンの使用状況の追跡

/usageの代わりに、使用状況イベントをサブスクライブします。

session.on("assistant.usage", (event) => {
  console.log("Tokens used:", {
    input: event.data.inputTokens,
    output: event.data.outputTokens,
  });
});

session.on("assistant.usage", (event) => {
  console.log("Tokens used:", {
    input: event.data.inputTokens,
    output: event.data.outputTokens,
  });
});

コンテキスト圧縮

/compactの代わりに、自動圧縮を構成するか、手動でトリガーします。

// Automatic compaction via config
const session = await client.createSession({
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // Start background compaction at 80% context utilization
    bufferExhaustionThreshold: 0.95,      // Block and compact at 95% context utilization
  },
});

// Manual compaction (experimental)
const result = await session.rpc.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

// Automatic compaction via config
const session = await client.createSession({
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // Start background compaction at 80% context utilization
    bufferExhaustionThreshold: 0.95,      // Block and compact at 95% context utilization
  },
});

// Manual compaction (experimental)
const result = await session.rpc.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

プランの管理

プログラムによるセッション 計画の読み取りと書き込み:

// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
  console.log(plan.content);
}

// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });

// Delete the plan
await session.rpc.plan.delete();

// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
  console.log(plan.content);
}

// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });

// Delete the plan
await session.rpc.plan.delete();

メッセージ制御

中止せずに、現在の LLM ターンにメッセージを挿入します。

// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });

// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });

// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });

// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });

プロトコルの制限事項

SDK は、CLI の JSON-RPC プロトコルを介して公開されている機能にのみアクセスできます。 使用できない CLI 機能が必要な場合:

• 代替手段を確認します。 多くの機能には、SDK に相当するものがあります (上記 の回避策を 参照)。
• CLI を直接使用します。 1 回限りの操作の場合は、CLI を呼び出します。
• 機能を要求します。 プロトコルのサポートを要求するには、 github/copilot-sdk リポジトリで問題を開きます。

バージョン互換性

SDK は起動時に CLI とプロトコル バージョンをネゴシエートします。 SDK では、プロトコル バージョン 2 から 3 がサポートされています。 v2 CLI サーバーに接続すると、SDK は tool.call と permission.request メッセージを v3 イベント モデルに自動的に適合させます。コードの変更は必要ありません。

実行時にバージョンを確認できます。

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);