Open Dots

クライアントは HTTP で API を呼び、応答トークンとツールイベントを SSE（Server-Sent Events）で受け取る。サーバー側はルーター層とサービス層に分かれ、副作用を持つ処理はすべて Action Gateway の下にぶら下がる。

flowchart TD
  C["Next.js client
ChatWindow / ApprovalCard / ComputerPanel"] -->|"HTTP + SSE"| API["FastAPI
認証ミドルウェア + routers"]
  API --> DB[("SQLite
bots / messages / approvals / audit_events")]
  API --> P["ModelProviderService
推論アダプタ"]
  API --> G{"Action Gateway
登録 → ポリシー → 承認 → 実行"}
  G --> AB["ApprovalBroker
asyncio.Future で待機"]
  G --> W["WorkspaceService
WORKSPACE_ROOT 内のみ"]
  G --> CN["Composio
GitHub issue 一覧 / 作成"]
  G --> CP["ComputerProvider"]
  CP --> F["fake
メモリ内"]
  CP --> D["docker
Playwright コンテナ"]
  CP --> R["remote
HTTP サービス"]
  G -.->|"監査イベント"| DB

1 回の発話は 2 つのリクエストに分かれる。POST /api/v1/chat/send がユーザーメッセージを保存し、続く GET /api/v1/chat/stream/{thread_id} が SSE で応答を流す。ツール操作はモデルが決めるのではなく、最後のユーザー発話が /workspace または /connector で始まるかをサーバーが構文解析して決まる。

sequenceDiagram
  participant U as Client
  participant S as chat router
  participant G as Action Gateway
  participant A as ApprovalBroker
  participant M as 推論 API
  U->>S: POST /chat/send
  U->>S: GET /chat/stream (SSE)
  S-->>U: turn.started
  S->>S: /workspace・/connector を解析
  S->>G: open(action)
  alt 承認が必要
    G->>A: open → Future 作成
    S-->>U: request.opened
    U->>A: POST /approvals/respond (allow / deny)
    A-->>G: decision
  end
  G->>G: execute
  S-->>U: tool.started → tool.completed / failed
  S->>M: 履歴 + 結果を system prompt に追記して送信
  M-->>S: 応答
  S-->>U: content.delta ... turn.completed

ツールの結果はモデルへの function calling ではなく、Action result (workspace.read): {...} のような文字列としてシステムプロンプトの末尾に足される。拒否・期限切れ・失敗も同じ形で伝わるため、モデルはそれを踏まえて返答を書く。

ActionGateway（server/app/services/action_gateway.py）は、操作名から ActionDefinition を引き、登録・形式・プレビューを確認してから実行する。未登録の名前は action.denied を記録して即座に拒否する。新しい操作を足すには register_action(definition, executor) で定義と実行関数を登録する必要がある。

execute() は保留中リストに無いリクエストや、承認必須なのに allow を得ていないリクエストを ActionGatewayError で止める。承認をすり抜けて実行関数を直接呼ぶ経路をゲートウェイ側で塞いでいる。

登録済みの操作

ApprovalBroker はプロセス内の asyncio.Future で承認を待つ。SSE ストリームを開いたコルーチンが wait() で止まり、クライアントの POST /api/v1/approvals/respond（{"request_id", "action": "allow" | "deny"}）が resolve() を呼ぶと再開する。

stateDiagram-v2
  [*] --> pending_approval: open()
  [*] --> denied: ポリシー違反
  pending_approval --> approved: allow
  pending_approval --> denied: deny
  pending_approval --> expired: 120 秒経過
  approved --> running: execute()
  running --> completed
  running --> failed
  completed --> [*]
  failed --> [*]
  denied --> [*]
  expired --> [*]

• タイムアウト: APPROVAL_TIMEOUT_SECONDS（既定 120 秒）を過ぎると expired になり、承認レコードと監査ログが更新される。
• 単一プロセス前提: 待機中の承認はメモリ上の Future なので、サーバー再起動や複数ワーカー構成では引き継がれない。コード上のコメントも「local single-user server」向けと明記している。
• コンピュータ操作の承認: POST /api/v1/computers/{bot_id}/actions で開いた要求は、承認後に /actions/{request_id}/execute を呼んで実行する 2 段階構成。

監査ログは audit_events テーブルに追記され、/api/v1/audit と UI の AuditPanel から参照できる。1 つの操作は次のイベント列を残す。

各イベントには request_id・thread_id・bot_id・tool・action・intent・target・arguments・preview・risk が秘匿処理済みで入る。

コマンドはシェルとして実行されず、shlex.split で 1 行目だけを分解する。書き込み内容や issue 本文は 2 行目以降に書く。構文が崩れているとゲートウェイに届く前に tool.failed を返し、その理由をモデルへのコンテキストに入れる。

# ワークスペース（WORKSPACE_ROOT からの相対パス）
/workspace list [path]
/workspace read <path>
/workspace write <path>
<ファイル内容（2 行目以降）>

# GitHub（Composio で OAuth 接続済みであること）
/connector github issues <owner>/<repo> [open|closed|all]
/connector github create-issue <owner>/<repo> "<title>"
/connector github create-issue <owner>/<repo>
<title>
[body]

owner と repo は英数字・ドット・ハイフン・アンダースコアのみ（各 100 文字まで）。コネクタは現在 GitHub の 2 操作に限られ、任意のツール探索や書き込みは実装されていない。

ComputerProvider は Protocol で定義された共通インターフェイス。create / start / stop / pause / reset / health のライフサイクルと、browser_navigate / terminal_execute / files_list / screenshot / send_input / cleanup の操作を持つ。コンピュータ ID は bot ID から computer-<bot_id> として導出し、他の bot のコンピュータ ID を指定すると拒否する。

DockerComputerProvider._launch() が docker run に渡すオプション。イメージは mcr.microsoft.com/playwright:v1.62.1-noble をベースに pwuser で動く。

docker build -t open-dots-computer:1.62.1 ./runtime
export COMPUTER_PROVIDER=docker
export COMPUTER_DOCKER_IMAGE=open-dots-computer:1.62.1

Node.js と npm、Python 3.10 以上と pip、推論 API のキーとベース URL。

1. API サーバー（ターミナル 1）

git clone https://github.com/Anil-matcha/open-dots.git
cd open-dots/server
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
export MODEL_API_KEY="your_api_key"
export MODEL_API_BASE_URL="https://your-inference-host.example/api/v1"
python run.py        # http://127.0.0.1:8000 （/docs に OpenAPI UI）

2. Web クライアント（ターミナル 2）

cd open-dots/client
npm install
npm run dev          # http://localhost:3000

API キーは環境変数の代わりに App Settings からも入力できる。初回起動時にセッション用トークンと暗号化鍵が DATA_DIR に作られる。

同梱の ModelProviderService は OpenAI 互換の chat completions を話さない。POST {MODEL_API_BASE_URL}/{model_id} に予測リクエストを送り、request_id が返れば GET {base}/predictions/{request_id}/result を最大 180 秒ポーリングする。画像は {base}/upload_file に上げる。この契約を実装したサービスが別途必要になる。

• 推論 API はステートレス扱いで、直前 10 件までの履歴をテキストにしてシステムプロンプトへ埋め込む。
• 応答はポーリング完了後にまとめて受け取り、サーバー側で空白ごとに区切り、20 ms 間隔で content.delta として流す。トークン単位のストリーミングではない。
• モデル一覧（/api/v1/models）は routers/models.py にハードコードされた 31 件の ID。実際に使えるかは接続先サービス次第。

• 利用者はローカルの 1 名のみ。ユーザー管理・ロール・マルチユーザーの権限付与は未実装。
• SQLite はローカル状態。複数インスタンスでの共有やバックアップの仕組みは無い。
• 汎用のプロバイダプラグイン機構は未実装。
• コンピュータランタイムは任意機能で、任意の Web コンテンツに対するセキュリティ境界ではない。
• コネクタ操作は意図的に絞られており、任意のツール探索や書き込みは無い。
• モバイル・デスクトップクライアント、永続メモリ、定期実行エンジンは無い。

• GitHub: Anil-matcha/open-dots — 本体リポジトリ（MIT）
• デモ動画（YouTube） — README に掲載されている紹介動画
• Composio ドキュメント — コネクタの OAuth と GitHub 操作に使うサービス
• Playwright Docker — コンピュータランタイムのベースイメージ