‏Statewright: گارد‌ریل ماشین وضعیت برای ایجنت‌های هوش مصنوعی

ایجنت‌های هوش مصنوعی وقتی با ۴۰ تا ابزار مختلف و یه مسئله باز روبه‌رو می‌شن، اغلب گیج می‌شن و کارایی‌شون افت می‌کنه. راه‌حل رایج اینه که مدل بزرگ‌تر بشه یا پرامپت طولانی‌تر نوشته بشه — که فقط «بعضی وقت‌ها» جواب می‌ده. Statewright یه رویکرد متفاوت داره: به‌جای بزرگ‌تر کردن مدل، مسئله رو کوچیک‌تر می‌کنه.

ایده اصلی اینه که یه ماشین وضعیت (state machine) تعریف کنی که مشخص می‌کنه ایجنت در هر فاز کاری به کدوم ابزارها دسترسی داره. مثلاً در فاز برنامه‌ریزی فقط ابزارهای خواندن (Read, Grep, Glob) فعال‌ان. در فاز پیاده‌سازی ابزارهای ویرایش باز می‌شن، ولی دستورات مخرب مثل rm یا ریدایرکت‌های شل همچنان بلاک‌ان. در فاز تست هم فقط دستوراتی مثل pytest یا npm test مجازن.

{
  "id": "bugfix",
  "initial": "planning",
  "states": {
    "planning": {
      "allowed_tools": ["Read", "Grep", "Glob"],
      "max_iterations": 8,
      "on": { "READY": "implementing" }
    },
    "implementing": {
      "allowed_tools": ["Read", "Edit", "Write"],
      "max_edit_lines": 20,
      "max_files_per_state": 3,
      "on": { "DONE": "testing" }
    }
  }
}

این تعریف ورک‌فلو به‌صورت JSON نوشته می‌شه و موتور Rust زیرین اون رو به‌شکل کاملاً قطعی (بدون هیچ مدل زبانی در حلقه) اجرا می‌کنه. اگه ایجنت سعی کنه از ابزاری خارج از فاز جاری استفاده کنه، درخواستش رد می‌شه و دقیقاً گفته می‌شه چی مجازه و چطور باید transition کنه.

نتایج آزمایش‌ها روی مدل‌های لوکال خیلی جالبه: در یه مجموعه ۵ تسکی از SWE-bench، دو مدل با وزن ۱۳.۸ و ۱۹.۹ گیگابایت با محدودیت‌های Statewright از نتیجه ۲ از ۱۰ به ۱۰ از ۱۰ رسیدن — همون سخت‌افزار، همون تسک‌ها. البته مدل‌های زیر ۱۳ گیگابایت همچنان مشکل دارن چون محتوای فایل رو به‌اندازه کافی نگه نمی‌دارن، که این محدودیت Statewright نیست.

یه فایده عملی دیگه برای مدل‌های بزرگ‌تر اینه که حلقه‌های «خواندن بی‌پایان» شکسته می‌شن — حالتی که مدل یه فایل رو ۵ بار پشت سر هم می‌خونه بدون اینکه دست به ویرایش بزنه. با محدود بودن فضای ابزار، مدل واقعاً استدلال می‌کنه به‌جای اینکه سرگردان بشه.

نصب Statewright روی Claude Code با یه دستور پلاگین انجام می‌شه و با ابزارهایی مثل Cursor، Codex، opencode و Pi هم کار می‌کنه. ورک‌فلوهای پیش‌فرض مثل bugfix آماده‌ان و می‌شه ورک‌فلوهای سفارشی هم تعریف کرد.

نکات کلیدی:

• ماشین وضعیت تعیین می‌کنه ایجنت در هر فاز به کدوم ابزارها دسترسی داشته باشه
• موتور Rust کاملاً قطعیه — هیچ مدل زبانی در اجرای گارد‌ریل‌ها دخیل نیست
• مدل‌های ۱۳ تا ۲۰ گیگابایتی لوکال در SWE-bench از ۲/۱۰ به ۱۰/۱۰ رسیدن
• دستورات مخرب شل حتی وقتی Bash مجازه، بلاک می‌مونن
• با Claude Code، Cursor، Codex، opencode و Pi سازگاره