statewright/statewright

Statewright とは？

Statewright は、明示的で強制可能なフェーズを持つエージェントワークフローを実行できるオープンソースフレームワークです。タスクの各ステップ（例：計画、実装、テスト）に対してステートマシンを定義し、各フェーズで許可される LLM ツールを制御します。サポートされている AI クライアント（Claude Code、Codex、Cursor、OpenCode、Pi、OMX、またはカスタム MCP ホスト）にプラグインすると、統合によりツール呼び出しがインターセプトされ、許可されていないアクションがブロックされ、異なるフェーズを異なるモデルにルーティングできます。

なぜ重要か

典型的な AI 支援コーディングエージェントは、ジョブ全体で同じツールを使用し続けることができ、レビュー前にコードを編集したり、テストが完了する前にデプロイしたりするのが簡単になります。Statewright は、これらの境界を明示的にし、ホストがサポートする場合は強制します。これにより、次のものが得られます：

• 安全性 – ファイル編集や破壊的なシェルコマンドなどのツールは、指定した状態でのみ許可されます。
• 粒度の細かいモデルルーティング – 安価なフェーズには安価なモデルを実行し、負荷の高いフェーズにはより大きなモデルに切り替えることができます。
• 承認ゲート – ワークフローは、先に進む前に人間のレビューのために一時停止できます。
• 再現可能で監査可能な実行 – すべての遷移、ガード、ツール使用がログに記録されます。

コアコンポーネント（README に記載）

コンポーネント	言語 / 役割	主な責任
エンジン (crates/engine)	Rust	純粋なステートマシン評価器 – LLM なし、決定論的、ガード、遷移、ツール許可リストを提供。
エージェントバイナリ (crates/cli, sw-agent)	Rust	制約されたループで LLM を実行し、JSONL イベントをストリーミングし、状態ごとのモデルルーティングを尊重し、オンデマンドで単一の状態を実行できます。
エグゼキュータ / プラグインレイヤー (plugins/*, crates/mcp-gateway)	Rust + ホストアダプター	ワークフローセッション、資格情報、テレメトリを保持し、サポートされている各クライアント（Claude、Codex、Pi など）のネイティブツールフックを変換します。
TUI (crates/tui, statewright)	Rust (ratatui)	sw-agent を実行するターミナル UI。ライブ JSONL イベントを表示し、ワークフローと対話できます。

ワークフローの外観

ワークフローは、状態、許可されたツール、オプションの状態ごとのモデル、ガード、遷移をリストする JSON 定義です。例（簡略化）：

{
  "id": "bugfix",
  "initial": "planning",
  "meta": {"default_model": "claude-sonnet-4"},
  "states": {
    "planning": {"allowed_tools": ["Read","Grep"], "model": "claude-haiku"},
    "implementing": {"allowed_tools": ["Read","Edit","Write"]},
    "testing": {"allowed_tools": ["Read","Bash"], "allowed_commands": ["pytest"]},
    "completed": {"type": "final"}
  }
}

エンジンは allowed_tools リストを強制し、許可されていない Bash コマンドをブロックし、遷移時に人間の承認を要求できます。

サポートされている AI ホスト

Statewright には、次のネイティブプラグインが付属しています：

• Claude Code (0.3.4 候補) – ネイティブ OAuth、事前権限チェック。
• Codex – マネージド App-Server アダプター。
• Pi、OpenCode、Cursor、OMX – それぞれに同じガードレールを強制する薄いブリッジがあります。 カスタム MCP ホストもゲートウェイを介して接続できます。

研究スナップショット

5 タスクの SWE-bench サブセットでの小規模な実験では、Statewright の制約により、大きなモデル（13.8 GB gpt-oss:20b と 19.9 GB gemma4:31b）がすべてのタスクを解決したのに対し、小さなモデルは失敗しました。著者らは、これは最小モデルサイズを証明するものではなく、ガードレールがエージェントを軌道に乗せるのに役立つことを示しているだけだと述べています。

価格とデプロイメント

• マネージドクラウド [statewright.ai] – 無料ティア（3 ワークフロー、200 遷移/月）と有料ティア（$9/月 Pro、$99/月 Team、エンタープライズカスタム）。請求は、ワークフローストレージ、実行履歴、MCP ゲートウェイをカバーします。
• セルフホスト – Docker-Compose スタック（PocketBase + ゲートウェイ + エディター）。モデルサービングには独自の Ollama を使用します。エンジンとエージェントは Apache-2.0 です。ゲートウェイは現在 FSL-1.1-ALv2 です（2029 年に Apache-2.0 に変換されます）。

トレードオフ / 制限

• MCP 対応クライアントまたはカスタムフックが必要 – すべての AI チャットツールがサポートしているわけではありません。
• ワークフローは手書きの JSON です（ただし、エージェントは statewright_create_workflow で生成できます）。
• 過度に制限的なワークフローはエージェントをスタックさせる可能性があります。statewright_deactivate コマンドでガードをバイパスできます。
• 研究結果は小さなベンチマークサブセットに限定されています。

誰が使うのか？

• 開発チーム – 安全で監査可能な AI 支援コード変更を望む。
• ツールビルダー – 厳格なポリシー執行で LLM エージェントを埋め込みたい。
• 研究者 – ステートマシンガイドのプロンプトや状態ごとのモデルルーティングを探求。

---

TL;DR: Statewright は Rust ベースのオープンソースツールキットで、ステートマシン駆動の AI エージェントワークフローを定義し、状態ごとのツール権限を強制し、異なるフェーズを異なるモデルにルーティングできます。いくつかの最新の AI コーディングアシスタントと統合し、セルフホストまたはマネージドクラウドサービスを介して使用できます。