SDKリファレンス

@beeuni/sdk APIの全体 — クライアントメソッド、モジュール、ターン、配布。

このページでは、@beeuni/sdk の全 API を紹介します。すべてのクライアントメソッド、 フレームワークに依存しないモジュール、ターンのヘルパー、パッケージの配布形式を扱います。 使い始めるには SDK を、セッションのライフサイクルの詳細については セッション を参照してください。

クライアント

createBeeuni(config) は 1 つのクライアントを返します。各メソッドは、プラットフォーム API への型付き呼び出しです。 project(id) と session(pid, sid) のハンドルは ID をバインドするため、 繰り返し指定する必要はありません。

const beeuni = createBeeuni({ backendUrl, getToken });

beeuni.accounts; // account / team operations
beeuni.accountInvites; // invite accept/decline by token alone
beeuni.projects; // top-level project operations
beeuni.connectors; // Connector calls scoped by an agent-minted token
beeuni.connector(slug); // one connector in the token's scope → see p.connector(slug)
beeuni.project(id); // id-bound project handle
beeuni.session(pid, sid); // id-bound session handle → see Sessions
beeuni.github; // GitHub App install + repo linking (account-scoped)
beeuni.gitBackend; // the instance git backend ("Beeuni managed")
beeuni.billing; // credits, subscription, tier, transactions
beeuni.sandboxShares; // public share links for a sandbox port
beeuni.connectStatus; // easy-connect status
beeuni.marketplace; // public marketplace catalog
beeuni.validateToken; // pasted-API-key check
beeuni.config; // platform config in effect
beeuni.runtime(); // 実行環境 REST compatibility client

アカウント — beeuni.accounts

accounts.tokens はアカウントスコープの API キー（beeuni_pat_...）を発行します。 トークンモデルの詳細は SDK 認証 を参照してください。

accounts.audit はエンタープライズ向けの再構成ログです。認証済みの API リクエストと、 セッション、コネクター、承認、コンピューターに関する意味情報を持つイベントを統合します。

各イベントには、アクションが提供する場合、project_id、session_id、actor_type、source、outcome、 request_id、trace_id、correlation_id が含まれます。 API は、リクエスト本文、プロンプト、シークレット、認証情報、未加工のコネクター引数を 集約イベントに保存しません。コネクターイベントには、認証情報らしきフィールドと不透明なデータを伏せた、 範囲を限定した引数プレビューを含めることができます。

アクセスの割り当て

Beeuni の権限付与レコードは assignment（割り当て） の 1 種類です。1 つのプリンシパル（user、 group、service_account、pending）を、1 つのスコープ（account または 1 つの project）で 1 つのロールにバインドします。任意で 1 つのオブジェクト（agent、skill、secret、 app、trigger）に限定したり、expires_at を付加したりできます。グループアクセス、 リソースごとのアクセス、カスタムロールのバインドはすべて割り当てです。モデルについては アカウントとアクセス を参照してください。

標準の REST API は次のとおりです。

SDK では、これらを listAssignments、createAssignment、 revokeAssignment、listPermissions として公開しています。カタログの各行には action、 scope_type、resource_type、delegable、description、area、level、 implies が含まれます。アクション文字列をハードコードせず、これを読み取ってください。

カスタムロールの割り当てには、アカウントの rbac 利用資格が必要です。これがない場合、ルートは code: "entitlement_required" を伴う 402 を返します。

アカウントへの招待 — beeuni.accountInvites

招待トークンだけでアクセスできます。招待された人は、まだメンバーでない場合があります。

プロジェクト — beeuni.projects

provision は新しいプロジェクトを作成します。既存プロジェクトの サンドボックスは起動しません。代わりにセッションを開始してください。セッション を参照してください。

再読み込み、別のタブ、タイムアウト後の再試行など、再試行が起こり得る場合は idempotency_key を送信してください。provision は呼び出しごとに新しい管理対象リポジトリを作成するため、 キーがなければ、それぞれが実際に重複プロジェクトを作成します。論理的に 1 回の作成に対するすべての 試行で同じキーを使うと、繰り返しの呼び出しは最初の試行で作成したプロジェクトを返します （201、同じ project_id、push_token: null）。キーが識別するのは 試行であり、ペイロードではありません。異なる name で同じキーを再利用すると、最初の プロジェクトを返し、新しい値を無視します。そのため、別の作成ごとに新しいキーを発行してください。 キーなしで同じ名前の 2 つ目のプロジェクトを作成することもできます。

最初の呼び出しがまだプロビジョニング中に繰り返しの呼び出しが届くと、その呼び出しがまだロールバックする可能性のある project_id ではなく、code: 'provision_in_flight' を伴う 409 が返されます。 同じキーで再試行してください。

project(id).sessions.list({ scope: 'project' }) は、プロジェクト管理者権限を持つ 呼び出し元向けのライフサイクル一覧です。アクセス可能な、利用不可、ウォーム状態、ソフト削除済みのセッションを、 所有者とランタイム状態のメタデータ付きで追加します。どちらの一覧スコープも、 呼び出し元が開けないセッションはすべて除外します。

sessions.list と sessions.listPage は、階層と帰属の フィルターも受け付けます。指定しなければ、一覧はフラットなまま変わりません。

各セッション行には parent_session_id と initiator （{ type: 'member' | 'trigger' | 'channel' | 'api' | 'system', id, label }）があります。 initiator は実行全体を開始した人を示し、子は親の値をコピーします。 sessionParentId(session) は parent_session_id、次に従来の metadata.spawned_by_session を読み取ります。カーソルは、それを発行したフィルターの組み合わせでのみ 有効です。

GitHub — beeuni.github

GitHub App のインストールとリポジトリのリンクは、プロジェクトスコープではなくアカウントスコープです。

このリストには実際のアカウント接続だけが含まれます。「Beeuni managed」は 含まれません。これは以下のインスタンスバックエンドです。

インスタンスのgitバックエンド — beeuni.gitBackend

デプロイ全体で1つの所有者と認証情報を使用し、Beeuni管理の リポジトリに使います。アカウント接続になることはなく、 beeuni.github.listInstallationsにも表示されません。

請求 — beeuni.billing

クレジット、サブスクリプション、プラン、取引履歴を取得します。支払いやクレジット購入には Beeuni の決済と請求管理を使用します。

sessionCosts.list()はaccountId、projectId、limit、offsetを受け付けます。 各行は、確定したLLM費用と請求済みのサンドボックス計算費用をまとめたものです。 sessionCosts.get()はモデル使用量と、LLM/計算を区別した台帳を追加します。 リストには、セッションに紐づかない費用の照合用合計も含まれます。

サンドボックス共有 — beeuni.sandboxShares

公開されたサンドボックスポート1つに対する公開共有リンク。 プロジェクト単位ではなく、サンドボックス単位です。

マーケットプレイスカタログ — beeuni.marketplace

公開カタログの閲覧専用。プロジェクトにアイテムをインストールする project(id).marketplaceとは異なります。

通知 — beeuni.notifications

すべてのアカウントとプロジェクトにわたる呼び出し元の通知。サインインした 各ユーザーは、受信トレイ1つ、設定レコード1つ、ブラウザー用のWeb Pushサブスクリプションを持ちます。 すべてのメソッドに個人の認証情報が必要です。サービスアカウントには 403が返されます。

const page = await beeuni.notifications.list({ limit: 20 });
await beeuni.notifications.markRead({ ids: [page.notifications[0].id] });
await beeuni.notifications.updatePreferences({ kinds: { turn_done: { push: false } } });

種類（InboxNotificationKind、INBOX_NOTIFICATION_KINDSに記載）：

DEFAULT_NOTIFICATION_PREFERENCESがこれらのデフォルト値を保持します。受信トレイの行は 常に書き込まれ、設定が決めるのはプッシュとメールだけです。ダイジェストメールには、 到着から15分後も未読の行が記載され、送信は1時間に最大1通です。 email_availableがfalseの場合はメール列を非表示にしてください。

各行のurlはその対象を開きます。?notification=<id>クエリにより、 ページはその行を既読にできます。

セッションハンドルは、1つのセッションに対する呼び出し元のウォッチ状態を保持します。

プロジェクトハンドル — beeuni.project(id)

プロジェクトIDをバインドします。すべてのサブリソースはこれに紐づきます。

const p = beeuni.project(projectId);
await p.detail();
await p.update({ name });
await p.llmCatalog();

p.tokens — プロジェクトスコープのAPIキー

セッション作成時にBEEUNI_TOKENとして自動発行されます。手動でも発行できます。

p.setupLinks — エージェントが発行するセットアップリンク

プロジェクト全体へのアクセス権なしで、ユーザーが開いてシークレットを入力したり、アプリを接続したりできるリンクです。

p.apps — Apps（リリース、マシン、ボリューム）

プロジェクト機能appsで有効になります。ガイド：SDK → Apps。

p.secrets — プロジェクトのシークレット

コンシューマーsandboxを指定したruntimeは、環境変数による公開です。これがデフォルトで、セッションに平文の値を配置する唯一のポリシーです。コンシューマーnetworkを指定したegressは、エグレス強制による公開です。セッションはハンドルを保持し、Beeuniがサンドボックスの外で、ポリシーに列挙されたHTTPSホストに限り実際の値を代入します。エグレス強制による公開は実験的機能で、secrets_egress機能フラグ（Settings → Feature flags）が必要です。フラグがオフの場合、エグレスポリシーを指定したsetStrategy(identifier, 'egress', …)とupsert(...)は403 feature_disabledを返します。すべてのbrokerコンシューマーは、セッション内には一切存在しません。シークレットを参照してください。broker(...)メソッドには、セッションスコープのトークンとアクティブなセッションハンドルが必要です。

p.access — プロジェクトの割り当て、招待、リクエスト

ここにあるすべてのメソッドは、このプロジェクトにスコープを限定した割り当てを読み書きします。プロジェクトのロールはmanagerとmemberです。

p.access.resourceGrantsはオブジェクト割り当てビューです。プリンシパルの対象を、プロジェクト全体ではなく、プロジェクト内の1つのオブジェクトに限定します。Beeuniは現在、エージェントとスキルにオブジェクト割り当てを適用しています。エージェントはデフォルトでアクセス不可です。メンバーは、自分自身または所属グループのいずれかが割り当てに指定されている場合にのみアクセスできます。オブジェクト割り当て自体には権限はなく、プロジェクトマネージャーにもメンバーと同じ制限が適用されます。

p.connector(slug) — 単一のコネクタ

options：account、approvalContext、timeoutMs（デフォルト90 000）、signal。beeuni connectors typesのファイルを使うと、引数と出力に型が付きます。

p.connectors — ツールコネクタ

p.connectors.discoverは直接接続コネクタのカタログを閲覧します。これは実験的機能で、デフォルトではオフです。プロジェクトごとにSettings → Feature flags → “Connectors API Discover”で有効にしてください。Easy Connectが引き続きデフォルトのコネクタマーケットプレイスです。

p.connectors.pipedream は旧マネージド OAuth 接続の互換経路です。listApps は OAuth アプリのみを返します。新しいマネージド連携には Easy Connect を使用してください。API キーを使うアプリは直接接続してください。

コネクターはツール、プロバイダーアプリ、ポリシーを定義します。connections は 接続済みのアカウントを保存します。1 つのコネクターに複数のアカウントを併存させられます。 セッションでは connector_bindings: { alias: { connection_id } } で全呼び出しに使うアカウントを固定でき、 個別の呼び出しでは call(tool, args, { account }) でアカウントを指定できます。 認証情報は暗号化されたまま保持され、リクエストごとに解決されます。

connections が唯一の有効な認可ファサードです。廃止された authorizations と profiles は、現在の SDK インターフェースには含まれません。

アカウントと呼び出し時のアクセス判定

各接続には owner_type があります。project（共有 — コネクターの利用権限を 付与された人間またはサービスアカウントがアクセス可能）か、member（非公開 — 所有者本人が非公開セッション内でのみアクセス可能。サービスアカウントは アクセス不可）のいずれかです。共有アカウントの利用範囲はグループや個人に限定できます。 connections.list() は付与された権限を shared_with に返し、 connectionSharedWithEveryone(connection) はプロジェクトの全員が利用できるかを返します。 利用範囲を限定したアカウントは、指定された人に対して非公開アカウントのルールに従います。 usable: false は、呼び出し元が管理目的でのみ表示できるアカウントを示します。 createAssignment / revokeAssignment（object: { type: 'connection', id }）で権限を付与または取り消せます。 共有アカウントを利用できる人を選ぶを参照してください。 p.connectors.accounts(slug) は、呼び出し元がアクセスできるすべてのアカウントを、 デフォルトを先頭にして一覧表示します。

const accounts = await beeuni.project(projectId).connectors.accounts('stripe-read');
// [{ connection_id, label, owner_type, is_default }, ...]

await beeuni.project(projectId).connectors.call(
  'stripe-read.get_balance',
  {},
  { account: 'My Stripe' }, // a connection id, a label, or the words `me` / `project`
);

アカウントを指定しない呼び出しは、まず呼び出し元自身のデフォルトの非公開アカウント、 次にプロジェクトのデフォルトの共有アカウントに解決されます。指定したアカウントを 解決できない場合、connector_not_connected で拒否されます。別のアカウントに黙って 置き換えられることはありません。拒否には requested_account と available_accounts が記載されます。成功した呼び出しはすべて、実行に使ったアカウントを返します。 result.account = { connection_id, label, owner_type }。

セッション作成時のコネクターのアクセス判定はなくなりました。以前は、必須のコネクターに 利用可能な接続がないと、セッションが 409 CONNECTOR_CONNECTION_REQUIRED で拒否されていましたが、 この拒否は廃止されました（require_connectors は機能しません。 p.sessionsを参照）。アクセス判定は呼び出し時に移りました。 拒否された connector_not_connected には、呼び出し元向けに発行できる場合、ホストされた 認可リンク connect_url が含まれます。トランスクリプトの接続ボタンから ワンクリックですべて解決できます。

p.policies — プロジェクトのポリシー

p.triggers — cron、webhook、監視、イベントの自動化

トリガーは、スケジュール、受信 webhook、監視対象のコマンド、またはコネクター上のアプリイベントに応じてエージェントのアクションを開始します。 セッション戦略とペイロードのテンプレート化については、 トリガーを参照してください。

create(input) は { name, type: 'cron' | 'webhook' | 'monitor' | 'event', prompt_template, slug?, agent?, model?, enabled?, session_mode?, session_id?, cron?, run_at?, timezone?, secret_env?, connector?, event?, event_source?, event_account?, event_config?, session_access? }. name and prompt_template を受け取り、これらは必須です。 cron/run_at は同時に指定できません（type: 'cron'）。secret_env（webhook の HMAC シークレット）は type: 'webhook' に適用されます。

event トリガーには connector（コネクターのスラッグ）と event（eventTypes の タイプ ID）が必要です。event_account は任意で、そのコネクターの共有アカウントの ラベルです。null または省略時は、コネクターのデフォルトの共有アカウントを使います。 event_source は任意で、composio などのイベントソースアダプター ID です。null または省略時は コネクターのプロバイダーを使います。タイプ ID はそのアダプターに属します。event_config の構造は、そのタイプの config_schema によって決まります。 eventTypes と eventApps は、アダプターを source として返します。provider は非推奨のエイリアスです。 一覧の各トリガーには event: { connector, account, connected_as, type, config, source, provider, app, status: 'active' | 'needs_connection' | 'error' | 'pending', error, last_event_at } | null が含まれます。プロンプトテンプレートでは、イベントを {{ event.data.<field> }} と event.id、event.type、event.app、 event.connector、event.occurred_at として読み取れます。

session_access は、トリガーが作成するセッションを誰が開けるかを制御します。 形式は { mode: 'private' | 'members' | 'project', memberIds: string[], groupIds: string[] } and defaults to private です。このポリシーはアカウントローカルの実行時 状態です。ポータブルな beeuni.yaml マニフェストには含まれません。session_access のみを 更新しても Git コミットは作成されません。固定されたセッションは独自の共有 設定を維持します。プロジェクト管理者は、private または選択したメンバーのみのアクセスを 使うセッションも含め、トリガーが作成したセッションを常に開けます。

session_access はロールモデルに加わるリソース単位の可視性設定であり、 ロールではありません。特定のトリガーのセッションを誰が開けるかを決めます。 ロール判定で拒否された権限を付与することはありません。 アカウントとアクセスを参照してください。

p.marketplace / p.registry — インストール済みアイテム

カタログアイテムのファイルをプロジェクトのデフォルトブランチにインストールします。 registry.* は marketplace.* と同一のエイリアスです。

p.files — リポジトリのファイル（読み取り）

プロジェクトの git ツリーへの読み取り専用アクセスです。実行中のセッション内で ファイルを読み書きするには、セッションのファイル操作を使ってください。 下記のモジュール内のファイルを参照してください。

p.git — 履歴

p.changeRequests — ライフサイクルとマージ

変更リクエスト（CR）は、セッションの作業をデフォルトブランチにマージするための仕組みです。

p.sessions — およびセッションハンドル

セッションハンドルはランタイムの中核です。セッションを参照してください。

create(input) は、コネクター接続のスラッグをキーとする connector_bindings を受け取ります。 各値は connection_id を指定します。また、バックエンド由来のシークレットを絞り込むための secrets も受け取ります。require_connectors は非推奨で、効果はありません。このフィールドは引き続き受け付けられます（古いクライアントが送信しても拒否されません）が、読み取られることはありません。使用可能なアカウントがないコネクターを理由に、セッションが作成時に拒否されることはありません。アカウントと呼び出し時のゲートを参照してください。

p.approvals — コネクター承認受信箱

判断待ちの、コネクターによって制御されるアクションです。権限承認 UX（APPROVE / ASK / BLOCK）を支えます。

p.gateway — LLM の可観測性

このプロジェクトのモデルトラフィックに関するリクエストログ、コスト/レイテンシの集計、予算、ゲートウェイ API キー。

ルーティングポリシーには、デフォルトモデル、画像対応モデル、順序付きのフォールバックチェーンが含まれ、各モデルの試行は最大 1 回です。fallbackOn は transient または any-error です。

ゲートウェイが次のフォールバックモデルに移るのは、現在のモデルが出力を返す前に失敗した場合だけです。

• transient: ネットワークエラー、タイムアウト、任意の 5xx、または 402、403、429。
• any-error: 400 を含むすべての失敗。

出力開始後の失敗では、そのモデルのままになります。独自のプロバイダーキー（BYOK）を使ったリクエストが、Beeuni によって課金されるモデルにフォールバックすることはありません。各フォールバックモデルには、それぞれ固有の生成デフォルト設定が適用されます。

p.channels — Slack / メール / 音声

エージェントが Slack アプリやメールアドレスとして動作したり、リアルタイム音声通話に参加したりできるコネクターインターフェース。

p.modelDefaults — デフォルトモデルの設定

ゲートウェイによって解決される、アカウント、エージェント、プロジェクト単位のモデルのデフォルト設定。

p.setDefaultAgent — プロジェクトのデフォルトエージェント

p.setDefaultAgent(agentName) は、エージェントが宣言済みで有効になっていることを確認し、プロジェクトの beeuni.yaml 内で default_agent として設定します。新しいセッションでは、ユーザーが別のエージェントを選ばない限り、このエージェントが優先されます。

p.updateFeatureFlag — 機能フラグ

p.updateFeatureFlag(feature, enabled) は、プロジェクトの 1 つの機能フラグをオンまたはオフにします。enabled: null を渡すと上書き設定を解除し、プラットフォームのデフォルトに戻ります。正規の PATCH /v1/projects/:id/features を呼び出します。

feature は FEATURE_FLAG_KEYS のいずれかです（@beeuni/sdk からエクスポートされ、型は FeatureFlagKey）。呼び出し元にはプロジェクトの project.settings.write 権限が必要です。それ以外の場合、ルートは 403 を返します。

フラグで制御されるすべてのルートは、フラグがオフの間、同じ方法で拒否します。HTTP 403 と { error, code: "feature_disabled", feature } を返します。isFeatureDisabledError(error) で分岐し、featureDisabledKey(error) でフラグキーを読み取ってください。メッセージのテキストで照合しないでください。

p.updateExperimentalFeature(feature, enabled) は非推奨のエイリアスです。 古いデプロイ済み API に固定された利用側が引き続き動作するよう、非推奨のルートエイリアス PATCH /v1/projects/:id/experimental を呼び出し続けます。新しいコードでは p.updateFeatureFlag を使用してください。

p.sandbox — テンプレートとスナップショットビルド

プロジェクトハンドルの sandboxHealth/sandboxTemplates に加わるサンドボックスのビルド設定です。Dockerfile/イメージ/ウォームプールのテンプレートと、それらのスナップショットビルドを扱います。

プラットフォーム管理者用フック（@beeuni/sdk/react）

これらのフックは管理コンソール向けです。API はプラットフォーム管理者に対してのみ応答します。各ミューテーションは ['admin', 'accounts'] クエリを無効化します。

エスケープハッチ

beeuni.runtime() は、アクティブなサンドボックス用の型付き 実行環境 REST クライアントを返します。 createScopedBeeuni（@beeuni/sdk/server）で作成されたクライアントでは、例外をスローします。マルチテナントサーバーでは、プロセス全体の「アクティブ」ランタイムが別のリクエストのサンドボックスとなり、テナント間の漏洩につながるためです。代わりに、セッションスコープの beeuni.session(pid, sid).runtime を使用してください（先に ensureReady() を呼び出します）。これにより、そのセッション自身のサンドボックスが解決されます。

モジュール

クライアントファサードと React フックの基盤となる、フレームワーク非依存のモジュールです。ファサードなしで 1 つの操作を実行したい場合、純粋なヘルパーや Node 専用の分離レイヤーが必要な場合に使用してください。各モジュールには安定性のティアが付いているため、何を基盤として構築できるかがわかります。

ルートエントリが標準です。以下のフレームワークに依存しない名前はすべて、@beeuni/sdk から直接インポートできます。

import { files, getSessionHealth, getClient, authenticatedFetch, backendApi } from '@beeuni/sdk';

標準モジュール

ファイル

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

const tree = await files.list('/workspace/src');
const { content } = await files.read('/workspace/README.md');
const hits = await files.findText('TODO');
await files.upload(file, '/workspace/uploads', file.name, {
  onProgress: ({ loadedBytes, totalBytes }) => {
    console.log(`${loadedBytes}/${totalBytes}`);
  },
});

64 KiB を超えるアップロードは、検証済みのチャンクでサンドボックスの境界を通過します。進捗コールバックは、各チャンクがセッションのファイルシステムに到達した後に実行されます。

uploadNativeFile({ uri, name, type? }, targetPath, baseUrl) は、React Native からデバイス上のファイルを1回のリクエストでアップロードします。ランタイムは uri からバイトをストリーミングするため、JS ヒープに入ることはありません。files.upload と同じ認証、期限、401 のリプレイを使います。チャンク分割はしません。

fetchProjectArchive、fetchCostExportCsv、およびサンドボックスのバージョン呼び出しは、同じトランスポートを通じて送信されます。失敗すると、status を伴う ApiError がスローされます。

files.write(path, blob) は path のファイルを置き換え、path がフォルダーの場合は失敗します。files.create(path) は空のファイルを作成し、上書きはしません。path にファイルまたはフォルダーがすでに存在する場合、FileExistsError（status 409、code 'FILE_EXISTS'）をスローします。

import { FileExistsError, files } from '@beeuni/sdk';

try {
  await files.create('/workspace/notes.md');
} catch (error) {
  if (error instanceof FileExistsError) console.log(`${error.path} already exists`);
  else throw error;
}

files は、グローバルにアクティブなサンドボックスを対象とします。ホストが複数のセッションを同時に実行する場合は、代わりにセッションハンドルで s.files を呼び出してください。常にそのセッション自身のサンドボックスを対象とします。セッション を参照してください。

セッションランタイムのヘルパー

import { getSessionHealth, isRuntimeReady } from '@beeuni/sdk';

const result = await getSessionHealth();
if (result.ok && isRuntimeReady(result.health)) {
  // the sandbox daemon is ready
}

getSessionHealth は、2xx 以外のステータスでもスローしません。{ status, ok, health, body } を返し、ステータスの意味は呼び出し側で判断できます。同じモジュールは、エージェントの localhost 出力を到達可能なプロキシ URL に書き換える URL ヘルパーもエクスポートします：detectLocalhostUrls、rewriteLocalhostUrl、proxyLocalhostUrl、parseLocalhostUrl、buildWebProxyUrl。

実行環境 クライアント

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

const client = getClient();
const { data } = await client.session.list({ limit: 100 });

getClient() は、認証が注入済みの、アクティブなサンドボックス用の型付き 実行環境 v2 互換クライアントを返します。ホストが複数のセッションを実行する場合は、グローバルな getClient() よりも、同じクライアントを1つのセッションにスコープした beeuni.session(pid, sid).runtime を優先してください。

認証ヘルパー

import { authenticatedFetch, getAuthToken } from '@beeuni/sdk';

const res = await authenticatedFetch(`${runtimeUrl}/beeuni/health`);
const token = await getAuthToken();

トークンは、createBeeuni に渡した getToken 関数から取得されます。ほとんどのアプリコードではこのモジュールは不要です。ファイル、セッション、ファサードの各レイヤーがすでに認証を処理します。

API クライアント

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

const data = await backendApi.get('/some/endpoint');
await backendApi.post('/some/endpoint', { name: 'x' });

backendApi は、すべての REST 関数の基盤となる型付き HTTP クライアントです。型付きラッパーがまだないエンドポイントにのみ使ってください。

コンポーザーのエージェントとモデルのリスト

Beeuni ウェブアプリと同じルールで、セッションコンポーザーのエージェント選択とモデル選択を構築します。すべての関数は純粋関数です。クライアントで入力を取得し、それを渡してください。

import {
  composerSelectableAgents,
  createModelVisibility,
  flattenModels,
  modelInDefaultView,
  pickerProviderList,
  projectConfigAgentsToRuntimeAgents,
  resolveComposerAgent,
  resolveComposerModel,
  resolveModelDefault,
} from '@beeuni/sdk';

// Agents: the roster, the picker list, and the agent the send carries.
const roster = projectConfigAgentsToRuntimeAgents(detail.config);
const pickerAgents = composerSelectableAgents(roster, { enableProjects: false });
const agent = resolveComposerAgent({
  agents: roster,
  boundAgent: session?.agent,
  defaultAgent: detail.config.default_agent,
  selectedAgent: pick,
});
if (agent.disabled) {
  // no accessible agent: refuse the send
}

// Models: gateway projects read /model-picker, native projects merge the
// catalog synthesis with the running sandbox's provider list.
const gatewayEnabled = detail.project.experimental?.llm_gateway === true;
const providers = pickerProviderList({
  gatewayEnabled,
  modelPicker,
  runtimeProviders,
  llmCatalogProviders,
  secretNames,
});
const models = flattenModels(providers, { providerMode: gatewayEnabled ? 'gateway' : 'native' });
const isVisible = createModelVisibility({ catalogModels: models });
const defaultView = models.filter(
  (m) => m.enabled !== false && modelInDefaultView(m, { search: '', isStoreVisible: isVisible, selected }),
);
const { model, explicit } = resolveComposerModel({
  models,
  picks: [sessionPick],
  serverDefault: resolveModelDefault(modelDefaults, agent.selected ?? undefined),
  providers,
});

resolveComposerModel は、コンポーザーがデフォルト設定の場合に explicit: undefined を返します。model は表示および送信するキーです。フラット化された各モデルの id は、選択時に保存される参照です。modelRefToKey(ref, gatewayEnabled) は、保存された参照（セッションのピン、チャネルのバインディング、トリガーの model）をキーに戻します。

サポート対象のサブパス

ワイヤーメッセージ ID

プロンプトの messageId は、トランスクリプト内の位置です。実行環境 は、msg_ + 48ビットのクロック（Date.now() * 0x1000、下位48ビット）+ 14文字の base62 文字列でメッセージを並べ替えます。クロックは 2^36 ms（約2.2年）ごとに周回します。手動でエンコードしないでください。

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

// `after`: the ids already in this session's transcript.
const messageId = mintWireMessageId({ after: transcriptIds });

生成時刻は2分前に設定され、その後、after 内で現在より最大1時間先までの最新 ID より1ティック上に引き上げられます。最新の位置を ID ではなくクロックとして保持する呼び出し側は、mintWireMessageIdAbove({ nowMs, newestKnownTime }), which returns { id, time }. newestWireIdClock(ids) を使ってそのクロックを取得します。すべての比較はリング上で行われるため、周回の両側にある ID も正しい順序を維持します。

48ビットのクロックは約2.2年ごとに周回するため、2つのクロックを > や <= で比較しないでください。周回直後に生成された ID は、直前に生成された ID より数値的に小さくなります。リング上の符号付き距離である wireIdClockDelta(clock, reference)（clock が先にある場合は正）を使い、複数の中から最新のものを選ぶには maxWireIdClock(clocks) を使ってください。

import { maxWireIdClock, wireIdClockDelta } from '@beeuni/sdk/wire-message-id';

const floor = maxWireIdClock([transcriptNewest, deliveredNewest]);
const stale = floor !== null && wireIdClockDelta(clientClock, floor) <= 0n;

サーバー側の分離

createBeeuni は、トークン関数を含む設定をプロセス全体で共有する1つの変数に保存します。ブラウザーのタブ、CLI、シングルテナントのサーバーでは問題ありません。異なるユーザーのリクエストを同時に処理する Node サーバーでは安全ではありません。最後の createBeeuni 呼び出しが、処理中のすべてのリクエストに適用されるためです。@beeuni/sdk/server は、リクエストごとの分離でこれを解決します。

import { createScopedBeeuni } from '@beeuni/sdk/server';

export async function handler(req: Request) {
  const beeuni = createScopedBeeuni({ backendUrl, getToken: () => tokenFor(req) });
  return beeuni.projects.list();
}

createScopedBeeuni と runWithBeeuni は、Node の AsyncLocalStorage を使ってリクエストごとに設定を分離します。ブラウザーバンドルから @beeuni/sdk/server をインポートしないでください。node:async_hooks が静的に取り込まれます。

スコープ付きクライアントのトップレベルの runtime() はスローします（別のテナントのサンドボックスを解決してしまうためです）。await s.ensureReady() の後に beeuni.session(pid, sid).runtime を使って、特定のセッションのランタイムにアクセスしてください。

非推奨のエイリアス

約20の古いサブパスが引き続き動作します：/files、/turns、/session、/auth、/projects-client、/api-client、/config、/event-stream、/opencode-client、/platform-client などです。それぞれ、ルートの @beeuni/sdk エントリがすでにエクスポートしているコードを再エクスポートします。既存のものに影響しないよう、引き続き動作します。 import breaks, but new code should import from the root.

内部モジュール

@beeuni/sdk/internal/* は、apps/web 自身のランタイムが内部で使う zustand ストアを保持します。セッションの同期状態、アクティブなランタイムの追跡、再接続の管理が含まれます。このサブパスは明示的に semver の対象外です。ホスト側のコードではインポートしないでください。必要な状態は React フック がすでに公開しています。

ターン

セッションのメッセージをターンにグループ化し、各メッセージパートを分類する通常の関数です。apps/web のリファレンス実装の代わりに、独自のチャットレンダラーを構築するために使えます。React も DOM も使いません。すべてのエクスポートは通常の関数または型で、どのホストからでも安全に呼び出せます。

import { classifyPart, classifyTurn, toolInfo, toolViewModel } from '@beeuni/sdk';

すべての関数をルートの @beeuni/sdk エントリからインポートしてください。@beeuni/sdk/turns サブパスは引き続き動作しますが、非推奨のエイリアスです。新しいコードではルートエントリを使う必要があります。配布 を参照してください。

パートを分類する

classifyPart(part) は、Beeuni のトランスクリプト形式（beeuni.transcript.v1、BEEUNI_TRANSCRIPT_SCHEMA）の12種類のパート型のいずれかを、kind をキーとするユニオン型 ClassifiedPart に正規化します。各バリアントでは、レンダラーに必要なフィールド（ツールの状態、解析済みの JSON 出力、画像の検出）がすでに解決されています。

import { classifyPart, type ClassifiedPart } from '@beeuni/sdk';

for (const part of message.parts) {
  const classified: ClassifiedPart = classifyPart(part);
  switch (classified.kind) {
    case 'text':
      render(classified.text);
      break;
    case 'tool':
      render(classified.tool.title, classified.tool.status);
      break;
  }
}

認識できない通信上のパートは、実行時に例外をスローせず、unknown にフォールバックします。これにより、古いクライアントでも新しいサーバーと通信できます。

ツールパートは ToolView に分類されます。

interface ToolView {
  name: string;
  title: string;
  status: 'pending' | 'running' | 'done' | 'error';
  input?: Record<string, unknown>;
  output?: string;
  error?: string;
  outputParsed?: unknown; // JSON.parse(output) when it parses, capped at 256KB
  outputText?: string;    // the raw output text, always present
  kind?: ToolKind;        // toolKind(name): the action, whatever the harness calls the tool
  files?: ToolFile[];     // the files a file tool read, wrote or changed: path, patch, additions/deletions
  diff?: string;          // a unified diff of the change
  diagnostics?: Record<string, unknown[]>; // language-server diagnostics, keyed by file path
  answers?: string[][];   // the answers to a `question`, one list per question
  childSessionId?: string; // the child session a delegating call (`task`) runs
}

toToolView(part) は、ツールパートから直接これを構築します。ハーネス独自の state.metadata ではなく、これらのフィールドを読み取ってください。そうすれば、同じカードで 実行環境 の edit（filePath、filediff）と pi の edit（path、edits、統一された patch）を表示できます。

一部のツール（web_search、image_search、コネクター呼び出し）は、JSON 本文に success: false が含まれていても state.status: 'completed' を報告します。classifyPart はこれを検出し、その場合も ToolView.status を 'error' に設定します。

classifyTurn(message) は、1つのアシスタントメッセージのすべてのパートを分類し、次の3つのフィールドを持つ ClassifiedTurn を返します。

• parts — 分類済みの各パート
• error — message.info.error があれば、そこから取得
• isEmpty — ターンにエラーがなく、表示可能なコンテンツを持つパートもない場合に true

ツールのメタデータ

toolKind(name) は、ツール分類の唯一の体系です。任意のハーネスのツール名（pi の write、実行環境 の oc-apply_patch、プラグインの pty_spawn）を、ToolKind（read、edit、write、bash、web_search、task、question、… または other）にマッピングします。ナレーションの系統、ビューモデル、toolInfo カテゴリ、コンテキストツールグループは、すべてここから派生します。inputPath(input) は、ファイルツールのパスを filePath、file_path、または path から読み取ります。

toolKind('oc-apply_patch'); // 'apply_patch'
toolKind('pty_spawn');      // 'pty'
inputPath({ path: 'app.py' }); // 'app.py'

さらに2つのルックアップがあり、どちらもツールを記述します。混同しないでください。

• toolInfo(name) — アイコンを含まず、{ label, category } を返します。classifyPart は内部でこれを使用します。ToolCategory は 'shell' | 'files' | 'search' | 'edit' | 'web' | 'task' | 'other' です。
• getToolInfo(name, input) — アイコンに対応し、リファレンスのツールカード UI 用に { icon, title, subtitle } を返します。サブタイトルは、ファイルパスや検索クエリなど、ツールの入力から取得されます。

toolInfo('bash'); // { label: 'Shell', category: 'shell' }
getToolInfo('write', { filePath: '/workspace/main.go' });
// { icon: 'file-pen', title: 'Write', subtitle: 'main.go /workspace' }

どちらの関数もツール名のプレフィックスで照合するため、Beeuni のプラグインツール群（agent_*、session_*、task_*、trigger_*、project_*、pty_*）はレジストリを更新せずに解決できます。不明なツール名でも例外はスローされず、カテゴリ 'other' の humanizeToolName(name) にフォールバックします。

ツールのビューモデル

toolViewModel(classifiedTool) は、分類済みのツールパートを、1つのツール群向けに構築された構造にマッピングします。UI はそれを汎用の JSON データとしてではなく、専用の形式で表示できます。

const vm = toolViewModel(classifiedTool);
if (vm.kind === 'shell') {
  render(vm.command, vm.stdout, vm.exitCode);
}

DiffLine は { type: 'added' | 'removed' | 'unchanged', text } です。大きなツール出力1つで表示が壊れないよう、文字列フィールドには上限があります。整形済み JSON は4000文字、差分処理前は256KBです。

メッセージをターンにまとめる

ターンは、1つのユーザーメッセージと、それに回答したアシスタントメッセージを組み合わせたものです。チャット UI が1回のやり取りとして表示する単位です。

import { groupMessagesIntoTurns, collectTurnParts, type TurnLike } from '@beeuni/sdk';

const turns: TurnLike[] = groupMessagesIntoTurns(messages);
for (const turn of turns) {
  const parts = collectTurnParts(turn);
}

groupMessagesIntoTurns は、各アシスタントメッセージを親のユーザーメッセージに関連付けます。親へのリンクがない場合は、メッセージの順序にフォールバックします。また、親を持たず、すべてのユーザーメッセージより前にある孤立したアシスタントメッセージは、最後ではなく最初のターンに関連付けます。

関連するヘルパー：

• findLastTextPart(parts) — ターンの最終応答テキスト
• turnHasSteps(parts) — tool、compaction、snapshot、または patch パートが存在する場合に true
• isShellMode(turn) / getShellModePart(turn) — 1つの合成プロンプトが1回の bash 呼び出しを駆動するターン

型ガード

type でパートの型を絞り込みます。

import { isTextPart, isToolPart, getPartText } from '@beeuni/sdk';

if (isTextPart(part)) {
  // part.type narrowed to 'text'
}
const text = getPartText(part); // works for 'text' and 'reasoning' parts

次も利用できます：isReasoningPart、isFilePart、isAgentPart、isCompactionPart、isSnapshotPart、isPatchPart、isStepPart（step-start と step-finish）。

状態とエラー

import { getWorkingState, getTurnStatus, formatDuration } from '@beeuni/sdk';

const status = getTurnStatus(parts, childMessages); // "Running commands..."
formatDuration(4300); // "4s" — durations under 1s return ''

getTurnStatus は、ターンのパートから最後のステータス行を探します。最後のパートが実行中の task 委任である場合は、childMessages を渡してください。汎用の「委任中…」という行ではなく、サブエージェントの実際の活動がステータスに表示されます。

import { getTurnError, getChildSessionError, unwrapError } from '@beeuni/sdk';

getTurnError(turn);                    // the first assistant error, unwrapped
getChildSessionError(childMessages);   // newest error in a sub-agent's messages
unwrapError(rawError);                 // normalizes double-JSON and mixed error shapes

コストとトークンの合計

import { getTurnCost, getSessionCost, formatCost, formatTokens } from '@beeuni/sdk';

const info = getTurnCost(partsWithMessage, modelPricingLookup);
const sessionCost = getSessionCost(messages, modelPricingLookup);

formatCost(0.0032);  // "$0.003"
formatTokens(12345); // "12k"

どちらの関数も、step-finish パートからコストとトークンの合計を読み取ります。パートがゼロを報告する場合は、ModelPricingLookup を使用し、トークン数からコストを推定します。

ChatGPT/Codex サブスクリプションのメッセージは、実行時コストがゼロでない過去のメッセージも含め、$0.00 として計上されます。トークンとコンテキストの使用量は引き続き表示されます。混在するセッションでは、有料 API メッセージの料金は維持されます。OpenAI API モデルは、名前に codex を含む API モデルも含め、引き続き課金対象です。

子セッションと保留中のリクエスト

プロジェクトセッションの会話ツリー（ルートと、そこから生成されたサブエージェントの会話）は、その runtime_sessions リストから取得されます。これらのヘルパーは、W4 以前の名前より現在の名前を優先して読み取ります。

import { directSubsessions, projectSessionForRuntimeId, rootRuntimeSession, runtimeSessionsOf } from '@beeuni/sdk';

const root = rootRuntimeSession(projectSession);            // the root conversation id
const children = directSubsessions(projectSession);         // its subagent conversations
const owner = projectSessionForRuntimeId(projectSessions, childId); // the session a conversation belongs to

task ツール呼び出しは、子セッションに委任します。これらのヘルパーは、親ターンをその子セッション自身のメッセージに関連付けます。

import { getChildSessionId, getChildSessionToolParts } from '@beeuni/sdk';

const childId = getChildSessionId(taskToolPart);
const steps = getChildSessionToolParts(childMessages);

保留中の権限リクエストや質問リクエストをツール呼び出しと照合し、リクエストがアクティブな間に非表示にするツールパートを特定します。

import { getPermissionForTool, getHiddenToolParts, isToolPartHidden } from '@beeuni/sdk';

const permission = getPermissionForTool(permissions, callID);
const hidden = getHiddenToolParts(activePermission, activeQuestion);

書式設定とリスト

import { getFilename, getDirectory, relativizePath, stripAnsi } from '@beeuni/sdk';

getFilename('/workspace/src/main.go');               // "main.go"
getDirectory('/workspace/src/main.go');               // "/workspace/src"
relativizePath('/workspace/src/main.go', '/workspace'); // "src/main.go"

セッションリストのヘルパーは、同じセッションデータを操作します。

import { sortSessions, childMapByParent, allDescendantIds } from '@beeuni/sdk';

sessions.sort(sortSessions(Date.now())); // pins sessions updated in the last 60s
const childMap = childMapByParent(sessions);
const descendants = allDescendantIds(childMap, sessionId);

リトライ状態：getRetryInfo(sessionStatus) は { attempt, message, next, details? } when status.type === 'retry', with message を60文字に制限して返します。details は、構造化された LLM ゲートウェイのエンベロープがある場合、それを保持します。内容は、最終プロバイダー、ゲートウェイコード、リクエスト ID、提案、アップストリームのステータス、順序付きの候補の失敗情報です。各候補の失敗情報には、attempt、provider、routeModel、resolvedModel、stage、省略可能な status、code、message が含まれます。従来のプレーンテキストのリトライは details: undefined を返します。 getRetryMessage(sessionStatus) は、ラップを解除した完全なメッセージを返します。実行環境 がそのメッセージだけを保持する場合でも、ゲートウェイの複合情報には、リクエスト ID と、各候補のプロバイダー、解決済みモデル、HTTP ステータス、コード、長さを制限したメッセージが含まれます。

構造型

グループ化とステータスの関数は、具体的なトランスクリプト型ではなく、最小限の構造型 — PartLike、MessageInfoLike、TurnLike、ToolStateLike、 SessionStatusLike — を受け取ります。 独自のメッセージやパートの構造も、必須フィールドを満たしていれば、そのまま扱われます。 ただし、classifyPart と classifyTurn は例外です。 これらは Beeuni の Part ユニオン（beeuni.transcript.v1）に対して型付けされているため、 網羅性チェックによって新しいパート型をビルド時に検出できます。

配布

npm install @beeuni/sdk

パッケージは、完全な TypeScript 型宣言を備えたコンパイル済み ESM として提供されます。 react と @tanstack/react-query はオプションのピア依存関係です。 @beeuni/sdk/react を使用する場合は、両方をインストールしてください。

import { createBeeuni } from '@beeuni/sdk'; // framework-free core
import { useSession } from '@beeuni/sdk/react'; // optional React layer
import { createScopedBeeuni } from '@beeuni/sdk/server'; // Node and Bun servers

エントリーポイントと安定性

ルートエントリー @beeuni/sdk が標準です。フレームワークに依存しない すべての API をエクスポートし、ブラウザー、Node 18 以降、Bun、エッジ ランタイムで動作します。

CDN バンドル

パッケージには、tsup でビルドされた 2 つのブラウザー用バンドルも含まれています。 ESM バンドル（dist/beeuni.esm.min.js）と、window.Beeuni を定義する IIFE グローバル（dist/beeuni.global.js）です。

<script src="https://unpkg.com/@beeuni/sdk/dist/beeuni.global.js"></script>
<script>
  const beeuni = Beeuni.createBeeuni({
    backendUrl: 'https://api.beeuni.ai/v1',
    getToken: async () => KEY,
  });
</script>

window.Beeuni は npm インポートと同じルートエントリーを公開します： Beeuni.createBeeuni、Beeuni.classifyTurn、Beeuni.ApiError。

関連項目

• SDK — インストールと最初のセッション。
• セッション — ライフサイクル、ストリーミング、エラー処理。
• React フック — これらのモジュール上に構築されたリアクティブ層。

エージェントのリポジトリアクセス

エージェント設定は repository_access?: boolean（デフォルトは true）を受け付けます。 false を設定すると、プロジェクトリポジトリやリポジトリ API へのアクセスなしで新しいセッションを実行できます。 Git、シークレット、コネクター、ツールの権限は引き続き別々です。既存のセッションは保存済みのポリシーを維持します。 AgentConfigBlock.workspace は非推奨です。SDK は従来の branch/runtime をブール値フィールドにマッピングします。 従来の read の書き込みには、repository_access の明示的な選択が必要です。リポジトリへの読み取り専用アクセスは有効になりません。

プロバイダーとモデルへのアクセス

beeuni.projects.modelAccess(projectId) を読み取ります。beeuni.projects.setModelAccess(projectId, { target: 'provider' | 'model', id, enabled }) で 1 つの対象を変更します。

Beeuni Managed Models にはプロバイダー ID beeuni を使用し、BYOK、Codex、カスタムプロバイダーにはカタログのプロバイダー ID を使用してください。モデルには完全なゲートウェイのワイヤー ID を使用してください。プロバイダーの無効化は今後追加されるモデルにも適用され、個々のモデルの設定と保存済み認証情報は保持されます。

現在のデフォルトモデルとそのプロバイダーを無効にするには、先に代替を指定する必要があります（409 cannot_disable_default）。無効な対象への直接のゲートウェイリクエストは、model_disabled または provider_disabled で失敗します。すでに処理中のアップストリームリクエストは正常に完了します。プロジェクトがゲートウェイではなくネイティブの 実行環境 を使用している場合、レスポンスの enforced フラグは false になります。

React を利用する側では、@beeuni/sdk/react の useModelAccess(projectId) を使用します。その setEnabled(change) ミューテーションは、管理カタログとセッションピッカーを更新します。