statewright/statewright

statewright – AI 에이전트 도구 사용을 위한 가드레일

무엇인가요 – LLM 기반 에이전트(Claude Code, Codex, Cursor, OpenCode, Pi 등)를 결정론적 상태기계로 감싸는 오픈소스 프레임워크입니다. 각 상태는 에이전트가 호출할 수 있는 도구(읽기, 편집, bash, 테스트 등), 사용할 모델, 예산 제한, 전이 조건을 정의합니다. 엔진은 런타임에 이러한 규칙을 강제하여 허용되지 않은 도구 호출을 거부하고 사용자에게 적절한 단계로 전환하도록 유도합니다.

왜 중요한가요 – 현대의 코드 작성 에이전트는 '취약한' 행동을 보입니다: 파일을 반복해서 읽고, 파괴적인 명령어를 실행하거나, 테스트가 통과하기 전에 배포합니다. Statewright는 에이전트의 행동을 제한함으로써 문제 영역을 축소하고, 자유로운 프롬프트를 가이드된 워크플로우로 전환하여 더 큰 모델 없이도 신뢰성을 향상시킵니다.

핵심 구성 요소

• 엔진 (Rust) – LLM에 의존하지 않는 순수 Rust 상태기계 평가기, 결정론적입니다.
• 에이전트 바이너리 (sw-agent) – Ollama 또는 호스트의 API를 통해 LLM을 현재 상태 내에서 실행하고, JSONL 이벤트를 스트리밍하며, 각 상태의 도구 정책을 준수합니다.
• 실행자 / MCP 게이트웨이 – 에이전트를 호스트 플랫폼(Claude Code, Codex, Cursor 등)에 연결하며, 인증, 세션 격리, 텔레메트리 처리를 담당합니다.
• TUI (statewright) – ratatui로 구축된 터미널 UI로 워크플로우를 시각화하고 슬래시 명령어로 워크플로우 시작/전이를 가능하게 합니다.

주요 기능

• 상태별 도구 강제 – allowed_tools에 나열된 도구만 호출 가능합니다.
• Bash 안전성 – 상태가 명시적으로 쓰기 수준 작업을 허용하지 않는 한, 파괴적인 리디렉션, rm -rf, 스크립트 인터프리터를 차단합니다.
• 편집 가드 – 각 상태당 편집된 라인 수/파일 수에 제한이 있습니다.
• 명령어 허용 목록 – 테스트 명령어(예: pytest)를 화이트리스트로 지정할 수 있습니다.
• 조건부 전이 및 승인 게이트 – 전이는 런타임 데이터(테스트 결과)에 따라 달라질 수 있으며, 인간의 승인이 필요할 수도 있습니다.
• 모델 라우팅 – 다른 상태는 서로 다른 모델을 대상으로 할 수 있습니다(예: 진단에는 저렴한 Haiku, 수정에는 비싼 Opus).
• 자체 호스팅 – BYO Ollama를 포함한 Docker-Compose 스택(PocketBase + 게이트웨이); Apache-2.0 라이선스 엔진.

빠른 시작 (호스트 선택)

# Codex
npx statewright-codex@latest init
# Claude Code
/plugin marketplace add statewright/statewright && /plugin install statewright
# OpenCode, Cursor 등
npx statewright-<host>@latest init

그런 다음 statewright.ai 에 가입하여 API 키를 얻고 워크플로우를 실행하세요:

❯ start the bugfix workflow — fix the failing tests in calc.py
…
[statewright] testing => completed
Workflow complete. 46 s.

슬래시 명령어 /statewright start bugfix 로도 호출할 수 있습니다.

연구 요약 – SWE-bench의 5개 작업 서브셋에서, 13GB 미만의 로컬 모델은 파일 편집을 올바르게 수행하지 못했지만, 13GB 이상의 모델은 Statewright 제약 하에서 10/10 성공을 달성했으며, 가드레일의 영향을 입증했습니다.

라이선스 – 엔진과 에이전트는 Apache 2.0; 전체 프로젝트는 FSL-1.1-ALv2 구성 요소를 포함하며, 2029년에 Apache 2.0으로 전환될 예정입니다. 독립 구현을 위한 특허 포기 보장이 있습니다.

더 알아보기 – 전체 문서, 워크플로우 스키마, 시각적 에디터는 https://docs.statewright.ai 에 있습니다. 리포지토리에는 예제 워크플로우, Rust 소스(crates/*), 각 지원 호스트용 플러그인 어댑터도 포함되어 있습니다.