Java SDK の Maven 座標は
SDK のメインエントリです。単発クエリ、複数ターンのセッション、事前起動を作成します。スレッドセーフで再利用できます。クローズすると、作成したすべてのクエリとセッションも連鎖的にクローズされます。
引数エラーとローカル状態のエラーは同期的にスローされます。例:
単発クエリのハンドルです。
CLI はこのターンの
複数ターンのセッションです。
一部のメソッドは、CLI が対応する capability をサポートしている必要があります。サポートしていない場合は
プッシュされたカタログは常に古い値を全体ごと置き換えます。空のリストは CLI がカタログを明示的に空にしたことを表します。
コマンドまたは skill のメタデータです。
起動、認証、初期化を済ませた CLI です。
変換済みまたはクローズ済みの状態で再度変換すると
クエリまたはセッションのメッセージストリームです。互いに排他的な 2 つの消費方法をサポートします。
各ストリームを消費できるのは 1 回だけで、
プル用のカーソルです。
複数ターンのセッションでは、1 つのカーソルをターンをまたいで使い続けてください。各ターンで
プッシュモードのメッセージハンドラーです。
ハンドラーがスローした例外により、
クエリとセッションの不変オプションです。
2 つのデフォルト値は定数としても提供されています:
単発クエリのリクエストです。1 つの
CLI に送る 1 件のユーザー入力です。コンテンツブロック、優先度、返信をトリガーするかどうか、さらに任意でカスタムコンテキストと skill の選択を含みます。不変です。
コンテンツブロックの型
この入力で明示的に選択した skill です。
名前は空や空白だけにはできません。
リストを受け取るコンストラクターでは、シードを適用する時点でセッションの作業ディレクトリを基準に相対パスを解決し、ファイルの現在の mtime を読み取ります。
ユーザー入力の優先度のヒントです。SDK は優先度で書き込み順を並べ替えません。スケジューリングは CLI が決定します。
マネージド CLI の設定です。
CLI の検索順序。 起動時、以下の順序で CLI を決定し、見つかった時点で止まります。
認証方式です。
起動時の認証設定は、現在のアカウントだけが読める一時ファイルを通じて CLI に渡されます。起動引数や環境変数には入りません。
ホストが短期の Service Account token を更新するためのコールバックです。長期キーはホストが保管します。
新しい token で完了する stage を返します。CLI は認証情報が必要になるたびに複数回呼び出すことがあります。token は SDK の制御チャネル経由で CLI に渡されます。ログには書き込まないでください。
ジョブごとに token を提供するコールバックです。SDK はコールバックにジョブ ID を渡しません。アプリケーション側でクロージャーに自分のジョブ ID を束縛してください。
token で完了する stage を返します。
SDK が管理するシークレット値です。
SDK は、診断イベントと stderr に現れた登録済みの認証情報をマスク(redact)します。この仕組みは業務データやサードパーティの出力には及ばないため、記録範囲はアプリケーション自身のログポリシーで管理してください。
CLI の子プロセスは、デフォルトで親プロセスの
ツール権限のコールバックです。
1 回分のツール権限リクエストです。
省略可能なフィールドが欠けているか型が合わない場合は、空の
ツールの入力、プレビュー、
明示的な承認スコープです。
権限コールバックの判定です。許可(ツールの入力を書き換え可能)または拒否(理由付き)を表します。
リクエストに
権限モードです。
コールバックが受け取るキャンセルトークンです。CLI がリクエストをキャンセルしたとき、コールバックがタイムアウトしたとき、またはセッションが閉じられたときにキャンセルされます。プロトコル上のキャンセル応答は SDK が送るため、アプリケーションは関連する処理を止めるだけで済みます。
キャンセルは協調的です。トークンを無視するコードは実行を続けます。キャンセル時の処理は短くし、ブロックしないでください。処理がスローした例外は無視されます。
Plan の状態は権限モードとは独立して設定できます。Plan をオンにしても現在の権限モードは保持されます。パッケージは
ルール:
Hook の登録 1 件分です。イベント名、省略可能な matcher、ハンドラーで構成されます。パッケージは
イベント名と matcher のマッチングは CLI が行い、ハンドラーは Java プロセス内で実行されます。
Hook ハンドラーです。SDK 専用の Hook スレッド上で呼び出され、
返した JSON はそのまま Hook の出力として CLI に渡されます。構造は CLI が定義します。Hooks の出力を参照してください。空のオブジェクトは介入しないことを意味します。
ハンドラーが例外をスローするか stage が例外で完了した場合、その Hook 呼び出しだけが
1 回分の Hook イベントです。
MCP サーバーの設定です。
適用対象外の形式でチェーンメソッドを呼ぶと
プロセス内 MCP サーバーの JSON-RPC エンドポイントです。
SDK は返された JSON をそのまま MCP のレスポンスとして CLI に転送します。レスポンスには
MCP サーバー 1 台分の状態です。
CLI は
MCP OAuth に使います。流れは次のとおりです。
認可 URL とコールバック URL には機密性の高い OAuth の state が含まれることがあります。ログには書き込まないでください。どちらのクラスの
MCP elicitation のコールバックです。MCP サーバーがユーザーから追加の情報を集める必要があるときに呼び出されます。
コールバックは
elicitation の結果です。
モデル関連の型は
初期化時、SDK は CLI にコールバックを宣言するだけで、呼び出しはしません。コールバックは CLI がモデルの決定を必要とするたびに実行されます。
タイムアウトは
Builder メソッドは
1 回のモデルリクエストのコンテキストで、SDK がモデルコールバックに渡します。
CLI が提供しないフィールドは
モデルカタログの 1 件のエントリです。
カタログには
モデル ID の値型です。
Memory の設定は
結果は
外部セッションストレージ関連の型です。
1 回のセッションでどの履歴ストレージを使うかを指定します。
最終的に有効になる外部ストアは、
外部セッションストアが実装するインターフェースです。クライアントは
どちらのメソッドも同期的に完了してかまいませんが、失敗は直接投げずに、例外で完了した stage で報告する必要があります。呼び出しスレッドでブロッキング I/O を実行せず、非同期クライアントかアプリケーション独自のスレッドプールを使ってください。ストアは各 transcript JSON(未知のフィールドを含む)をそのまま保存し、別のエンベロープで包まないでください。
ミラーリングの書き込み失敗は
列挙可能なストアです。
セッション全体の削除をサポートするストアです。
実装は、追記と同じトランザクションまたはクリティカルセクション内でルート transcript とすべてのサブパスを削除し、そのセッションを削除済みとして永続的にマークする必要があります。以降そのセッションへの書き込みはすべて
SDK 組み込みのインメモリ実装で、
外部ストアへの書き込み(ミラーリング)のリソース上限で、
あるキーへの書き込みが失敗またはタイムアウトすると、そのキーへの書き込みは停止しますが、他のキーには影響しません。セッション全体の上限を超えると、セッション全体のミラーリングが停止します。これらのエラーは
保存済みのセッションの読み取り、継続、フォーク、削除を行います。
スコープの規則:
初期化ハンドシェイクの結果で、
実行中に CLI が capability で制御されるリクエストを「サポートしていない」として拒否すると、SDK はその capability を
次のメソッドや設定には、CLI がハンドシェイク時に対応する capability を宣言している必要があります。capability の状態が
CLI の capability の 3 つの状態です。
成功は CLI が中断リクエストを受け付けたことだけを意味し、ターンがいつ終わるかは
書き込みの確認だけが必要な場合は
メッセージストリーム内のすべてのメッセージの抽象基底クラスで、
具体的な型:
専用の system メッセージはすべて
アシスタントが応答を 1 つ生成したときに配信されます。コンテンツブロックは出力側の型で、入力側の
Java SDK がモデル化するのは
1 ターンの対話が終わったときに配信されます。Agent の業務上の失敗(ターン数の上限到達など)は、
CLI が送るシステムメッセージです。
Hook の実行時の通知です。
各アクセサーは同名の snake_case フィールド(
メモリの生成と読み込みの結果です。どちらも対話のターンを終了させません。結果の型は
SDK に付属するイミュータブルな JSON 型で、
SDK の構造化された診断イベントを受け取ります。セッションの初期化、クローズのタイムアウト、capability のダウングレード、マネージド CLI のインストールなどです。
イミュータブルな診断イベントです。SDK が生成した
アプリケーションが
SDK の今後のバージョンでイベントタイプが追加される可能性があります。
SDK の例外はすべて非チェック例外の
例外のメッセージと cause は生成時にマスクされ、
次の場合にスローされます。
下表に挙げたアクセサーを除き、各例外クラスにはコンストラクターしかなく、エラーコードの定数は
次のエラーコードは
次のエラーコードは
com.qoder.sdk:qoder-agent-sdk、パッケージは com.qoder.sdk.* です。動作環境は JRE 8 以上で、core アーティファクトはサードパーティのランタイム依存を持ちません。
SDK はローカルで qodercli 子プロセスを起動してタスクを実行します。CLI のパスを指定しない場合、初回起動時にこの SDK バージョンで固定された CLI をダウンロードし、SHA-256 を検証したうえでキャッシュして再利用します。マネージド対象のプラットフォームは macOS arm64/x64、Linux x64/arm64(glibc と musl)、Windows x64 です。Windows x64 では Windows 10 1809 / Windows Server 2019 以降が必要です。SDK は OS のバージョンを確認しないため、それより古いシステムでは CLI を自分で指定してください。qoderCliPath または環境変数 QODERCLI_PATH でインストール済みの CLI を指定することもできます。現在のプラットフォームがマネージド対象外の場合(Windows arm64 など)、SDK は ~/.local/bin と PATH から検索します。検索順序の全体は ManagedRuntimeOptions を参照してください。
以下の宣言コードブロックでは、メソッド本体と import を省略しています。インストールと最初に実行できるサンプルはクイックスタート、TypeScript・Python との機能差は言語間の差分、組み込みツール名は組み込みツール一覧を参照してください。
Entry Points
QoderClient
SDK のメインエントリです。単発クエリ、複数ターンのセッション、事前起動を作成します。スレッドセーフで再利用できます。クローズすると、作成したすべてのクエリとセッションも連鎖的にクローズされます。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
builder() | QoderClient.Builder | ビルダーを作成します |
query(OneShotQueryRequest) | QoderQuery | 単発クエリを開始します。ハンドルは同期的に返り、CLI は非同期に起動します |
openSession(SessionOptions) | CompletionStage<QoderSession> | 複数ターンのセッションを開きます。初期化ハンドシェイクの完了後に返ります |
prepare(SessionOptions) | CompletionStage<PreparedQuery> | CLI を事前に起動して認証と初期化を済ませます。入力は送信しません |
sessions() | SessionRepository | クライアントのデフォルトストレージとプロジェクトディレクトリでセッションリポジトリを取得します |
sessions(SessionOptions) | SessionRepository | 指定したオプションの sessionStorage と workingDirectory でセッションリポジトリを取得します。CLI は起動しません。null を渡すと sessions() と同じです |
installRuntime() | CompletionStage<Path> | マネージド CLI のインストールまたは再利用だけを行い、実行ファイルのパスを返します。CLI は起動しません。ManagedRuntimeOptions を参照してください |
pruneRuntimes() | CompletionStage<Integer> | 固定バージョン以外のマネージド CLI を削除し、削除したディレクトリ数を返します |
closeAsync() | CompletionStage<Void> | 非同期に連鎖クローズします。冪等です |
close() | void | ブロッキングでクローズします。SDK スレッドやコールバック内で呼ぶ場合の制限はスレッドモデルとリソース解放を参照してください |
null 引数、build() の検証失敗。起動中・実行中の失敗は、返された CompletionStage またはメッセージストリームで通知されます。SDK 独自の例外はすべて QoderException を継承します。Java 標準の引数例外と状態例外は元の型のままです。
QoderClient.Builder
| メソッド | パラメータの型 | 説明 |
|---|---|---|
auth(Auth) | Auth | 必須。認証方式 |
callbackExecutor(Executor) | Executor | 権限、MCP、モデルポリシー、認証トークン、Memory の各コールバックのエグゼキューター。Hook は SDK の専用スレッドを使います |
diagnosticsListener(DiagnosticsListener) | DiagnosticsListener | クライアントレベルの診断リスナー |
sessionStore(SessionStore) | SessionStore | クライアントのデフォルトの外部セッションストア。セッションリポジトリとすべてのセッションで使われます。セッションオプションで上書きできます |
projectDirectory(Path) | Path | セッションリポジトリのプロジェクトディレクトリ。workingDirectory を設定していないセッションのデフォルト作業ディレクトリにもなります |
managedRuntime(ManagedRuntimeOptions) | ManagedRuntimeOptions | マネージド CLI のキャッシュディレクトリ、ダウンロードポリシー、ミラー、タイムアウト。null でデフォルトに戻します |
build() | — | クライアントを構築します。auth が未設定の場合は InvalidOptionsException をスローします |
QoderQuery
単発クエリのハンドルです。QoderClient.query() または PreparedQuery.toQuery() が返します。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
messages() | MessageStream | メッセージストリームを取得します |
initialization() | CompletionStage<InitializationResult> | 初期化ハンドシェイクの結果 |
interrupt() | CompletionStage<InterruptResult> | 実行中のターンを中断します |
flushMemory() | CompletionStage<Void> | 開始済みの Memory 処理の終了を待ちます。完了してもすべての書き込みが成功したとは限りません |
refreshMemory() | CompletionStage<Void> | Memory の利用設定を再読み込みします |
closeAsync() / close() | CompletionStage<Void> / void | クエリをクローズしてリソースを解放します |
result の後に終了しますが、メッセージストリームは最後まで消費してから、ハンドルまたはカーソルをクローズしてください。Memory を有効にしている場合、ResultMessage の後に Memory メッセージが届くことがあります。ResultOutcome.ERROR はターンの失敗を表します。例外がスローされないことは成功を意味しません。
QoderSession
複数ターンのセッションです。QoderClient.openSession() または PreparedQuery.toSession() が返します。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
messages() | MessageStream | メッセージストリームを取得します。消費できるのは 1 回だけです |
initialization() | CompletionStage<InitializationResult> | 初期化ハンドシェイクの結果。CLI の capability とバージョンを含みます |
send(UserInput) | CompletionStage<MessageId> | 入力が CLI に書き込まれた時点で完了します。回答の終了を意味しません |
submit(UserInput) | MessageSubmission | 割り当てられた MessageId を同期的に返します。書き込み結果は written() で確認します。書き込み前に ID が必要な場合に使います |
completeInput() | CompletionStage<Void> | 以降の入力を拒否し、受け付け済みの入力の書き込み完了を待ちます。回答は待ちません |
cancelQueuedMessage(MessageId) | CompletionStage<Boolean> | CLI にまだ書き込まれていないキュー内の入力を取り消します。書き込みが始まっている場合は、CLI が対応する capability をサポートしているときだけリモートでの取り消しを試み、それ以外は false を返します |
interrupt() | CompletionStage<InterruptResult> | 現在のターンを中断します。セッションは引き続き使えます |
setPermissionMode(PermissionMode) | CompletionStage<Void> | 実行中に権限モードを切り替えます。bypass に切り替えるには、セッションで allowDangerouslySkipPermissions(true) を設定しておく必要があります |
getPlanMode() / setPlanMode(boolean) | CompletionStage<PlanModeSnapshot> | 独立 Plan の状態を照会または切り替え、CLI が確認した値を返します。独立 Plan を参照してください |
setPermissionModePreservingPlan(PermissionMode) | CompletionStage<Void> | Plan の状態を保ったまま権限モードを切り替えます。PLAN は受け付けません |
setProxy(ProxySettings) | CompletionStage<Void> | CLI のネットワークプロキシを設定します |
addDirectories(List<Path>) | CompletionStage<Void> | CLI に追加ディレクトリへのアクセスを許可します |
applyFlagSettings(FlagSettings) | CompletionStage<Void> | 機能フラグを適用します |
generateSessionTitle([String]) | CompletionStage<SessionTitle> | CLI にセッションタイトルを生成させます。説明を添えることもできます |
seedReadState(ReadStateSeed) | CompletionStage<Void> | ユーザーが既に見たファイルを CLI に伝えます。ローカルの検証がすべて通ってから送信します |
supportedCommands() | CompletionStage<List<String>> | 現在のコマンドカタログにあるコマンド名。リクエストは送信しません |
commandCatalog() | CompletionStage<List<CommandInfo>> | 現在のコマンドカタログ。リクエストは送信しません |
modelCatalogSnapshot() | CompletionStage<Optional<ModelCatalogSnapshot>> | CLI が直近に提供したモデルカタログ。まだ受け取っていない場合は空です。リクエストは送信しません |
reloadSkills() | CompletionStage<List<CommandInfo>> | CLI に skills を再読み込みさせ、skills の一覧を返します |
getAvailableModels([ModelCatalogOptions]) | CompletionStage<List<ModelInfo>> | 利用可能なモデルを CLI に問い合わせます。キャッシュを使うかどうかを選べます。ModelCatalogOptions を参照してください |
backgroundTasks([String]) | CompletionStage<Boolean> | フォアグラウンドのタスク(または指定した tool use のタスク)をバックグラウンドに移し、成功したかどうかを返します |
stopTask(TaskId) | CompletionStage<Void> | バックグラウンドタスクを停止します |
reloadPlugins() | CompletionStage<Void> | CLI にプラグインを再読み込みさせます |
mcpServerStatus() | CompletionStage<List<McpServerStatus>> | すべての MCP サーバーの状態 |
beginMcpAuthentication(String[, McpAuthenticationOptions]) | CompletionStage<McpAuthenticationResult> | MCP サーバーの OAuth を開始し、結果またはユーザーが開く必要のある認可 URL を返します |
mcpSubmitOAuthCallbackUrl(String, String) | CompletionStage<Void> | OAuth コールバック URL 全体を CLI に渡します。CLI が検証し、認証情報に交換して再接続します |
rewindHistory(MessageId) | CompletionStage<Void> | 会話履歴を指定したメッセージまで巻き戻します |
rewindFiles(MessageId, RewindFilesOptions) | CompletionStage<RewindFilesResult> | チェックポイントで追跡しているファイルを、指定したメッセージの時点の状態に戻します。Checkpoint を参照してください |
flushMemory() / refreshMemory() | CompletionStage<Void> | QoderQuery と同じです |
closeAsync() / close() | CompletionStage<Void> / void | セッションをクローズしてリソースを解放します |
UnsupportedCliCapabilityException で失敗し、リクエストは送信されません。capability 要件を参照してください。セッションをクローズすると、まだ書き込まれていないキュー内の入力は SessionClosedException で終了します。受け付け済みの入力を確実に CLI へ書き込むには、先に completeInput() を待ってください。
ランタイムカタログ
| メソッド | データの出所 | リクエストを送信するか |
|---|---|---|
commandCatalog() / supportedCommands() | 初期化時のコマンドカタログ。CLI がコマンドの変更をプッシュすると全体が置き換わります | しない |
modelCatalogSnapshot() | 初期化時または CLI のプッシュによる最新の完全なモデルカタログ | しない |
getAvailableModels(...) | 今回の問い合わせ結果。上のスナップショットは更新しません | する |
reloadSkills() | 再読み込み後の skills 一覧。コマンドカタログ全体は置き換えません | する |
modelCatalogSnapshot() が Optional.empty() を返す場合は、まだカタログを受け取っていません。現在のアカウントの最新モデル一覧が必要な場合は getAvailableModels(...) を呼び出してください。
CommandInfo
コマンドまたは skill のメタデータです。com.qoder.sdk.command にあります。
name() は必ず値を持ちます。raw() は CLI が返したすべてのフィールドを保持し、SDK がモデル化していないフィールドも含みます。
PreparedQuery
起動、認証、初期化を済ませた CLI です。QoderClient.prepare() が返します。最初のリクエストの起動待ち時間をなくすために使います。使えるのは 1 回だけで、クエリへの変換、セッションへの変換、クローズのいずれかを行います。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
initialization() | CompletionStage<InitializationResult> | 初期化ハンドシェイクの結果 |
toQuery(UserInput) | QoderQuery | 単発クエリに変換します |
toSession() | QoderSession | 複数ターンのセッションに変換します |
closeAsync() / close() | CompletionStage<Void> / void | 使わなかった事前起動を破棄します |
IllegalStateException がスローされます。変換後のリソース解放は新しい QoderQuery または QoderSession が担当し、PreparedQuery をクローズしても影響しません。toQuery() の入力が拒否された場合、返されたクエリのメッセージストリームはそのエラーで終了します。
MessageStream
クエリまたはセッションのメッセージストリームです。互いに排他的な 2 つの消費方法をサポートします。openCursor() でプルするか、consume() で SDK にプッシュさせます。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
openCursor() | MessageCursor | プル用のカーソルを開き、メッセージを順番に 1 件ずつ読み取ります |
consume(MessageHandler, Executor) | CompletionStage<Void> | 指定したエグゼキューター上で、メッセージごとにハンドラーを順番に呼び出します。前のメッセージの処理が終わってから次を渡します |
consume() が返す stage は、ストリームの終了時に正常完了します。以下の場合は例外完了し、所属するクエリまたはセッションをクローズします。
| 状況 | 例外 |
|---|---|
| ハンドラーが例外をスローした | CallbackExecutionException |
| エグゼキューターがタスクを拒否した | CallbackRejectedException |
| 消費スレッドが割り込まれた | ConsumerInterruptedException |
| メッセージの読み取りまたはデコードに失敗した | ストリームの失敗原因。SDK 以外の例外はエラーコード MESSAGE_DELIVERY_FAILED でラップされます |
openCursor() と consume() のどちらかを選びます。2 回目の購読は MessageStreamAlreadyConsumedException をスローします。最初の購読は失敗しても消費済みとみなされます。CLI が出力を停止した後も、バッファ済みのメッセージは読み取れます。
MessageCursor
プル用のカーソルです。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
hasNext() | boolean | 次のメッセージまでブロックします。ストリームが終了すると false を返し、ストリームが失敗している場合は失敗原因をスローします |
next() | SdkMessage | 次のメッセージを返します。ストリームが終了している場合は NoSuchElementException をスローします |
close() | void | カーソルをクローズし、所属するクエリまたはセッションも非同期にクローズします |
ResultMessage を読んだら次のターンを送信できます。ターンごとにクローズして開き直さないでください。あるメッセージの読み取りに失敗するとストリームはそこで終了し、以降の hasNext() / next() はすべて同じ例外をスローします。その場合はカーソルをクローズし、必要に応じて resume で新しいセッションを作成します。消費スレッドが割り込まれると ConsumerInterruptedException がスローされます。
MessageHandler
プッシュモードのメッセージハンドラーです。
consume() が返す stage は CallbackExecutionException で完了します。直接実行するエグゼキューター(Runnable::run など)を使うと、ハンドラーは SDK の配信スレッド上で動作するため、すぐに戻る必要があります。
スレッドモデルとリソース解放
- 非同期メソッドは
CompletionStageを返し、呼び出しごとに独立した観測結果が得られます。toCompletableFuture()をキャンセルしたり手動で完了したりしても、その待機に影響するだけで、SDK の操作は取り消されません。操作を止めるにはinterrupt()、cancelQueuedMessage()、closeAsync()を使います。 openSession()とprepare()が返すハンドルは、渡された時点でアプリケーションの所有になります。get()を一度も呼ばなくても、クローズする責任があります。渡される前に観測側の future がキャンセルされていた場合、SDK は起動済みのリソースを自動的にクローズします。- クエリ、セッション、事前起動はそれぞれ 1 つの CLI 子プロセスを使うため、アプリケーション側で同時実行数を制限してください。
QoderClient自体のコストは小さく再利用できます。クライアントをクローズすると、作成したすべてのリソースが連鎖的にクローズされます。 - 権限、MCP、モデルポリシー、認証トークン、Memory の各コールバックは
callbackExecutor上で動作し、Hook は SDK の専用スレッドを使います。callbackExecutorを設定しない場合、同じセッションのこれらのコールバックは 1 つの SDK スレッド上で直列に実行されます。1 つのコールバックがブロックすると他のコールバックが遅れ、タイムアウトの原因になります。コールバックはすぐに戻り、時間のかかる処理はアプリケーション自身のエグゼキューターに渡して、返す stage で完了を通知してください。 - SDK のコールバック、プッシュハンドラー、SDK スレッドの中でブロックして待たないでください。これらの場所から所属するセッションやクライアントをクローズするときは、
closeAsync()を呼んでそのまま戻ります。SDK 所有のスレッドやプッシュハンドラーの中でブロッキングのclose()を呼ぶと、非同期クローズを開始したうえでIllegalBlockingCloseExceptionをスローします。SDK 所有のスレッドには、callbackExecutorを設定していない場合にコールバックを実行するスレッドと、Hook や診断リスナーを実行するスレッドが含まれます。セッションやクエリのclose()は自身のスレッドだけを確認し、クライアントのclose()は作成したすべてのセッションとクエリのスレッドを確認します。プッシュハンドラーはアプリケーションのエグゼキューター上で動いていてもスローします。カスタムのcallbackExecutorを設定した場合、コールバックはアプリケーションのスレッドで実行され、そこでclose()を呼んでもこの例外はスローされず、クローズが完了するまでブロックします。 closeAsync()の完了は、SDK が入力の受け付けを停止し、キュー内の入力と制御リクエストの決着がつき、CLI プロセスがクローズ手順(stdin を閉じ、タイムアウト後に終了要求、強制終了の順)を終えたことを表します。実行中のアプリケーションのコールバックや continuation の終了は待たず、CLI の子孫プロセスの終了や一時ファイルの削除も保証しません。Memory を有効にしている場合、アイドル状態のセッションはクローズ前に Memory の後処理を完了し、最大drainTimeoutMs(デフォルト 60 秒)待ちます。
Configuration
SessionOptions
クエリとセッションの不変オプションです。openSession()、prepare()、OneShotQueryRequest で使います。
SessionOptions.Builder
| グループ | メソッド | デフォルト | 説明 |
|---|---|---|---|
| Runtime | workingDirectory(Path) | クライアントの projectDirectory、次にプロセスのカレントディレクトリ | CLI の作業ディレクトリ |
| Runtime | qoderCliPath(Path) | マネージド CLI | CLI の実行ファイルを明示的に指定します。設定するとマネージド CLI はダウンロードされず、パスが無効な場合はすぐに失敗します |
| Runtime | putEnvironment(String, String) | — | CLI に渡す環境変数を 1 つ追加します。プロキシ URL の変数は自動的に機密情報として扱われます |
| Runtime | putProxyEnvironment(String, SecretValue) | — | プロキシ URL の変数を SecretValue で追加します。変数名は認識可能なプロキシ変数(HTTPS_PROXY など)である必要があり、そうでない場合は IllegalArgumentException をスローします |
| Runtime | environment(Map<String, String>) | — | 環境変数をまとめて追加します。置き換えではなく追加です |
| Prompt | systemPrompt(String) | 置き換えない | システムプロンプトを置き換えます |
| Prompt | appendSystemPrompt(String) | 追加しない | システムプロンプトの末尾に追加します |
| Prompt | customContext(Map<String, String>) | 未設定 | このセッションの入力のデフォルトのカスタムコンテキスト。UserInput を参照してください |
| Prompt | maxTurns(int) | 制限なし | 最大ターン数。正の数である必要があります |
| Prompt | includePartialMessages(boolean) | false | 増分の PartialMessage を配信します。ストリーミング出力を参照してください |
| Model | modelSelection(ModelSelection) | CLI のデフォルトモデル | 固定モデル、動的コールバック、構造化ポリシーのいずれか。ModelSelection を参照してください |
| Tools | tools(List<String>) | CLI のデフォルト | 基本ツールの一覧。空のリストは未設定と同じです |
| Tools | allowedTools(List<String>) | — | 事前に許可するツール |
| Tools | disallowedTools(List<String>) | — | 禁止するツール。allowedTools より優先されます |
| Permission | permissionMode(PermissionMode) | CLI が決定 | 権限モード。PermissionMode を参照してください |
| Permission | planMode(boolean) | 未設定 | 独立 Plan の開始時の状態。permissionMode(PLAN) とは排他です。独立 Plan を参照してください |
| Permission | allowDangerouslySkipPermissions(boolean) | false | BYPASS_PERMISSIONS の 2 つ目のスイッチ |
| Permission | canUseTool(ToolPermissionHandler) | なし | ツール権限のコールバック。ToolPermissionHandler を参照してください |
| MCP | mcpServers(List<McpServerConfig>) | — | MCP サーバーの設定。名前の重複は不可です。McpServerConfig を参照してください |
| MCP | allowedMcpServerNames(List<String>) | — | 使用を許可する MCP サーバー名 |
| MCP | onElicitation(ElicitationHandler) | なし | MCP elicitation のコールバック。ElicitationHandler を参照してください |
| Hooks | hooks(List<HookRegistration>) | — | Hook の登録。HookRegistration を参照してください |
| Hooks | includeHookEvents(boolean) | false | Hook の通知メッセージをメッセージストリームに配信します。Hook のコールバック自体には影響しません |
| Session | resume(String) | — | セッション ID で再開します。ID に使えるのは ASCII の英字、数字、_、- だけです |
| Session | continueSession(boolean) | false | 直近のセッションを継続します。一覧取得できる外部ストアを設定している場合は、ストア内のタイムスタンプで選びます |
| Session | forkSession(boolean) | false | resume または continueSession と組み合わせて、新しいセッションとしてフォークします |
| Session | sessionStorage(SessionStorage) | SessionStorage.inherit() | クライアントの設定を継承するか、CLI のローカルストレージまたは外部ストアを使います。SessionStorage を参照してください |
| Session | sessionMirrorOptions(SessionMirrorOptions) | defaults() | 外部ストアへのミラーリングのバッチと待機の上限。SessionMirrorOptions を参照してください |
| Session | fileCheckpointing(boolean) | false | ファイルチェックポイントを有効にします。Checkpoint を参照してください |
| Memory | memory(MemoryOptions) | 無効 | ネイティブまたはアプリケーション管理の Memory。Memory を参照してください |
| Control | controlRequestTimeoutMs(long) | 60000 | 制御リクエストのタイムアウト(ミリ秒)。0 は無制限、負の値は無効です |
| Control | resolveModelTimeoutMs(long) | 500 | 動的モデルコールバックのタイムアウト(ミリ秒)。0 は無制限、負の値は無効です |
| Control | debug(boolean) | false | CLI のデバッグ出力を有効にします |
| Control | diagnosticsListener(DiagnosticsListener) | — | セッションレベルの診断リスナー |
Builder.DEFAULT_CONTROL_REQUEST_TIMEOUT_MS(60000L)、Builder.DEFAULT_RESOLVE_MODEL_TIMEOUT_MS(500L)。
maxTurns() は正でない値を受け取るとすぐに IllegalArgumentException をスローします。build() は以下の場合に InvalidOptionsException をスローします。
BYPASS_PERMISSIONSでallowDangerouslySkipPermissions(true)を同時に設定していない。- 外部の
sessionStorageとfileCheckpointing(true)を同時に設定している。 planMode(...)とpermissionMode(PLAN)を同時に設定している(planMode(false)を含む)。resumeとcontinueSessionを同時に設定している。forkSessionをresumeまたはcontinueSessionと組み合わせていない。resumeの ID に不正な文字が含まれている。- 環境変数名が空、または
=や NUL を含む。あるいは値が NUL を含む。 mcpServersがnullまたは名前の重複するサーバーを含む。
build() が成功しても、選択した機能を CLI がサポートしているとは限りません。planMode、customContext、外部ストア上での forkSession など CLI の capability を必要とする設定は、起動時または送信時に確認されます。capability 要件を参照してください。
CLI 子プロセスはデフォルトで PATH だけを継承します。その他の変数は明示的に渡す必要があります。子プロセス環境を参照してください。
OneShotQueryRequest
単発クエリのリクエストです。1 つの UserInput と 1 組の SessionOptions を含みます。
of(prompt) は単一のテキスト入力とデフォルトのオプションを使います。Builder の prompt() と input() はどちらか一方しか設定できず、両方を設定すると InvalidOptionsException をスローします。どちらも設定しないと build() が同じ例外をスローします。options() を設定しない場合はデフォルトのオプションを使います。
UserInput
CLI に送る 1 件のユーザー入力です。コンテンツブロック、優先度、返信をトリガーするかどうか、さらに任意でカスタムコンテキストと skill の選択を含みます。不変です。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
text(String) | UserInput | 単一のテキストブロック。優先度は NOW、shouldQuery は true です |
content() | List<Content> | コンテンツブロックの一覧。空にはなりません |
priority() | SendPriority | 優先度のヒント |
shouldQuery() | boolean | 返信をトリガーするかどうか。false の場合はコンテキストを補足するだけです |
customContext() | Optional<Map<String, String>> | この入力のカスタムコンテキスト |
clientComposed() | Optional<Boolean> | クライアントが slash コマンドを処理済みであると宣言するかどうか |
selectedSkills() | List<SelectedSkill> | この入力で明示的に選択した skills。デフォルトは空です |
UserInput.Builder
| メソッド | 説明 |
|---|---|
addText(String) | テキストブロックを追加します |
addImage(String mediaType, String base64Data) | base64 の画像ブロックを追加します(例:image/png) |
addImageUrl(URI) | URL の画像ブロックを追加します。ホスト名を含む絶対 HTTP(S) URL である必要があります。SDK は画像をダウンロードしません |
addToolResult(String toolUseId, String content) | 先行するツール呼び出しに応答するツール結果ブロックを追加します |
customContext(Map<String, String>) | この入力の完全なコンテキスト。セッションのデフォルトを上書きします。空の map はクリアを意味します |
clientComposed(boolean) | true はクライアントが slash コマンドを処理済みであることを表し、CLI は先頭の / を解析しなくなります |
selectedSkills(List<SelectedSkill>) | この入力で明示的に選択する skills |
priority(SendPriority) | 優先度。デフォルトは NOW です |
shouldQuery(boolean) | 返信をトリガーするかどうか。デフォルトは true です |
build() | 構築します。コンテンツブロックが 1 つもない場合は IllegalStateException をスローします |
UserInput.Content は閉じた階層で、出力側の ContentBlock とは独立しています。
| 型 | アクセサー |
|---|---|
UserInput.TextContent | String text() |
UserInput.ImageContent | String mediaType()、String base64Data() |
UserInput.UrlImageContent | URI url() |
UserInput.ToolResultContent | String toolUseId()、String content() |
customContext を設定しない場合は SessionOptions のデフォルト値を継承します。明示的に設定するとデフォルト値を完全に置き換え、マージはしません。明示的に設定した customContext(空の map を含む)と空でない selectedSkills は、CLI が対応する capability をサポートしている必要があります。capability 要件を参照してください。セッションで拒否された入力は send() の stage で通知されます。クエリと PreparedQuery.toQuery() で入力が拒否された場合、メッセージストリームはそのエラーで終了します。
SelectedSkill
この入力で明示的に選択した skill です。
arguments はそのまま CLI に渡されます。
ReadStateSeed
seedReadState() に渡し、ホストアプリケーションがユーザーに表示したファイルを CLI に伝えます。
of(path, mtime) はホストが既に観測した mtime(エポックミリ秒)を使います。実際に表示したファイルだけを設定してください。この呼び出しでファイルの内容が入力に加わることはありません。
SendPriority
ユーザー入力の優先度のヒントです。SDK は優先度で書き込み順を並べ替えません。スケジューリングは CLI が決定します。
| 値 | 説明 |
|---|---|
NOW | できるだけ早く処理します(デフォルト) |
NEXT | 現在処理中のメッセージの後に処理します |
LATER | キュー内のすべてのメッセージの後に処理します |
FlagSettings
applyFlagSettings() に渡す機能フラグです。
flags はフラグ名からブール値へのマップで、必須です。flags() は不変のコピーを返します。
ProxySettings
setProxy() に渡すプロキシ設定です。
ProxySettings.of(SecretValue.of(url)) でプロキシを設定し、clear() で解除します。プロキシ URL とその中のユーザー名・パスワードは機密情報として登録され、SDK は診断情報でマスク(redact)します。非推奨の String コンストラクターと proxyUrl() は平文を露出するため、ログには使わないでください。
ManagedRuntimeOptions
マネージド CLI の設定です。QoderClient.Builder.managedRuntime() で設定します。qoderCliPath を指定しない起動と installRuntime() に適用されます。
| Builder メソッド | デフォルト | 説明 |
|---|---|---|
cacheDirectory(Path) | ~/.qoder/runtimes/managed | キャッシュディレクトリ。ローカルディスク上に置いてください。null でデフォルトに戻します |
downloadPolicy(DownloadPolicy) | ALLOW | DISALLOW の場合はネットワークに一切接続せず、キャッシュもローカルのアーカイブもないときは失敗します |
baseUrl(URI) | 公式のダウンロード URL | ミラーの URL。ユーザー情報を含まない絶対 https URL である必要があります(ループバックアドレスは http も可) |
authorization(SecretValue) | — | ミラーにアクセスするときの Authorization ヘッダー。設定したホストにだけ送られ、別のホストへのリダイレクトでは転送されません |
localArchive(Path) | — | ローカルにある固定バージョンのアーカイブ。ダウンロードより優先して使われます |
connectTimeoutMs(long) / readTimeoutMs(long) | 30000 | 接続と 1 回の読み取りのタイムアウト(ミリ秒)。正の数である必要があります |
totalTimeoutMs(long) | 600000 | ダウンロード全体のタイムアウト(ミリ秒)。正の数である必要があります |
build() | — | タイムアウトが正でない場合、または baseUrl が不正な場合は InvalidOptionsException をスローします |
SessionOptions.Builder.qoderCliPath()で指定したパス。パスが無効な場合はすぐに失敗します。- 環境変数
QODERCLI_PATH。 - マネージド CLI:キャッシュを再利用し、なければ
localArchive、classpath リソースMETA-INF/qoder-sdk/runtime/<ファイル名>、ダウンロード URL の順にインストールします。現在のプラットフォームがマネージド対象外の場合はスキップします。インストールに失敗した場合はそのままエラーになり、別の CLI には切り替えません。 ~/.qoder/runtimes/以下に旧バージョンの SDK が残した同じバージョンの CLI。~/.local/bin/qodercli、次にPATH。
| シナリオ | 方法 |
|---|---|
| ローカル開発 | デフォルト設定のまま使います。初回起動時に自動でダウンロードされます |
| イメージのビルド時に事前準備する | イメージのビルド段階で java -cp qoder-agent-sdk-VERSION.jar com.qoder.sdk.RuntimeInstaller [--cache-dir <dir>](VERSION はアプリケーションが依存する SDK バージョン)を実行します。実行時にはダウンロードしません |
| アーカイブをアプリケーションに同梱する | 固定バージョンのアーカイブを classpath の META-INF/qoder-sdk/runtime/<ファイル名> に置くか、localArchive(Path) でローカルファイルを指定します。あわせて downloadPolicy(DISALLOW) を設定し、ネットワークに接続しないようにします |
| 社内ミラー | baseUrl(URI) でミラーを指定します。ミラーは <CLI バージョン>/<ファイル名> のレイアウトで同じバイト列のファイルを提供します。認証が必要な場合は authorization(SecretValue) を設定します |
| 自前で管理する CLI | qoderCliPath(Path) または QODERCLI_PATH で指定します |
RuntimeInstaller はコマンドラインのエントリポイントで、--cache-dir、--base-url、--local-archive、--no-download、--prune、--print-url をサポートします。成功すると実行ファイルのパスを出力して 0 で終了し、失敗すると 1 で終了します。ミラーの認証はコードでしか設定できず、コマンドラインは認証情報を受け付けません。
ダウンロード時のプロキシは環境変数 HTTPS_PROXY、ALL_PROXY、NO_PROXY で選ばれ、http:// のプロキシだけをサポートします。ダウンロードが禁止されていて利用できる取得元がない場合、ネットワーク障害、タイムアウト、検証の不一致のいずれかが起きた場合は、RuntimeInstallException をスローします。
installRuntime() は、デプロイ段階でキャッシュを事前準備したり、インストールの問題を早めに洗い出したりするのに向いています。現在のプラットフォームがマネージド対象外の場合は RuntimeInstallException で失敗します。pruneRuntimes() は他の CLI バージョンと、このプラットフォームの他のダイジェストディレクトリを削除します。他のプロセスがインストール中のディレクトリはスキップします。実行する前に、同じキャッシュを共有するすべての SDK プロセスで新しいセッションの開始を止めてください。セッションをクローズしてもキャッシュは削除されません。
Authentication
Auth
認証方式です。QoderClient.Builder.auth(...) に渡します。パッケージは com.qoder.sdk.auth です。コンストラクターは公開されておらず、インスタンスは静的ファクトリーからのみ取得できます。インスタンスは不変です。
| ファクトリー | 認証情報の取得元 | 主な用途 |
|---|---|---|
qoderCli() | ローカルの CLI に保存済みのログイン状態を再利用 | 開発者のローカル環境 |
accessToken(SecretValue) | 呼び出し側が渡す access token | CI、スクリプト、ユーザーに代わって動くサービス |
accessTokenEnv() | 起動時に環境変数 QODER_PERSONAL_ACCESS_TOKEN を読み取る | CI、コンテナでのデプロイ |
accessTokenEnv(String) | 起動時に呼び出し側が指定した環境変数を読み取る | 独自のシークレット注入 |
serviceAccountKey(SecretValue) | Service Account Key。SDK と CLI が短期 token に交換する | 組織内の無人サービス |
serviceAccountTokenProvider(ServiceAccountTokenProvider) | ホストが必要に応じて更新する Service Account token。長期キーは SDK に入らない | 自前の token 基盤 |
jobTokenProvider(JobTokenProvider) | ホストがジョブごとに提供する token | マルチテナントのジョブランナー |
java.io.tmpdir とそのすべての親ディレクトリは、ほかのアカウントが中のエントリを置き換えられない状態である必要があります。そうでない場合、起動は UnsupportedSecureSecretTransportException で失敗します。必要に応じて起動引数 -Djava.io.tmpdir= で現在のアカウント専用のディレクトリを指定してください。CLI が認証失敗で終了すると AuthenticationException がスローされます。先に認証情報やアカウントの権限を修正してから Query または Session を作り直してください。同じ認証情報でそのまま再試行しても意味はありません。
各方式の詳しい使い方は SDK 認証を参照してください。
ServiceAccountTokenProvider
ホストが短期の Service Account token を更新するためのコールバックです。長期キーはホストが保管します。
JobTokenProvider
ジョブごとに token を提供するコールバックです。SDK はコールバックにジョブ ID を渡しません。アプリケーション側でクロージャーに自分のジョブ ID を束縛してください。
null は返さないでください。CLI は必要に応じて複数回呼び出すことがあります。
SecretValue
SDK が管理するシークレット値です。toString() は常に [REDACTED] を返し、equals と hashCode の処理時間は長さだけに依存します。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
of(char[]) | SecretValue | 渡された配列をコピーしてから作成 |
of(String) | SecretValue | 文字列から作成 |
reveal() | char[] | 平文のコピーを返す。使用後は呼び出し側でゼロクリアする |
length() | int | シークレットの長さ |
子プロセス環境
CLI の子プロセスは、デフォルトで親プロセスの PATH だけを継承します。Windows ではさらに SystemRoot、TEMP、TMP、USERPROFILE、APPDATA、LOCALAPPDATA などのシステムディレクトリ変数も継承します。CLI が必要とする HOME、ロケール、設定ディレクトリなどの変数は、SessionOptions.Builder の putEnvironment(String, String) または environment(Map) で明示的に渡してください。プロキシのアドレスは putProxyEnvironment(String, SecretValue) で渡します。SDK はその中の認証情報をマスクします。SDK が管理する認証情報の変数は取り除かれるため、環境変数で Auth を代替することはできません。
Permissions
ToolPermissionHandler
ツール権限のコールバックです。SessionOptions.Builder.canUseTool(...) で登録します。パッケージは com.qoder.sdk.permission です。CLI があるツール呼び出しについて確認が必要になったときに呼び出されます。登録していない場合、確認が必要な呼び出しは CLI 自身のルールで処理されます。
| パラメータ | 型 | 説明 |
|---|---|---|
request | ToolPermissionRequest | 判定待ちのツール呼び出し |
cancellation | CancellationToken | CLI がリクエストを破棄したとき、リクエストがタイムアウトしたとき、またはセッションが閉じられたときにキャンセルされる |
PermissionResult で完了する stage を返します。null は返せません。コールバックは callbackExecutor 上で実行されます。スレッドモデルとリソース解放を参照してください。コールバックが例外をスローするか stage が例外で完了した場合、その権限リクエストだけが CALLBACK_EXECUTION_FAILED で失敗し、セッションには影響しません。controlRequestTimeoutMs を過ぎても完了しない場合は CONTROL_REQUEST_TIMEOUT で失敗し、同時にトークンがキャンセルされます。使い方は権限制御と承認とユーザー入力を参照してください。
ToolPermissionRequest
1 回分のツール権限リクエストです。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
toolName() | String | ツール名 |
toolInput() | JsonValue | ツールの入力パラメータ |
suggestions() | List<JsonValue> | CLI が示す権限の提案。権限ルールの更新など |
toolUseId() | Optional<String> | このツール呼び出しの ID |
agentId() | Optional<String> | 呼び出し元の Agent |
title() / displayName() / description() | Optional<String> | 承認画面に表示するタイトル、名前、説明 |
blockedPath() | Optional<String> | 確認のきっかけになったパス |
decisionReason() / decisionReasonType() | Optional<String> | CLI が確認を求める理由とその種類 |
permissionKind() | Optional<String> | 権限の種類。オープンな文字列 |
classifierApprovable() | Optional<Boolean> | CLI のヒント。アプリケーションが承認したことを意味しない |
options() | List<PermissionOption> | CLI が提示する承認オプション。不変 |
details() | Optional<PermissionDetails> | 追加の詳細 |
raw() | JsonObject | リクエスト全体 |
Optional を返します。SDK は権限の種類、オプションの結果、詳細の種類を閉じた列挙型に変換しません。未知の値は raw() から読み取ってください。
PermissionOption と PermissionDetails
PermissionOption は CLI が提示する承認オプションの 1 つです。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
outcome() | Optional<String> | オプションの結果。未知の値も保持する。PermissionScope.outcome() に対応 |
name() | Optional<String> | 表示名 |
allowed() | boolean | 元のフィールドが明示的に true の場合だけ選択可能。欠落や形式不正は false として扱う |
raw() | JsonObject | オプション全体 |
PermissionDetails はオープンな詳細モデルで、repeated_tool_call などの通知に使われます。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
type() / title() / toolName() / inputPreview() | Optional<String> | 詳細の種類、タイトル、ツール名、入力プレビュー |
repeatCount() / threshold() | Optional<Long> | 繰り返し回数としきい値。整数でない場合や範囲外の場合は空 |
raw() | JsonObject | オブジェクト全体 |
raw() には業務データが含まれることがあります。デフォルトではログに書き込まないでください。
PermissionScope
明示的な承認スコープです。PermissionResult.withScope(...) で使います。
| 定数 | 意味 | outcome() |
|---|---|---|
ONCE | この呼び出しだけを承認 | proceed_once |
SESSION | この CLI セッションの間は常に承認 | proceed_always |
PERSIST | 承認の永続保存を CLI に依頼 | proceed_always_and_save |
PERSIST の保存は CLI が担当します。SDK は独自の権限ストアを持たず、すべての権限の種類で使えることも保証しません。
PermissionResult
権限コールバックの判定です。許可(ツールの入力を書き換え可能)または拒否(理由付き)を表します。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
allow() | PermissionResult | 元のツール入力のまま許可 |
allow(JsonValue) | PermissionResult | 許可し、CLI は指定した入力を使う |
deny(String) | PermissionResult | 拒否。理由は CLI に渡される |
withScope(PermissionScope) | PermissionResult | 明示的なスコープ付きの新しい allow を返す。deny に対して呼ぶと IllegalStateException をスロー |
isAllowed() | boolean | 許可かどうか |
updatedInput() | Optional<JsonValue> | 書き換え後の入力 |
denyReason() | Optional<String> | 拒否の理由 |
scope() | Optional<PermissionScope> | 明示的なスコープ。withScope を呼んでいない場合は空で、CLI は ONCE として扱う |
options() がある場合、許可の判定(スコープ未指定の allow() を含む)は allowed() が true のオプションのいずれかに対応している必要があります。対応しない場合、その権限リクエストは失敗し、許可は送信されません。CLI がリクエストをキャンセルした後に届いた判定は送信されません。
PermissionMode
権限モードです。enum ではなく final クラスで、未知の値もそのまま保持します。新しい CLI で追加されたモードとの互換性を保つためです。
| 定数 | value() | 説明 |
|---|---|---|
DEFAULT | default | CLI のルールに従って権限を求める |
ACCEPT_EDITS | acceptEdits | ファイル編集を自動的に受け入れる |
BYPASS_PERMISSIONS | bypassPermissions | すべての権限チェックをスキップ。allowDangerouslySkipPermissions(true) の設定も必須 |
PLAN | plan | 計画のみで実行しない。ほかのモードと併用する場合は独立 Planを使う |
DONT_ASK | dontAsk | 確認しない。確認が必要な操作はそのまま拒否する |
AUTO | auto | 自動で判定する |
of(String) は既知のモードについて、大文字小文字と英数字以外の文字を無視します。"yolo" は BYPASS_PERMISSIONS と同じです。起動時は SessionOptions.Builder.permissionMode(...) で設定し、実行中は QoderSession.setPermissionMode(...) で切り替えます。どちらで BYPASS_PERMISSIONS を使う場合も、そのセッションで allowDangerouslySkipPermissions(true) を設定している必要があります。設定していない場合は InvalidOptionsException で失敗します。各モードの動作は権限制御を参照してください。
CancellationToken
コールバックが受け取るキャンセルトークンです。CLI がリクエストをキャンセルしたとき、コールバックがタイムアウトしたとき、またはセッションが閉じられたときにキャンセルされます。プロトコル上のキャンセル応答は SDK が送るため、アプリケーションは関連する処理を止めるだけで済みます。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
isCancelled() | boolean | キャンセル済みかどうか。一度 true になると変わらない |
onCancel(Runnable) | void | キャンセル時の処理を登録する。トークンがすでにキャンセル済みでも呼び出される。処理は非同期に実行され、登録したスレッド上でインラインに実行されることはなく、callbackExecutor も使わない |
registerOnCancel(Runnable) | CancellationRegistration | 上と同じ。登録を解除できるハンドルを返す |
CancellationRegistration.close() | void | 処理の登録を解除する。冪等でブロックしない。すでに実行が始まった処理は中断されない |
onCancel の処理はベストエフォートで実行され、セッションが閉じられるとキュー内の処理は破棄されることがあります。確実に止める必要がある処理は、自身の副作用の境界で isCancelled() を確認してください。長く続く処理には registerOnCancel を使い、処理の終了時に close() を呼んで、登録した処理とそれが保持するオブジェクトを解放することを推奨します。
独立 Plan
Plan の状態は権限モードとは独立して設定できます。Plan をオンにしても現在の権限モードは保持されます。パッケージは com.qoder.sdk.plan です。
| メソッド | 説明 |
|---|---|
SessionOptions.Builder.planMode(boolean) | 起動時の Plan の状態。呼ばない場合、CLI の Plan の状態は変わらない。明示的に false を渡すと CLI に Plan の終了を求める |
setPlanMode(boolean) | 実行中に Plan をオンまたはオフにし、CLI が確認した状態を返す |
getPlanMode() | CLI の現在の Plan の状態を問い合わせる |
setPermissionModePreservingPlan(PermissionMode) | Plan の状態を保ったまま権限モードを切り替える。PermissionMode.PLAN を渡すと InvalidOptionsException で失敗する |
PlanModeSnapshot.active() | Plan がオンかどうか |
- 上記の入口はいずれも、CLI が対応する capability をサポートしている必要があります。capability 要件を参照してください。サポートしていない場合は
UnsupportedCliCapabilityExceptionで失敗し、リクエストは送信されません。 - 起動時の
planMode(...)とpermissionMode(PermissionMode.PLAN)は同時に指定できません。planMode(false)を渡した場合も同様で、build()はInvalidOptionsExceptionをスローします。 QoderSession.setPermissionMode(...)は Plan が保たれることを保証しません。保つ必要がある場合はsetPermissionModePreservingPlan(...)を使ってください。- CLI が返す
PlanModeSnapshotまたはメッセージストリームのPlanModeChangedMessageを正としてください。ローカルで最後に設定した値から現在の状態を推測しないでください。
Hooks Reference
HookRegistration
Hook の登録 1 件分です。イベント名、省略可能な matcher、ハンドラーで構成されます。パッケージは com.qoder.sdk.hook です。不変で、builder() で構築し、SessionOptions.Builder.hooks(List<HookRegistration>) で登録します。
| Builder メソッド | パラメータの型 | 説明 |
|---|---|---|
event(String) | String | 必須。イベント名。PreToolUse、PostToolUse、Stop など |
matcher(String) | String | 省略可能。CLI がマッチングする。ツール名 Bash など |
handler(HookHandler) | HookHandler | 必須。ハンドラー |
timeoutMs(long) | long | この登録について Java 側で待つ上限(ミリ秒)。0(デフォルト)は controlRequestTimeoutMs を使う。負の値は IllegalArgumentException をスロー |
build() | — | 登録を構築する。event または handler がない場合は NullPointerException をスロー |
timeoutMs は Java 側の待ち時間だけを制限し、CLI には渡されません。メッセージストリームで Hook のライフサイクルイベントを確認したい場合は、includeHookEvents(true) も設定してください。対応するメッセージは HookEventMessage を参照してください。利用できるイベントと使い方は Hooksを参照してください。
HookHandler
Hook ハンドラーです。SDK 専用の Hook スレッド上で呼び出され、callbackExecutor は使いません。時間のかかる処理はアプリケーションのエグゼキューターに渡し、完了を表す stage を返してください。
PreToolUse で次の構造を返すと、そのツール呼び出しを拒否できます。
CALLBACK_EXECUTION_FAILED で失敗します。タイムアウトした場合は CONTROL_REQUEST_TIMEOUT で失敗します。
HookEvent
1 回分の Hook イベントです。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
eventName() | String | イベント名。CLI の入力にある hook_event_name から取得 |
matcher() | Optional<String> | CLI が返した matcher。通常は空 |
payload() | JsonValue | CLI の Hook 入力オブジェクト。元の JSON のまま |
payload() のよく使うフィールドは次のとおりです。共通フィールドは session_id、cwd、hook_event_name です。PreToolUse と PostToolUse には tool_name、tool_input、tool_use_id があり、PostToolUse にはさらに tool_response があります。UserPromptSubmit には prompt、Stop には stop_hook_active があります。フィールドの構成は CLI のバージョンによって決まり、SDK はモデル化も検証もしません。読み取るときはフィールドの欠落を許容してください。
MCP
McpServerConfig
MCP サーバーの設定です。SessionOptions.Builder.mcpServers(List<McpServerConfig>) で登録します。パッケージは com.qoder.sdk.mcp です。インスタンスは不変です。
| ファクトリー | type() | 説明 |
|---|---|---|
stdio(name, command, args) | stdio | CLI が起動する子プロセスのサーバー。args が null の場合は空のリストとして扱う |
sse(name, url) | sse | SSE のリモートサーバー |
http(name, url) | http | Streamable HTTP のリモートサーバー |
inProcess(name, handler) | sdk | JVM プロセス内のサーバー。メッセージは SDK 経由で InProcessMcpHandler に転送され、子プロセスはない |
| チェーンメソッド | 適用対象 | 説明 |
|---|---|---|
withEnv(String, String) | stdio | 環境変数を追加 |
withSecretEnv(String, SecretValue) | stdio | シークレットの環境変数を追加。同名の通常の変数より優先 |
withHeader(String, String) | sse / http | リクエストヘッダーを設定。名前は大文字小文字を区別しない |
withSecretHeader(String, SecretValue) | sse / http | シークレットのリクエストヘッダーを設定。同名の通常のヘッダーより優先 |
IllegalStateException をスローします。同じリスト内のサーバー名は一意である必要があります(大文字小文字を区別)。重複すると SessionOptions.Builder.build() が InvalidOptionsException をスローします。MCP の設定はシークレットも含めて、現在のアカウントだけが読める一時ファイルを通じて CLI に渡され、起動引数や環境変数には入りません。セッションの実行中にこれらのファイルを手動で削除しないでください。接続方法は MCP 統合を参照してください。
InProcessMcpHandler
プロセス内 MCP サーバーの JSON-RPC エンドポイントです。McpServerConfig.inProcess(name, handler) で登録します。
| メソッド | 説明 |
|---|---|
handle(JsonValue) | JSON-RPC メッセージを 1 件処理し、レスポンスで完了する stage を返す |
handle(JsonValue, CancellationToken) | SDK が実際に呼び出す入口。デフォルトでは引数 1 つの版に委譲する。キャンセルを検知したい場合はこちらをオーバーライドする。CancellationToken を参照 |
newConnection() | セッションがこのサーバーを登録するたびに 1 回呼び出される。デフォルトは自身を返す。接続ごとの状態を持つハンドラーは別のインスタンスを返す必要があり、null は返せない |
jsonrpc と対応するリクエストの id を含める必要があります。返す stage は null にできません。JsonNull.INSTANCE で完了すると、JSON-RPC のレスポンスがないこと(通知など)を表します。ハンドラーは callbackExecutor 上で実行され、例外をスローするか stage が例外で完了しても、影響はそのメッセージだけに限られます。同じ接続内では、リクエスト ID は handle() が返した stage が完了するまで使用中のままで、再利用すると DUPLICATE_MCP_REQUEST_ID になります。未完了のリクエストが 128 件に達すると、新しいリクエストは MCP_REQUEST_CAPACITY_EXCEEDED になります。キャンセルしても、ハンドラーがすでに起こした副作用は取り消されません。
McpServerStatus
MCP サーバー 1 台分の状態です。QoderSession.mcpServerStatus() が返します。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
name() | String | サーバー名 |
status() | String | 状態を表す文字列。値は CLI の報告に従う |
raw() | JsonValue | 元の状態 |
raw() にサーバーの有効な設定(env や headers を含む)を含めて返すことがあります。withSecretEnv、withSecretHeader などで登録したシークレットは [REDACTED] に置き換えられ、名前と状態のテキストも同様に処理されます。
McpAuthenticationResult と McpAuthenticationOptions
MCP OAuth に使います。流れは次のとおりです。QoderSession.beginMcpAuthentication(serverName[, options]) で認証を開始します。結果がユーザーの操作を必要とする場合、ホストは authUrl() を表示し、完全なコールバック URL を受け取ったら mcpSubmitOAuthCallbackUrl(serverName, callbackUrl) を呼び出します。SDK はブラウザーを開きません。state の検証、認証情報の交換、再接続は CLI が行います。最初の業務入力を送る前に認証を済ませておくことを推奨します。
| メソッド | 説明 |
|---|---|
requiresUserAction() | ホストがユーザーの認可を完了させる必要があるかどうか。false の場合は認証が完了している |
authUrl() | 認可の入口。ユーザーの操作が必要な場合は必ず存在する |
McpAuthenticationOptions.defaults() | CLI のデフォルトのコールバックアドレスを使う |
McpAuthenticationOptions.redirectUri(String) | ホストがコールバックを受け取る URI を指定する。空白にはできない |
toString() にも URL は含まれません。全体の流れは MCP OAuth 認証を参照してください。
ElicitationHandler
MCP elicitation のコールバックです。MCP サーバーがユーザーから追加の情報を集める必要があるときに呼び出されます。SessionOptions.Builder.onElicitation(...) で登録します。
callbackExecutor 上で実行され、controlRequestTimeoutMs の制限を受けます。例外をスローするか stage が例外で完了した場合、その elicitation だけが CALLBACK_EXECUTION_FAILED で失敗します。
ElicitationRequest
ElicitationResult
elicitation の結果です。
| ファクトリー | action() | 説明 |
|---|---|---|
accept(JsonValue) | accept | ユーザーが受け入れた。schema に沿って入力された内容を含む。内容が null の場合は NullPointerException をスロー |
decline() | decline | ユーザーが回答を拒否した |
cancel() | cancel | ユーザーがこのリクエストをキャンセルした |
Models
モデル関連の型は com.qoder.sdk.model パッケージにあります。選択方式とコールバックの使い方はモデル選択を参照してください。
ModelSelection
SessionOptions.Builder.modelSelection(...) に渡すモデル選択戦略です。3 つの戦略から 1 つだけを選びます。
| ファクトリメソッド | 戻り値の型 | 説明 |
|---|---|---|
staticModel(ModelId) | StaticModelSelection | セッション全体で固定のモデルを使用します |
dynamic(ModelPolicyProvider) | DynamicModelSelection | 初期モデルは CLI のデフォルトで選ばれ、以降はモデルリクエストごとにコールバックがモデル ID を返します |
dynamic(ModelId, ModelPolicyProvider) | DynamicModelSelection | 上と同じで、初期モデルを明示的に指定します |
policy(ModelDecisionProvider) | PolicyModelSelection | 初期モデルは CLI のデフォルトで選ばれます。コールバックは構造化された結果を返し、現在のモデルを維持するか、モデルとパラメータを上書きできます |
policy(ModelId, ModelDecisionProvider) | PolicyModelSelection | 上と同じで、初期モデルを明示的に指定します |
openSession() の完了前に実行されることを前提にしないでください。
ModelPolicyProvider
dynamic(...) が使うコールバックです。今回のリクエストで使うモデル ID を返します。
| パラメータ | 型 | 説明 |
|---|---|---|
context | ModelRequestContext | 今回のモデルリクエストのコンテキスト |
SessionOptions.Builder.resolveModelTimeoutMs(long) で設定します。デフォルトは 500 ミリ秒で、0 は無制限を意味します。コールバックが例外を投げた場合、失敗した stage を返した場合、タイムアウトした場合は、今回のモデルリクエストが失敗し、初期モデルへのフォールバックはありません。これらの失敗は例外としてアプリケーションに渡されず、メッセージカーソルも SDK の非同期メソッドも例外を投げません。SDK は CLI にエラーコード(タイムアウトは MODEL_RESOLUTION_TIMEOUT、コールバックの失敗は CALLBACK_EXECUTION_FAILED)を返し、detail に error=<エラーコード> を含む inbound_control_request_failed 診断イベントを発行するだけです。検知が必要な場合は DiagnosticsListener を登録し、そのターンの結果は ResultMessage の outcome() で処理してください。
ModelDecisionProvider
policy(...) が使うコールバックで、ModelPolicyResult を返します。コンテキスト、実行スレッド、タイムアウトの予算は ModelPolicyProvider と同じです。
null を返した場合、stage が null で完了した場合、例外を投げた場合、タイムアウトした場合は、今回のモデルリクエストが失敗します。CLI が現在選択しているモデルを維持するには、ModelPolicyResult.keepCurrent() を明示的に返す必要があります。
ModelPolicyResult
ModelDecisionProvider の不変の戻り値です。明示的に設定したフィールドだけが送信されます。モデルを設定しない場合は、CLI がすでに選択したモデルが維持されます。
| Builder メソッド | 説明 |
|---|---|
model(ModelId) | 今回のリクエストのモデルを上書きします |
parameters(JsonObject) | CLI に渡すリクエストパラメータです。SDK はその意味を解釈しません |
taskId(String) | 推論タスクの識別子 |
subTask(String) | 業務サブタスクの識別子 |
build() | 結果を作成します。何も設定しない場合は keepCurrent() と同じです |
null を受け付けません。parameters は秘密情報を渡すための経路ではないため、認証情報を入れないでください。
ModelRequestContext
1 回のモデルリクエストのコンテキストで、SDK がモデルコールバックに渡します。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
sessionId() | Optional<String> | 所属するセッションの ID |
purpose() | Optional<String> | CLI が今回モデルを呼び出す用途 |
turnIndex() | Optional<Integer> | ターンのインデックス |
agentId() / agentType() | Optional<String> | リクエスト元のサブエージェントの ID と種類 |
resolvedModel() | Optional<ModelId> | コールバックの前に CLI が仮選択したモデル |
availableModels() | List<ModelInfo> | 今回のリクエストに付属するモデルカタログ(不変)。提供されない場合は空リスト |
Optional.empty() です。availableModels() は今回のリクエスト時点のスナップショットにすぎないため、セッション全体の固定カタログとしてキャッシュしないでください。
ModelInfo
モデルカタログの 1 件のエントリです。QoderSession.getAvailableModels() が返すほか、ModelRequestContext と ModelCatalogSnapshot にも含まれます。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
modelId() | ModelId | モデル選択に使えるモデル ID |
displayName() / description() | Optional<String> | 表示名と説明 |
source() / outerProvider() / descriptionEn() | Optional<String> | ソース、外部プロバイダー、英語の説明 |
isEnabled() | boolean | 現在のアカウントで選択できるかどうか。CLI がこのフィールドを返さない場合は false として扱います |
raw() | JsonValue | 完全な元のエントリ。コンテキストウィンドウや価格など、モデル化されていないフィールドも含みます |
isEnabled() が false のモデルが含まれることがあります。選択可能なモデルを表示するときは除外してください。
ModelCatalogOptions
QoderSession.getAvailableModels(ModelCatalogOptions) の読み取りオプションです。
defaults() と引数なしの getAvailableModels() は、どちらも CLI のデフォルトのキャッシュ戦略を使います。Builder の fetchStrategy(FetchStrategy) でリアルタイム読み取り(LIVE)かキャッシュ(CACHE)を明示的に選び、uid(String) でカタログの uid を指定します。
ModelCatalogSnapshot
QoderSession.modelCatalogSnapshot() が返すローカルのモデルカタログのスナップショットです。初期化結果、または CLI がプッシュした最新のカタログ更新から取得します。
modelCatalogSnapshot() が Optional.empty() を返す場合は、まだカタログを受信していません。スナップショットが返り models() が空の場合は、CLI が空のカタログを明示的に返したことを意味します。スナップショットの読み取りは CLI にリクエストを送りません。現在のアカウントのリアルタイムの結果が必要な場合は getAvailableModels(...) を呼び出してください。
ModelId
モデル ID の値型です。
Memory
Memory の設定は SessionOptions.Builder.memory(MemoryOptions) で渡します。関連する型は com.qoder.sdk.memory パッケージにあります。メモリの生成、書き込み、読み込みは CLI が行い、セッション記録を保存する SessionStore とは独立した機能です。有効化の方法、アプリケーション管理のディレクトリ、ターンごとの生成制御はメモリを参照してください。
Memory 型一覧
| 型 | 役割 |
|---|---|
MemoryOptions | クエリレベルの設定の入口です。disabled() がデフォルトで、nativeBuilder() は CLI ネイティブのメモリを使い、customBuilder() ではアプリケーションが生成と読み込みの設定を指定します。ユーザーレベル/プロジェクトレベルのスコープ、結果コールバック、drainTimeoutMs(デフォルト 60000 ミリ秒)を設定できます |
MemoryGenerationOptions | custom モードの生成設定:有効/無効、メモリディレクトリ(roots)、生成プロンプト、ターン終了後の自動抽出 |
MemoryTurnCompleteOptions | ターン終了後の自動抽出の設定:有効/無効、shouldGenerate 判定コールバック、タイムアウト(デフォルト 10000 ミリ秒)、判定失敗時のポリシー OnGateError(SKIP / REPORT_FAILED) |
MemoryShouldGenerate | ターンごとの判定コールバックで、CompletionStage<MemoryGenerationGateResult> を返します |
MemoryGenerationGateInput / MemoryGenerationGateResult | 判定コールバックの入力(セッション、ターン、prompt、回答など)と、run() / skip(reason) の判定結果 |
MemoryConsumptionOptions | custom モードの読み込み設定:有効/無効、ファイル一覧、maxTokens、上限超過時の処理 Overflow(TRUNCATE / FAIL_QUERY)、読み取り失敗時の処理 FailureMode(BEST_EFFORT / FAIL_QUERY) |
MemoryRoot / MemoryConsumptionFile | builder(String id, Path path) で作成するメモリディレクトリと読み込みファイルです。ディレクトリにはアクセス権(READ / READ_WRITE)とインデックスファイルを、読み込みファイルには必須指定を設定できます |
MemoryGenerationHandler / MemoryConsumptionHandler | 生成結果と読み込み結果の通知コールバックで、CompletionStage<Void> を返します |
EffectiveMemoryConfig | CLI が初期化時に確認した実際の設定で、InitializationResult.memory() が返します。有効状態、モード、各スイッチ、roots の id とアクセス権を含みますが、解決後のファイルパスは含みません |
MemoryGenerationResult / MemoryConsumptionResult | 生成結果と読み込み結果:ステータス、ファイルごとの詳細、元の JSON。生成のステータスは SAVED、PARTIAL、NO_CHANGE、SKIPPED、FAILED、読み込みのステータスは SUCCESS、PARTIAL、FAILED です。認識できないステータスは UNKNOWN になります |
MemoryUsage | メモリ生成そのものが消費した使用量です。CLI が返さない値は Optional.empty() です |
MemoryGenerationMessage と MemoryConsumptionMessage としてメッセージストリームにも現れます。memory(null) は NullPointerException を投げます。Memory を無効にするには MemoryOptions.disabled() を渡してください。
flushMemory() と refreshMemory()
QoderQuery と QoderSession の両方がこの 2 つのメソッドを提供します。CompletionStage<Void> を返し、初期化の完了を自動で待ちます。
flushMemory():CLI がすでに開始したメモリ処理の終了を待ちます。以降のターンは待たず、すべてのファイルの保存成功も保証しないため、結果は引き続きMemoryGenerationResultで確認する必要があります。待機の上限はdrainTimeoutMsです。refreshMemory():現在の読み込み設定でメモリファイルを読み直します。外部でメモリファイルを変更した後に呼び出すのに適しており、設定は変更しません。タイムアウトにはcontrolRequestTimeoutMsを使います。
UnsupportedCliCapabilityException で失敗します。単発クエリで Memory を有効にした場合、ResultMessage の後もメッセージストリームにメモリ処理のメッセージが届くため、ストリームを最後まで消費してください。
Session Storage
外部セッションストレージ関連の型です。SessionStorage と SessionRepository は com.qoder.sdk パッケージに、それ以外は com.qoder.sdk.session パッケージにあります。使い方は外部セッションストレージとセッション制御を参照してください。
SessionStorage
1 回のセッションでどの履歴ストレージを使うかを指定します。SessionOptions.Builder.sessionStorage(...) で設定します。
| ファクトリメソッド | 説明 |
|---|---|
inherit() | デフォルト値です。QoderClient.Builder.sessionStore(...) で設定したクライアントのストアを使い、クライアントに設定がない場合は CLI のローカル履歴を使います |
cliLocal() | このセッションでは外部ストアを使わず、CLI のローカル履歴だけを使います |
external(SessionStore) | このセッションで指定した外部ストアを使います。引数に null は指定できません |
fileCheckpointing(true) と同時に使えません。
SessionStore
外部セッションストアが実装するインターフェースです。クライアントは QoderClient.Builder.sessionStore(...) でデフォルトのストアを設定し、このストアは client.sessions() でも使われます。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
append(SessionKey, AppendBatch) | CompletionStage<AppendResult> | 1 つのバッチをアトミックに追記します |
load(SessionKey) | CompletionStage<Optional<SessionSnapshot>> | transcript の完全なスナップショットを読み込みます。キーが存在しないか削除済みの場合は空を返します |
実装契約
| 契約 | 要件 |
|---|---|
| 順序と分離 | load は追記順にエントリを返します。異なる SessionKey のデータは互いに見えません |
| アトミック性 | 同じキーへの並行した追記は直列化する必要があります。バッチは全体が書き込まれるか、全体が失敗するかのどちらかです |
| 冪等性 | 同じキーですでに書き込まれた operationId を再度書き込んではいけません。元の操作の newVersion と appendedCount を返し、再生(リプレイ)としてマークします。このチェックは CAS より先に行います。削除済みのキーは常に SessionStoreDeletedException で拒否します |
| CAS | expectedVersion が null でない場合は現在のバージョンと一致する必要があり、一致しない場合は現在のバージョンを含む SessionStoreConflictException を投げます。null の場合は無条件に追記します。空のキーの現在のバージョンは VersionToken.initial() です |
| UUID の整合性 | uuid と rawJson がどちらも同じエントリは重複して書き込みません。uuid が同じで rawJson が異なる場合は競合として報告する必要があります。uuid のないエントリは内容による重複排除を行いません |
MirrorErrorMessage と診断イベントで報告され、メインの回答は続行することがあります。回答が成功しても、記録が永続化されたとは限りません。
ListableSessionStore
列挙可能なストアです。SessionRepository の list()、最新のセッションの継続、サブエージェントの復元はこれに依存します。
listSessions はプロジェクト配下のすべてのキー(サブパスのキーを含む)を返し、順序は保証されません。deleteSession は指定した 1 つのキーだけを削除し、同じセッションの他のサブパスは削除しません。
SessionDeletionStore
セッション全体の削除をサポートするストアです。SessionRepository.delete(...) はストアがこのインターフェースを実装していることを要求します。
SessionStoreDeletedException で拒否され、古いバージョンからデータを再構築することもできません。存在しないセッションや削除済みのセッションの削除も成功させてください。削除済みのセッション ID は再利用できません。
InMemorySessionStore
SDK 組み込みのインメモリ実装で、SessionDeletionStore を実装しています。データはプロセスの終了とともに失われるため、テストや短時間で終わるプロセスに適しています。
SessionMirrorOptions
外部ストアへの書き込み(ミラーリング)のリソース上限で、SessionOptions.Builder.sessionMirrorOptions(...) で設定します。builder() で作成し、defaults() はデフォルト値を返します。すべての値は正の数である必要があります。
| 設定項目 | デフォルト値 | 説明 |
|---|---|---|
maxPendingBatches | 256 | 書き込み待ちバッチ数の上限 |
maxPendingBytes | 64 MiB | 書き込み待ちバッチの元の内容のバイト数上限 |
operationTimeoutMs | 60000 | 各バッチについて、バージョンの読み取りから追記完了まで(リトライを含む)の合計時間 |
closeDrainTimeoutMs | 5000 | セッションを閉じるときに残りのバッチの書き込みを待つ時間 |
MirrorErrorMessage と診断イベントで報告され、モデルのターンは中断されません。
SessionRepository
保存済みのセッションの読み取り、継続、フォーク、削除を行います。client.sessions() でクライアントのデフォルトスコープのリポジトリを、client.sessions(SessionOptions) で特定のセッションが使うスコープのリポジトリを取得します。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
list() | CompletionStage<List<String>> | 現在のスコープに保存されているセッション ID。ListableSessionStore が必要です |
get(String) | CompletionStage<Optional<SessionSnapshot>> | 1 つのセッションの transcript スナップショット。外部ストアが必要です |
delete(String) | CompletionStage<Void> | セッションとそのすべてのサブパスを削除します。SessionDeletionStore が必要です |
continueSession(String, SessionOptions) | CompletionStage<QoderSession> | 新しい CLI プロセスでセッションを継続します。sessionId に null を渡すと最新のセッションを継続します |
fork(String, SessionOptions) | CompletionStage<QoderSession> | 指定したセッションを起点に新しいセッションを作成します |
- リポジトリは 1 つのストアとプロジェクトキーに固定されます。ストアは
sessionStorageから解決します。プロジェクトキーはworkingDirectoryから取り、未設定の場合はクライアントのprojectDirectoryを使い、どちらもない場合はdefaultになります。 sessions(options)はそのうちストアとディレクトリの 2 項目だけを採用します。プロセスは起動せず、CLI のパスや環境変数などその他の設定も保持しません。continueSessionとforkのoptionsでディレクトリやストアを指定しない場合は、リポジトリのスコープを引き継ぎます。明示的に上書きすると別のスコープのセッションを開けますが、現在のリポジトリのlist、get、deleteは変わりません。
UnsupportedCliCapabilityException で失敗し、キーごとの削除にフォールバックすることはありません。外部ストア上の fork には、CLI が対応する capability をサポートしていることも必要です。capability 要件を参照してください。
ストレージ値の型
SessionStore の実装で使う値型です。
| 型 | メンバー | 説明 |
|---|---|---|
SessionKey | projectKey / sessionId / subpath | ストアのキーです。セッションルートの subpath は空文字列で、サブエージェントの transcript は空でないサブパスを使います。projectKeyFor(Path) はプロジェクトディレクトリからプロジェクトキーを生成します |
AppendBatch | operationId | 冪等 ID。同じ ID でリトライしても一度だけ適用されます |
expectedVersion | CAS の期待バージョン。null は無条件の追記を意味します | |
firstSequence | バッチ先頭エントリの順序の参考値で、CAS のバージョンや冪等 ID の代わりにはなりません | |
entries | バッチのエントリ。Builder は operationId、expectedVersion、firstSequence、addEntry、addEntries を提供します | |
AppendResult | applied(...) / replayed(...) | 実際に書き込んだ結果、または冪等な再生の結果です。再生の場合は元の操作のバージョンと件数を渡します |
alreadyApplied() | 再生かどうか | |
SessionSnapshot | entries / version | 追記順に並んだエントリと現在のバージョン |
SessionStoreEntry | rawJson() | 元の JSON 行です。type、uuid、timestamp はここから抽出されます。toString() は本文を出力しません |
OperationId | of / random | 冪等な操作 ID |
VersionToken | initial() | 空のストアの開始バージョンです。書き込みが成功するたびにバージョンを進める必要があります |
SessionStoreDeletedException | CODE | 削除済みのセッションへの書き込みを拒否します。エラーコードは SESSION_STORE_DELETED で、リトライできません。CAS の競合ではないため、現在のバージョンでリトライしないでください |
Results and Identifiers
InitializationResult
初期化ハンドシェイクの結果で、QoderQuery.initialization()、QoderSession.initialization() などのメソッドが返します。ハンドシェイク完了時点の読み取り専用スナップショットで、以降は変化しません。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
capabilities() | Map<String, CapabilityState> | CLI がハンドシェイク時に宣言した capability(不変) |
capability(String) | CapabilityState | 1 つの capability の状態。宣言されていない場合は UNKNOWN を返します |
cliVersion() | Optional<String> | CLI のバージョン |
wireVersion() | Optional<String> | ネゴシエートされた通信プロトコルのバージョン |
sessionId() | Optional<String> | CLI が割り当てたセッション ID |
memory() | Optional<EffectiveMemoryConfig> | CLI が確認した Memory の設定。有効でない場合は空です |
UNSUPPORTED に下げ、同じセッションでの以降の呼び出しはローカルで直接失敗します。InitializationResult はこの変化を反映しません。検知が必要な場合は、type が capability_downgraded の診断イベントを監視してください。
メソッドと必要な capability
次のメソッドや設定には、CLI がハンドシェイク時に対応する capability を宣言している必要があります。capability の状態が SUPPORTED でない場合(宣言されていない UNKNOWN を含む)、SDK はリクエストを送らず、UnsupportedCliCapabilityException で失敗します。
| メソッドまたは設定 | 必要な capability | サポートされていない場合 |
|---|---|---|
QoderSession.backgroundTasks() / backgroundTasks(String) | background_tasks_v1 | 返された stage が例外で完了します |
QoderSession.stopTask(TaskId) | background_tasks_v1 | 返された stage が例外で完了します |
QoderSession.rewindHistory(MessageId) | session_rewind_v1 | 返された stage が例外で完了します |
QoderSession.reloadSkills() | reload_skills_v1 | 返された stage が例外で完了します |
getPlanMode() / setPlanMode(boolean) / setPermissionModePreservingPlan(PermissionMode) | plan_mode_v1 | 返された stage が例外で完了します |
SessionOptions.Builder.planMode(boolean) | plan_mode_v1 | 初期化が失敗します |
SessionOptions.Builder.customContext(Map) | custom_context_v1 | 初期化が失敗します |
UserInput.Builder.customContext(Map)(空の map を含む) | custom_context_v1 | その入力の書き込み stage が例外で完了します。最初の入力の場合は初期化が失敗します |
UserInput.Builder.selectedSkills(List)(空でない場合) | selected_skills_v1 | その入力の書き込み stage が例外で完了します。最初の入力の場合は初期化が失敗します |
QoderSession.cancelQueuedMessage(MessageId) のリモートキャンセル | interrupt_cancel_queued_v1 | ローカルのキャンセルだけを行います。入力の書き込みがすでに始まっている場合は、例外を投げずに false を返します |
外部 SessionStore と forkSession(true) の組み合わせ(SessionRepository.fork(...) を含む) | session_store_fork_barrier_v1 | 初期化が失敗します |
QoderSession のその他の制御メソッド(getAvailableModels、rewindFiles、setPermissionMode など)は capability をチェックせず、直接リクエストを送ります。
CapabilityState
CLI の capability の 3 つの状態です。
| 値 | 説明 |
|---|---|
SUPPORTED | CLI がサポートを宣言しています |
UNSUPPORTED | CLI が非サポートを明示的に宣言したか、実行中にこの capability のリクエストを拒否しました |
UNKNOWN | CLI が宣言していません。この capability に依存するメソッドは直接失敗し、SDK は試行しません |
InterruptResult
interrupt() の結果です。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
interrupted() | boolean | 実行中のターンに中断を送ったかどうか。実行中のターンがない場合は false です |
turnState() | String | 戻った時点のターンの状態:IDLE、RUNNING、INTERRUPTING のいずれか |
ResultMessage で判断します。中断リクエストが失敗した場合(タイムアウトを含む)、ターンは RUNNING に戻り、リトライできます。
MessageSubmission
QoderSession.submit(UserInput) が返す送信ハンドルです。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
id() | MessageId | すぐに使える入力 ID で、cancelQueuedMessage に渡せます。入力が受け付けられた、または書き出されたことは意味しません |
written() | CompletionStage<MessageId> | 入力が CLI に書き込まれた後に完了し、回答は待ちません。入力が拒否された場合や書き込みに失敗した場合は例外で完了し、ローカルのキャンセルに成功した場合は CancellationException で完了します |
send(input) を、書き込み前にキャンセルする可能性がある場合は submit(input) を使います。written() は呼び出すたびに独立した stage を返し、それをキャンセルしても入力自体はキャンセルされません。
識別子の型
| 型 | 説明 |
|---|---|
MessageId | ユーザー入力の ID で、MessageSubmission.id() または send(...) の戻り値から取得します。cancelQueuedMessage、rewindHistory、rewindFiles で使います |
TaskId | バックグラウンドタスクの ID で、stopTask(TaskId) に渡します |
SessionTitle | generateSessionTitle() が返すセッションタイトル |
RewindFilesOptions / RewindFilesResult
QoderSession.rewindFiles(MessageId, RewindFilesOptions) のオプションと結果です。セッションは SessionOptions.Builder.fileCheckpointing(true) で起動しておく必要があります。ファイル Checkpoint と Rewindを参照してください。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
RewindFilesOptions.defaults() | RewindFilesOptions | 実際にファイルを巻き戻します |
RewindFilesOptions.dryRun() | RewindFilesOptions | どのファイルが変わるかだけを報告し、ディスクには書き込みません |
canRewind() | boolean | 巻き戻せるかどうか(試行時)、または巻き戻したかどうか |
filesChanged() | List<String> | 影響を受けるファイル |
error() | Optional<String> | 巻き戻せない理由 |
Message Types
SdkMessage
メッセージストリーム内のすべてのメッセージの抽象基底クラスで、com.qoder.sdk.message にあります。具体的な型は instanceof で判定します。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
wireType() | String | メッセージのトップレベルの type |
uuid() | Optional<String> | メッセージ UUID。CLI が提供した場合に値があります |
sessionId() | Optional<String> | 所属するセッションの ID。CLI が提供した場合に値があります |
rawJson() | Optional<String> | メッセージの元の JSON。SDK がモデル化していないフィールドは、JsonValue.parse で解析してから読み取ります |
| クラス | wireType() | 説明 |
|---|---|---|
AssistantMessage | assistant | アシスタントの応答 |
ResultMessage | result | ターン終了時の結果 |
UserReplayMessage | user | CLI がリプレイしたユーザーメッセージ |
PartialMessage | partial | ストリーミングの増分イベント |
SystemMessage とサブクラス | system | システムメッセージ。subtype() ごとに専用クラスに分かれ、Hook 通知や Memory の結果を含みます |
HookEventMessage | hook_event | 旧形式の Hook イベント |
MirrorErrorMessage | mirror_error | セッションのミラーリング書き込みの失敗 |
UnknownMessage | 元の値 | 未知のトップレベル型 |
SystemMessage を継承しています。分岐では専用サブクラスを先に判定し、SystemMessage はその後に判定してください。そうしないと、広い分岐が専用の型を覆い隠します。
AssistantMessage とコンテンツブロック
アシスタントが応答を 1 つ生成したときに配信されます。コンテンツブロックは出力側の型で、入力側の UserInput のコンテンツブロックとは別のものです。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
AssistantMessage.content() | List<ContentBlock> | コンテンツブロックのリスト |
AssistantMessage.getText() | String | すべての TextBlock のテキストを連結したもの |
ContentBlock.type() | String | コンテンツブロックの type(例:text) |
TextBlock.text() | String | テキストの内容 |
UnknownContentBlock.rawJson() | String | このコンテンツブロックの元の JSON |
text ブロック(TextBlock)だけです。tool_use、thinking などのほかのブロックは UnknownContentBlock として保持されます。type() は元の型を返すので、必要に応じて rawJson() を解析してください。TypeScript と Python の SDK には、これらのブロック用の型付きクラスがあります。
ResultMessage と使用量
1 ターンの対話が終わったときに配信されます。Agent の業務上の失敗(ターン数の上限到達など)は、outcome() が ERROR の ResultMessage で報告され、例外はスローされません。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
wireSubtype() | String | 元の subtype(例:success、error_max_turns) |
wireIsError() | Optional<Boolean> | 元の is_error。CLI が提供しない場合は空です |
outcome() | ResultOutcome | 正規化された結果。規則は下記を参照 |
result() | Optional<String> | 最終的な結果テキスト |
errors() | List<String> | エラーの説明。空の場合はありますが、null にはなりません |
usage() | Usage | このターンのトークン使用量 |
Usage.inputTokens() / outputTokens() | long | 入力・出力のトークン数 |
outcome() の規則:is_error が true、または subtype が error で始まる場合は ERROR、subtype が success の場合は SUCCESS、それ以外は UNKNOWN です。
Usage には入力と出力の 2 つのカウントしかなく、料金、キャッシュトークン、コンテキスト使用量は含まれません。これらが必要な場合は rawJson() から読み取ります。カウントが欠けているか、long で正確に表せない場合は 0 になります。そのため、0 は CLI が使用量ゼロを確認したことを意味しません。
メモリを有効にすると、ResultMessage は回答ターンの終了だけを表し、その後にも Memory の結果メッセージが配信されることがあります。単発クエリはストリームの終わりまで読み取ってください。Memory 生成の使用量は別に報告され、このメッセージの usage() には含まれません。
SystemMessage とサブクラス
CLI が送るシステムメッセージです。SystemMessage 自体は専用クラスのない subtype に使われ、未知の subtype もこれで保持されます。
subtype() | クラス | 主なアクセサー | 説明 |
|---|---|---|---|
| その他または未知の値 | SystemMessage | subtype() | 完全なペイロードは rawJson() にあります |
plan_mode_changed | PlanModeChangedMessage | planMode() → PlanModeSnapshot | 独立 Plan の状態変化。権限を参照 |
commands_changed | CommandsChangedMessage | commands() → List<CommandInfo> | 今回の完全なコマンドカタログ。空のリストはクリアを表します |
available_models_update | AvailableModelsUpdateMessage | catalog() → ModelCatalogSnapshot | 今回の完全なモデル一覧と現在のモデル |
agents_md_size_warning | AgentsMdSizeWarningMessage | totalBytes()、files() など | AGENTS ファイルのサイズ警告 |
permission_denied | PermissionDeniedMessage | なし。rawJson() を読み取ります | ツールの権限が 1 回拒否された |
background_tasks_changed | BackgroundTasksChangedMessage | なし。rawJson() を読み取ります | バックグラウンドタスクの集合が変化した |
task_updated | TaskUpdatedMessage | なし。rawJson() を読み取ります | あるタスクの状態が更新された |
hook_started / hook_progress / hook_response | HookStartedMessage など | Hook 通知メッセージを参照 | Hook の実行通知 |
memory_generation / memory_consumption | MemoryGenerationMessage / MemoryConsumptionMessage | result() | メモリの生成・読み込みの結果 |
AgentsMdSizeWarningMessage のサイズはすべて CLI が報告する UTF-8 のバイト数で、SDK は再計算しません。truncated() は CLI が報告した読み込み状態を表し、SDK が切り詰めたことを意味するものではありません。
PermissionDeniedMessage、BackgroundTasksChangedMessage、TaskUpdatedMessage の WIRE_TYPE 定数は非推奨です。型または subtype() で判定してください。
コマンドまたはモデルのカタログ更新が無効な場合、SDK は対応する専用メッセージを作らず、直前のカタログのスナップショットを保持します。元のメッセージは汎用の SystemMessage として配信され、同時に invalid_catalog_update 診断が発行されます。
PartialMessage と UserReplayMessage
PartialMessage はストリーミングの増分イベントで、SessionOptions.Builder.includePartialMessages(true) のときだけ配信されます。wireType() は partial で、CLI の元の stream_event フレームは rawJson() にあります。Java SDK には型付きのストリームイベントがないため、テキストの増分もツール入力の増分も rawJson() から解析します。ストリーミング出力を参照してください。
UserReplayMessage は、CLI がメッセージストリームにリプレイしたユーザーメッセージ(type=user)です。UserInput とは別の型なので、そのまま再送信することはできません。
Hook 通知メッセージ
Hook の実行時の通知です。SessionOptions.Builder.includeHookEvents(true) のときだけメッセージストリームに入ります。このオプションをオフにしても Hook コールバックの実行には影響しません。これらは通知だけなので、アプリケーションが応答する必要はありません。実行をブロックまたは変更するには HookHandler を使います。
hook_id、exit_code など)に対応します。outcome() は未知の値もそのまま保持します。フィールドが欠けているか型が合わない場合は空を返します。exitCode() は値が int の範囲の整数でない場合に空を返し、切り詰めは行いません。元の値は引き続き rawJson() から読み取れます。
HookEventMessage は旧形式の type=hook_event メッセージに対応します。SDK は上の 3 種類の system 通知をこの型に変換しません。
MemoryGenerationMessage と MemoryConsumptionMessage
メモリの生成と読み込みの結果です。どちらも対話のターンを終了させません。結果の型は com.qoder.sdk.memory にあります。使い方はメモリを参照してください。
MemoryGenerationResult には生成状態、書き込んだファイルと失敗したファイル、所要時間、任意の独立した使用量が含まれます。flush が成功してもすべてのファイルが保存されたとは限らないため、status() と failedFiles() を確認してください。MemoryConsumptionResult には全体の状態とファイルごとの読み込み状態が含まれます。未知の状態は UNKNOWN にマップされ、元の値は wireStatus() に残ります。結果コールバックを登録しても、この 2 種類のメッセージはメッセージストリームから取り除かれません。
MirrorErrorMessage と UnknownMessage
MirrorErrorMessage は、外部セッションストレージへのミラーリング書き込みが失敗したときに配信されます。専用のアクセサーはありません。エラーテキストは rawJson() の error フィールドにあり、マスク済みで形式も安定していないため、文字列で照合しないでください。分類するときは sessionId() と診断タイプ mirror_append_failed を組み合わせます。
UnknownMessage は SDK が認識しないトップレベルのメッセージ型を保持します。wireType() は元の値を、wireSubtype() は元の subtype を返し、完全なペイロードは rawJson() にあります。
JSON Types
JsonValue とサブタイプ
SDK に付属するイミュータブルな JSON 型で、com.qoder.sdk.json にあり、サードパーティへの依存はありません。Hook や MCP などのコールバックのペイロードはこれらの型を使います。メッセージの rawJson() は文字列を返すので、必要に応じて JsonValue.parse(...) で解析します。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
asXxx() | 対応する型 | 型を変換します。型が一致しない場合は IllegalStateException をスローします |
asNumber() / JsonNumber.value() | BigDecimal | 数値は BigDecimal で正確に保持されます |
JsonObject.get(String) | JsonValue | メンバーが存在しない場合は null を返します。存在の確認には contains を使います |
JsonObject.members() | Map<String, JsonValue> | 読み取り専用のビューで、挿入順を保ちます |
JsonObject.Builder.put(String, JsonValue) | Builder | メンバーを追加します。同名の場合は後の値が優先されます。名前も値も null にはできません |
parseは、ネストの深さが 1000 階層を超える場合、または 1 つの数値が 1024 文字を超える場合にIllegalArgumentExceptionをスローします。JsonNumber.of(double)は NaN と無限大を受け付けません。JsonNumber.of(BigDecimal)は、シリアライズ結果が 1024 文字を超える場合にIllegalArgumentExceptionをスローします。
Diagnostics
DiagnosticsListener
SDK の構造化された診断イベントを受け取ります。セッションの初期化、クローズのタイムアウト、capability のダウングレード、マネージド CLI のインストールなどです。
- 2 つの登録レベル。 クライアントレベルは
QoderClient.Builder.diagnosticsListener(...)、セッションレベルはSessionOptions.Builder.diagnosticsListener(...)で登録します。両者は重ねて使われません。セッションにリスナーが設定されていればセッションレベルだけを使い、なければクライアントレベルにフォールバックします。マネージド CLI のmanaged_runtime_*イベントはクライアントレベルのリスナーにだけ送られます。 - スレッド。 各セッションは SDK 独自の診断スレッドでリスナーを逐次呼び出し、
callbackExecutorは使いません。同じリスナーを複数のセッションに登録すると並行して呼ばれる可能性があるため、スレッドセーフにしてください。 - ベストエフォートの配信。 キューに溜まったイベントが上限を超えると、新しいイベントは破棄されます。リスナーが例外をスローしても失われるのはその 1 回の通知だけです。クローズ時は排出に限られた時間しか与えられず、タイムアウトするとリスナーを中断して残りのイベントを破棄します。診断はロスのない監査ログとしても、業務状態の唯一の根拠としても使えません。
- すぐに戻ること。 時間のかかる処理はアプリケーション自身の非同期の仕組みに渡してください。リスナーは SDK のスレッドで実行されます。イベントを発行したセッションやそのクライアントを閉じる必要がある場合は、
closeAsync()を呼んですぐに戻ります。リスナー内でそれらのブロッキングのclose()を呼ぶとIllegalBlockingCloseExceptionがスローされます。
DiagnosticEvent
イミュータブルな診断イベントです。SDK が生成した detail はマスク済みです。登録済みの認証情報を取り除き、認証情報らしきテキストもできる範囲で検出しますが、任意の業務データまで対象になる保証はありません。
| フィールド | 型 | 説明 |
|---|---|---|
type | String | イベントタイプ。必須です。よく使われる値は下表を参照 |
sessionId | Optional<String> | 所属するセッションの ID |
requestType | Optional<String> | 関連する制御リクエストの種類 |
durationMs | Optional<Long> | 処理の所要時間(ミリ秒) |
queueDepth | Optional<Integer> | キューの深さのスナップショット |
exitCode | Optional<Integer> | CLI の終了コード |
capability | Optional<String> | 関連する capability 名 |
detail | Optional<String> | 自由形式の詳細 |
builder(type) で独自にイベントを作った場合、SDK は detail をマスクしません。
よく使われるイベントタイプ
type | 主なフィールド | 意味 |
|---|---|---|
session_initialized | sessionId、detail | 初期化ハンドシェイクが完了した。detail にプロトコルバージョンが含まれます |
protocol_handshake_warning | detail | ハンドシェイク時のプロトコルネゴシエーションによる警告 |
session_failed | sessionId、exitCode、detail | セッションがエラーで終了した |
control_request_completed | requestType、durationMs | 制御リクエストが成功レスポンスを受け取った |
inbound_control_request_failed | sessionId、detail | CLI が発行したコールバックリクエスト(権限、Hook、MCP、モデルポリシー、認証トークンなど)が失敗またはタイムアウトし、SDK が CLI にエラーを返した。detail に request_id と error=<エラーコード>(例:MODEL_RESOLUTION_TIMEOUT)が含まれます |
capability_downgraded | capability、requestType | capability チェックを通過した制御リクエストが、実行時に CLI からサポート外と判定された。以降はダウングレード後の状態でチェックされます。すでに返された InitializationResult は変わりません |
invalid_catalog_update | sessionId | コマンドまたはモデルのカタログ更新が無効だった。直前のスナップショットが保持されます |
memory_callback_failed | detail | Memory の結果コールバックが失敗したか、エグゼキューターに拒否された。メッセージは保持され、セッションは継続します |
memory_drain_failed / memory_drain_timeout | detail | 自動の後処理で Memory の待機が失敗またはタイムアウトした。メインの回答は保持され、リソースの解放は続行されます |
mirror_append_failed | sessionId、detail | 外部セッションストレージへのミラーリング書き込みが失敗した。あわせて MirrorErrorMessage が配信されます |
mirror_drain_timeout | sessionId、detail | クローズ時にミラーリング書き込みが制限時間内に完了しなかった |
process_tree_cleanup_degraded | capability、detail | 現在の環境では CLI のプロセスツリーを完全にはクリーンアップできない。初期化には影響せず、子プロセスが回収されたことも意味しません |
stdin_writer_stop_timeout | sessionId | クローズ時に書き込みスレッドが時間内に停止しなかった。書き込み中のメッセージが切り詰められる可能性があり、SDK は代わりに CLI プロセスを終了します |
cli_process_alive_after_close | detail | クローズ処理の完了後も CLI プロセスが動作している。detail に実行済みの終了手順が列挙されます |
lane_shutdown_timeout | detail | SDK 内部のスレッドがクローズの制限時間内に停止しなかった。割り込みを無視するコールバックは、クローズ後も動作し続ける可能性があります |
spool_cleanup_deferred | detail | クローズ時にメッセージバッファの一時ファイルがまだ使用中だった。読み書きが戻った後に削除されます |
private_directory_cleanup_failed | detail | 認証または MCP 設定用のプライベート一時ディレクトリのクリーンアップが完了しなかった。detail に credential files may remain が含まれる場合、認証情報ファイルがディスクに残っている可能性があります |
session_store_cleanup_failed | detail | 外部セッションの復元に使う一時ディレクトリのクリーンアップに失敗した |
managed_runtime_reused | detail | キャッシュ済みのマネージド CLI を使用した |
managed_runtime_install_started / managed_runtime_installed | detail | マネージド CLI のインストールを開始した/完了した |
managed_runtime_stale_install_removed | detail | 破損または不完全な古いインストールを削除した |
managed_runtime_unsupported_platform | detail | 現在のプラットフォームにはマネージド CLI がないため、インストール済みの CLI を探す |
type で分岐する場合はデフォルトの分岐を残してください。
Exceptions
SDK の例外はすべて非チェック例外の QoderException を継承します。同期メソッドは直接スローします。非同期メソッドは返された CompletionStage を失敗させます。join() で待機すると CompletionException にラップされるので、getCause() で元の例外を取り出します。Agent の業務上の失敗は例外をスローせず、outcome() が ERROR の ResultMessage でターンを終えます。
QoderException
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
getCode() | String | 安定した機械可読のエラーコード。例外一覧を参照 |
isRetryable() | boolean | リトライする価値があるかどうか |
printStackTrace() はマスク後のスナップショットを出力します。SDK は自動でリトライせず、現在の組み込み例外の isRetryable() はすべて false を返します。新しいセッションでリトライするかどうかは、アプリケーションがエラーコードで判断します。
UnsupportedCliCapabilityException
- 呼び出したメソッドが CLI の機能(capability)を必要とし、CLI がサポート外と宣言している(
UNSUPPORTED)か、一度も宣言していない(UNKNOWN)場合。SDK はローカルで直接失敗し、CLI にリクエストを送りません。必要な capability はcapability 要件を参照してください。 - 基本的な制御リクエストが実行時に CLI から拒否された場合。
SessionRepositoryのローカル操作に列挙可能なストアが必要で、現在のストアがそれをサポートしていない場合。
capabilityState() は失敗の原因となった CapabilityState を返します。
例外一覧
下表に挙げたアクセサーを除き、各例外クラスにはコンストラクターしかなく、エラーコードの定数は CODE です。
| クラス | エラーコード | スローされる場面 |
|---|---|---|
AuthenticationException | AUTHENTICATION_FAILED、CLI_AUTH_FATAL | 認証に失敗した。CLI が終了コード 41 で致命的な認証失敗を報告した場合、エラーコードは CLI_AUTH_FATAL(定数 CODE_CLI_AUTH_FATAL)になり、プロセスの失敗としてリトライすべきではありません |
CliNotFoundException | CLI_NOT_FOUND | CLI が見つからない。明示したパスが無効か、自動検索で実行ファイルが見つからなかった |
RuntimeInstallException | RUNTIME_INSTALL_FAILED | マネージド CLI のインストールに失敗した。ダウンロードが禁止されていてローカルのアーカイブもない、ネットワークの失敗やタイムアウト、サイズや SHA-256 の検証不一致などです。SDK はほかのバージョンに切り替えません。ManagedRuntimeOptions を参照 |
CliProcessException | CLI_PROCESS_FAILED | CLI プロセスが異常終了した(認証関連の終了コードを除く)。getExitCode() は終了コードを、getStderrTail() は上限付きでマスク済みの stderr の末尾を返し、取得できない場合は null です |
ProtocolException | PROTOCOL_ERROR | CLI の出力がプロトコルに違反した。下の 3 つのサブクラス以外の場合です |
FrameTooLargeException | FRAME_TOO_LARGE | 1 つのメッセージがサイズ上限を超えた |
MalformedUtf8Exception | MALFORMED_UTF8 | CLI の出力が正しい UTF-8 ではない |
ProtocolVersionMismatchException | PROTOCOL_VERSION_MISMATCH | CLI のプロトコルバージョンが SDK と互換性がない |
ControlRequestTimeoutException | CONTROL_REQUEST_TIMEOUT | 制御リクエストが controlRequestTimeoutMs(デフォルト 60000 ミリ秒)以内にレスポンスを受け取らなかった |
UnsupportedCliCapabilityException | UNSUPPORTED_CLI_CAPABILITY | 上記を参照 |
SessionClosedException | SESSION_CLOSED | クローズ済みのクライアント、セッション、クエリで操作を続けた。完全なクローズの途中で CLI が先に終了した場合も、コンシューマーはこの例外を受け取ります |
SessionStoreConflictException | SESSION_STORE_CONFLICT | セッションストアのバージョン競合(expectedVersion が古い)、または同じ UUID に異なる内容が対応している。currentVersion() はストアの現在のバージョンを返します |
SessionStoreDeletedException | SESSION_STORE_DELETED | SessionStoreDeletedException を参照 |
SpoolIoException | SPOOL_IO_ERROR | メッセージバッファのディスクファイルの読み書きに失敗した |
SpoolCapacityExceededException | SPOOL_CAPACITY_EXCEEDED | 未消費のメッセージがバッファの上限を超え、メッセージストリームが失敗した。メッセージストリームを速やかに消費すれば避けられます |
MessageStreamAlreadyConsumedException | MESSAGE_STREAM_ALREADY_CONSUMED | 同じ MessageStream を 2 回目に消費した。openCursor() と consume() は合わせて 1 回しか呼べません |
ConsumerInterruptedException | CONSUMER_INTERRUPTED | MessageCursor.hasNext() または next() でブロックしているスレッドが割り込まれた。スレッドの割り込みフラグは保持されます |
CallbackExecutionException | CALLBACK_EXECUTION_FAILED | アプリケーションのコールバック(権限、Hook、MCP、メッセージハンドラー)が例外をスローした |
CallbackRejectedException | CALLBACK_REJECTED | callbackExecutor がコールバックタスクの実行を拒否した。スレッドプールがシャットダウン済み、キューが満杯などの場合です |
IllegalBlockingCloseException | ILLEGAL_BLOCKING_CLOSE | リソース自身の SDK スレッドまたはプッシュハンドラー内で、ブロッキングの close() を呼んだ。スローする前に SDK は closeAsync() と同じようにクローズを開始しています。スレッドモデルとリソース解放を参照 |
InvalidOptionsException | INVALID_OPTIONS | 設定が無効。たとえば QoderClient.Builder に auth がない、SessionOptions に相互排他のオプションが同時に設定されているなど |
UnsupportedSecureSecretTransportException | UNSUPPORTED_SECURE_SECRET_TRANSPORT | 認証や MCP 設定用のプライベート一時ファイルを安全に作成・書き込みできない。java.io.tmpdir またはその上位ディレクトリで、ほかのアカウントがエントリを置き換えられる場合も含みます。SDK は起動を拒否し、平文の引数や環境変数による受け渡しには切り替えません |
QoderException として直接スローされます。
| エラーコード | スローされる場面 |
|---|---|
CLI_START_FAILED | CLI プロセスの起動に失敗した。権限不足、無効な作業ディレクトリ、長すぎる引数などです。Windows で CLI が .cmd/.bat で、起動引数に cmd.exe の特殊文字(Bash(git:*) のような括弧を含む)が含まれる場合も起動を拒否します。qoderCliPath を .exe に向けてください |
MODEL_RESOLUTION_TIMEOUT はアプリケーションにスローされません。動的なモデル選択コールバックがタイムアウトすると、SDK はこのエラーコードを CLI に返し、inbound_control_request_failed 診断イベントを発行します。ModelPolicyProvider を参照してください。
セッション終了エラーコード
次のエラーコードは QoderException.getCode() で公開され、メッセージストリームや関連する非同期メソッドの例外に現れることがあります。元の原因は getCause() で取得します。発生した後は元のセッションを使い続けられません。対処方法はエラー処理とエラーコードを参照してください。
| エラーコード | 意味 |
|---|---|
QUERY_WRITE_FAILED | 単発クエリの入力が CLI に書き込まれなかった |
CONTROL_WRITE_FAILED | 制御リクエストまたはレスポンスが CLI に書き込まれなかった |
TURN_ACCOUNTING_FAILED | セッションのターン状態をこれ以上処理できない |
MESSAGE_DELIVERY_FAILED | バッファ内のメッセージ 1 件をデコードできず、失われた。メッセージストリームはここで終了し、所属する Query または Session も同時にクローズされます |