セッション

セッションを実行し、イベントをストリーミングして、発生しうるエラーを処理します。

セッションは、専用のサンドボックスと専用の git ブランチで行われる、エージェントの1回の実行です。 beeuni.session(projectId, sessionId) は、セッションのすべての操作に使うハンドルを返します。 開始、プロンプトの送信、イベントのストリーミング、ステータスの読み取りができます。 このページでは、ハンドル、準備完了のハンドシェイク、ストリーミング、SDK 呼び出しがスローしうる型付きエラーを説明します。

const s = beeuni.session(projectId, sessionId);

s は、セッションのすべての操作に使うハンドルです。セッション ID、サンドボックス ID、ブランチ名は同じ値です。概念については セッションを参照してください。

セッションのライフサイクル

ラベルとメタデータ

すべてのセッションには labels: string[] と metadata オブジェクトがあります。これらを使って セッションを分類し、アプリでの表示方法を決めます。

• ラベルは自由形式です。各ラベルは前後の空白が除去され、1～64文字、1セッションあたり最大20個で、 重複は除去されます。照合は完全一致で、大文字と小文字を区別します。
• メタデータは独自のキーを格納する自由形式の JSON オブジェクトで、1回の書き込みにつき JSON で最大16,384文字です。 サーバーも独自のキーをここに保存します （custom_name、source、…）。サーバー管理のキーを指定するリクエストは 400 で拒否されます。競合を避けるため、キーにプレフィックス（app_…）を付けてください。

// Set both at create.
const project = beeuni.project(projectId)
const created = await project.sessions.create({
  initial_prompt: 'Triage ticket T-142',
  labels: ['support', 'tier:gold'],
  metadata: { app_ticket: 'T-142', app_priority: 2 },
})

// Update later. `labels` replaces the list; `metadata` merges keys and a
// `null` value removes that key.
const s = beeuni.session(projectId, created.session_id)
await s.update({ labels: ['support', 'resolved'], metadata: { app_priority: null } })

// List by label, server-side: a session must carry EVERY given label.
const { items } = await project.sessions.listPage({ labels: ['support', 'resolved'] })

// Render conditionally.
for (const session of items) {
  const badge = session.labels?.includes('tier:gold') ? 'Gold' : null
  const ticket = session.metadata.app_ticket as string | undefined
}

React では、labels を useProjectSessions(projectId, { labels }) に渡します。 ラベルの組み合わせごとに個別のキャッシュエントリが作成されます。エージェントは CLI （beeuni sessions new --label … --meta k=v、beeuni sessions update --label …） およびホスト型 MCP サーバー（start_session labels / metadata、 list_sessions labels）から同じフィールドを設定します。実行可能なバージョンは packages/sdk/examples/12-session-labels.ts です。

pooled_provider_secrets と llm_gateway が有効な場合、セッションは1つのプロバイダーに対して 利用可能な複数のアカウントシークレットを選択できます。beeuni.accounts.secretResources.create(accountId, { project_id: projectId, ...input }) を通じて プロジェクトスコープのリソースを作成します。 デフォルトでは、すべてのプロジェクトメンバーが使用できます。 .setAccess(accountId, secretId, 'members', userIds) で制限してください。読み取りではメタデータと権限が返され、 シークレットの値は決して返されません。出力開始前にプロバイダーが 429 となった場合、ゲートウェイは 選択された別のキーを試します。

await s.providerSecretPool.set('anthropic', [primarySecretId, backupSecretId]);
const selected = await s.providerSecretPool.get('anthropic');
await s.providerSecretPool.set('anthropic', null); // inherit project default

呼び出し元がリロードの進行状況を表示する場合は、ストリーミングメソッドを使用してください。

await s.reloadConfigStream({ refresh_repo: false }, (event) => {
  if (event.type === 'phase') console.log(event.phase);
});

フェーズは checking-session、refreshing-workspace、compiling-config、 applying-config、confirming-config です。refresh_repo が false の場合、サーバーは refreshing-workspace を省略します。 applying-config フェーズには、デーモンによって検証されたランタイムの置き換えが含まれます。

API が設定リリースをサポートしている場合、s.configState() は release を返します。 その型は SessionConfigRelease です。リロードの結果にも同じオブジェクトが含まれます。

const { stale, release } = await s.configState();
if (release?.fallback_reason) {
  // The desired config failed on the box. An earlier config runs the session.
  console.warn(release.fallback_reason, release.running_release_id);
} else if (stale === true) {
  // Moves the session onto the base branch's current config AND
  // fast-forwards its /workspace checkout. `workspace_checkout` says what
  // happened to the checkout; `detail` words both halves.
  const result = await s.reloadConfig();
  console.log(result.workspace_checkout, result.detail);
}

stale は3状態です。null は Beeuni が判定できなかったことを意味します。stale === true をテストし、 !stale は決して使わないでください。古い API は release を省略します。 設定の収束を参照してください。

s.participants() は { participants, total, multi_user } を返します。participants は、 現在セッションを開けるユーザーを、所有者を先頭に最大20人まで一覧表示し、各項目は { user_id, name, email, avatar_url, is_viewer } です。total は総数です。 2人以上がセッションを開ける場合、multi_user は true です。React では、 useSessionParticipants(projectId, sessionId) が同じデータを読み取ります。各メッセージの作成者は s.messageAuthors() です。

さらに3つの読み取りメソッドが、このハンドルを補完します。

• s.previews() — ランタイムが公開するプレビュー用ポートの候補。
• s.publicShares.list() / .create(input) / .revoke(shareId) — 公開共有リンク。
• s.reminders.list() / .create(input) / .update(reminderId, { enabled }) / .remove(reminderId) — このセッションに送る予約済みプロンプト。リマインダーを参照してください。 .create({ transcript: true }) は会話への読み取り専用リンクを作成します（有効なリンクはセッションごとに1つで、2回目の呼び出しでは同じリンクを返します）。getPublicSessionShareMessages(token) で匿名で読み取れます。findActiveTranscriptShare(shares) は .list() から有効なリンクを選びます。
• s.audit(limit?) — セッション内のエージェント操作の監査証跡。
• s.attachments.upload(file, options?) — 起動前に非公開ファイルを保存します。最大50 MiB。プロンプトのファイルパート用に固定URLを返します。
• s.attachments.read(attachmentId, signal?) — サンドボックスを起動せずに、保存済みバイトを Blob として読み取ります。
• s.transcript(options?) — コンパクトなサーバー側のトランスクリプト（テキストとツール呼び出しのみで、ツールの入力や出力は含みません）。プロジェクトスコープのセッショントークンで利用できます。
• s.transcriptSync(options?) — 各ターンの終了時にサーバーが保存するトランスクリプト。実行環境のメッセージエンベロープ形式です。添付ファイルのバイトを除き、すべてのパートを1。テキスト、推論、各ツール呼び出しとその入力、出力、エラー、メタデータが含まれます。サンドボックスが停止中または起動途中でも、起動させずに応答します。最新のウィンドウを取得するには limit（最大500）を渡し、それより古いウィンドウを読み取るには、ウィンドウの next_cursor を before として渡します。ウィンドウはJSONが1,000,000文字に達しても打ち切られます。その際は最新のメッセージを保持し、next_cursor が保持された最古のメッセージを示します。サブエージェント自身の保存済みトランスクリプトを読み取るには、child（サブエージェントの ses_… ID、サブエージェントの行から開くセッション）を渡します。会話から派遣されたすべてのサブエージェントが保存されます。source は mirror です。complete がtrueになるのは、ウィンドウが保存済みメッセージをすべて含み、保存されたコピーがセッションの最初のメッセージまで到達している場合のみです。ランタイムを完全に読み取り、メッセージがなかったセッションは、available: true、complete: true、total: 0 を返し、メッセージは返しません。保存履歴でツールの入力と出力が省かれていた2026-09-28より前に保存されたツール呼び出しは、タイトルまたはメタデータから確認できる入力とともに返され、コマンドの場合は出力も返されます。
• s.voiceTranscript(options?) — このセッションのライブ音声通話のトランスクリプト（発話ターンと ask_beeuni/run_command ワーカーのツール呼び出し）。セッションにライブ通話がない場合は、404ではなく空のリストを返します。

セッションが保存したファイル

findSessionAttachments(messages) は、トランスクリプトが参照するすべての保存済みファイルを、順番に重複なく一覧表示します。ユーザーのアップロード、プロンプト内の <file> 参照、またはエージェントが表示したファイルの保存履歴内のコピーが対象です。ライブのトランスクリプトも保存済みのものも読み取り、不正な形式でも例外をスローしません。

import { findSessionAttachments } from '@beeuni/sdk'

const saved = await s.transcriptSync({ limit: 500 })
for (const file of findSessionAttachments(saved.messages)) {
  const blob = await s.attachments.read(file.attachment_id) // no sandbox needed
  console.log(file.filename, file.role, blob.size)
}

各結果は { url, attachment_id, filename, mime, message_id, role } です。 role はアップロードの場合は user、エージェントが表示したファイルの場合は assistant です。 後者では mime はnullで、バイト自体に型が含まれます。

各メッセージの作成者

すべてのメッセージには作成者がいます。サーバーはプロンプトを送信した認証情報から作成者を読み取ります。作成者はプロジェクトメンバー、または別のセッションのエージェントです。ランタイムのトランスクリプトには含まれません。

const { authors, initial_author } = await beeuni.session(projectId, sessionId).messageAuthors()
// getSessionMessageAuthors(projectId, sessionId) is the same call as a function.

const author = authors[runtimeMessageId] // undefined when the sender is unknown

authors はランタイムのメッセージIDをキーとします。initial_author は、生成されたセッションの最初のメッセージに対する親セッションです。セッションに最初のプロンプトがなかった場合は null です。各作成者は SessionMessageAuthor です。

ターンに応答したモデル

トランスクリプトのメッセージには、そのターンで要求したモデル名が記録されます。プロジェクトのフォールバックチェーンが別のモデルで応答した場合、応答したモデルとBeeuniの請求額が記録されるのは、ゲートウェイのリクエスト記録のみです。

const { latest, billed_cost, turns } = await beeuni.session(projectId, sessionId).modelUsage()
// getSessionModelUsage(projectId, sessionId) is the same call as a function.

latest?.served_model   // 'glm-5.3-flash': the model that answered the newest request
latest?.fallback_from  // 'codex/gpt-6.1-sol' when a fallback model answered, else null
turns[userMessageId]   // { served_models, fallback_from, billed_cost } for one turn

最初の応答前は、latest は null です。billed_cost は、セッションのモデル呼び出しに対してBeeuniが差し引いた米ドル額です。turns は、各ターンを開始したプロンプトのランタイムメッセージIDをキーとします。served_models は、そのターンで応答したモデルをリクエスト数の多い順に一覧表示します。Reactでは、useSessionModelUsage(projectId, sessionId) が同じ記録を読み取ります。ターンが終了したら、その refetch() を呼び出してください。

Reactでは、useSessionMessageAuthors(projectId, sessionId, messageCount) が同じデータを読み取ります。トランスクリプトのメッセージ数を渡してください。作成者が追加されるのは新しいメッセージが届いたときだけなので、メッセージ数が変わるとクエリが再取得されます。

準備完了の確認はハンドシェイク

プロンプトを送信する前に、ensureReady() を呼び出してください。必要に応じてサンドボックスをプロビジョニングし、ランタイムの起動を待ち、解決されたランタイムを返します。

const { runtimeSessionId, runtimeUrl, sandboxId } = await s.ensureReady();

コールドブート時には、ensureReady() が RUNTIME_UNAVAILABLE をスローすることがあります。その意味と再試行方法については、コールドブート時の再試行を参照してください。

s.send() と s.abort() は、ensureReady() を代わりに呼び出します。

サーバーが認可したランタイムセッションピンを初期値として設定する

サーバーレンダリングされるReactホストは、同じBeeuniセッションにすでに永続化されているランタイムセッションピンを渡せます。

const session = useSession(projectId, sessionId, {
  initialRuntimeSessionId: persistedSession.runtime_session_id ?? persistedSession.opencode_session_id,
});

この初期値は、/start の実行中にキャッシュ済みトランスクリプトの内容をハイドレートするだけです。ランタイムの識別情報を上書きしません。/start が返すピンが正となり、古い初期値を置き換えます。

opencode_session_id は runtime_session_id の非推奨の名称です。どちらも同じ値を持ちます。旧名称は上記のフォールバックとしてのみ読み取ってください。

信頼できないテナントセレクターからこの値を受け取らないでください。ホストでランタイムセッションを作成しないでください。Beeuniがルートセッションを作成して永続化します。ランタイムのクエリキャッシュとトランスクリプトコントローラーはサンドボックスのランタイムをスコープとするため、異なるサンドボックスでランタイムセッションIDが同じでも、キャッシュエントリは共有されません。

セッションを切り替えても、保留中のメッセージの再試行は元のサンドボックスURLを保持します。404 または 410 のメッセージ応答は、トランスクリプトを消去せずに自動再試行を停止します。明示的な再照合では読み取りを再試行でき、応答が成功すると通常の同期を復元できます。

プロンプトを送信する

s.setModel({ providerID, modelID }); // sticky for later send() calls
s.setAgent('build'); // sticky for later send() calls

await s.send('Refactor the auth module');
await s.send('One-off task', { model, agent }); // overrides for this call only
await s.abort(); // stop the current run

send() は、セッションの永続的なプロンプト受信箱（POST .../prompts）にプロンプトを入れます。これはWebの入力欄とCLIが使う経路です。ターンの終了時ではなく、プロンプトの保存時に、受信箱の行（prompt_id、state、message_id）を返して解決します。返信は s.stream() またはトランスクリプトから読み取ってください。

実行環境 RESTセッションでは、ハンドルに対する最初の send() が、Beeuniセッションに永続化されたモデルとエージェントを読み取ります。これにより、スナップショットから継承された実行環境セッションが古いスナップショットのデフォルトを再利用するのを防ぎます。

プロンプトの選択の優先順位は次のとおりです。

1. send() の呼び出し。
2. ハンドルの setModel() または setAgent() の値。
3. 永続化されたBeeuniセッションのデフォルト。

setModel は、次のローカルな send が何を要求するかを選ぶだけで、ハンドルの外には出ません。実行中のセッションの新しいモデルをサーバー側で永続化するには、changeModel を使います。

const { applied_live } = await s.changeModel('anthropic/claude-opus-4-8');

変更はランタイムの再起動によって反映されるため、進行中のターンは終了します。applied_live は、実行中のセッションに即時適用された場合は true、次回起動時に適用される場合は false です。モデルを変更できるのはセッションの所有者、またはプロジェクトマネージャー権限を持つ呼び出し元のみです。それ以外には 403 が返されます。

send() はランタイムを解決してから、プロンプトを送信します。abort() はセッションを削除せずに現在の実行を停止します。

セッションのスコープとコスト

保存されたシークレットの制限範囲と、具体化された接続バインディングを読み取ります。 secrets_allowlist: null は、エージェントのシークレット許可が適用されることを意味します。

const scope = await s.scope();
scope.connector_bindings_configured; // false = inherits the project defaults

connector_bindings は解決済みのマップなので、コネクターを上書きしたセッションでも、プロジェクトのデフォルトを継承するセッションでも同じように見えます。スコープを表示したり返送したりする前に、connector_bindings_configured を読み取って両者を区別してください。

スコープフィールドの一方または両方を置き換えます。

await s.rescope({
  secrets: ['DATABASE_URL'],
  connector_bindings: {
    github: { connection_id: connectionId },
  },
});

指定した各フィールドは、それまでの値全体を置き換えます。変更しないフィールドは省略してください。接続の変更は、次のツール呼び出しに適用されます。 シークレットを削除すると以後の配信は停止しますが、すでに開示された値をモデルのコンテキストや既存のプロセスから削除することはできません。

どちらの軸にも、明示的にデフォルトへ戻す方法があります。空の値とは異なります。

await s.rescope({
  secrets: null, // inherit the agent's secret grant
  connector_bindings: null, // drop the override; inherit the project defaults
});

secrets: [] と connector_bindings: {} は逆の指示で、プロジェクトのデフォルトも含めて、明示的に「プロジェクトのシークレットなし」「コネクターを一切使用しない」を指定します。null を意図して {} を送信したセッションでは、指定しなかったすべてのエイリアスへのアクセスが拒否されます。

統合コストレコードを読み取ります。

const cost = await s.cost();

このレコードには、確定した LLM コスト、請求対象のサンドボックス計算コスト、モデル使用量、トークン合計、計算時間、台帳エントリがまとめられています。s.cost() は ensureReady() を呼び出しません。

ランタイムの状態とプレビュー

const { ok, health } = await s.health();
const url = s.previewUrl(3000, '/docs');

s.health() は例外をスローしません。セッションにランタイムがまだない場合も含め、いつでも呼び出せます。s.previewUrl() と s.proxyUrl() には解決済みのランタイムが必要です。先に s.ensureReady() を呼び出してください。そうしないと SessionNotReadyError がスローされます。セッション準備状態のエラーを参照してください。

ランタイムがサポートする機能

health.capabilities は、ランタイムが提供するセッション機能の一覧です。runtimeSupports(capabilities, capability) で機能を読み取り、false が返された場合は、そのコントロールを非表示にしてください。実行環境 セッションは全 10 機能を提供します。pi セッションは session.subagents のみを提供し、その他には 501 feature_not_supported（設定ドキュメントには 404）を返します。実行環境 と pi の完全な対応表はハーネスにあります。

import { runtimeSupports } from '@beeuni/sdk';

const { health } = await s.health();
if (!runtimeSupports(health?.capabilities, 'session.compact')) hideCompact();

runtimeSupports は、ヘルス応答が届く前と、session.* ケイパビリティを列挙しないランタイムに対して、true を返します。ケイパビリティの導入前にビルドされたデーモンは 実行環境 を実行し、すべての機能を提供するためです。React では、useRuntimeSupportsを使用してください。

start の応答にも一覧が含まれ、SessionStartResult.capabilities は stage: 'ready' とともに設定されます。useSession がこれを記録するため、最初のヘルスプローブが応答する前から、ケイパビリティによる機能の出し分けが正しく行われます。

ステータス用語

すべてのホストが同じ語彙を使うため、同じ状態はどの画面でも同じ言葉で表示されます。

トーンは actionable、live、progress、muted、danger です。緑は live と actionable にのみ使用します。終了したセッションは muted です。新しい API が送信した、このビルドでは未知のステータスは stopped と表示され、failed にはなりません。

ストリーミング

スクリプトやサーバーでライブイベントを受信するには、s.stream() を使用してください。React アプリでは、代わりに useSessionを使用してください。セッションのライフサイクル全体を管理します。

s.stream() は、実行環境 REST 互換のイベントストリームです。Beeuni API がサンドボックスからプロキシします。独立した WebSocket エンドポイントはありません。トランスポートはストリーミング応答ボディを持つ fetch で、ReadableStream と TextDecoderStream を通じて読み取ります。SDK が再接続、バックオフ、ハートビートチェックを処理します。

セッションをストリーミングする手順：

1. 最初に ensureReady() を呼び出します。サンドボックスが起動するまで、ランタイムは存在しません。
2. 初期のイベントを取りこぼさないよう、メッセージを送信する前にストリームを開きます。
3. メッセージを送信します。
4. session.idle を確認したら、ストリームを閉じます。

const session = beeuni.session(projectId, sessionId);
const { runtimeSessionId } = await session.ensureReady();

const stream = await session.stream({
  onEvent: (event) => {
    if (event.type === 'session.idle' && event.properties.sessionID === runtimeSessionId) {
      onTurnDone();
      stream.close();
    }
  },
});

await session.send('Refactor the auth module');

ストリームは、16 ms 間隔でイベントをバッチ配信します。バッチ内で同じパーツフィールドに対する message.part.delta イベントが連続すると、1 つのイベントとして届きます。その properties.delta は各イベントのテキストを順番に結合したものです。id は最後のイベントの ID です。coalesced 配列には、置き換えられたイベントが列挙されます。単一のデルタと同様に、delta をパーツのフィールドに追加してください。

ストリーミングには、実際の ReadableStream ボディと TextDecoderStream を備えた fetch が必要です。ブラウザー、Node 18 以降、Bun、Cloudflare Workers はすべてこれをサポートしています。

fetch がストリーミングできないホストは、独自のトランスポートを提供します。SDK は接続ごとにそれを 1 回呼び出し、再接続、Last-Event-ID による再開、バックオフ、ハートビートは引き続き自身で処理します。

import { configureBeeuni, notifyHostSignal, type RuntimeEventTransport } from '@beeuni/sdk';

const transport: RuntimeEventTransport = async function* ({ url, headers, signal }) {
  // Yield { data, id?, retry? } for each server-sent message of ONE connection.
  // Return when the server ends it. Throw (with `status` for a non-2xx answer)
  // when it fails.
};

configureBeeuni({ backendUrl, getToken, eventStreamTransport: transport });

// A host without `visibilitychange` / `online` events reports them itself.
notifyHostSignal('visible'); // the app is back in the foreground
notifyHostSignal('online');  // the network is back
notifyHostSignal('retry');   // a person asked to reconnect now

React Native には、デフォルトでストリーミング対応の fetch がありません。Beeuni モバイルアプリは、react-native-sse を使ってこの拡張ポイントを利用します。範囲を限定した履歴とステータス同期だけが必要なホストでは、引き続き createHttpSessionSyncController を利用できます。

コントローラーは、最初に最新の 10 件のメッセージを読み込みます。loadOlder() はサーバーのカーソルをたどります。loadHttpSessionHistory() は、明示的なエクスポートのためにすべてのカーソルをたどります。

イベントの種類

各イベントには、type と、そのデータを保持する properties オブジェクトがあります。例：event.properties.sessionID。

classifyTurn を使って、生のメッセージとパートを描画可能な出力に変換します。 SDK リファレンスを参照してください。

コールドブート時の再試行

ensureReady() はセッションの /start エンドポイントをポーリングします。各呼び出しは最大 30 秒間ロングポーリングし、ランタイムが終端ステージ ready/failed/stopped に達するか、 期限（readyTimeoutMs、デフォルトは約 180 秒）が過ぎるまで続けます。ウォームセッションでは、 最初のポーリングで即座に ready が返ります。コールドブートでは、サンドボックスが retriable: true を報告している間ポーリングを続けるため、起動が遅くても例外をスローせず、 時間が長くかかるだけです。期限が切れた場合にのみ、code: 'RUNTIME_UNAVAILABLE' if the runtime is still not ready を伴う ApiError を スローします。

ensureReady() は冪等なので、同じセッションへの同時呼び出しは複数のリクエストを送らず、 1 つの /start リクエストを共有します。以下の retryUntilReady ヘルパーは 現在は任意です。ensureReady() がすでに内部で再試行するためですが、デフォルトの readyTimeoutMs より長い合計待機時間を確保したい場合には引き続き役立ちます。

async function retryUntilReady<T>(ensure: () => Promise<T>): Promise<T> {
  const deadline = Date.now() + 300_000;
  for (;;) {
    try {
      return await ensure();
    } catch (error) {
      const provisioning = error instanceof ApiError && error.code === 'RUNTIME_UNAVAILABLE';
      if (!provisioning || Date.now() > deadline) throw error;
      await new Promise((r) => setTimeout(r, 3_000));
    }
  }
}

ApiError の完全な構造は、エラークラスを参照してください。React では、 useSession が /start を再試行するため、このパターンは 不要です。

/start が伝える情報

/start の各応答が示すのはその呼び出しの内容であり、行に蓄積された 履歴ではありません。4 つのフィールドがその情報を伝えます。

boot.actively_starting は「このセッションで今、プロバイダーの操作が実行中か？」に 答えます。actively_starting: false を伴う starting ペイロードは、 サーバーが再試行のクールダウン終了を待っていることを意味し、マシンが起動中という意味ではありません。

{
  "stage": "starting",
  "retriable": true,
  "reason": "runtime_wake_cooldown",
  "observed_at": "2026-08-26T14:00:00.000Z",
  "action": "cooling_down",
  "boot": { "phase": "resuming", "since": "2026-08-26T13:58:00.000Z", "actively_starting": false },
  "observation": {
    "provider": { "known": false, "status": null, "checked_at": null },
    "runtime": { "known": false, "state": null, "boot_phase": null, "checked_at": null }
  },
  "failure": {
    "category": "sandbox-provider",
    "message": "The runtime did not start (attempt 2). Retrying automatically.",
    "retryable": true,
    "evidence": {
      "check": "provider_not_running",
      "observed_at": "2026-08-26T13:58:00.000Z",
      "error": null,
      "attempts": 2,
      "next_retry_at": "2026-08-26T14:03:00.000Z"
    }
  }
}

起動に失敗すると自動で再試行されます

起動に失敗すると、恒久的な判定ではなくクールダウンが記録されます。クールダウン後の 次の /start は、自動で再び起動を試みます。クールダウンは 連続失敗に応じて長くなります（2 分、5 分、10 分）。5 回連続で 失敗すると、/start は stage: "failed" を返し、試行回数を failure.message に含めます。この判定は最後の失敗から 30 分後に失効し、 POST …/restart は即座に解除します。

retriable は呼び出しごとに導出されます。サーバーがまだ再試行できる状態には、 retriable: false が付くことはありません。

failure.evidence は、否定的な結果を出したチェック、その実行時刻、 サーバーの再試行時刻を示します。/start の失敗には必ずこれが含まれます。

プロンプトの添付ファイル

ユーザーが入力欄にローカルファイルを追加したらアップロードします。非公開のアップロードは プロジェクトに属し、実行中のセッションは不要です。

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

const uploads = usePromptAttachments(projectId);
// File picker, paste, and drop handlers call uploads.add(file) or uploads.addMany(files).
// Render uploads.attachments. Refuse Send only while an attachment is `error` or `aborted`.

async function submit() {
  const ids = uploads.attachments.map((item) => item.id);
  uploads.submit(ids); // Send never waits: the composer clears and uploads continue.
  paintMessage(text, ids);
  try {
    const parts = await uploads.whenReady(ids);
    await beeuni.session(projectId, sessionId).prompts.create({
      clientMessageId,
      messageId,
      parts: [{ type: 'text', text }, ...parts],
    });
    uploads.forget(ids);
  } catch {
    uploads.reclaim(ids);
  }
}

whenReady(ids, { signal }) はすべてのアップロードが準備できると、ids の順序で解決されます。 アップロードが失敗、中止、削除された場合、または signal が中止された場合は拒否されます。 submit(ids) はエントリをその送信に引き渡します。エントリは attachments から外れ、 制限の計算対象ではなくなり、入力欄がアンマウントされてもアップロードを続けます。 POST が成功したら forget(ids) を呼び出し、送信に失敗した場合は reclaim(ids) を呼び出して 入力欄に戻します。 解決されたファイルパートには attachment_id、filename、mime が含まれます。 URL やファイルのバイトデータは含まれません。サーバーがアップロードを紐付け、実体化します。 画像や PDF を含め、すべてのファイルがセッションのコンピューターに届きます。プロンプトの 実行前にサーバーが /workspace/uploads/.beeuni-inbox/ に書き込み、 プロンプトはパスで参照します。プロンプト自体にファイルのバイトデータは含まれません。 履歴保存が有効なら、サーバーは会話記録用のコピーも保持します。コピーに失敗しても、 ファイルがコンピューターに届くことは妨げられません。サーバーがファイルを書き込めない場合は プロンプトが保留され、再試行されます。 これらのパートは、プラットフォームのセッション作成、ウォームセッションの開始、またはプロンプト受信箱の ルートで使用してください。非公開ハンドルを 実行環境 ランタイムの sendParts に直接渡さないでください。 url を持つ従来のプラットフォームのファイルパートも引き続き使用できます。

各項目には、安定した id、元の file への参照、receivedBytes、および ステータス（pending、uploading、processing、ready、error、aborted）があります。 進捗は送信済みバイト数で決まります。コントローラーはパーセントの整数値が変わったときだけ、 アップロードごとに毎秒最大 10 回、進捗スナップショットを公開します。processing は サーバーがアップロードを完了するまで 100% のままになることがあります。制限はファイルごとに 50 MiB、 メッセージごとに 100 MiB、ファイル数は 20 個です。空のファイルは使用できません。デフォルトでは 2 つのファイルを同時にアップロードします。

retry(id) は同じハンドルで再開します。attachment_size_mismatch または attachment_failed の後はサーバーに使用可能なハンドルが残らないため、retry(id) は File を新しい添付ファイルとして再アップロードします。期限切れのアップロードは再試行できません。retry(id) は 例外をスローし、項目のエラーにはコード attachment_expired が含まれます。abort(id) は 未完了の処理をキャンセルします。 remove(id) はエントリを削除し、アップロードを中止して、即座に解決されます。 サーバーの DELETE はベストエフォートで行われ、拒否されることはありません。削除できないアップロードは 24 時間後に失効します。 forget(ids) はサーバー上のオブジェクトを削除せずにエントリを解放します。 フックはアンマウント時またはプロジェクト変更時に、一覧内の処理を中止し、アップロードを ベストエフォートで削除します。どの送信もそれらを保持せず、下書きにもハンドルは残りません。引き渡し済みのアップロードは 続行します。

選択内容はメモリ内にのみ存在します。File オブジェクト、blob URL、署名付き URL、アップロードハンドルを下書きに永続化しないでください。放置されたアップロードは 24 時間後に失効します。

フレームワークを使わないホストでは、同じメソッドを持つ beeuni.project(projectId).attachments.createController() を 使用します。subscribe(listener) を通じて購読し、 getSnapshot() を読み取ります。入力欄を閉じるときは dispose() を呼び出してください。 直接呼び出す場合は attachments.upload(file, { signal, onProgress, onUpload, resume }) and attachments.delete(attachmentId) を使用できます。 同じ ID で手動再開するために、onUpload メタデータを保持してください。

サーバーはハンドルの upload フィールドで転送方式を選択します：

• デフォルトは kind: 'direct' です。SDK はファイル全体を 1 回の PUT で upload.url に送信します。upload.headers を使用し、Authorization ヘッダーは付けません。 XMLHttpRequest（ブラウザー、React Native）では、進捗は送信済みバイト数を報告します。 fetch では、進捗は 0、次にファイルの全サイズを報告します。URL の有効期限が切れた場合、または Storage が 400、401、403 で拒否した場合は、同じ attachment_id に対して 1 回だけ再署名します。Storage からの 409 は、以前の試行でファイルが保存されたことを意味します。
• kind: 'chunked' は、認証付きの PUT を upload.chunk_size バイトずつ順に送信します。SDK は正の chunk_size をすべて受け付けます。エッジが 大きなリクエストボディを破棄するデプロイのみが、このモードを選択します。

完了処理では、保存されたサイズと SHA-256 を検証します。完了処理が 409 attachment_not_uploaded, onUpload を返した場合、直接ハンドルを received_bytes: 0 とともに報告するため、retry(id) または再開によってファイルが再送信されます。 開始、アップロード、完了処理は、タイムアウト、ネットワークエラー、429、 5xx に対して、ジッター付き指数バックオフで再試行します。再試行の制限時間は最初の 失敗から 60 秒なので、長いアップロードが終盤で失敗しても再試行されます。完了処理では attachment_processing も再試行し、制限時間は 5 分です。開始処理は 402 （BillingError：アカウントを実行できない）や 429 attachment_budget_exceeded（ユーザーあたり 未完了のアップロードが 40 件、または未送信のアップロードが 500 MiB。未使用のアップロードは 24 時間以内に期限切れになります）を再試行しません。サーバーは 1 回の完了処理に対して 105 秒以内に応答または拒否します。各完了リクエストの制限時間は 120 秒です。呼び出し元による中止は再試行しません。

送信済み添付ファイルの参照は、そのプロンプトが配信されてから 1 時間後、 およびそのセッションまたはプロジェクトが削除されたときに解放されます。その後、次のメンテナンス巡回で ファイルが削除され、その attachment_id は送信できなくなります。

ファイル

s.files はセッションのサンドボックスを読み書きします：list、read、readBlob、 status、findFiles、findText、upload、create、copy、remove、 mkdir、rename。すべての呼び出しは最初にランタイムを解決し、常に このセッション自身のサンドボックスを対象にします。メソッドの全一覧は SDK リファレンス を 参照してください。

セッションの操作メソッド

ハンドルがランタイムの読み取りと応答を代行します。各操作メソッドは最初に セッションをプロビジョニングし、実行するハーネスに関係なく、このセッション自身のサンドボックスを対象にします。

// A page of the transcript, oldest first: { info, parts } messages (beeuni.transcript.v1).
const { messages, hasMore } = await s.messages({ limit: 50 });
// What the agent waits on.
const { statuses, permissions, questions } = await s.pending();
await s.answerPermission(permissions[0].id, 'once'); // 'once' | 'always' | 'reject'
await s.answerQuestion(questions[0].id, [['Yes']]); // null dismisses the question
// Summarize the conversation. Needs the `session.compact` capability (see health()).
await s.compact();

生の REST 互換クライアントである s.runtime は非推奨です。上記の操作メソッドを send、abort、rewind、stream とともに使用してください。

プロジェクトセッションをウォームアップする

プロジェクトのランディングページで、最初のプロンプトの前にランタイムを 1 つ準備しておく必要がある場合は、 ensureWarm() を呼び出します。

const project = beeuni.project(projectId);
const warm = await project.sessions.ensureWarm();

// An ORDINARY session. Prompt it like any other.
await beeuni.session(projectId, warm.session.session_id).send("Build me a widget");

ensureWarm() は、現在のユーザー用に未使用のセッションを 1 つ作成するか、返します。 これは sessions.create() が実行するものと同じ作成処理で、プロジェクトのデフォルトを使用します。 課金条件もコネクター要件も同じです。唯一の 違いは metadata.warm で、最初のプロンプトが届くまで sessions.list() からセッションを非表示にします。

これは先行準備として扱ってください。409 WARM_SESSION_UNAVAILABLE は、プロジェクトを 今はウォームアップできないことを意味します。その場合は sessions.create() に進むと、 実際の理由が報告されます。

ウォームセッションはプロジェクトの DEFAULT エージェントとサンドボックスを使用します。ユーザーが 別のものを選んだ場合は、そのセッションを破棄して sessions.create() を呼び出してください。未使用のウォーム セッションは非表示になり、自動的に回収されます。

エラー処理

createBeeuni 経由のすべての呼び出しは、型付きの Error サブクラスで拒否され、 プレーンオブジェクトは返しません。エラーをキャッチし、instanceof を確認して、 .status または .code に応じて分岐してください。

import { ApiError, BillingError } from '@beeuni/sdk';

try {
  await beeuni.project(projectId).sessions.create();
} catch (err) {
  if (err instanceof BillingError) {
    // 402 — out of credits or over a plan limit
  } else if (err instanceof ApiError) {
    // any other failed request — err.status, err.code, err.detail
  } else {
    throw err;
  }
}

エラークラス

ApiError.name はデフォルトで 'ApiError' です。次の 2 つの場合は上書きされます。

• name: 'AbortError'、code: 'ABORTED' — 画面遷移などによってリクエストがキャンセルされました。これは失敗ではありません。無視してください。
• code: 'TIMEOUT' — リクエスト自体の制限時間が経過しました。url、endpoint、timeout が、何がタイムアウトしたかを示します。

その他の失敗では、status に HTTP ステータスコードが格納されます。code はバックエンドの error_code から取得され、なければステータスを文字列にしたものになります。message は ApiError の列挙可能な自身のプロパティなので、JSON.stringify やオブジェクトのスプレッドでも保持されます。

Beeuni は、401 を受け取ったリクエストを、getToken() から取得した新しいトークンで再度送信します。ただし、そのトークンが送信済みのものと異なる場合に限ります。一度しか使用できないストリームボディを持つリクエストは再送信しません。

Beeuni は、コードにエラーが届く前に一部のリクエストを再試行します。GET または HEAD リクエストが 502、503、504 を返した場合、Beeuni は 250ms、次に 500ms の間隔で最大 2 回再試行します。GET または HEAD で一時的なトランスポート障害（ステータスコードではなくネットワークエラー）が発生した場合も、同様に再試行します。再試行が成功した場合、onError には到達しません。Beeuni は POST、PUT、PATCH、DELETE リクエストや、500 レスポンスを再試行しません。

getToken() が null を返すと、Beeuni はリクエストを送信する前にクライアント側で AuthError をスローします。AuthError は ApiError を継承するため、err instanceof ApiError は引き続き一致します。「未サインイン」をバックエンド障害と別のケースとして扱うには、err instanceof AuthError または err.code === 'NO_SESSION' を確認してください。

Beeuni は、クレジット不足、プランの上限超過、その他の課金条件による、すべての HTTP 402 レスポンスに対して BillingError をスローします。detail.message にはバックエンドからの理由が、code にはバックエンドの機械可読コード（例：app_account_unfunded）が格納されます。BillingError は ApiError を継承するため、両方を処理する場合は先に BillingError を確認してください。

Beeuni は HTTP 431 に対して RequestTooLargeError をスローします。これは通常、リクエストに含まれるファイルが多すぎることを意味します。detail.suggestion には、そのままユーザーに表示できるヒントが格納されます。

セッションの準備状態に関するエラー

セッションのサンドボックスがまだ準備できていないことを示すエラーは 2 つあります。それぞれ異なる方法で処理してください。

SessionNotReadyError は、このセッションハンドルが自身のサンドボックスを解決する前にランタイムアクセサー（session.previewUrl() または session.proxyUrl()）を呼び出すと、同期的にスローされます。セッションハンドルは自身のサンドボックスのみを解決し、別のセッションのサンドボックスにフォールバックすることはありません。

import { SessionNotReadyError } from '@beeuni/sdk';

const s = beeuni.session(projectId, sessionId);
try {
  const url = s.previewUrl(3000); // throws: not resolved yet
} catch (err) {
  if (err instanceof SessionNotReadyError) {
    await s.ensureReady();
  }
}

まず await session.ensureReady() を呼び出すか、内部でセッションを準備する send() を呼び出してください。session.health() はこのエラーをスローしない唯一のアクセサーなので、セッションが起動する前でもポーリングできます。

RUNTIME_UNAVAILABLE は2つ目のエラーで、ensureReady() 自体がコールドブートを待っている間にタイムアウトしたことを意味します。完全なパターンについては、コールドブート時の再試行を参照してください。React では、useSession がこの再試行を行い、スローする代わりに phase の値を通じてエラーを公開します。

ヘルパー

import { formatBillingErrorForUI } from '@beeuni/sdk';

try {
  await beeuni.session(projectId, sessionId).start();
} catch (err) {
  const ui = formatBillingErrorForUI(err);
  if (ui) showUpgradeModal(ui.alertTitle, ui.alertSubtitle);
}

@beeuni/sdk/react での利用

@beeuni/sdk/react は BillingError、RequestTooLargeError、parseBillingError、isBillingError、formatBillingErrorForUI を再エクスポートします。ApiError と AuthError は再エクスポートしません。これらは @beeuni/sdk からインポートしてください。

useSession は、send、answerQuestion、answerPermission、rejectQuestion のすべての失敗を1つの sendError オブジェクトに分類するため、instanceof のチェックを手動で記述する必要はありません。

interface BeeuniSendError {
  kind: 'billing' | 'runtime-not-ready' | 'runtime-error';
  message: string;
  billing?: BillingError; // set when kind is 'billing'
  cause: unknown;
}

const s = useSession(projectId, sessionId);

if (s.sendError?.kind === 'billing') {
  const ui = formatBillingErrorForUI(s.sendError.billing);
}

useSession のその他の内容については、React フックを参照してください。