Skip to main content
リファレンス

SDK リファレンス - Java

Java SDK の Maven 座標は 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 のメインエントリです。単発クエリ、複数ターンのセッション、事前起動を作成します。スレッドセーフで再利用できます。クローズすると、作成したすべてのクエリとセッションも連鎖的にクローズされます。
public final class QoderClient implements AutoCloseable {
    public static Builder builder();
    public QoderQuery query(OneShotQueryRequest request);
    public CompletionStage<QoderSession> openSession(SessionOptions options);
    public CompletionStage<PreparedQuery> prepare(SessionOptions options);
    public SessionRepository sessions();
    public SessionRepository sessions(SessionOptions options);
    public CompletionStage<Path> installRuntime();
    public CompletionStage<Integer> pruneRuntimes();
    public CompletionStage<Void> closeAsync();
    public void close();
}
メソッド戻り値の型説明
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() が返します。
public final class QoderQuery implements AutoCloseable {
    public MessageStream messages();
    public CompletionStage<InitializationResult> initialization();
    public CompletionStage<InterruptResult> interrupt();
    public CompletionStage<Void> flushMemory();
    public CompletionStage<Void> refreshMemory();
    public CompletionStage<Void> closeAsync();
    public void close();
}
メソッド戻り値の型説明
messages()MessageStreamメッセージストリームを取得します
initialization()CompletionStage<InitializationResult>初期化ハンドシェイクの結果
interrupt()CompletionStage<InterruptResult>実行中のターンを中断します
flushMemory()CompletionStage<Void>開始済みの Memory 処理の終了を待ちます。完了してもすべての書き込みが成功したとは限りません
refreshMemory()CompletionStage<Void>Memory の利用設定を再読み込みします
closeAsync() / close()CompletionStage<Void> / voidクエリをクローズしてリソースを解放します
CLI はこのターンの result の後に終了しますが、メッセージストリームは最後まで消費してから、ハンドルまたはカーソルをクローズしてください。Memory を有効にしている場合、ResultMessage の後に Memory メッセージが届くことがあります。ResultOutcome.ERROR はターンの失敗を表します。例外がスローされないことは成功を意味しません。

QoderSession

複数ターンのセッションです。QoderClient.openSession() または PreparedQuery.toSession() が返します。
public final class QoderSession implements AutoCloseable {
    public MessageStream messages();
    public CompletionStage<InitializationResult> initialization();
    public CompletionStage<MessageId> send(UserInput input);
    public MessageSubmission submit(UserInput input);
    public CompletionStage<Void> completeInput();
    public CompletionStage<Boolean> cancelQueuedMessage(MessageId id);
    public CompletionStage<InterruptResult> interrupt();
    public CompletionStage<Void> setPermissionMode(PermissionMode mode);
    public CompletionStage<PlanModeSnapshot> getPlanMode();
    public CompletionStage<PlanModeSnapshot> setPlanMode(boolean active);
    public CompletionStage<Void> setPermissionModePreservingPlan(PermissionMode mode);
    public CompletionStage<Void> setProxy(ProxySettings proxy);
    public CompletionStage<Void> addDirectories(List<Path> directories);
    public CompletionStage<Void> applyFlagSettings(FlagSettings settings);
    public CompletionStage<SessionTitle> generateSessionTitle();
    public CompletionStage<SessionTitle> generateSessionTitle(String description);
    public CompletionStage<Void> seedReadState(ReadStateSeed seed);
    public CompletionStage<List<String>> supportedCommands();
    public CompletionStage<List<CommandInfo>> commandCatalog();
    public CompletionStage<Optional<ModelCatalogSnapshot>> modelCatalogSnapshot();
    public CompletionStage<List<CommandInfo>> reloadSkills();
    public CompletionStage<List<ModelInfo>> getAvailableModels();
    public CompletionStage<List<ModelInfo>> getAvailableModels(ModelCatalogOptions options);
    public CompletionStage<Boolean> backgroundTasks();
    public CompletionStage<Boolean> backgroundTasks(String toolUseId);
    public CompletionStage<Void> stopTask(TaskId taskId);
    public CompletionStage<Void> reloadPlugins();
    public CompletionStage<List<McpServerStatus>> mcpServerStatus();
    public CompletionStage<McpAuthenticationResult> beginMcpAuthentication(String serverName);
    public CompletionStage<McpAuthenticationResult> beginMcpAuthentication(String serverName, McpAuthenticationOptions options);
    public CompletionStage<Void> mcpSubmitOAuthCallbackUrl(String serverName, String callbackUrl);
    public CompletionStage<Void> rewindHistory(MessageId toMessageId);
    public CompletionStage<RewindFilesResult> rewindFiles(MessageId messageId, RewindFilesOptions options);
    public CompletionStage<Void> flushMemory();
    public CompletionStage<Void> refreshMemory();
    public CompletionStage<Void> closeAsync();
    public void close();
}
メソッド戻り値の型説明
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セッションをクローズしてリソースを解放します
一部のメソッドは、CLI が対応する capability をサポートしている必要があります。サポートしていない場合は UnsupportedCliCapabilityException で失敗し、リクエストは送信されません。capability 要件を参照してください。セッションをクローズすると、まだ書き込まれていないキュー内の入力は SessionClosedException で終了します。受け付け済みの入力を確実に CLI へ書き込むには、先に completeInput() を待ってください。

ランタイムカタログ

メソッドデータの出所リクエストを送信するか
commandCatalog() / supportedCommands()初期化時のコマンドカタログ。CLI がコマンドの変更をプッシュすると全体が置き換わりますしない
modelCatalogSnapshot()初期化時または CLI のプッシュによる最新の完全なモデルカタログしない
getAvailableModels(...)今回の問い合わせ結果。上のスナップショットは更新しませんする
reloadSkills()再読み込み後の skills 一覧。コマンドカタログ全体は置き換えませんする
プッシュされたカタログは常に古い値を全体ごと置き換えます。空のリストは CLI がカタログを明示的に空にしたことを表します。modelCatalogSnapshot() が Optional.empty() を返す場合は、まだカタログを受け取っていません。現在のアカウントの最新モデル一覧が必要な場合は getAvailableModels(...) を呼び出してください。

CommandInfo

コマンドまたは skill のメタデータです。com.qoder.sdk.command にあります。
public final class CommandInfo {
    public static CommandInfo of(String name, JsonObject raw);
    public String name();
    public Optional<String> description();
    public Optional<String> argumentHint();
    public JsonObject raw();
}
name() は必ず値を持ちます。raw() は CLI が返したすべてのフィールドを保持し、SDK がモデル化していないフィールドも含みます。

PreparedQuery

起動、認証、初期化を済ませた CLI です。QoderClient.prepare() が返します。最初のリクエストの起動待ち時間をなくすために使います。使えるのは 1 回だけで、クエリへの変換、セッションへの変換、クローズのいずれかを行います。
public final class PreparedQuery implements AutoCloseable {
    public CompletionStage<InitializationResult> initialization();
    public QoderQuery toQuery(UserInput input);
    public QoderSession toSession();
    public CompletionStage<Void> closeAsync();
    public void close();
}
メソッド戻り値の型説明
initialization()CompletionStage<InitializationResult>初期化ハンドシェイクの結果
toQuery(UserInput)QoderQuery単発クエリに変換します
toSession()QoderSession複数ターンのセッションに変換します
closeAsync() / close()CompletionStage<Void> / void使わなかった事前起動を破棄します
変換済みまたはクローズ済みの状態で再度変換すると IllegalStateException がスローされます。変換後のリソース解放は新しい QoderQuery または QoderSession が担当し、PreparedQuery をクローズしても影響しません。toQuery() の入力が拒否された場合、返されたクエリのメッセージストリームはそのエラーで終了します。

MessageStream

クエリまたはセッションのメッセージストリームです。互いに排他的な 2 つの消費方法をサポートします。openCursor() でプルするか、consume() で SDK にプッシュさせます。
public final class MessageStream {
    public MessageCursor openCursor();
    public CompletionStage<Void> consume(MessageHandler handler, Executor executor);
}
メソッド戻り値の型説明
openCursor()MessageCursorプル用のカーソルを開き、メッセージを順番に 1 件ずつ読み取ります
consume(MessageHandler, Executor)CompletionStage<Void>指定したエグゼキューター上で、メッセージごとにハンドラーを順番に呼び出します。前のメッセージの処理が終わってから次を渡します
consume() が返す stage は、ストリームの終了時に正常完了します。以下の場合は例外完了し、所属するクエリまたはセッションをクローズします。
状況例外
ハンドラーが例外をスローしたCallbackExecutionException
エグゼキューターがタスクを拒否したCallbackRejectedException
消費スレッドが割り込まれたConsumerInterruptedException
メッセージの読み取りまたはデコードに失敗したストリームの失敗原因。SDK 以外の例外はエラーコード MESSAGE_DELIVERY_FAILED でラップされます
各ストリームを消費できるのは 1 回だけで、openCursor() と consume() のどちらかを選びます。2 回目の購読は MessageStreamAlreadyConsumedException をスローします。最初の購読は失敗しても消費済みとみなされます。CLI が出力を停止した後も、バッファ済みのメッセージは読み取れます。

MessageCursor

プル用のカーソルです。
public interface MessageCursor extends AutoCloseable {
    boolean hasNext();
    SdkMessage next();
    void close();
}
メソッド戻り値の型説明
hasNext()boolean次のメッセージまでブロックします。ストリームが終了すると false を返し、ストリームが失敗している場合は失敗原因をスローします
next()SdkMessage次のメッセージを返します。ストリームが終了している場合は NoSuchElementException をスローします
close()voidカーソルをクローズし、所属するクエリまたはセッションも非同期にクローズします
複数ターンのセッションでは、1 つのカーソルをターンをまたいで使い続けてください。各ターンで ResultMessage を読んだら次のターンを送信できます。ターンごとにクローズして開き直さないでください。あるメッセージの読み取りに失敗するとストリームはそこで終了し、以降の hasNext() / next() はすべて同じ例外をスローします。その場合はカーソルをクローズし、必要に応じて resume で新しいセッションを作成します。消費スレッドが割り込まれると ConsumerInterruptedException がスローされます。

MessageHandler

プッシュモードのメッセージハンドラーです。
@FunctionalInterface
public interface MessageHandler {
    void onMessage(SdkMessage message) throws Exception;
}
ハンドラーがスローした例外により、consume() が返す stage は CallbackExecutionException で完了します。直接実行するエグゼキューター(Runnable::run など)を使うと、ハンドラーは SDK の配信スレッド上で動作するため、すぐに戻る必要があります。

スレッドモデルとリソース解放

  1. 非同期メソッドは CompletionStage を返し、呼び出しごとに独立した観測結果が得られます。toCompletableFuture() をキャンセルしたり手動で完了したりしても、その待機に影響するだけで、SDK の操作は取り消されません。操作を止めるには interrupt()、cancelQueuedMessage()、closeAsync() を使います。
  2. openSession() と prepare() が返すハンドルは、渡された時点でアプリケーションの所有になります。get() を一度も呼ばなくても、クローズする責任があります。渡される前に観測側の future がキャンセルされていた場合、SDK は起動済みのリソースを自動的にクローズします。
  3. クエリ、セッション、事前起動はそれぞれ 1 つの CLI 子プロセスを使うため、アプリケーション側で同時実行数を制限してください。QoderClient 自体のコストは小さく再利用できます。クライアントをクローズすると、作成したすべてのリソースが連鎖的にクローズされます。
  4. 権限、MCP、モデルポリシー、認証トークン、Memory の各コールバックは callbackExecutor 上で動作し、Hook は SDK の専用スレッドを使います。callbackExecutor を設定しない場合、同じセッションのこれらのコールバックは 1 つの SDK スレッド上で直列に実行されます。1 つのコールバックがブロックすると他のコールバックが遅れ、タイムアウトの原因になります。コールバックはすぐに戻り、時間のかかる処理はアプリケーション自身のエグゼキューターに渡して、返す stage で完了を通知してください。
  5. SDK のコールバック、プッシュハンドラー、SDK スレッドの中でブロックして待たないでください。これらの場所から所属するセッションやクライアントをクローズするときは、closeAsync() を呼んでそのまま戻ります。SDK 所有のスレッドやプッシュハンドラーの中でブロッキングの close() を呼ぶと、非同期クローズを開始したうえで IllegalBlockingCloseException をスローします。SDK 所有のスレッドには、callbackExecutor を設定していない場合にコールバックを実行するスレッドと、Hook や診断リスナーを実行するスレッドが含まれます。セッションやクエリの close() は自身のスレッドだけを確認し、クライアントの close() は作成したすべてのセッションとクエリのスレッドを確認します。プッシュハンドラーはアプリケーションのエグゼキューター上で動いていてもスローします。カスタムの callbackExecutor を設定した場合、コールバックはアプリケーションのスレッドで実行され、そこで close() を呼んでもこの例外はスローされず、クローズが完了するまでブロックします。
  6. closeAsync() の完了は、SDK が入力の受け付けを停止し、キュー内の入力と制御リクエストの決着がつき、CLI プロセスがクローズ手順(stdin を閉じ、タイムアウト後に終了要求、強制終了の順)を終えたことを表します。実行中のアプリケーションのコールバックや continuation の終了は待たず、CLI の子孫プロセスの終了や一時ファイルの削除も保証しません。Memory を有効にしている場合、アイドル状態のセッションはクローズ前に Memory の後処理を完了し、最大 drainTimeoutMs(デフォルト 60 秒)待ちます。

Configuration

SessionOptions

クエリとセッションの不変オプションです。openSession()、prepare()、OneShotQueryRequest で使います。
public final class SessionOptions {
    public static Builder builder();
    public static SessionOptions defaults();   // builder().build() と同じ
    public Builder toBuilder();                // 現在の値を設定済みの新しい Builder
    // Builder の各設定項目には同名の getter があります(例:workingDirectory()、maxTurns())。
    // resume(String) に対応するのは resumeSessionId() です。未設定のオプション項目は Optional.empty() を返します。
}

SessionOptions.Builder

グループメソッドデフォルト説明
RuntimeworkingDirectory(Path)クライアントの projectDirectory、次にプロセスのカレントディレクトリCLI の作業ディレクトリ
RuntimeqoderCliPath(Path)マネージド CLICLI の実行ファイルを明示的に指定します。設定するとマネージド CLI はダウンロードされず、パスが無効な場合はすぐに失敗します
RuntimeputEnvironment(String, String)—CLI に渡す環境変数を 1 つ追加します。プロキシ URL の変数は自動的に機密情報として扱われます
RuntimeputProxyEnvironment(String, SecretValue)—プロキシ URL の変数を SecretValue で追加します。変数名は認識可能なプロキシ変数(HTTPS_PROXY など)である必要があり、そうでない場合は IllegalArgumentException をスローします
Runtimeenvironment(Map<String, String>)—環境変数をまとめて追加します。置き換えではなく追加です
PromptsystemPrompt(String)置き換えないシステムプロンプトを置き換えます
PromptappendSystemPrompt(String)追加しないシステムプロンプトの末尾に追加します
PromptcustomContext(Map<String, String>)未設定このセッションの入力のデフォルトのカスタムコンテキスト。UserInput を参照してください
PromptmaxTurns(int)制限なし最大ターン数。正の数である必要があります
PromptincludePartialMessages(boolean)false増分の PartialMessage を配信します。ストリーミング出力を参照してください
ModelmodelSelection(ModelSelection)CLI のデフォルトモデル固定モデル、動的コールバック、構造化ポリシーのいずれか。ModelSelection を参照してください
Toolstools(List<String>)CLI のデフォルト基本ツールの一覧。空のリストは未設定と同じです
ToolsallowedTools(List<String>)—事前に許可するツール
ToolsdisallowedTools(List<String>)—禁止するツール。allowedTools より優先されます
PermissionpermissionMode(PermissionMode)CLI が決定権限モード。PermissionMode を参照してください
PermissionplanMode(boolean)未設定独立 Plan の開始時の状態。permissionMode(PLAN) とは排他です。独立 Plan を参照してください
PermissionallowDangerouslySkipPermissions(boolean)falseBYPASS_PERMISSIONS の 2 つ目のスイッチ
PermissioncanUseTool(ToolPermissionHandler)なしツール権限のコールバック。ToolPermissionHandler を参照してください
MCPmcpServers(List<McpServerConfig>)—MCP サーバーの設定。名前の重複は不可です。McpServerConfig を参照してください
MCPallowedMcpServerNames(List<String>)—使用を許可する MCP サーバー名
MCPonElicitation(ElicitationHandler)なしMCP elicitation のコールバック。ElicitationHandler を参照してください
Hookshooks(List<HookRegistration>)—Hook の登録。HookRegistration を参照してください
HooksincludeHookEvents(boolean)falseHook の通知メッセージをメッセージストリームに配信します。Hook のコールバック自体には影響しません
Sessionresume(String)—セッション ID で再開します。ID に使えるのは ASCII の英字、数字、_、- だけです
SessioncontinueSession(boolean)false直近のセッションを継続します。一覧取得できる外部ストアを設定している場合は、ストア内のタイムスタンプで選びます
SessionforkSession(boolean)falseresume または continueSession と組み合わせて、新しいセッションとしてフォークします
SessionsessionStorage(SessionStorage)SessionStorage.inherit()クライアントの設定を継承するか、CLI のローカルストレージまたは外部ストアを使います。SessionStorage を参照してください
SessionsessionMirrorOptions(SessionMirrorOptions)defaults()外部ストアへのミラーリングのバッチと待機の上限。SessionMirrorOptions を参照してください
SessionfileCheckpointing(boolean)falseファイルチェックポイントを有効にします。Checkpoint を参照してください
Memorymemory(MemoryOptions)無効ネイティブまたはアプリケーション管理の Memory。Memory を参照してください
ControlcontrolRequestTimeoutMs(long)60000制御リクエストのタイムアウト(ミリ秒)。0 は無制限、負の値は無効です
ControlresolveModelTimeoutMs(long)500動的モデルコールバックのタイムアウト(ミリ秒)。0 は無制限、負の値は無効です
Controldebug(boolean)falseCLI のデバッグ出力を有効にします
ControldiagnosticsListener(DiagnosticsListener)—セッションレベルの診断リスナー
2 つのデフォルト値は定数としても提供されています: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 を含みます。
public final class OneShotQueryRequest {
    public static OneShotQueryRequest of(String prompt);
    public static Builder builder();
    public UserInput input();
    public SessionOptions options();

    public static final class Builder {
        public Builder prompt(String prompt);
        public Builder input(UserInput input);
        public Builder options(SessionOptions options);
        public OneShotQueryRequest build();
    }
}
of(prompt) は単一のテキスト入力とデフォルトのオプションを使います。Builder の prompt() と input() はどちらか一方しか設定できず、両方を設定すると InvalidOptionsException をスローします。どちらも設定しないと build() が同じ例外をスローします。options() を設定しない場合はデフォルトのオプションを使います。

UserInput

CLI に送る 1 件のユーザー入力です。コンテンツブロック、優先度、返信をトリガーするかどうか、さらに任意でカスタムコンテキストと skill の選択を含みます。不変です。
public final class UserInput {
    public static UserInput text(String text);
    public static Builder builder();
    public List<Content> content();
    public SendPriority priority();
    public boolean shouldQuery();
    public Optional<Map<String, String>> customContext();
    public Optional<Boolean> clientComposed();
    public List<SelectedSkill> selectedSkills();
}
メソッド戻り値の型説明
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.TextContentString text()
UserInput.ImageContentString mediaType()、String base64Data()
UserInput.UrlImageContentURI url()
UserInput.ToolResultContentString toolUseId()、String content()
customContext を設定しない場合は SessionOptions のデフォルト値を継承します。明示的に設定するとデフォルト値を完全に置き換え、マージはしません。明示的に設定した customContext(空の map を含む)と空でない selectedSkills は、CLI が対応する capability をサポートしている必要があります。capability 要件を参照してください。セッションで拒否された入力は send() の stage で通知されます。クエリと PreparedQuery.toQuery() で入力が拒否された場合、メッセージストリームはそのエラーで終了します。

SelectedSkill

この入力で明示的に選択した skill です。
public final class SelectedSkill {
    public static SelectedSkill of(String name);
    public static SelectedSkill of(String name, String arguments);
    public String name();
    public Optional<String> arguments();
}
名前は空や空白だけにはできません。arguments はそのまま CLI に渡されます。

ReadStateSeed

seedReadState() に渡し、ホストアプリケーションがユーザーに表示したファイルを CLI に伝えます。
public final class ReadStateSeed {
    public ReadStateSeed(List<String> readFiles);
    public static ReadStateSeed of(String path, long mtime);
    public List<String> readFiles();
}
リストを受け取るコンストラクターでは、シードを適用する時点でセッションの作業ディレクトリを基準に相対パスを解決し、ファイルの現在の mtime を読み取ります。of(path, mtime) はホストが既に観測した mtime(エポックミリ秒)を使います。実際に表示したファイルだけを設定してください。この呼び出しでファイルの内容が入力に加わることはありません。

SendPriority

ユーザー入力の優先度のヒントです。SDK は優先度で書き込み順を並べ替えません。スケジューリングは CLI が決定します。
public enum SendPriority { NOW, NEXT, LATER }
値説明
NOWできるだけ早く処理します(デフォルト)
NEXT現在処理中のメッセージの後に処理します
LATERキュー内のすべてのメッセージの後に処理します

FlagSettings

applyFlagSettings() に渡す機能フラグです。
public final class FlagSettings {
    public FlagSettings(Map<String, Boolean> flags);
    public Map<String, Boolean> flags();
}
flags はフラグ名からブール値へのマップで、必須です。flags() は不変のコピーを返します。

ProxySettings

setProxy() に渡すプロキシ設定です。
public final class ProxySettings {
    public static ProxySettings of(SecretValue proxyUrl);
    public static ProxySettings clear();
    public SecretValue proxyUrlSecret();
    @Deprecated public ProxySettings(String proxyUrl);
    @Deprecated public String proxyUrl();
}
ProxySettings.of(SecretValue.of(url)) でプロキシを設定し、clear() で解除します。プロキシ URL とその中のユーザー名・パスワードは機密情報として登録され、SDK は診断情報でマスク(redact)します。非推奨の String コンストラクターと proxyUrl() は平文を露出するため、ログには使わないでください。

ManagedRuntimeOptions

マネージド CLI の設定です。QoderClient.Builder.managedRuntime() で設定します。qoderCliPath を指定しない起動と installRuntime() に適用されます。
public final class ManagedRuntimeOptions {
    public static final long DEFAULT_IO_TIMEOUT_MS = 30_000L;
    public static final long DEFAULT_TOTAL_TIMEOUT_MS = 600_000L;

    public enum DownloadPolicy { ALLOW, DISALLOW }

    public static Builder builder();
    public static ManagedRuntimeOptions defaults();
    public Builder toBuilder();
    public Optional<Path> cacheDirectory();
    public DownloadPolicy downloadPolicy();
    public Optional<URI> baseUrl();
    public Optional<SecretValue> authorization();
    public Optional<Path> localArchive();
    public long connectTimeoutMs();
    public long readTimeoutMs();
    public long totalTimeoutMs();
}
Builder メソッドデフォルト説明
cacheDirectory(Path)~/.qoder/runtimes/managedキャッシュディレクトリ。ローカルディスク上に置いてください。null でデフォルトに戻します
downloadPolicy(DownloadPolicy)ALLOWDISALLOW の場合はネットワークに一切接続せず、キャッシュもローカルのアーカイブもないときは失敗します
baseUrl(URI)公式のダウンロード URLミラーの URL。ユーザー情報を含まない絶対 https URL である必要があります(ループバックアドレスは http も可)
authorization(SecretValue)—ミラーにアクセスするときの Authorization ヘッダー。設定したホストにだけ送られ、別のホストへのリダイレクトでは転送されません
localArchive(Path)—ローカルにある固定バージョンのアーカイブ。ダウンロードより優先して使われます
connectTimeoutMs(long) / readTimeoutMs(long)30000接続と 1 回の読み取りのタイムアウト(ミリ秒)。正の数である必要があります
totalTimeoutMs(long)600000ダウンロード全体のタイムアウト(ミリ秒)。正の数である必要があります
build()—タイムアウトが正でない場合、または baseUrl が不正な場合は InvalidOptionsException をスローします
CLI の検索順序。 起動時、以下の順序で CLI を決定し、見つかった時点で止まります。
  1. SessionOptions.Builder.qoderCliPath() で指定したパス。パスが無効な場合はすぐに失敗します。
  2. 環境変数 QODERCLI_PATH。
  3. マネージド CLI:キャッシュを再利用し、なければ localArchive、classpath リソース META-INF/qoder-sdk/runtime/<ファイル名>、ダウンロード URL の順にインストールします。現在のプラットフォームがマネージド対象外の場合はスキップします。インストールに失敗した場合はそのままエラーになり、別の CLI には切り替えません。
  4. ~/.qoder/runtimes/ 以下に旧バージョンの SDK が残した同じバージョンの CLI。
  5. ~/.local/bin/qodercli、次に PATH。
各 SDK バージョンが使うのは、固定された 1 つの CLI バージョンだけです。最新バージョンの確認も自動アップグレードも行いません。どこから取得したアーカイブも、組み込みのバイト数と SHA-256 に一致しなければインストールは失敗します。
事前準備とオフライン。
シナリオ方法
ローカル開発デフォルト設定のまま使います。初回起動時に自動でダウンロードされます
イメージのビルド時に事前準備するイメージのビルド段階で 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) を設定します
自前で管理する CLIqoderCliPath(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 です。コンストラクターは公開されておらず、インスタンスは静的ファクトリーからのみ取得できます。インスタンスは不変です。
public abstract class Auth {
    public static Auth qoderCli();
    public static Auth accessToken(SecretValue token);
    public static Auth accessTokenEnv();
    public static Auth accessTokenEnv(String environmentVariable);
    public static Auth serviceAccountKey(SecretValue key);
    public static Auth serviceAccountTokenProvider(ServiceAccountTokenProvider provider);
    public static Auth jobTokenProvider(JobTokenProvider provider);
}
ファクトリー認証情報の取得元主な用途
qoderCli()ローカルの CLI に保存済みのログイン状態を再利用開発者のローカル環境
accessToken(SecretValue)呼び出し側が渡す access tokenCI、スクリプト、ユーザーに代わって動くサービス
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マルチテナントのジョブランナー
起動時の認証設定は、現在のアカウントだけが読める一時ファイルを通じて CLI に渡されます。起動引数や環境変数には入りません。java.io.tmpdir とそのすべての親ディレクトリは、ほかのアカウントが中のエントリを置き換えられない状態である必要があります。そうでない場合、起動は UnsupportedSecureSecretTransportException で失敗します。必要に応じて起動引数 -Djava.io.tmpdir= で現在のアカウント専用のディレクトリを指定してください。CLI が認証失敗で終了すると AuthenticationException がスローされます。先に認証情報やアカウントの権限を修正してから Query または Session を作り直してください。同じ認証情報でそのまま再試行しても意味はありません。 各方式の詳しい使い方は SDK 認証を参照してください。

ServiceAccountTokenProvider

ホストが短期の Service Account token を更新するためのコールバックです。長期キーはホストが保管します。
public interface ServiceAccountTokenProvider {
    CompletionStage<SecretValue> fetchServiceAccountToken();
}
新しい token で完了する stage を返します。CLI は認証情報が必要になるたびに複数回呼び出すことがあります。token は SDK の制御チャネル経由で CLI に渡されます。ログには書き込まないでください。

JobTokenProvider

ジョブごとに token を提供するコールバックです。SDK はコールバックにジョブ ID を渡しません。アプリケーション側でクロージャーに自分のジョブ ID を束縛してください。
public interface JobTokenProvider {
    CompletionStage<SecretValue> fetchJobToken();
}
token で完了する stage を返します。null は返さないでください。CLI は必要に応じて複数回呼び出すことがあります。

SecretValue

SDK が管理するシークレット値です。toString() は常に [REDACTED] を返し、equals と hashCode の処理時間は長さだけに依存します。
public final class SecretValue {
    public static SecretValue of(char[] value);
    public static SecretValue of(String value);
    public char[] reveal();
    public int length();
}
メソッド戻り値の型説明
of(char[])SecretValue渡された配列をコピーしてから作成
of(String)SecretValue文字列から作成
reveal()char[]平文のコピーを返す。使用後は呼び出し側でゼロクリアする
length()intシークレットの長さ
SDK は、診断イベントと stderr に現れた登録済みの認証情報をマスク(redact)します。この仕組みは業務データやサードパーティの出力には及ばないため、記録範囲はアプリケーション自身のログポリシーで管理してください。

子プロセス環境

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 自身のルールで処理されます。
@FunctionalInterface
public interface ToolPermissionHandler {
    CompletionStage<PermissionResult> canUseTool(ToolPermissionRequest request,
                                                 CancellationToken cancellation)
            throws Exception;
}
パラメータ型説明
requestToolPermissionRequest判定待ちのツール呼び出し
cancellationCancellationTokenCLI がリクエストを破棄したとき、リクエストがタイムアウトしたとき、またはセッションが閉じられたときにキャンセルされる
PermissionResult で完了する stage を返します。null は返せません。コールバックは callbackExecutor 上で実行されます。スレッドモデルとリソース解放を参照してください。コールバックが例外をスローするか stage が例外で完了した場合、その権限リクエストだけが CALLBACK_EXECUTION_FAILED で失敗し、セッションには影響しません。controlRequestTimeoutMs を過ぎても完了しない場合は CONTROL_REQUEST_TIMEOUT で失敗し、同時にトークンがキャンセルされます。使い方は権限制御と承認とユーザー入力を参照してください。

ToolPermissionRequest

1 回分のツール権限リクエストです。
public final class ToolPermissionRequest {
    public String toolName();
    public JsonValue toolInput();
    public List<JsonValue> suggestions();
    public Optional<String> toolUseId();
    public Optional<String> agentId();
    public Optional<String> title();
    public Optional<String> displayName();
    public Optional<String> description();
    public Optional<String> blockedPath();
    public Optional<String> decisionReason();
    public Optional<String> decisionReasonType();
    public Optional<String> permissionKind();
    public Optional<Boolean> classifierApprovable();
    public List<PermissionOption> options();
    public Optional<PermissionDetails> details();
    public JsonObject raw();
}
メソッド戻り値の型説明
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(...) で使います。
public enum PermissionScope {
    ONCE, SESSION, PERSIST;
    public String wireValue();
    public String outcome();
}
定数意味outcome()
ONCEこの呼び出しだけを承認proceed_once
SESSIONこの CLI セッションの間は常に承認proceed_always
PERSIST承認の永続保存を CLI に依頼proceed_always_and_save
PERSIST の保存は CLI が担当します。SDK は独自の権限ストアを持たず、すべての権限の種類で使えることも保証しません。

PermissionResult

権限コールバックの判定です。許可(ツールの入力を書き換え可能)または拒否(理由付き)を表します。
public final class PermissionResult {
    public static PermissionResult allow();
    public static PermissionResult allow(JsonValue updatedInput);
    public static PermissionResult deny(String reason);
    public PermissionResult withScope(PermissionScope scope);
    public boolean isAllowed();
    public Optional<JsonValue> updatedInput();
    public Optional<String> denyReason();
    public Optional<PermissionScope> scope();
}
メソッド戻り値の型説明
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 で追加されたモードとの互換性を保つためです。
public final class PermissionMode {
    public static final PermissionMode DEFAULT;
    public static final PermissionMode ACCEPT_EDITS;
    public static final PermissionMode BYPASS_PERMISSIONS;
    public static final PermissionMode PLAN;
    public static final PermissionMode DONT_ASK;
    public static final PermissionMode AUTO;
    public static PermissionMode of(String value);
    public String value();
}
定数value()説明
DEFAULTdefaultCLI のルールに従って権限を求める
ACCEPT_EDITSacceptEditsファイル編集を自動的に受け入れる
BYPASS_PERMISSIONSbypassPermissionsすべての権限チェックをスキップ。allowDangerouslySkipPermissions(true) の設定も必須
PLANplan計画のみで実行しない。ほかのモードと併用する場合は独立 Planを使う
DONT_ASKdontAsk確認しない。確認が必要な操作はそのまま拒否する
AUTOauto自動で判定する
of(String) は既知のモードについて、大文字小文字と英数字以外の文字を無視します。"yolo" は BYPASS_PERMISSIONS と同じです。起動時は SessionOptions.Builder.permissionMode(...) で設定し、実行中は QoderSession.setPermissionMode(...) で切り替えます。どちらで BYPASS_PERMISSIONS を使う場合も、そのセッションで allowDangerouslySkipPermissions(true) を設定している必要があります。設定していない場合は InvalidOptionsException で失敗します。各モードの動作は権限制御を参照してください。

CancellationToken

コールバックが受け取るキャンセルトークンです。CLI がリクエストをキャンセルしたとき、コールバックがタイムアウトしたとき、またはセッションが閉じられたときにキャンセルされます。プロトコル上のキャンセル応答は SDK が送るため、アプリケーションは関連する処理を止めるだけで済みます。
public interface CancellationToken {
    boolean isCancelled();
    void onCancel(Runnable action);
    default CancellationRegistration registerOnCancel(Runnable action);
}

public interface CancellationRegistration extends AutoCloseable {
    @Override void close();
}
メソッド戻り値の型説明
isCancelled()booleanキャンセル済みかどうか。一度 true になると変わらない
onCancel(Runnable)voidキャンセル時の処理を登録する。トークンがすでにキャンセル済みでも呼び出される。処理は非同期に実行され、登録したスレッド上でインラインに実行されることはなく、callbackExecutor も使わない
registerOnCancel(Runnable)CancellationRegistration上と同じ。登録を解除できるハンドルを返す
CancellationRegistration.close()void処理の登録を解除する。冪等でブロックしない。すでに実行が始まった処理は中断されない
キャンセルは協調的です。トークンを無視するコードは実行を続けます。キャンセル時の処理は短くし、ブロックしないでください。処理がスローした例外は無視されます。onCancel の処理はベストエフォートで実行され、セッションが閉じられるとキュー内の処理は破棄されることがあります。確実に止める必要がある処理は、自身の副作用の境界で isCancelled() を確認してください。長く続く処理には registerOnCancel を使い、処理の終了時に close() を呼んで、登録した処理とそれが保持するオブジェクトを解放することを推奨します。

独立 Plan

Plan の状態は権限モードとは独立して設定できます。Plan をオンにしても現在の権限モードは保持されます。パッケージは com.qoder.sdk.plan です。
public final class PlanModeSnapshot {
    public boolean active();
}

// SessionOptions.Builder
public Builder planMode(boolean active);

// QoderSession
public CompletionStage<PlanModeSnapshot> setPlanMode(boolean active);
public CompletionStage<PlanModeSnapshot> getPlanMode();
public CompletionStage<Void> setPermissionModePreservingPlan(PermissionMode mode);
メソッド説明
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>) で登録します。
public final class HookRegistration {
    public static Builder builder();
    public String event();
    public Optional<String> matcher();
    public HookHandler handler();
    public long timeoutMs();
}
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 をスロー
イベント名と matcher のマッチングは CLI が行い、ハンドラーは Java プロセス内で実行されます。timeoutMs は Java 側の待ち時間だけを制限し、CLI には渡されません。メッセージストリームで Hook のライフサイクルイベントを確認したい場合は、includeHookEvents(true) も設定してください。対応するメッセージは HookEventMessage を参照してください。利用できるイベントと使い方は Hooksを参照してください。

HookHandler

Hook ハンドラーです。SDK 専用の Hook スレッド上で呼び出され、callbackExecutor は使いません。時間のかかる処理はアプリケーションのエグゼキューターに渡し、完了を表す stage を返してください。
@FunctionalInterface
public interface HookHandler {
    CompletionStage<JsonValue> onHookEvent(HookEvent event) throws Exception;
}
返した JSON はそのまま Hook の出力として CLI に渡されます。構造は CLI が定義します。Hooks の出力を参照してください。空のオブジェクトは介入しないことを意味します。PreToolUse で次の構造を返すと、そのツール呼び出しを拒否できます。
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "..."
  }
}
ハンドラーが例外をスローするか stage が例外で完了した場合、その Hook 呼び出しだけが CALLBACK_EXECUTION_FAILED で失敗します。タイムアウトした場合は CONTROL_REQUEST_TIMEOUT で失敗します。

HookEvent

1 回分の Hook イベントです。
public final class HookEvent {
    public String eventName();
    public Optional<String> matcher();
    public JsonValue payload();
}
メソッド戻り値の型説明
eventName()Stringイベント名。CLI の入力にある hook_event_name から取得
matcher()Optional<String>CLI が返した matcher。通常は空
payload()JsonValueCLI の 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 です。インスタンスは不変です。
public final class McpServerConfig {
    public static McpServerConfig stdio(String name, String command, List<String> args);
    public static McpServerConfig sse(String name, String url);
    public static McpServerConfig http(String name, String url);
    public static McpServerConfig inProcess(String name, InProcessMcpHandler handler);

    // 新しいインスタンスを返す
    public McpServerConfig withEnv(String envName, String value);
    public McpServerConfig withSecretEnv(String envName, SecretValue value);
    public McpServerConfig withHeader(String headerName, String value);
    public McpServerConfig withSecretHeader(String headerName, SecretValue value);

    public String name();
    public String type();
    public Optional<String> command();
    public List<String> args();
    public Map<String, String> env();
    public Map<String, SecretValue> secretEnv();
    public Optional<String> url();
    public Map<String, String> headers();
    public Map<String, SecretValue> secretHeaders();
    public Optional<InProcessMcpHandler> inProcessHandler();
    public boolean hasSecrets();
}
ファクトリーtype()説明
stdio(name, command, args)stdioCLI が起動する子プロセスのサーバー。args が null の場合は空のリストとして扱う
sse(name, url)sseSSE のリモートサーバー
http(name, url)httpStreamable HTTP のリモートサーバー
inProcess(name, handler)sdkJVM プロセス内のサーバー。メッセージは 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) で登録します。
@FunctionalInterface
public interface InProcessMcpHandler {
    CompletionStage<JsonValue> handle(JsonValue message) throws Exception;
    default CompletionStage<JsonValue> handle(JsonValue message,
                                              CancellationToken cancellation) throws Exception;
    default InProcessMcpHandler newConnection();
}
メソッド説明
handle(JsonValue)JSON-RPC メッセージを 1 件処理し、レスポンスで完了する stage を返す
handle(JsonValue, CancellationToken)SDK が実際に呼び出す入口。デフォルトでは引数 1 つの版に委譲する。キャンセルを検知したい場合はこちらをオーバーライドする。CancellationToken を参照
newConnection()セッションがこのサーバーを登録するたびに 1 回呼び出される。デフォルトは自身を返す。接続ごとの状態を持つハンドラーは別のインスタンスを返す必要があり、null は返せない
SDK は返された JSON をそのまま MCP のレスポンスとして CLI に転送します。レスポンスには 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() が返します。
public final class McpServerStatus {
    public String name();
    public String status();
    public JsonValue raw();
}
メソッド戻り値の型説明
name()Stringサーバー名
status()String状態を表す文字列。値は CLI の報告に従う
raw()JsonValue元の状態
CLI は raw() にサーバーの有効な設定(env や headers を含む)を含めて返すことがあります。withSecretEnv、withSecretHeader などで登録したシークレットは [REDACTED] に置き換えられ、名前と状態のテキストも同様に処理されます。

McpAuthenticationResult と McpAuthenticationOptions

MCP OAuth に使います。流れは次のとおりです。QoderSession.beginMcpAuthentication(serverName[, options]) で認証を開始します。結果がユーザーの操作を必要とする場合、ホストは authUrl() を表示し、完全なコールバック URL を受け取ったら mcpSubmitOAuthCallbackUrl(serverName, callbackUrl) を呼び出します。SDK はブラウザーを開きません。state の検証、認証情報の交換、再接続は CLI が行います。最初の業務入力を送る前に認証を済ませておくことを推奨します。
public final class McpAuthenticationResult {
    public boolean requiresUserAction();
    public Optional<String> authUrl();
}

public final class McpAuthenticationOptions {
    public static McpAuthenticationOptions defaults();
    public static McpAuthenticationOptions redirectUri(String redirectUri);
    public Optional<String> redirectUri();
}
メソッド説明
requiresUserAction()ホストがユーザーの認可を完了させる必要があるかどうか。false の場合は認証が完了している
authUrl()認可の入口。ユーザーの操作が必要な場合は必ず存在する
McpAuthenticationOptions.defaults()CLI のデフォルトのコールバックアドレスを使う
McpAuthenticationOptions.redirectUri(String)ホストがコールバックを受け取る URI を指定する。空白にはできない
認可 URL とコールバック URL には機密性の高い OAuth の state が含まれることがあります。ログには書き込まないでください。どちらのクラスの toString() にも URL は含まれません。全体の流れは MCP OAuth 認証を参照してください。

ElicitationHandler

MCP elicitation のコールバックです。MCP サーバーがユーザーから追加の情報を集める必要があるときに呼び出されます。SessionOptions.Builder.onElicitation(...) で登録します。
@FunctionalInterface
public interface ElicitationHandler {
    CompletionStage<ElicitationResult> onElicitation(ElicitationRequest request)
            throws Exception;
}
コールバックは callbackExecutor 上で実行され、controlRequestTimeoutMs の制限を受けます。例外をスローするか stage が例外で完了した場合、その elicitation だけが CALLBACK_EXECUTION_FAILED で失敗します。

ElicitationRequest

public final class ElicitationRequest {
    public String serverName();
    public String message();
    public JsonValue requestedSchema();
    public JsonValue raw();
}
メソッド戻り値の型説明
serverName()Stringリクエスト元の MCP サーバー名
message()Stringユーザーに表示するメッセージ
requestedSchema()JsonValue期待する回答の JSON Schema。リクエストに含まれない場合は空のオブジェクトで、null にはならない
raw()JsonValue元のリクエスト

ElicitationResult

elicitation の結果です。
public final class ElicitationResult {
    public static ElicitationResult accept(JsonValue content);
    public static ElicitationResult decline();
    public static ElicitationResult cancel();
    public String action();
    public Optional<JsonValue> content();
}
ファクトリーaction()説明
accept(JsonValue)acceptユーザーが受け入れた。schema に沿って入力された内容を含む。内容が null の場合は NullPointerException をスロー
decline()declineユーザーが回答を拒否した
cancel()cancelユーザーがこのリクエストをキャンセルした

Models

モデル関連の型は com.qoder.sdk.model パッケージにあります。選択方式とコールバックの使い方はモデル選択を参照してください。

ModelSelection

SessionOptions.Builder.modelSelection(...) に渡すモデル選択戦略です。3 つの戦略から 1 つだけを選びます。
public abstract class ModelSelection {
    public static StaticModelSelection staticModel(ModelId model);
    public static DynamicModelSelection dynamic(ModelPolicyProvider provider);
    public static DynamicModelSelection dynamic(ModelId initialModel, ModelPolicyProvider provider);
    public static PolicyModelSelection policy(ModelDecisionProvider provider);
    public static PolicyModelSelection policy(ModelId initialModel, ModelDecisionProvider provider);
}

public final class StaticModelSelection extends ModelSelection {
    public Optional<ModelId> model();
}

public final class DynamicModelSelection extends ModelSelection {
    public ModelPolicyProvider provider();
    public Optional<ModelId> initialModel();
}

public final class PolicyModelSelection extends ModelSelection {
    public ModelDecisionProvider provider();
    public Optional<ModelId> initialModel();
}
ファクトリメソッド戻り値の型説明
staticModel(ModelId)StaticModelSelectionセッション全体で固定のモデルを使用します
dynamic(ModelPolicyProvider)DynamicModelSelection初期モデルは CLI のデフォルトで選ばれ、以降はモデルリクエストごとにコールバックがモデル ID を返します
dynamic(ModelId, ModelPolicyProvider)DynamicModelSelection上と同じで、初期モデルを明示的に指定します
policy(ModelDecisionProvider)PolicyModelSelection初期モデルは CLI のデフォルトで選ばれます。コールバックは構造化された結果を返し、現在のモデルを維持するか、モデルとパラメータを上書きできます
policy(ModelId, ModelDecisionProvider)PolicyModelSelection上と同じで、初期モデルを明示的に指定します
初期化時、SDK は CLI にコールバックを宣言するだけで、呼び出しはしません。コールバックは CLI がモデルの決定を必要とするたびに実行されます。openSession() の完了前に実行されることを前提にしないでください。

ModelPolicyProvider

dynamic(...) が使うコールバックです。今回のリクエストで使うモデル ID を返します。
@FunctionalInterface
public interface ModelPolicyProvider {
    CompletionStage<ModelId> resolveModel(ModelRequestContext context) throws Exception;
}
パラメータ型説明
contextModelRequestContext今回のモデルリクエストのコンテキスト
タイムアウトは 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 と同じです。
@FunctionalInterface
public interface ModelDecisionProvider {
    CompletionStage<ModelPolicyResult> resolve(ModelRequestContext context) throws Exception;
}
null を返した場合、stage が null で完了した場合、例外を投げた場合、タイムアウトした場合は、今回のモデルリクエストが失敗します。CLI が現在選択しているモデルを維持するには、ModelPolicyResult.keepCurrent() を明示的に返す必要があります。

ModelPolicyResult

ModelDecisionProvider の不変の戻り値です。明示的に設定したフィールドだけが送信されます。モデルを設定しない場合は、CLI がすでに選択したモデルが維持されます。
public final class ModelPolicyResult {
    public static ModelPolicyResult keepCurrent();
    public static ModelPolicyResult select(ModelId model);
    public static Builder builder();
    public Optional<ModelId> model();
    public Optional<JsonObject> parameters();
    public Optional<String> taskId();
    public Optional<String> subTask();
}
Builder メソッド説明
model(ModelId)今回のリクエストのモデルを上書きします
parameters(JsonObject)CLI に渡すリクエストパラメータです。SDK はその意味を解釈しません
taskId(String)推論タスクの識別子
subTask(String)業務サブタスクの識別子
build()結果を作成します。何も設定しない場合は keepCurrent() と同じです
Builder メソッドは null を受け付けません。parameters は秘密情報を渡すための経路ではないため、認証情報を入れないでください。

ModelRequestContext

1 回のモデルリクエストのコンテキストで、SDK がモデルコールバックに渡します。
public final class ModelRequestContext {
    public Optional<String> sessionId();
    public Optional<String> purpose();
    public Optional<Integer> turnIndex();
    public Optional<String> agentId();
    public Optional<String> agentType();
    public Optional<ModelId> resolvedModel();
    public List<ModelInfo> availableModels();
}
メソッド戻り値の型説明
sessionId()Optional<String>所属するセッションの ID
purpose()Optional<String>CLI が今回モデルを呼び出す用途
turnIndex()Optional<Integer>ターンのインデックス
agentId() / agentType()Optional<String>リクエスト元のサブエージェントの ID と種類
resolvedModel()Optional<ModelId>コールバックの前に CLI が仮選択したモデル
availableModels()List<ModelInfo>今回のリクエストに付属するモデルカタログ(不変)。提供されない場合は空リスト
CLI が提供しないフィールドは Optional.empty() です。availableModels() は今回のリクエスト時点のスナップショットにすぎないため、セッション全体の固定カタログとしてキャッシュしないでください。

ModelInfo

モデルカタログの 1 件のエントリです。QoderSession.getAvailableModels() が返すほか、ModelRequestContext と ModelCatalogSnapshot にも含まれます。
public final class ModelInfo {
    public ModelId modelId();
    public Optional<String> displayName();
    public Optional<String> description();
    public Optional<String> source();
    public Optional<String> outerProvider();
    public Optional<String> descriptionEn();
    public boolean isEnabled();
    public JsonValue raw();
}
メソッド戻り値の型説明
modelId()ModelIdモデル選択に使えるモデル ID
displayName() / description()Optional<String>表示名と説明
source() / outerProvider() / descriptionEn()Optional<String>ソース、外部プロバイダー、英語の説明
isEnabled()boolean現在のアカウントで選択できるかどうか。CLI がこのフィールドを返さない場合は false として扱います
raw()JsonValue完全な元のエントリ。コンテキストウィンドウや価格など、モデル化されていないフィールドも含みます
カタログには isEnabled() が false のモデルが含まれることがあります。選択可能なモデルを表示するときは除外してください。

ModelCatalogOptions

QoderSession.getAvailableModels(ModelCatalogOptions) の読み取りオプションです。
public final class ModelCatalogOptions {
    public enum FetchStrategy { LIVE, CACHE }
    public static ModelCatalogOptions defaults();
    public static Builder builder();
    public Optional<FetchStrategy> fetchStrategy();
    public Optional<String> uid();
}
defaults() と引数なしの getAvailableModels() は、どちらも CLI のデフォルトのキャッシュ戦略を使います。Builder の fetchStrategy(FetchStrategy) でリアルタイム読み取り(LIVE)かキャッシュ(CACHE)を明示的に選び、uid(String) でカタログの uid を指定します。

ModelCatalogSnapshot

QoderSession.modelCatalogSnapshot() が返すローカルのモデルカタログのスナップショットです。初期化結果、または CLI がプッシュした最新のカタログ更新から取得します。
public final class ModelCatalogSnapshot {
    public List<ModelInfo> models();
    public Optional<ModelId> currentModel();
}
modelCatalogSnapshot() が Optional.empty() を返す場合は、まだカタログを受信していません。スナップショットが返り models() が空の場合は、CLI が空のカタログを明示的に返したことを意味します。スナップショットの読み取りは CLI にリクエストを送りません。現在のアカウントのリアルタイムの結果が必要な場合は getAvailableModels(...) を呼び出してください。

ModelId

モデル ID の値型です。
public final class ModelId {
    public static ModelId of(String value);
    public String value();
}

Memory

Memory の設定は SessionOptions.Builder.memory(MemoryOptions) で渡します。関連する型は com.qoder.sdk.memory パッケージにあります。メモリの生成、書き込み、読み込みは CLI が行い、セッション記録を保存する SessionStore とは独立した機能です。有効化の方法、アプリケーション管理のディレクトリ、ターンごとの生成制御はメモリを参照してください。

Memory 型一覧

型役割
MemoryOptionsクエリレベルの設定の入口です。disabled() がデフォルトで、nativeBuilder() は CLI ネイティブのメモリを使い、customBuilder() ではアプリケーションが生成と読み込みの設定を指定します。ユーザーレベル/プロジェクトレベルのスコープ、結果コールバック、drainTimeoutMs(デフォルト 60000 ミリ秒)を設定できます
MemoryGenerationOptionscustom モードの生成設定:有効/無効、メモリディレクトリ(roots)、生成プロンプト、ターン終了後の自動抽出
MemoryTurnCompleteOptionsターン終了後の自動抽出の設定:有効/無効、shouldGenerate 判定コールバック、タイムアウト(デフォルト 10000 ミリ秒)、判定失敗時のポリシー OnGateError(SKIP / REPORT_FAILED)
MemoryShouldGenerateターンごとの判定コールバックで、CompletionStage<MemoryGenerationGateResult> を返します
MemoryGenerationGateInput / MemoryGenerationGateResult判定コールバックの入力(セッション、ターン、prompt、回答など)と、run() / skip(reason) の判定結果
MemoryConsumptionOptionscustom モードの読み込み設定:有効/無効、ファイル一覧、maxTokens、上限超過時の処理 Overflow(TRUNCATE / FAIL_QUERY)、読み取り失敗時の処理 FailureMode(BEST_EFFORT / FAIL_QUERY)
MemoryRoot / MemoryConsumptionFilebuilder(String id, Path path) で作成するメモリディレクトリと読み込みファイルです。ディレクトリにはアクセス権(READ / READ_WRITE)とインデックスファイルを、読み込みファイルには必須指定を設定できます
MemoryGenerationHandler / MemoryConsumptionHandler生成結果と読み込み結果の通知コールバックで、CompletionStage<Void> を返します
EffectiveMemoryConfigCLI が初期化時に確認した実際の設定で、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 を使います。
セッションで Memory が有効になっていない場合、どちらのメソッドもリクエストを送らずに UnsupportedCliCapabilityException で失敗します。単発クエリで Memory を有効にした場合、ResultMessage の後もメッセージストリームにメモリ処理のメッセージが届くため、ストリームを最後まで消費してください。

Session Storage

外部セッションストレージ関連の型です。SessionStorage と SessionRepository は com.qoder.sdk パッケージに、それ以外は com.qoder.sdk.session パッケージにあります。使い方は外部セッションストレージとセッション制御を参照してください。

SessionStorage

1 回のセッションでどの履歴ストレージを使うかを指定します。SessionOptions.Builder.sessionStorage(...) で設定します。
public final class SessionStorage {
    public enum Mode { INHERIT, CLI_LOCAL, EXTERNAL }
    public static SessionStorage inherit();
    public static SessionStorage cliLocal();
    public static SessionStorage external(SessionStore store);
    public Mode mode();
    public Optional<SessionStore> externalStore();
}
ファクトリメソッド説明
inherit()デフォルト値です。QoderClient.Builder.sessionStore(...) で設定したクライアントのストアを使い、クライアントに設定がない場合は CLI のローカル履歴を使います
cliLocal()このセッションでは外部ストアを使わず、CLI のローカル履歴だけを使います
external(SessionStore)このセッションで指定した外部ストアを使います。引数に null は指定できません
最終的に有効になる外部ストアは、fileCheckpointing(true) と同時に使えません。

SessionStore

外部セッションストアが実装するインターフェースです。クライアントは QoderClient.Builder.sessionStore(...) でデフォルトのストアを設定し、このストアは client.sessions() でも使われます。
public interface SessionStore {
    CompletionStage<AppendResult> append(SessionKey key, AppendBatch batch);
    CompletionStage<Optional<SessionSnapshot>> load(SessionKey key);
}
メソッド戻り値の型説明
append(SessionKey, AppendBatch)CompletionStage<AppendResult>1 つのバッチをアトミックに追記します
load(SessionKey)CompletionStage<Optional<SessionSnapshot>>transcript の完全なスナップショットを読み込みます。キーが存在しないか削除済みの場合は空を返します
どちらのメソッドも同期的に完了してかまいませんが、失敗は直接投げずに、例外で完了した stage で報告する必要があります。呼び出しスレッドでブロッキング I/O を実行せず、非同期クライアントかアプリケーション独自のスレッドプールを使ってください。ストアは各 transcript JSON(未知のフィールドを含む)をそのまま保存し、別のエンベロープで包まないでください。

実装契約

契約要件
順序と分離load は追記順にエントリを返します。異なる SessionKey のデータは互いに見えません
アトミック性同じキーへの並行した追記は直列化する必要があります。バッチは全体が書き込まれるか、全体が失敗するかのどちらかです
冪等性同じキーですでに書き込まれた operationId を再度書き込んではいけません。元の操作の newVersion と appendedCount を返し、再生(リプレイ)としてマークします。このチェックは CAS より先に行います。削除済みのキーは常に SessionStoreDeletedException で拒否します
CASexpectedVersion が null でない場合は現在のバージョンと一致する必要があり、一致しない場合は現在のバージョンを含む SessionStoreConflictException を投げます。null の場合は無条件に追記します。空のキーの現在のバージョンは VersionToken.initial() です
UUID の整合性uuid と rawJson がどちらも同じエントリは重複して書き込みません。uuid が同じで rawJson が異なる場合は競合として報告する必要があります。uuid のないエントリは内容による重複排除を行いません
ミラーリングの書き込み失敗は MirrorErrorMessage と診断イベントで報告され、メインの回答は続行することがあります。回答が成功しても、記録が永続化されたとは限りません。

ListableSessionStore

列挙可能なストアです。SessionRepository の list()、最新のセッションの継続、サブエージェントの復元はこれに依存します。
public interface ListableSessionStore extends SessionStore {
    CompletionStage<List<SessionKey>> listSessions(String projectKey);
    CompletionStage<Void> deleteSession(SessionKey key);
}
listSessions はプロジェクト配下のすべてのキー(サブパスのキーを含む)を返し、順序は保証されません。deleteSession は指定した 1 つのキーだけを削除し、同じセッションの他のサブパスは削除しません。

SessionDeletionStore

セッション全体の削除をサポートするストアです。SessionRepository.delete(...) はストアがこのインターフェースを実装していることを要求します。
public interface SessionDeletionStore extends ListableSessionStore {
    CompletionStage<Void> deleteSessionTree(String projectKey, String sessionId);
}
実装は、追記と同じトランザクションまたはクリティカルセクション内でルート transcript とすべてのサブパスを削除し、そのセッションを削除済みとして永続的にマークする必要があります。以降そのセッションへの書き込みはすべて SessionStoreDeletedException で拒否され、古いバージョンからデータを再構築することもできません。存在しないセッションや削除済みのセッションの削除も成功させてください。削除済みのセッション ID は再利用できません。

InMemorySessionStore

SDK 組み込みのインメモリ実装で、SessionDeletionStore を実装しています。データはプロセスの終了とともに失われるため、テストや短時間で終わるプロセスに適しています。
public final class InMemorySessionStore implements SessionDeletionStore {
    public InMemorySessionStore();
}

SessionMirrorOptions

外部ストアへの書き込み(ミラーリング)のリソース上限で、SessionOptions.Builder.sessionMirrorOptions(...) で設定します。builder() で作成し、defaults() はデフォルト値を返します。すべての値は正の数である必要があります。
設定項目デフォルト値説明
maxPendingBatches256書き込み待ちバッチ数の上限
maxPendingBytes64 MiB書き込み待ちバッチの元の内容のバイト数上限
operationTimeoutMs60000各バッチについて、バージョンの読み取りから追記完了まで(リトライを含む)の合計時間
closeDrainTimeoutMs5000セッションを閉じるときに残りのバッチの書き込みを待つ時間
あるキーへの書き込みが失敗またはタイムアウトすると、そのキーへの書き込みは停止しますが、他のキーには影響しません。セッション全体の上限を超えると、セッション全体のミラーリングが停止します。これらのエラーは MirrorErrorMessage と診断イベントで報告され、モデルのターンは中断されません。

SessionRepository

保存済みのセッションの読み取り、継続、フォーク、削除を行います。client.sessions() でクライアントのデフォルトスコープのリポジトリを、client.sessions(SessionOptions) で特定のセッションが使うスコープのリポジトリを取得します。
public interface SessionRepository {
    CompletionStage<List<String>> list();
    CompletionStage<Optional<SessionSnapshot>> get(String sessionId);
    CompletionStage<Void> delete(String sessionId);
    CompletionStage<QoderSession> continueSession(String sessionId, SessionOptions options);
    CompletionStage<QoderSession> fork(String sessionId, SessionOptions options);
}
メソッド戻り値の型説明
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. リポジトリは 1 つのストアとプロジェクトキーに固定されます。ストアは sessionStorage から解決します。プロジェクトキーは workingDirectory から取り、未設定の場合はクライアントの projectDirectory を使い、どちらもない場合は default になります。
  2. sessions(options) はそのうちストアとディレクトリの 2 項目だけを採用します。プロセスは起動せず、CLI のパスや環境変数などその他の設定も保持しません。
  3. continueSession と fork の options でディレクトリやストアを指定しない場合は、リポジトリのスコープを引き継ぎます。明示的に上書きすると別のスコープのセッションを開けますが、現在のリポジトリの list、get、delete は変わりません。
必要なストアの機能がない場合、メソッドは UnsupportedCliCapabilityException で失敗し、キーごとの削除にフォールバックすることはありません。外部ストア上の fork には、CLI が対応する capability をサポートしていることも必要です。capability 要件を参照してください。

ストレージ値の型

SessionStore の実装で使う値型です。
public final class SessionKey {
    public static final String DEFAULT_PROJECT; // "default"
    public static SessionKey of(String projectKey, String sessionId);
    public static SessionKey of(String projectKey, String sessionId, String subpath);
    public static String projectKeyFor(Path workingDirectory);
    public String projectKey();
    public String sessionId();
    public String subpath();
}

public final class AppendBatch {
    public static Builder builder();
    public OperationId operationId();
    public VersionToken expectedVersion();
    public long firstSequence();
    public List<SessionStoreEntry> entries();
}

public final class AppendResult {
    public static AppendResult applied(VersionToken newVersion, int appendedCount);
    public static AppendResult replayed(VersionToken newVersion, int appendedCount);
    public VersionToken newVersion();
    public int appendedCount();
    public boolean alreadyApplied();
}

public final class SessionSnapshot {
    public static SessionSnapshot of(List<SessionStoreEntry> entries, VersionToken version);
    public List<SessionStoreEntry> entries();
    public VersionToken version();
}

public final class SessionStoreEntry {
    public static SessionStoreEntry of(String rawJson);
    public String rawJson();
    public Optional<String> type();
    public Optional<String> uuid();
    public Optional<String> timestamp();
}

public final class OperationId {
    public static OperationId of(String value);
    public static OperationId random();
    public String value();
}

public final class VersionToken {
    public static VersionToken of(String value);
    public static VersionToken initial();
    public String value();
}

public class SessionStoreDeletedException extends QoderException {
    public static final String CODE = "SESSION_STORE_DELETED";
    public SessionStoreDeletedException(String message);
    public SessionStoreDeletedException(String message, Throwable cause);
}
型メンバー説明
SessionKeyprojectKey / sessionId / subpathストアのキーです。セッションルートの subpath は空文字列で、サブエージェントの transcript は空でないサブパスを使います。projectKeyFor(Path) はプロジェクトディレクトリからプロジェクトキーを生成します
AppendBatchoperationId冪等 ID。同じ ID でリトライしても一度だけ適用されます
expectedVersionCAS の期待バージョン。null は無条件の追記を意味します
firstSequenceバッチ先頭エントリの順序の参考値で、CAS のバージョンや冪等 ID の代わりにはなりません
entriesバッチのエントリ。Builder は operationId、expectedVersion、firstSequence、addEntry、addEntries を提供します
AppendResultapplied(...) / replayed(...)実際に書き込んだ結果、または冪等な再生の結果です。再生の場合は元の操作のバージョンと件数を渡します
alreadyApplied()再生かどうか
SessionSnapshotentries / version追記順に並んだエントリと現在のバージョン
SessionStoreEntryrawJson()元の JSON 行です。type、uuid、timestamp はここから抽出されます。toString() は本文を出力しません
OperationIdof / random冪等な操作 ID
VersionTokeninitial()空のストアの開始バージョンです。書き込みが成功するたびにバージョンを進める必要があります
SessionStoreDeletedExceptionCODE削除済みのセッションへの書き込みを拒否します。エラーコードは SESSION_STORE_DELETED で、リトライできません。CAS の競合ではないため、現在のバージョンでリトライしないでください

Results and Identifiers

InitializationResult

初期化ハンドシェイクの結果で、QoderQuery.initialization()、QoderSession.initialization() などのメソッドが返します。ハンドシェイク完了時点の読み取り専用スナップショットで、以降は変化しません。
public final class InitializationResult {
    public Map<String, CapabilityState> capabilities();
    public CapabilityState capability(String capability);
    public Optional<String> cliVersion();
    public Optional<String> wireVersion();
    public Optional<String> sessionId();
    public Optional<EffectiveMemoryConfig> memory();
}
メソッド戻り値の型説明
capabilities()Map<String, CapabilityState>CLI がハンドシェイク時に宣言した capability(不変)
capability(String)CapabilityState1 つの capability の状態。宣言されていない場合は UNKNOWN を返します
cliVersion()Optional<String>CLI のバージョン
wireVersion()Optional<String>ネゴシエートされた通信プロトコルのバージョン
sessionId()Optional<String>CLI が割り当てたセッション ID
memory()Optional<EffectiveMemoryConfig>CLI が確認した Memory の設定。有効でない場合は空です
実行中に CLI が capability で制御されるリクエストを「サポートしていない」として拒否すると、SDK はその capability を 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 つの状態です。
public enum CapabilityState { SUPPORTED, UNSUPPORTED, UNKNOWN }
値説明
SUPPORTEDCLI がサポートを宣言しています
UNSUPPORTEDCLI が非サポートを明示的に宣言したか、実行中にこの capability のリクエストを拒否しました
UNKNOWNCLI が宣言していません。この capability に依存するメソッドは直接失敗し、SDK は試行しません

InterruptResult

interrupt() の結果です。
public final class InterruptResult {
    public boolean interrupted();
    public String turnState();
}
メソッド戻り値の型説明
interrupted()boolean実行中のターンに中断を送ったかどうか。実行中のターンがない場合は false です
turnState()String戻った時点のターンの状態:IDLE、RUNNING、INTERRUPTING のいずれか
成功は CLI が中断リクエストを受け付けたことだけを意味し、ターンがいつ終わるかは ResultMessage で判断します。中断リクエストが失敗した場合(タイムアウトを含む)、ターンは RUNNING に戻り、リトライできます。

MessageSubmission

QoderSession.submit(UserInput) が返す送信ハンドルです。
public final class MessageSubmission {
    public MessageId id();
    public CompletionStage<MessageId> written();
}
メソッド戻り値の型説明
id()MessageIdすぐに使える入力 ID で、cancelQueuedMessage に渡せます。入力が受け付けられた、または書き出されたことは意味しません
written()CompletionStage<MessageId>入力が CLI に書き込まれた後に完了し、回答は待ちません。入力が拒否された場合や書き込みに失敗した場合は例外で完了し、ローカルのキャンセルに成功した場合は CancellationException で完了します
MessageSubmission submission = session.submit(UserInput.text("処理待ちの入力"));
CompletionStage<Boolean> cancelled = session.cancelQueuedMessage(submission.id());
書き込みの確認だけが必要な場合は send(input) を、書き込み前にキャンセルする可能性がある場合は submit(input) を使います。written() は呼び出すたびに独立した stage を返し、それをキャンセルしても入力自体はキャンセルされません。

識別子の型

public final class MessageId {
    public static MessageId of(String value);
    public String value();
}

public final class TaskId {
    public static TaskId of(String value);
    public String value();
}

public final class SessionTitle {
    public SessionTitle(String title);
    public String title();
}
型説明
MessageIdユーザー入力の ID で、MessageSubmission.id() または send(...) の戻り値から取得します。cancelQueuedMessage、rewindHistory、rewindFiles で使います
TaskIdバックグラウンドタスクの ID で、stopTask(TaskId) に渡します
SessionTitlegenerateSessionTitle() が返すセッションタイトル

RewindFilesOptions / RewindFilesResult

QoderSession.rewindFiles(MessageId, RewindFilesOptions) のオプションと結果です。セッションは SessionOptions.Builder.fileCheckpointing(true) で起動しておく必要があります。ファイル Checkpoint と Rewindを参照してください。
public final class RewindFilesOptions {
    public static RewindFilesOptions defaults();
    public static RewindFilesOptions dryRun();
    public boolean isDryRun();
}

public final class RewindFilesResult {
    public boolean canRewind();
    public List<String> filesChanged();
    public Optional<String> error();
}
メソッド戻り値の型説明
RewindFilesOptions.defaults()RewindFilesOptions実際にファイルを巻き戻します
RewindFilesOptions.dryRun()RewindFilesOptionsどのファイルが変わるかだけを報告し、ディスクには書き込みません
canRewind()boolean巻き戻せるかどうか(試行時)、または巻き戻したかどうか
filesChanged()List<String>影響を受けるファイル
error()Optional<String>巻き戻せない理由

Message Types

SdkMessage

メッセージストリーム内のすべてのメッセージの抽象基底クラスで、com.qoder.sdk.message にあります。具体的な型は instanceof で判定します。
public abstract class SdkMessage {
    public final String wireType();
    public final Optional<String> uuid();
    public final Optional<String> sessionId();
    public final Optional<String> rawJson();
}
メソッド戻り値の型説明
wireType()Stringメッセージのトップレベルの type
uuid()Optional<String>メッセージ UUID。CLI が提供した場合に値があります
sessionId()Optional<String>所属するセッションの ID。CLI が提供した場合に値があります
rawJson()Optional<String>メッセージの元の JSON。SDK がモデル化していないフィールドは、JsonValue.parse で解析してから読み取ります
具体的な型:
クラスwireType()説明
AssistantMessageassistantアシスタントの応答
ResultMessageresultターン終了時の結果
UserReplayMessageuserCLI がリプレイしたユーザーメッセージ
PartialMessagepartialストリーミングの増分イベント
SystemMessage とサブクラスsystemシステムメッセージ。subtype() ごとに専用クラスに分かれ、Hook 通知や Memory の結果を含みます
HookEventMessagehook_event旧形式の Hook イベント
MirrorErrorMessagemirror_errorセッションのミラーリング書き込みの失敗
UnknownMessage元の値未知のトップレベル型
専用の system メッセージはすべて SystemMessage を継承しています。分岐では専用サブクラスを先に判定し、SystemMessage はその後に判定してください。そうしないと、広い分岐が専用の型を覆い隠します。

AssistantMessage とコンテンツブロック

アシスタントが応答を 1 つ生成したときに配信されます。コンテンツブロックは出力側の型で、入力側の UserInput のコンテンツブロックとは別のものです。
public final class AssistantMessage extends SdkMessage {
    public List<ContentBlock> content();
    public String getText();
}

public abstract class ContentBlock {
    public abstract String type();
}

public final class TextBlock extends ContentBlock {
    public static final String TYPE = "text";
    public String text();
}

public final class UnknownContentBlock extends ContentBlock {
    public String rawJson();
}
メソッド戻り値の型説明
AssistantMessage.content()List<ContentBlock>コンテンツブロックのリスト
AssistantMessage.getText()Stringすべての TextBlock のテキストを連結したもの
ContentBlock.type()Stringコンテンツブロックの type(例:text)
TextBlock.text()Stringテキストの内容
UnknownContentBlock.rawJson()Stringこのコンテンツブロックの元の JSON
Java SDK がモデル化するのは text ブロック(TextBlock)だけです。tool_use、thinking などのほかのブロックは UnknownContentBlock として保持されます。type() は元の型を返すので、必要に応じて rawJson() を解析してください。TypeScript と Python の SDK には、これらのブロック用の型付きクラスがあります。

ResultMessage と使用量

1 ターンの対話が終わったときに配信されます。Agent の業務上の失敗(ターン数の上限到達など)は、outcome() が ERROR の ResultMessage で報告され、例外はスローされません。
public final class ResultMessage extends SdkMessage implements TurnTerminalMessage {
    public static final String SUBTYPE_SUCCESS = "success";
    public String wireSubtype();
    public Optional<Boolean> wireIsError();
    public ResultOutcome outcome();
    public Optional<String> result();
    public List<String> errors();
    public Usage usage();
    public boolean terminatesTurn();   // 常に true
}

public enum ResultOutcome { SUCCESS, ERROR, UNKNOWN }

public final class Usage {
    public static Usage empty();
    public long inputTokens();
    public long outputTokens();
}

public interface TurnTerminalMessage {
    boolean terminatesTurn();
}
メソッド戻り値の型説明
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()クラス主なアクセサー説明
その他または未知の値SystemMessagesubtype()完全なペイロードは rawJson() にあります
plan_mode_changedPlanModeChangedMessageplanMode() → PlanModeSnapshot独立 Plan の状態変化。権限を参照
commands_changedCommandsChangedMessagecommands() → List<CommandInfo>今回の完全なコマンドカタログ。空のリストはクリアを表します
available_models_updateAvailableModelsUpdateMessagecatalog() → ModelCatalogSnapshot今回の完全なモデル一覧と現在のモデル
agents_md_size_warningAgentsMdSizeWarningMessagetotalBytes()、files() などAGENTS ファイルのサイズ警告
permission_deniedPermissionDeniedMessageなし。rawJson() を読み取りますツールの権限が 1 回拒否された
background_tasks_changedBackgroundTasksChangedMessageなし。rawJson() を読み取りますバックグラウンドタスクの集合が変化した
task_updatedTaskUpdatedMessageなし。rawJson() を読み取りますあるタスクの状態が更新された
hook_started / hook_progress / hook_responseHookStartedMessage などHook 通知メッセージを参照Hook の実行通知
memory_generation / memory_consumptionMemoryGenerationMessage / MemoryConsumptionMessageresult()メモリの生成・読み込みの結果
public class SystemMessage extends SdkMessage {
    public final Optional<String> subtype();
}

public final class AgentsMdSizeWarningMessage extends SystemMessage {
    public static final String SUBTYPE = "agents_md_size_warning";
    public long totalBytes();
    public long thresholdBytes();
    public Optional<String> thresholdSource();
    public Optional<String> loadStatus();
    public Optional<String> severity();
    public Optional<String> code();
    public boolean truncated();
    public List<FileSize> files();

    public static final class FileSize {
        public String path();
        public long bytes();
    }
}

// その他のサブクラスのアクセサーは上の表を参照。Hook 通知と Memory 結果は後続の節を参照
AgentsMdSizeWarningMessage のサイズはすべて CLI が報告する UTF-8 のバイト数で、SDK は再計算しません。truncated() は CLI が報告した読み込み状態を表し、SDK が切り詰めたことを意味するものではありません。 PermissionDeniedMessage、BackgroundTasksChangedMessage、TaskUpdatedMessage の WIRE_TYPE 定数は非推奨です。型または subtype() で判定してください。 コマンドまたはモデルのカタログ更新が無効な場合、SDK は対応する専用メッセージを作らず、直前のカタログのスナップショットを保持します。元のメッセージは汎用の SystemMessage として配信され、同時に invalid_catalog_update 診断が発行されます。

PartialMessage と UserReplayMessage

public final class PartialMessage extends SdkMessage {}

public final class UserReplayMessage extends SdkMessage {
    public List<ContentBlock> content();
}
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 を使います。
public final class HookStartedMessage extends SystemMessage {   // subtype=hook_started
    public static final String SUBTYPE = "hook_started";
    public Optional<String> hookId();
    public Optional<String> hookName();
    public Optional<String> hookEvent();
    public Optional<String> stdout();
    public Optional<String> stderr();
    public Optional<String> output();
    public Optional<String> outcome();
    public Optional<Integer> exitCode();
}
// HookProgressMessage(hook_progress)と HookResponseMessage(hook_response)のアクセサーも同じ

public final class HookEventMessage extends SdkMessage {        // type=hook_event
    public String eventName();
}
各アクセサーは同名の snake_case フィールド(hook_id、exit_code など)に対応します。outcome() は未知の値もそのまま保持します。フィールドが欠けているか型が合わない場合は空を返します。exitCode() は値が int の範囲の整数でない場合に空を返し、切り詰めは行いません。元の値は引き続き rawJson() から読み取れます。 HookEventMessage は旧形式の type=hook_event メッセージに対応します。SDK は上の 3 種類の system 通知をこの型に変換しません。

MemoryGenerationMessage と MemoryConsumptionMessage

メモリの生成と読み込みの結果です。どちらも対話のターンを終了させません。結果の型は com.qoder.sdk.memory にあります。使い方はメモリを参照してください。
public final class MemoryGenerationMessage extends SystemMessage {     // subtype=memory_generation
    public MemoryGenerationResult result();
}

public final class MemoryConsumptionMessage extends SystemMessage {    // subtype=memory_consumption
    public MemoryConsumptionResult result();
}
MemoryGenerationResult には生成状態、書き込んだファイルと失敗したファイル、所要時間、任意の独立した使用量が含まれます。flush が成功してもすべてのファイルが保存されたとは限らないため、status() と failedFiles() を確認してください。MemoryConsumptionResult には全体の状態とファイルごとの読み込み状態が含まれます。未知の状態は UNKNOWN にマップされ、元の値は wireStatus() に残ります。結果コールバックを登録しても、この 2 種類のメッセージはメッセージストリームから取り除かれません。

MirrorErrorMessage と UnknownMessage

public final class MirrorErrorMessage extends SdkMessage {}   // type=mirror_error

public final class UnknownMessage extends SdkMessage {
    public Optional<String> wireSubtype();
}
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(...) で解析します。
public abstract class JsonValue {
    public static JsonValue parse(String json);
    public final String toJson();

    public boolean isNull();
    public boolean isBoolean();
    public boolean isNumber();
    public boolean isString();
    public boolean isArray();
    public boolean isObject();

    public boolean asBoolean();
    public BigDecimal asNumber();
    public String asString();
    public JsonArray asArray();
    public JsonObject asObject();
}

public final class JsonNull extends JsonValue {
    public static final JsonNull INSTANCE;
}

public final class JsonBoolean extends JsonValue {
    public static final JsonBoolean TRUE;
    public static final JsonBoolean FALSE;
    public static JsonBoolean of(boolean value);
    public boolean value();
}

public final class JsonNumber extends JsonValue {
    public static JsonNumber of(BigDecimal value);
    public static JsonNumber of(long value);
    public static JsonNumber of(double value);
    public BigDecimal value();
}

public final class JsonString extends JsonValue {
    public static JsonString of(String value);
    public String value();
}

public final class JsonArray extends JsonValue {
    public static JsonArray empty();
    public static JsonArray of(List<? extends JsonValue> values);
    public static JsonArray of(JsonValue... values);
    public List<JsonValue> values();
    public int size();
    public JsonValue get(int index);
}

public final class JsonObject extends JsonValue {
    public static JsonObject empty();
    public static JsonObject of(Map<String, ? extends JsonValue> members);
    public static Builder builder();
    public Map<String, JsonValue> members();
    public JsonValue get(String name);
    public boolean contains(String name);
    public Set<String> names();
    public int size();

    public static final class Builder {
        public Builder put(String name, JsonValue value);
        public JsonObject build();
    }
}
メソッド戻り値の型説明
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 をスローします。
JsonObject payload = JsonObject.builder()
        .put("path", JsonString.of("src/Parser.java"))
        .put("dryRun", JsonBoolean.TRUE)
        .build();

Diagnostics

DiagnosticsListener

SDK の構造化された診断イベントを受け取ります。セッションの初期化、クローズのタイムアウト、capability のダウングレード、マネージド CLI のインストールなどです。
public interface DiagnosticsListener {
    void onDiagnostic(DiagnosticEvent event);
}
  • 2 つの登録レベル。 クライアントレベルは QoderClient.Builder.diagnosticsListener(...)、セッションレベルは SessionOptions.Builder.diagnosticsListener(...) で登録します。両者は重ねて使われません。セッションにリスナーが設定されていればセッションレベルだけを使い、なければクライアントレベルにフォールバックします。マネージド CLI の managed_runtime_* イベントはクライアントレベルのリスナーにだけ送られます。
  • スレッド。 各セッションは SDK 独自の診断スレッドでリスナーを逐次呼び出し、callbackExecutor は使いません。同じリスナーを複数のセッションに登録すると並行して呼ばれる可能性があるため、スレッドセーフにしてください。
  • ベストエフォートの配信。 キューに溜まったイベントが上限を超えると、新しいイベントは破棄されます。リスナーが例外をスローしても失われるのはその 1 回の通知だけです。クローズ時は排出に限られた時間しか与えられず、タイムアウトするとリスナーを中断して残りのイベントを破棄します。診断はロスのない監査ログとしても、業務状態の唯一の根拠としても使えません。
  • すぐに戻ること。 時間のかかる処理はアプリケーション自身の非同期の仕組みに渡してください。リスナーは SDK のスレッドで実行されます。イベントを発行したセッションやそのクライアントを閉じる必要がある場合は、closeAsync() を呼んですぐに戻ります。リスナー内でそれらのブロッキングの close() を呼ぶと IllegalBlockingCloseException がスローされます。
QoderClient client = QoderClient.builder()
        .auth(Auth.accessTokenEnv())
        .diagnosticsListener(event -> System.err.println(
                "[qoder-diag] type=" + event.type()
                + " requestType=" + event.requestType().orElse("-")
                + " exitCode=" + event.exitCode().map(String::valueOf).orElse("-")))
        .build();

DiagnosticEvent

イミュータブルな診断イベントです。SDK が生成した detail はマスク済みです。登録済みの認証情報を取り除き、認証情報らしきテキストもできる範囲で検出しますが、任意の業務データまで対象になる保証はありません。
public final class DiagnosticEvent {
    public static Builder builder(String type);
    public String type();
    public Optional<String> sessionId();
    public Optional<String> requestType();
    public Optional<Long> durationMs();
    public Optional<Integer> queueDepth();
    public Optional<Integer> exitCode();
    public Optional<String> capability();
    public Optional<String> detail();
    // Builder は下表の各オプションフィールドと同名の setter を持つ。最後に build() を呼ぶ
}
フィールド型説明
typeStringイベントタイプ。必須です。よく使われる値は下表を参照
sessionIdOptional<String>所属するセッションの ID
requestTypeOptional<String>関連する制御リクエストの種類
durationMsOptional<Long>処理の所要時間(ミリ秒)
queueDepthOptional<Integer>キューの深さのスナップショット
exitCodeOptional<Integer>CLI の終了コード
capabilityOptional<String>関連する capability 名
detailOptional<String>自由形式の詳細
アプリケーションが builder(type) で独自にイベントを作った場合、SDK は detail をマスクしません。

よく使われるイベントタイプ

type主なフィールド意味
session_initializedsessionId、detail初期化ハンドシェイクが完了した。detail にプロトコルバージョンが含まれます
protocol_handshake_warningdetailハンドシェイク時のプロトコルネゴシエーションによる警告
session_failedsessionId、exitCode、detailセッションがエラーで終了した
control_request_completedrequestType、durationMs制御リクエストが成功レスポンスを受け取った
inbound_control_request_failedsessionId、detailCLI が発行したコールバックリクエスト(権限、Hook、MCP、モデルポリシー、認証トークンなど)が失敗またはタイムアウトし、SDK が CLI にエラーを返した。detail に request_id と error=<エラーコード>(例:MODEL_RESOLUTION_TIMEOUT)が含まれます
capability_downgradedcapability、requestTypecapability チェックを通過した制御リクエストが、実行時に CLI からサポート外と判定された。以降はダウングレード後の状態でチェックされます。すでに返された InitializationResult は変わりません
invalid_catalog_updatesessionIdコマンドまたはモデルのカタログ更新が無効だった。直前のスナップショットが保持されます
memory_callback_faileddetailMemory の結果コールバックが失敗したか、エグゼキューターに拒否された。メッセージは保持され、セッションは継続します
memory_drain_failed / memory_drain_timeoutdetail自動の後処理で Memory の待機が失敗またはタイムアウトした。メインの回答は保持され、リソースの解放は続行されます
mirror_append_failedsessionId、detail外部セッションストレージへのミラーリング書き込みが失敗した。あわせて MirrorErrorMessage が配信されます
mirror_drain_timeoutsessionId、detailクローズ時にミラーリング書き込みが制限時間内に完了しなかった
process_tree_cleanup_degradedcapability、detail現在の環境では CLI のプロセスツリーを完全にはクリーンアップできない。初期化には影響せず、子プロセスが回収されたことも意味しません
stdin_writer_stop_timeoutsessionIdクローズ時に書き込みスレッドが時間内に停止しなかった。書き込み中のメッセージが切り詰められる可能性があり、SDK は代わりに CLI プロセスを終了します
cli_process_alive_after_closedetailクローズ処理の完了後も CLI プロセスが動作している。detail に実行済みの終了手順が列挙されます
lane_shutdown_timeoutdetailSDK 内部のスレッドがクローズの制限時間内に停止しなかった。割り込みを無視するコールバックは、クローズ後も動作し続ける可能性があります
spool_cleanup_deferreddetailクローズ時にメッセージバッファの一時ファイルがまだ使用中だった。読み書きが戻った後に削除されます
private_directory_cleanup_faileddetail認証または MCP 設定用のプライベート一時ディレクトリのクリーンアップが完了しなかった。detail に credential files may remain が含まれる場合、認証情報ファイルがディスクに残っている可能性があります
session_store_cleanup_faileddetail外部セッションの復元に使う一時ディレクトリのクリーンアップに失敗した
managed_runtime_reuseddetailキャッシュ済みのマネージド CLI を使用した
managed_runtime_install_started / managed_runtime_installeddetailマネージド CLI のインストールを開始した/完了した
managed_runtime_stale_install_removeddetail破損または不完全な古いインストールを削除した
managed_runtime_unsupported_platformdetail現在のプラットフォームにはマネージド CLI がないため、インストール済みの CLI を探す
SDK の今後のバージョンでイベントタイプが追加される可能性があります。type で分岐する場合はデフォルトの分岐を残してください。

Exceptions

SDK の例外はすべて非チェック例外の QoderException を継承します。同期メソッドは直接スローします。非同期メソッドは返された CompletionStage を失敗させます。join() で待機すると CompletionException にラップされるので、getCause() で元の例外を取り出します。Agent の業務上の失敗は例外をスローせず、outcome() が ERROR の ResultMessage でターンを終えます。
RuntimeException
└── QoderException
    ├── AuthenticationException
    ├── CliNotFoundException
    ├── RuntimeInstallException
    ├── CliProcessException
    ├── ProtocolException
    │   ├── FrameTooLargeException
    │   ├── MalformedUtf8Exception
    │   └── ProtocolVersionMismatchException
    ├── ControlRequestTimeoutException
    ├── UnsupportedCliCapabilityException
    ├── SessionClosedException
    ├── SessionStoreConflictException
    ├── SessionStoreDeletedException
    ├── SpoolIoException
    ├── SpoolCapacityExceededException
    ├── MessageStreamAlreadyConsumedException
    ├── ConsumerInterruptedException
    ├── CallbackExecutionException
    ├── CallbackRejectedException
    ├── IllegalBlockingCloseException
    ├── InvalidOptionsException
    └── UnsupportedSecureSecretTransportException

QoderException

public class QoderException extends RuntimeException {
    public QoderException(String code, String message, boolean retryable);
    public QoderException(String code, String message, boolean retryable, Throwable cause);
    public final String getCode();
    public final boolean isRetryable();
}
メソッド戻り値の型説明
getCode()String安定した機械可読のエラーコード。例外一覧を参照
isRetryable()booleanリトライする価値があるかどうか
例外のメッセージと cause は生成時にマスクされ、printStackTrace() はマスク後のスナップショットを出力します。SDK は自動でリトライせず、現在の組み込み例外の isRetryable() はすべて false を返します。新しいセッションでリトライするかどうかは、アプリケーションがエラーコードで判断します。

UnsupportedCliCapabilityException

public class UnsupportedCliCapabilityException extends QoderException {
    public static final String CODE = "UNSUPPORTED_CLI_CAPABILITY";
    public CapabilityState capabilityState();
}
次の場合にスローされます。
  • 呼び出したメソッドが CLI の機能(capability)を必要とし、CLI がサポート外と宣言している(UNSUPPORTED)か、一度も宣言していない(UNKNOWN)場合。SDK はローカルで直接失敗し、CLI にリクエストを送りません。必要な capability はcapability 要件を参照してください。
  • 基本的な制御リクエストが実行時に CLI から拒否された場合。
  • SessionRepository のローカル操作に列挙可能なストアが必要で、現在のストアがそれをサポートしていない場合。
capabilityState() は失敗の原因となった CapabilityState を返します。

例外一覧

下表に挙げたアクセサーを除き、各例外クラスにはコンストラクターしかなく、エラーコードの定数は CODE です。
クラスエラーコードスローされる場面
AuthenticationExceptionAUTHENTICATION_FAILED、CLI_AUTH_FATAL認証に失敗した。CLI が終了コード 41 で致命的な認証失敗を報告した場合、エラーコードは CLI_AUTH_FATAL(定数 CODE_CLI_AUTH_FATAL)になり、プロセスの失敗としてリトライすべきではありません
CliNotFoundExceptionCLI_NOT_FOUNDCLI が見つからない。明示したパスが無効か、自動検索で実行ファイルが見つからなかった
RuntimeInstallExceptionRUNTIME_INSTALL_FAILEDマネージド CLI のインストールに失敗した。ダウンロードが禁止されていてローカルのアーカイブもない、ネットワークの失敗やタイムアウト、サイズや SHA-256 の検証不一致などです。SDK はほかのバージョンに切り替えません。ManagedRuntimeOptions を参照
CliProcessExceptionCLI_PROCESS_FAILEDCLI プロセスが異常終了した(認証関連の終了コードを除く)。getExitCode() は終了コードを、getStderrTail() は上限付きでマスク済みの stderr の末尾を返し、取得できない場合は null です
ProtocolExceptionPROTOCOL_ERRORCLI の出力がプロトコルに違反した。下の 3 つのサブクラス以外の場合です
FrameTooLargeExceptionFRAME_TOO_LARGE1 つのメッセージがサイズ上限を超えた
MalformedUtf8ExceptionMALFORMED_UTF8CLI の出力が正しい UTF-8 ではない
ProtocolVersionMismatchExceptionPROTOCOL_VERSION_MISMATCHCLI のプロトコルバージョンが SDK と互換性がない
ControlRequestTimeoutExceptionCONTROL_REQUEST_TIMEOUT制御リクエストが controlRequestTimeoutMs(デフォルト 60000 ミリ秒)以内にレスポンスを受け取らなかった
UnsupportedCliCapabilityExceptionUNSUPPORTED_CLI_CAPABILITY上記を参照
SessionClosedExceptionSESSION_CLOSEDクローズ済みのクライアント、セッション、クエリで操作を続けた。完全なクローズの途中で CLI が先に終了した場合も、コンシューマーはこの例外を受け取ります
SessionStoreConflictExceptionSESSION_STORE_CONFLICTセッションストアのバージョン競合(expectedVersion が古い)、または同じ UUID に異なる内容が対応している。currentVersion() はストアの現在のバージョンを返します
SessionStoreDeletedExceptionSESSION_STORE_DELETEDSessionStoreDeletedException を参照
SpoolIoExceptionSPOOL_IO_ERRORメッセージバッファのディスクファイルの読み書きに失敗した
SpoolCapacityExceededExceptionSPOOL_CAPACITY_EXCEEDED未消費のメッセージがバッファの上限を超え、メッセージストリームが失敗した。メッセージストリームを速やかに消費すれば避けられます
MessageStreamAlreadyConsumedExceptionMESSAGE_STREAM_ALREADY_CONSUMED同じ MessageStream を 2 回目に消費した。openCursor() と consume() は合わせて 1 回しか呼べません
ConsumerInterruptedExceptionCONSUMER_INTERRUPTEDMessageCursor.hasNext() または next() でブロックしているスレッドが割り込まれた。スレッドの割り込みフラグは保持されます
CallbackExecutionExceptionCALLBACK_EXECUTION_FAILEDアプリケーションのコールバック(権限、Hook、MCP、メッセージハンドラー)が例外をスローした
CallbackRejectedExceptionCALLBACK_REJECTEDcallbackExecutor がコールバックタスクの実行を拒否した。スレッドプールがシャットダウン済み、キューが満杯などの場合です
IllegalBlockingCloseExceptionILLEGAL_BLOCKING_CLOSEリソース自身の SDK スレッドまたはプッシュハンドラー内で、ブロッキングの close() を呼んだ。スローする前に SDK は closeAsync() と同じようにクローズを開始しています。スレッドモデルとリソース解放を参照
InvalidOptionsExceptionINVALID_OPTIONS設定が無効。たとえば QoderClient.Builder に auth がない、SessionOptions に相互排他のオプションが同時に設定されているなど
UnsupportedSecureSecretTransportExceptionUNSUPPORTED_SECURE_SECRET_TRANSPORT認証や MCP 設定用のプライベート一時ファイルを安全に作成・書き込みできない。java.io.tmpdir またはその上位ディレクトリで、ほかのアカウントがエントリを置き換えられる場合も含みます。SDK は起動を拒否し、平文の引数や環境変数による受け渡しには切り替えません
次のエラーコードは QoderException として直接スローされます。
エラーコードスローされる場面
CLI_START_FAILEDCLI プロセスの起動に失敗した。権限不足、無効な作業ディレクトリ、長すぎる引数などです。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 も同時にクローズされます