Reactフック

useSessionフックを使って、ReactでBeeuniセッションを実行します。

@beeuni/sdk/reactはSDKにReactフックを追加します。このページでは、 セッションを最初から最後まで実行するフックuseSessionと、Reactアプリ向けに 安定性が確認されているその他のフックを説明します。

useSession(projectId, sessionId, options?)

useSessionはセッションを開始し、サーバーが選択したイベントトランスポートを開き、 メッセージ、ステータス、保留中のプロンプトを同期します。セッションビューごとに1回呼び出してください。

import { useSession } from '@beeuni/sdk/react';

function Chat({ projectId, sessionId }: { projectId: string; sessionId: string }) {
  const s = useSession(projectId, sessionId);

  if (s.phase !== 'ready') return <Booting stage={s.stage} onRetry={s.retry} />;

  return (
    <>
      {s.messages.map(({ info, parts }) => (
        <Message key={info.id} info={info} parts={parts} />
      ))}
      <Composer busy={s.isBusy} onSend={s.send} onStop={s.cancel} />
    </>
  );
}

準備状態はサーバーの情報が正となります。POST /startが stage: 'ready'を返すと、ランタイムは準備完了です。useSessionはクライアント側で別途ヘルスチェックを実行しません。

戻り値

アクション

useSessionはremoveQuestionとremovePermissionも返します。これらは使用しないでください。 ローカル状態からプロンプトをクリアするだけでエージェントには通知しないため、 実行がブロックされたままになります。代わりにanswerQuestion、rejectQuestion、または answerPermissionを使用してください。

オプション

送信は楽観的に処理されます。sendはメッセージを即座に表示し、その後ストリーム イベントがエージェントの返信を埋めていきます。

rewind(messageId)はセッションを作成しません。POST /startの正規セッションを使用します。 ランタイムはファイルの状態を復元し、削除された会話履歴のパスを 復元可能な状態に保ちます。次に受理されたプロンプトが置き換え後のパスを確定します。

その他の安定したフック

@beeuni/sdk/reactは、実行中のセッションを必要としないデータ用のReact Queryフックも エクスポートします。各フックは clientのメソッドに対応し、プロバイダーは不要です。

3つの通知フックは userId（qk.notifications）をキャッシュのキーにするため、 同じタブでユーザーを切り替えても、前のユーザーの受信トレイが表示されることはありません。 サインイン中のユーザーのIDを渡してください。

通知はプロジェクトごとの notification_center 機能フラグで制御され、デフォルトではオフです。各フックを enabled: useFeatureFlag(projectId, 'notification_center').enabled で制御し、 フラグがオフのプロジェクトでは通知リクエストが送信されないようにしてください。

コネクター設定リンク

エージェントはワンクリック接続リンク（/connect/<token>）を発行できます。フローのデータと ランタイムポリシーはSDK内にあり、ホストはそれらを使って独自のダイアログを表示し、 アダプターを注入します。

コネクターデータ

useConnectorQuery(projectId, slug, action, args, { account, enabled, staleTime }) は 1つのコネクターアクションの出力をキャッシュされたクエリとして読み取ります。error は ConnectorCallError です。error.connectUrl から接続ボタンを、または error.availableAccounts からアカウント選択UIを描画します。読み取りを行うアクションにのみ使用してください。 取得のたびにアクションが実行され、監査イベントが書き込まれます。出力は 30秒間最新として扱われ、フォーカス時に再取得されることはなく、上流の 429 または 503 のみが 再試行されます。コードからコネクターを使うを参照してください。

セッションを開く読み取りを早めに開始する

prefetchSessionOpen(queryClient, projectId, sessionId) はセッションビューがマウントされる前に、セッションを開くための 読み取りを開始します。1回の GET .../snapshot リクエスト （セッション行、ターン、キュー、トランスクリプトの最初の40メッセージ）を送信し、その結果で セッション行キャッシュを初期化します。その後、useSession は独自のリクエストを 開始する代わりに、そのリクエストを使用します。

ルートがセッションを指定するとき、またはセッションリンクのホバー、フォーカス、タッチ時に 呼び出してください。読み取り専用で、/start を呼び出すことも、コンピューターを起動することもありません。 拒否されることはありません。30秒以内に同じセッションに対して再度呼び出しても、 リクエストは送信されません。

import { prefetchSessionOpen } from '@beeuni/sdk/react';

<a
  href={`/projects/${projectId}/sessions/${sessionId}`}
  onFocus={() => void prefetchSessionOpen(queryClient, projectId, sessionId)}
/>;

再読み込み時にキャッシュから描画する

2つのストアがユーザーがすでに見た内容を保持するため、再読み込みやアプリのコールドスタートでも 最初のフレームにそれを描画し、その場で更新できます。どちらもユーザーごとに管理され、上限があり、 ホストはサインアウト時に両方をクリアします。

• createPersistedQueryCache は、ユーザーが移動に使うReact Queryの結果を保持します： アカウント、プロジェクト、プロジェクト詳細、ページ分割されたセッション一覧、セッション行 （isPersistableQueryKey）。復元されたエントリは元の経過時間を維持するため、マウント時に 再取得されます。デフォルトの上限は1,000,000文字、7日間です。
• createSavedCopyStore は、サーバーが送信したトランスクリプトの最後に保存されたコピーを 保持します。setSavedCopyStore で登録すると、useSession が最初のフレームの前に 保持されたコピーを描画します。その後、サーバーのコピーがメッセージIDで照合・統合され、 SDKは各ターンの終了から3秒後に再読み取りします。デフォルトの上限は12 セッション、1,500,000文字、14日間です。300,000文字を超えるコピーでは、 上限に収まる最新のメッセージを保持します。古いメッセージは、ユーザーが 上にスクロールしたときにサーバーから読み込まれます。

import {
  browserKeyValueStorage,
  createPersistedQueryCache,
  createSavedCopyStore,
  isPersistableQueryKey,
  setSavedCopyStore,
} from '@beeuni/sdk';

const storage = browserKeyValueStorage(); // null where there is no localStorage
if (storage) {
  const cache = createPersistedQueryCache({ storage, userId, shouldPersist: isPersistableQueryKey });
  cache.restore(queryClient); // synchronous with localStorage: no pending frame
  const stop = cache.persist(queryClient);
  setSavedCopyStore(createSavedCopyStore({ storage, userId }));
}

React Nativeでは、AsyncStorageを storage として渡してください。その場合、restore はPromiseを返します。

保存コピーのストアは、サーバーによる記録のみを保持します。これは、ターン終了時にAPIが 書き込むトランスクリプトのミラーです。ライブのトランスクリプトはデバイスに書き込まれないため、 停止したターンが実行中として復元されることはありません。ランタイムの読み取りでメッセージが返されない場合も、 保存済みメッセージは画面に残ります。これは会話が空であることではなく、コンピューターが状態を失ったことを 意味します。メッセージを含む最初のランタイム読み取りで、それらを照合・統合します。

サインアウトとアカウントの切り替え

SDKはユーザーごとのセッション状態をメモリに保持します：トランスクリプト、保留中の質問 と権限、ターンの受領記録、モデルの選択。サインアウトや別のユーザーのサインインなど、 IDが変わるたびに resetIdentityState() を呼び出してください。これには、 別のタブでのサインインにより、ページを読み込まずにユーザーが変わる場合も含まれます。

認証フローでユーザーがサインインまたはサインアウトしたときに、このハンドラーを呼び出します。

import { resetIdentityState } from '@beeuni/sdk/react';

let previousUserId: string | null = null;

function onIdentityChange(userId: string | null) {
  if (userId !== previousUserId) {
    queryClient.clear();
    resetIdentityState();
  }
  previousUserId = userId;
}

resetIdentityState() はモデルストアの localStorage エントリも削除します。 React Query などのホスト自身のキャッシュや、createBeeuni に渡されたトークンソースは クリアしません。同じハンドラー内でリセットしてください。例外をスローすることはありません。

再読み込み時にキャッシュから描画する のストアを使う場合は、 同じハンドラー内でクリアしてください。await cache.clear()、続いて await savedCopies.clear() と setSavedCopyStore(null) の順です。どちらのストアも別のユーザーのデータを 復元することはありませんが、サインアウトしたデバイスにデータを残すべきではありません。

次のステップ

• セッション — useSession がラップするセッションハンドルと、BeeuniSendError の種類。
• リファレンス — これらのフックが読み取る REST API の全体。

起動中の保存済み履歴

useSession(projectId, sessionId) はコンピューターの起動中に保存済みのチャット履歴を表示します。 SDK はランタイムの準備状態とは独立してデータベースを読み取ります。その後、ライブメッセージは 元の ID に基づいて整合されます。ホストに別途の履歴リクエストやメッセージストアは不要です。

保存済み履歴はライブの会話記録とまったく同じように描画されます。テキスト、推論、そしてすべてのツール呼び出しの 入力、出力、エラーが含まれます。サブエージェントの完全なビューは、そのサブエージェント自身の保存済み 会話記録を読み取ります。親のスコープと savedChild: true を useSessionSync(subAgentSessionId, { beeuniSessionScope, savedChild: true }) に渡してください。初期ウィンドウには最新の40件のメッセージが含まれ、 最大1,000,000文字です。上にスクロールすると、コンピューターがオフの間も保存済み履歴から 古いウィンドウを読み込みます。コンピューターを必要とする添付ファイルは、 ランタイムの準備が整うと利用可能になります。

savedTranscript は、コンピューターの起動中に何を描画するかをホストに伝えます。保存済みコピーが まだ届く可能性がある間は loading、メッセージが messages に入ると shown、ランタイムが応答するまで 何も表示できない場合は none です。不明な状態は loading であり、none にはなりません。

conversationEmpty は、待つものが何もない場合に true になります。保存済みコピーによって 会話が空であることが証明されています。セッションのランタイムを完全に読み取った結果、メッセージが見つからなかった状態です。その後に終了したターンはなく、 開いているものやキューに入っているものもありません。レコードの欠落によって true になることはないため、履歴のある古いセッションが 空として表示されることはありません。セッションは、履歴保存を有効にして初めて起動したときに この証明を得ます。

if (s.messages.length === 0) {
  // Nothing saved and nothing to wait for: the user can type now.
  if (s.conversationEmpty) return <Composer />;
  // One round trip for a saved copy; the computer can take minutes.
  return s.savedTranscript === 'none' ? <Booting stage={s.stage} /> : <MessageSkeleton />;
}

2026-09-28 より前に保存されたツール呼び出しでは、入力と出力が失われていました。サーバーは各呼び出しを、 保持されたタイトルやメタデータから確認できる入力とともに提供します。コマンドのコマンドと出力、ファイル呼び出しのパス、 検索のパターン、サブエージェントの説明、フェッチの URL、Todo リスト、スキルの名前です。 セッションの次回起動時に、履歴全体が再び1対1で保存されます。

保留中のプロンプト

useSessionPrompts(projectId, sessionId) は永続的なセッション受信トレイに送信します。 サーバーは保留中のプロンプトを、それぞれ独立したターンとして自動的に実行します。

会話内に保留中のメッセージを表示するには、placement: 'transcript' を渡してください。 これはすべての composer エントリより先に実行され、現在のツール呼び出しが完了すると 進行中の応答を終了します。 入力欄の上の編集可能なリストに保持するには、placement: 'composer' を渡してください。 これは進行中の応答が終わるまで待機します。各配置は送信順を維持します。 実行中のターンにプロンプトをどう届けるかを指定するには、delivery: 'steer' | 'queue' | 'interrupt' を 渡してください。steer は次のステップでターンに渡し、ターンは 停止しません。queue はターンの終了を待ちます。interrupt は実行中の ツールの後にターンを終了します。delivery だけを指定すると、SDK はそれが意味する配置を送信します。 interrupt は transcript、それ以外は composer です。誘導できない steer 行は delivery: 'queue' となり、steer_fallback が unsupported、 not_prompter、または turn_ended に設定されます。interrupt(promptId)（「Stop and send」）は 待機中の行を会話記録のエントリに変えます。すでに送信中の行は 409 を返します。

Web の入力欄では、ターンの実行中は Enter で steer として送信し、セッションがアイドル状態なら 会話記録への送信になります。Command+Enter（Windows/Linux では Control+Enter）は 入力欄への配置です。Shift+Enter は改行を挿入します。

リストの行には、再読み込み後に完全なプレビューを表示するための full_text が含まれます。text は 古いクライアント向けのサイズ制限付きプレビューとして残ります。添付ファイルのバイトデータはリストの レスポンスに含まれません。削除時には、情報を失わずに元に戻せるよう、完全なプロンプトが返されます。

保留中の配信と進行中の応答

useSessionWorking() は、プロンプトが永続的な受信トレイで待機している間、state: 'working' を 維持します。これにより Stop を利用できます。pendingDelivery: true は、まだ ランタイムに向かっている途中のプロンプトを示します。Web アプリは、そのフラグの値にかかわらず、state が working のときに動作中インジケーターを1つ表示します。進行中のランタイムターンと新たなランタイムの アクティビティによって、この状態はクリアされます。キャンセルがタイムアウトしても、実行が停止したことは確認できません。

ワーカーによる取得は、受け入れ可否を確認するだけで、プロンプトは待機したままです。配信は 受け入れが成功してから始まります。進行中のターンが確認されると、前の受信トレイのスナップショットにそのプロンプトがまだ載っていても、 保留中の表示はクリアされます。この引き継ぎ中、ランタイムのアクティビティは 進行中のターンのメッセージ ID を維持します。

Web の入力欄では、Command/Ctrl+Enter を Queue List、行の「Stop and send」を Quick Queue と呼びます。Quick Queue のエントリは先に実行されます。待機中の Quick Queue エントリは、 配信済みターンの後に色付きの吹き出しとして表示され、ステータステキストはありません。Queue List のエントリは配信が始まるまで編集可能です。 サーバーは、再読み込み後も含め、正確なランタイムの証拠から取り逃した完了イベントを復元します。 到達できないランタイムを完了したターンとして扱うことはありません。

個々の Enter 操作は、先の受け入れリクエストが未解決でも、その保留中のプロンプトを 即座に表示します。テキストが追加されるのは配信に失敗した場合だけです。原因、 Retry、Remove が表示されます。実行順は引き続きサーバーの受信トレイが管理します。

フックはセッションの制御ストリーム （GET .../sessions/:id/events?channels=control）からキューの変更を読み取ります。マウントするコンポーネントの数にかかわらず、 接続はセッションごとに1つです。受信トレイの行への書き込みはすべて beeuni.control.queue フレームとして届きます。GET .../prompts のポーリングは、その ストリームが接続されていない間だけ実行されます。

ターンが終了した理由

中断されたターンの会話記録には MessageAbortedError だけが含まれます。 コントロールプレーンは、各ターンがどのように終了したかについて把握している情報を保持します。サンドボックスが 示した原因（たとえば SandboxMemoryGuard）や、原因が示されずに終了したターンです。 誰かが要求した停止（Stop ボタン、abort()、ビジー状態のセッションに 送信されたプロンプト）はリクエストとして記録され、失敗として報告されることは ありません。

useSessionTurnOutcome(projectId, sessionId) は、useSessionWorking() が最新に保つキャッシュから last_ended、recent_failures、読み取り時刻 atMs を 返します。リクエストは行いません。その結果を、会話記録がターンについて示す情報とともに turnEndNotice に渡してください。

const outcome = useSessionTurnOutcome(projectId, sessionId);
const notice = turnEndNotice(outcome, turn.userMessage.info.id, {
  hasError: Boolean(turnError),
  isAbort: turnErrorIsAbort,
});
// notice: { kind: 'sandbox-memory', usedPct: 97, detail: 'sandbox memory at 97% …' }
//       | { kind: 'cause', name: 'SomeGuard', message: '…' }
//       | { kind: 'unexplained' }
//       | null

ホストは各 kind を自身の表示文言に対応付け、サンドボックスの メッセージを解析することはありません。null は「会話記録に表示されているものを表示する」という意味です。実際のエラーは残り、 中止の場合は何も描画しません。原因不明の失敗は、読み取り時刻が ターン終了の数秒後になってから報告されます。原因は中止の1フレーム後に届くことが 多いためです。turnEndCause(outcome, messageId) は記録された生の 原因、または null を返します。