Web チャット UI

完全なブラウザチャットクライアント - サイドバー、ストリーミング、承認、SQLite ストア。

Web チャット UI

exposes: "webui" を持つ gateways/*.bx エントリは、エージェント向けの完全なブラウザチャットクライアント - 会話サイドバー、推論とツール呼び出しを伴うストリーミング、human-in-the-loop 承認、訪問者ごとのテーマ、そしてその背後にある実際の SQLite ストア - を出荷します。

これは公開が宣言される場所であるという理由で gateways/ の下にありますが、それ自体が独立したサブシステムであり、それゆえに独自のページを持っています。

// gateways/chat.bx
class {
	function configure() {
		return {
			exposes     : "webui",
			path        : "/chat",
			apiKeyEnvVar: "CHAT_UI_API_KEY"   // optional - see Securing the API
		};
	}
}

これは静的な <path>/index.html (直接配信され、ルートは不要です) と、生成された handlers/ChatUi.bx と models/ChatDb.bx に支えられた <path>/api 配下の専用 API を生成します。

この UI は依存関係のない素の HTML/CSS/JS です - Bootstrap、AlpineJS、Vite のビルドステップは一切ありません - そして BX Agents 自体の中にあらかじめビルドされてバンドルされています: bxAgents build が npm install/npm run build を実行することは決してなく、生成されたプロジェクトは Node や npm をインストールする必要が一切ありません。ページが必要とするものはすべて、生成された単一の index.html にインライン化されています。

その制約はビルドについてのものであり、スコープについてのものではありません。このページは完全なクライアントです: 会話サイドバー、推論とツール呼び出しを伴うストリーミング、承認、圧縮 (compaction)、サーバー側のテーマです。実際にまだ足りていないものは What is not here yet に一覧があります。

このページは、生成された自身の <path>/api ルートと、POST <path>/api/stream (Accept: text/event-stream) を介して通信します。POST もカスタムヘッダーの設定もできないブラウザの EventSource ではなく、fetch() + 手動の ReadableStream リーダーを使います。両方ともここでは必要だからです。

event: chunk
data: {"object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":"Ray","reasoning":"...","tool_calls":[...]}}]}

event: done
data: [DONE]

エンベロープ全体が届くため、推論とツール呼び出しはすでに配線の上に載っており、追加のエンドポイントは不要です: delta.reasoning (bx-ai によってすべてのプロバイダーにわたって正規化されています) は折りたたまれた「Thinking」ストリップとして描画され、delta.tool_calls は折りたたまれた呼び出しごとのチップとして描画されます。ツール呼び出しの引数は index でキー付けされた部分的な JSON フラグメントとしてストリーミングされるため、ページは単一のどのチャンクが完全な呼び出しを保持しているとも仮定せず、インデックスごとに蓄積していきます。

ストリーミングターンの実際の様子

sequenceDiagram
    autonumber
    participant B as browser (generated index.html)
    participant H as handlers/ChatUi.bx
    participant A as the agent
    participant D as models/ChatDb.bx (SQLite)

    B->>H: POST /chat/api/stream, Accept: text/event-stream
    H->>D: resolve the conversation for this session
    H->>A: agent.stream( ... )
    H-->>B: event: thread - the threadId, sent BEFORE the first chunk
    loop for every chunk bx-ai emits
        A-->>H: a full normalized bx-ai envelope
        H-->>B: event: chunk - choices[0].delta.content / .reasoning / .tool_calls
    end
    H->>D: persist the turn
    H-->>B: event: done - [DONE]

thread イベントが最初に送られるのは、レスポンスヘッダーはボディが届き始める前には読めないためで、ページはターンの途中で POST /cancel できるように、その threadId を必要とします。

生成される API

webui エントリは、生成された handlers/ChatUi.bx によって配信される 20 個のアクションを <path>/api の下にマウントします。

すべて、userId として ColdBox の getUserSessionIdentifier() によってスコープされています。最初の 3 つは toAi() の形とワイヤーフォーマットを正確に保っています。

threadId はサーバー権威です: 与えられればリクエストから取得され、そうでなければ発行され、常にエコーバックされます - /invoke と /batch では X-Thread-Id レスポンスヘッダーとして、/stream では最初のチャンクより前に送られる thread SSE イベントとして (ヘッダーはボディが届き始める前には読めないためです)。これは ColdBox 8.1 自身の toAi() が採用しているのと同じ契約なので、一方向けに書かれたクライアントはもう一方に対しても動作します。

/clear と /compact はどちらもスコープに注意深いです。/clear は、引数を取らずすべての訪問者の履歴を消してしまう AiAgent.clearMemory() ではなく、各メモリ自身の clear( userId, conversationId ) を経由します。/compact も同じ理由で summarize( config, userId, conversationId ) を経由します。圧縮は、この会話の古いメッセージを AI が書いた要約に置き換え、直近のいくつかは保持し、呼び出し元の (userId, conversationId) ペア以外には一切触れません。

// Agent.bx - what makes /compact functional
memory: {
	type            : "cache",
	summaryProvider : "openai",
	summaryModel    : "gpt-4o-mini",
	summaryThreshold: 10
}

ユーザーとサインイン

デフォルトでは Web UI にはアカウントもゲートもありません — オープンで、すべての訪問者は匿名です。それがゼロ儀式な bxAgents serve の体験であり、これはデプロイの姿勢ではありません。webui エントリで users を宣言すると、cbauth と、他のすべてが使うのと同じ SQLite ストアに支えられた、本物のサインインゲートが有効になります。

アカウントなしでは、UI は 1 つの共有ワークスペースです

意図的に、訪問者ごとのアイデンティティは存在しません。アカウントのない Web UI へのすべての訪問者は、同じ会話、設定、エージェントメモリを読み書きします — そのページに到達できる人は誰でも、その中のすべてを見ることができます。

これは見落としではなく、アカウントなしで実行することの要点そのものです - オープンな UI は 1 つの共有ツール (ラップトップ、信頼できる社内マシン) であり、マルチテナントサービスではありません。ブラウザごとに独自のスライスを持たせても、誰も求めていないブラウザごとのコピーに 1 つのワークスペースを断片化させるだけであり、その断片化を行う任意のクライアント側 ID は、どのみち偽装可能です。

// gateways/chatUi.bx
users : [
    { username: "ada",   passwordEnvVar: "ACME_ADA_PASSWORD", displayName: "Ada Lovelace" },
    { username: "grace", passwordHash: "pbkdf2$210000$...",   displayName: "Grace Hopper" }
]

パスワードは config に決して書き込まれません

アカウントは、パスワードを保持する環境変数の名前 (passwordEnvVar) を指定するか、すでにハッシュ化された値 (passwordHash) を持ちます。リテラルな password キーは、警告ではなくビルドエラーです — サイレントに無視してしまうと、実際には何もコミットしていないのにパスワードを設定したと信じ込んでしまいます。

passwordHash は、それが逆算不能であるからこそコミットしても安全です。アプリが使うのと同じハッシャーで生成してください。

bxAgents hash-password --password="correct horse battery staple"

サインインが変えるもの

ユーザースコープのものはすべて、実際のアカウントに再キーされます。生成された handlers/ChatUi.bx は、1 つのメソッド (resolveUserId()) で cbauth から直接アイデンティティを解決し、エージェントメモリ、会話インデックス、設定、保留中のラン所有権はすべてその戻り値をキーにします。

これは意図的に ColdBox の identifierProvider 設定ではなく cbauth を読み取ります: coldbox config 構造体の中で宣言されたクロージャは決して configSettings に届かない (文書化されているリテラルな形と、後からの代入の両方で、実際の起動で確認済みです) ため、その設定に頼っていたものは何であれ、サイレントにセッション id を代わりに受け取っていました。

実務上の違いは: 会話と設定はブラウザやデバイスをまたいでその人についていき、Cookie をクリアしても新しい「ユーザー」が作られることはもうありません。

ライフサイクル

アカウントは、すべての起動のたびに、この順序で config から調整されます: スキーマインターセプターがマイグレーションを行い、シーダーがアカウントを書き込み、その後ログインゲートが強制を開始します。

• 追加 config にユーザーを追加すると作成されます。
• 変更 パスワードを変更すると更新されます。シーダーは、設定されたパスワードが保存されているものと一致しなくなった場合にのみ再ハッシュするため、変更のないパスワードには 1 回の検証コストしかかかりません。
• 削除 config から削除すると、削除ではなくアカウントを無効化します。彼らの会話は彼らの id を参照しているため、行を削除するとアクセスを取り消す代わりにその履歴を孤立させてしまいます。彼らはもうサインインできませんが、データはそのまま残り、アカウントが復元されれば戻ってきます。
• 変数が未設定の passwordEnvVar を持つアカウントは、そのアカウントを完全にスキップし、webui-auth に警告をログします。これは意図的にクローズ (安全側) に失敗します - 空のパスワードでアカウントを作成してしまうことは、存在しないことよりもずっと悪いことだからです。

これではないもの

これは固定された、オペレーターが用意したアカウントの一覧であり、ユーザー管理システムではありません。セルフ登録も、パスワードリセットも、ロールや権限も、ユーザーごとのレート制限や支出上限もありません。連合アイデンティティが必要な場合は、生成されたハンドラの resolveUserId() を編集して、あなた自身の認証済みプリンシパルを返すようにしてください - Web UI の残りの部分は、その id がどこから来たのか一切知りませんし、気にもしません。

Human-in-the-loop

エージェントが承認のために一時停止すると、ストリームは詳細を運ばない middleware_stop チャンクを発行します。そのためページは GET /pending?threadId= に何がリクエストされているかを尋ね、Approve / Reject でレンダリングし、POST /resume 経由で答えます - これは同じターンの継続をストリーミングするので、その結果は新しいターンを始めるのではなく、会話の中に収まります。

decidedBy はセッションからサーバー側で埋められ、リクエストボディからは決して埋められません: 何かを承認したのが誰かというのは、まさに呼び出し元が自分自身について主張すべきではない類のことです。

履歴と再読み込み

トランスクリプトは DOM の中に存在し、会話はエージェントのメモリの中に存在します。再水和がなければ、リロードは空の画面を表示するのに、エージェントはすべてを覚えたままです - そのためページは空白に見えたのに、ユーザーには見えていないメッセージについてのフォローアップに答えてしまうことになります。そのためページはロード時に GET <path>/api/history を呼び出し、保存されたメッセージ (マークダウンも含めて) を再生し、会話が空か、フェッチが失敗した場合はウェルカムメッセージにフォールバックします。

New は新しい conversationId を開始します。何も削除しません - 以前の会話は自身の id のもとでサーバー上に残り、サイドバーに表示されます。それこそが会話テーブルの存在意義です。

ページが行うこと

出荷されるページは、デモ用のシェルではなく実際のチャットクライアントです。まず GET /info を読み取り、サーバーが実際に報告する内容に自分自身を合わせるので、あるコントロールは、その機能が実在する場所にのみ現れます。

復旧はその響き以上に重要です。 最後に開いた会話は localStorage に記憶されますが、会話自体はサーバー上に存在します。その id がもう存在しない場合 (別のタブで削除された、あるいは新しいストアである) — ページは、アクティブな行のない空の画面に再水和する代わりに、残っている中で最新の会話にフォールバックします。

狭い画面には、押しつぶされたものではなく本物のレイアウトが用意されます: 40rem 未満では、サイドバーはトランスクリプトの幅を奪うのではなく、その上にオーバーレイされ、prefers-reduced-motion は尊重されます。

SQLite ストア

すべての webui プロジェクトは SQLite データベースを得ます。これは任意ではなく、オフにするフラグもありません。

その理由は好みではなく、実際のギャップです: bx-ai の IAiMemory には列挙 API がありません。 これは (userId, conversationId) ごとのバケットです — 1 つを読み書き・クリアできますが、その中の何も「このユーザーはどの会話を持っているか」には答えません。会話一覧、ユーザーごとの設定、その他のリレーショナルなものはすべて、メモリの内部ではなく、それに並ぶ実際のストレージが必要です。

データソースは Application.bx に登録され、グラマーは config/ColdBox.bx に固定されます。

// Application.bx (generated)
this.datasources[ "bxagents" ] = {
	"driver"  : "sqlite",
	"database": expandPath( "./data/chat.db" )
}
this.datasource = "bxagents"   // NOT this.defaultDatasource - see below

// config/ColdBox.bx (generated)
qb : {
	defaultGrammar : "SQLiteGrammar@qb",
	defaultOptions : { datasource : "bxagents" }
}

どちらも、エントリごとに上書きするのは任意です。

絶対パスの database.path はビルドを失敗させます: これは生成されたアプリの内部で expandPath() によって解決されるため、絶対パスはサイレントにアプリディレクトリの外に脱出し、パッケージ化された .bxa デプロイを壊します。

スキーマはバージョン管理され、前方向専用です。 ChatDb.migrate() は適用したものを bxagents_schema_version テーブルに記録し、新しいものだけを適用するので、既存のストアに対して起動するのは無操作です。v1 は conversations と preferences を作成します。新しい applyV<n>() を追加し SCHEMA_VERSION を上げることで進化させてください — 出荷済みのマイグレーションを編集することでは決して行わないでください。SQLite はカラムを変更したり削除したりできないからで、qb の SQLiteGrammar はそうであるかのように装う代わりに UnsupportedOperation を投げます。

グラマーだけが SQLite 固有の部分です。それ以外はすべて qb を経由するので、これを後で Postgres や MySQL に向けるのは書き直しではなく、グラマーとデータソースの変更で済みます。

会話と設定

これらは SQLite ストアが存在する理由そのものであり、どちらも他のすべてと同じ、サーバー由来の userId でスコープされています。

会話。 /invoke、/stream、/batch を通るすべてのターンは、それ自身をインデックスに記録します: その行は初回利用時に作成され、updatedAt が動き、最初のユーザーメッセージがタイトルになります (1 行に折りたたまれ、60 文字に切り詰められます) - すでに設定されている場合を除きます。そのため、名前変更が次のターンによってサイレントに元に戻されることはありません。messageCount は表示用のカウンターで、ターンごとに 2 ずつ増えます。途中で終わったターンは 1 だけ多く残すことがあり、/clear はこれをリセットします。実際に何が話されたかについての権威であり続けるのは、エージェント自身のメモリです。

/conversations/delete は、インデックス行とその会話に対するエージェントのメッセージの両方を削除します。行だけを落とすと、誰かがその id を再利用した瞬間にモデルのコンテキストにまだ座ったまま、会話が見えなくなってしまいます。

設定。 localStorage ではなくサーバー側なので、ブラウザではなくアイデンティティについていきます。identifierProvider を実際の認証済みプリンシパルに向ければ、生成されたコードを一切変更することなく、訪問者の設定はデバイスをまたいでその人についていきます。

ブランディングとテーマ

以下のキーはすべて任意です - このエントリは exposes と path だけでも動作します。

theme はページの CSS カスタムプロパティに直接マッピングされます: accent、accentFg、bg、fg、muted、border、surface、inputBg、bubbleUser、bubbleUserFg、bubbleAssistant、bubbleAssistantFg、bubbleError、reasoningFg、reasoningBg、toolFg、toolBg、radius、radiusSm、font、fontMono、fontSize、maxWidth。ネストされた theme.dark ブロックは、ダークモード向けに同じトークンのいずれかを上書きします。未知のトークンは、サイレントに無視されるのではなくビルドを失敗させるので、タイプミスは、ブランドカラーがなぜ現れなかったのか悩ませる代わりに即座に表面化します。

// gateways/chat.bx
theme: {
	accent : "0f766e",
	radius : "10px",
	font   : "Inter, system-ui, sans-serif",
	dark   : { accent : "rgb(45, 212, 191)" }
}

トークンがカバーしない部分 - カスタムフォント、レイアウト、要素ごとのルール - については、プロジェクトに resources/webui/theme.css を置いてください。これはページの <style> に最後にインライン化されるので、出荷時のデフォルトと theme トークンの両方に勝ちます。そして実際の .css ファイルなので、普通の #rrggbb の 16 進表記もそこでは正常に動作します。(そのファイル内のリテラルな </style はページのスタイルブロックを早期に終了させてしまうため、ビルドを失敗させます。)

会話のアイデンティティ: セッションこそがユーザー識別子

エージェントが保持するすべてのメモリは (userId, conversationId) でキー付けされています - そしてエージェントは一度に複数のメモリを保持できます (AiAgent の memories は配列で、loadMemoryMessages() はすべてを同じペアで反復します)。AiAgent.run()/.stream() は、何も供給されない場合、どちらにも "" にフォールバックします。つまり、サーバー側のアイデンティティが一切なければ、どんなメモリタイプが設定されていようとすべての訪問者は 1 つの共有バケットに収まります。

その修正はメモリのタイプではなく、アイデンティティです。webui 公開を持つプロジェクトは、そのため次を得ます。

1. 生成された Application.bx でのセッション管理の有効化 - this.sessionManagement = true、this.setClientCookies = true、60 分の sessionTimeout。Cookie はここでの基盤です: Cookie がなければセッション id もありません。
2. 自身の handlers/ChatUi.bx。これは ColdBox の getUserSessionIdentifier() を、3 つすべてのランナーの形 - invoke、stream、batch - でエージェントの userId として渡します。

// handlers/ChatUi.bx (generated)
private string function resolveUserId() {
	return controller.getUserSessionIdentifier()
}

session.sessionId を直接読み取るのではなく ColdBox に委譲することで 3 つの恩恵が得られます: id はアプリケーションごとにプレフィックスされ、セッションが何らかの理由で利用できない場合は URLToken/CFID を通じてフォールバックし - そして最も重要なものとして、identifierProvider config 設定が尊重されます。それをあなたの認証済みプリンシパルに向ければ、生成されたハンドラを一切変更することなく、すべてのメモリが実際のユーザーに再キーされます。

アイデンティティがサーバー発行であるため、プロジェクトがどんなメモリを設定していても - 1 つでも複数でも、window、cache、jdbc、ベクトル、どんな組み合わせでも - スコープは保たれます。

conversationId は依然としてクライアントから来ますが、それは意図的です: これは同じ訪問者に属する複数の会話を区別するためのものです - New ボタンが回転させるものです。これは分離境界ではありません。分離境界はセッション由来の userId です。

どんなメモリタイプも強制されません。Agent.bx の memory キーで、エージェントごとに 1 つ (または複数) 選んでください。checkpointer と同じ形です。

// Agent.bx
memory: { type: "cache", maxMessages: 50 }

webui を持たないプロジェクトは、セッションをオフのまま、bx-ai 自身のメモリのデフォルトを保ちます - API/ゲートウェイのみのアプリには追跡すべきブラウザがなく、そこでのセッションは、誰も求めていない Cookie を伴うオーバーヘッドでしかありません。

返信のレンダリング

アシスタントの返信は、意図的に小さなマークダウンのサブセットを通してレンダリングされます: フェンス付き/インラインコード、太字/斜体、リンク、箇条書き/番号付きリスト、見出しです。これはエスケープファーストで適用されます: モデルのテキストは、タグが 1 つでも導入される前に HTML エスケープされるので、モデルの出力がライブなマークアップになることは決してなく、リンクの href は http(s)/mailto にホワイトリスト化されているので、javascript: URL がアンカーに変換されることは決してありません。

What is not here yet

このページは、それ自身の API に対しては完全です - 必要なルートはすべて存在し、実行されています。以下がそのギャップです。

実際の ColdBox の起動に対して何が検証済みで何が未検証か (ブラウザを駆動するのではなくジェネレータレベルのアサーションだけでカバーされているこのページの部分も含む) については、既知の制限 を参照してください。