qodercli はデフォルトで、実行中のマシンにセッション履歴を保存します。複数インスタンス、コンテナ、Serverless 環境では、次のリクエストが別のマシンに届き、以前のセッションを参照できないことがあります。
外部セッションストレージは、アプリケーションが管理するストレージに各セッションのミラーを保持します。ミラーは追加のコピーです。qodercli は引き続きセッションをローカルに書き込み、どのホストからでも後で session ID を使って同じセッションを継続できます。
次のような場合に外部ストレージが適しています。
この設計から 2 つの性質が生まれます。
SDK が同じプロジェクトとして認識できるように、すべてのホストで同じ
セッションのミラーリングや復元が必要なクエリごとに、options で store を渡し(TypeScript は
セッション管理関数はローカルファイルではなく store に対して操作します。TypeScript では
セッション一覧の関数は store にセッション一覧メソッドの実装を要求します。サブエージェント一覧は
SDK は本番利用可能なストレージ実装を提供しません。アプリケーションが選んだ共有ストレージに対して
Java のインターフェースはバッチ単位で追加し、上のチェックリストとは次の点が異なります:
失敗時の処理。 外部書き込みの失敗は進行中の会話を中断しません。最後のリトライが失敗すると、SDK はミラーエラーメッセージ(TypeScript は
- リクエストが複数のサービスインスタンス間を移動する
- ローカルディスクが一時的、または信頼できない
- アクセス制御、暗号化、バックアップ、保持期間をアプリケーション側で管理したい
仕組み
- 書き込みはベストエフォート。 SDK はバックグラウンドで entry をミラーします。書き込みの失敗は通知されますが、進行中の会話を止めることはありません。詳しくは運用を参照してください。
- entry は不透明。 ストアは SDK が定義した transcript entry をそのまま保存して返します。アプリケーションが qodercli のローカルファイル形式を理解する必要はありません。
クイックスタート
InMemorySessionStore はデータを現在のプロセス内だけに保持します。共有バックエンドへ接続する前に、これで、query がストアへ保存しストアから再開できるという配線を検証してください。プロセス終了時にデータが失われるため、ホストをまたいだ再開は示せません。それには実際のストアを実装してください。ストアの実装を参照してください。
cwd(Java では workingDirectory)を使用してください。
Java のミラーリング書き込みは非同期です。セッションを閉じるとき、SDK は残りのレコードの書き込みを最大 closeDrainTimeoutMs(デフォルト 5 秒)待ちます。上の例のように同じプロセスですぐに再開する場合は、前のクエリの closeAsync() が完了するのを先に待ってください。
アプリケーションでの使用
セッションのミラーリングや復元が必要なクエリごとに、options で store を渡し(TypeScript は sessionStore、Python は session_store)、セッションの指定方法を選びます:
- session ID が既知 ——
resumeを渡します。 - プロジェクトの直近セッション ——
continue: true(TypeScript)/continue_conversation=True(Python)/continueSession(true)(Java)を渡します。store がセッション一覧メソッドを実装している必要があります。
QoderClient.Builder.sessionStore(store) でクライアントのデフォルト store を設定し、クエリ、セッション、client.sessions() のすべてがそれを使います。個別のセッションでは SessionOptions.Builder.sessionStorage(...) で上書きできます。SessionStorage.external(otherStore) は別の store を使い、SessionStorage.cliLocal() は CLI のローカル履歴だけを使います。
Java は store 内のルート transcript entry の最新の timestamp で直近のセッションを選びます。entry にタイムスタンプがない、最新時刻が並んでいる、または使えるセッションがない場合、起動は InvalidOptionsException で失敗します。明示的な session ID を渡してください。
セッションの管理
セッション管理関数はローカルファイルではなく store に対して操作します。TypeScript では sessionStore オプションで store を渡し、Python では各関数の第1引数に store を渡します。Java では client.sessions(options) で、store とプロジェクトディレクトリに紐づいた SessionRepository を取得します。options にはセッション作成時と同じものを渡してください。そうしないと、その workingDirectory で保存されたセッションは見つかりません。client.sessions() はクライアントの projectDirectory を使うため、QoderClient.Builder でプロジェクトディレクトリを一括設定している場合に向いています:
listSubkeys / list_subkeys を、セッション削除は delete を要求します。listSubkeys / list_subkeys が実装されていれば、サブエージェントメッセージの取得関数もそれを使います。
Java の list() は store が ListableSessionStore を、delete() は SessionDeletionStore を実装している必要があります。delete() はセッションのルート transcript とすべてのサブエージェント transcript を削除します。store が設定されていない場合や必要なインターフェースがない場合、これらのメソッドは UnsupportedCliCapabilityException で失敗します。組み込みの InMemorySessionStore は両方のインターフェースを実装しています。Java にはセッションの名前変更、タグ付け、インポートの関数はありません。
既存のローカルセッションを store にコピーするには——たとえば外部ストレージ未使用だったマシンの移行時——インポート関数を使います。session ID が先、store が後である点に注意してください:
ストアの実装
SDK は本番利用可能なストレージ実装を提供しません。アプリケーションが選んだ共有ストレージに対して SessionStore インターフェース(TypeScript)/ プロトコル(Python)/ インターフェース(Java)を実装します。Redis と PostgreSQL の実行可能なリファレンス実装が具体的な使い方を示しています。TypeScript サンプル または Python サンプル を参照してください。これらは出発点であり、本番利用可能な実装ではありません。
SessionKey は1つの transcript を識別します。メインセッションには subpath がありません。各サブエージェントの transcript は同じ project key と session ID を再利用し、異なる subpath を持ちます。key と entry は不透明データとして扱い——そのまま保存してそのまま返し、メッセージ内容を解析しないでください。
必須の 2 メソッドが保存と復元を提供します。各任意メソッドが 1 つの機能を有効にします。
| メソッド | 有効になる機能 |
|---|---|
append、load | セッションのミラーと ID による再開 —— 必須 |
listSessions / list_sessions | 直近セッションの再開。保存済みセッションの一覧 |
delete | store からのセッション削除 |
listSubkeys / list_subkeys | サブエージェント transcript の完全な復元と閲覧 |
実装チェックリスト
- key ごとに追加順を保持し、
loadでは履歴全体を返す。再生は順序に依存します。 - key を分離する。 ある key の entry を別の key の下で返さないこと。
appendを冪等にする。 SDK は失敗した書き込みを同じ entry で再試行する場合があるため、再試行で履歴が重複してはいけません。- セッション一覧の
mtimeは Unix ミリ秒タイムスタンプを返し、メインセッション(subpathを持たないもの)のみを返します。 - 削除をカスケードする。 メインセッションの削除時は、そのサブエージェント transcript も削除します。
listSubkeys/list_subkeysは相対識別子のみを返します——絶対パスや./..を含むパスは返さないでください。これらはストレージキーになり、パストラバーサル片があると transcript が名前空間の外に出てしまいます。- 同時書き込みを直列化する。 同じセッションを複数プロセスが書き込む可能性がある場合は、ストレージ層で直列化します。
SessionStore conformance テストを同梱、Python は qoder_agent_sdk.testing の run_session_store_conformance を提供)、バックエンド固有の並行・リトライテストを追加してください。接続管理、権限、暗号化、バックアップ、移行、データ保持は引き続きアプリケーションの責務です。
Java 実装の違い
Java のインターフェースはバッチ単位で追加し、上のチェックリストとは次の点が異なります:
- 冪等性と CAS。
appendはAppendBatch.operationId()ごとに冪等で、リプレイ時は元の操作のバージョンと件数を返します。expectedVersion()がnullでない場合は CAS を行い、バージョンが一致しないとSessionStoreConflictExceptionで失敗します。 - セッション一覧。
listSessionsはプロジェクト配下のすべてのキー(サブエージェントの subpath キーを含む)を返し、順序は保証されません。直近のセッションは entry 内のtimestampで選ばれるため、mtimeは不要です。 - 削除。
deleteSessionTreeはルート transcript とすべての subpath を同じトランザクション内で削除し、セッションを削除済みとして永続的にマークします。以降、そのセッションへの書き込みはSessionStoreDeletedExceptionで拒否されます。deleteSessionは単一のキーだけを削除します。 - 非同期。 2 つの必須メソッドは同期的に完了してもかまいませんが、失敗は直接スローせず、例外で完了した stage で報告してください。呼び出し元スレッドでブロッキング I/O を行わないでください。
運用
失敗時の処理。 外部書き込みの失敗は進行中の会話を中断しません。最後のリトライが失敗すると、SDK はミラーエラーメッセージ(TypeScript は system/mirror_error、Python は SDKMirrorErrorMessage、Java は MirrorErrorMessage)を発行します。ミラーの完全性が重要な場合は監視してください——書き込みが失敗しても会話は成功裏に完了することがあります。
Java では、あるキーへの書き込みが失敗またはタイムアウトすると、そのキーのミラーリングが停止します。他のキーには影響しません。MirrorErrorMessage のエラーテキストは rawJson() の error フィールドにあります。形式は安定していないため、文字列でマッチさせないでください。
チューニング。
- 外部読み取りはデフォルトで最大60秒待機します。
loadTimeoutMs/load_timeout_msで調整します。 - flush 戦略(
sessionStoreFlush/session_store_flush)のデフォルトはbatchedです。eagerにすると entry をより早くミラーしますが、ストレージリクエストが増えます。 - Java には
loadTimeoutMsと flush 戦略のオプションはありません。ミラーの保留バッチ、バイト数、待機の上限はsessionMirrorOptions(...)で設定します。SessionMirrorOptionsを参照してください。
- 明示的に指定したセッションが store にない場合、SDK は同じ ID のローカルセッションにフォールバックできます。Java はフォールバックしません。明示的に指定したレコードが store にない、または空の場合、起動は
InvalidOptionsExceptionで失敗します。 - store はファイル checkpoint、カスタム transport、実験的な Cloud Agent runtime と併用できません(TypeScript では
persistSession: falseとも併用不可)。TypeScript では組み込みの Process / Worker transport で、Python では組み込みの subprocess transport でサポートされます。 - store が保持するのはセッション履歴だけです。認証状態、アプリケーション設定、ファイル checkpoint、保持ポリシーは保持しません。
- Java で有効な store と
fileCheckpointing(true)を同時に設定すると、InvalidOptionsExceptionで失敗します。 - Java で外部 store 上のセッションをフォークするには、CLI が対応する capability をサポートしている必要があります(capability 要件を参照)。SDK はフォークの初期レコードが store に書き込まれてから初期化を完了し、入力を送信します。capability がない場合や書き込みに失敗した場合、起動は失敗します。
CLI_START_FAILED で失敗し、エラーメッセージに理由が示されます。