Codex Runway

Codex Runway — локальный инструмент в статусе Alpha для длинной работы Codex. Перед большой или тесно связанной фазой он выдаёт рекомендацию, стоит ли начинать её в текущем окне контекста. Если граница контекста всё же наступит, проект сохраняет короткое рабочее состояние вне репозитория и позволяет продолжить с проверяемой точки, а не восстанавливать ход задачи по обрывкам диалога.

Это не ещё один индикатор остатка токенов. Одинаковые 20 000 токенов могут означать дешёвую правку, которую легко повторить, или выпуск, где потеря промежуточных решений обойдётся дорого. Поэтому Runway сопоставляет телеметрию конкретного треда с оценкой всей следующей фазы, стоимостью её прерывания и свежестью сохранённого состояния.

Решение относится к фазе, а не ко всей задаче

Фаза — это ограниченный смысловой блок, который агент намерен закончить в рамках одной оценки и одной модели восстановления: например, изменить парсер и прогнать связанные тесты или провести выпуск вместе с финальной проверкой. На входе Runway получает явную оценку такого блока и возвращает одно из четырёх решений:

• go — фаза помещается вместе с резервом на безопасное завершение;
• checkpoint_first — места хватает, но сначала нужно обновить контрольную точку и повторить preflight;
• defer — именно эта фаза не помещается; можно выделить меньшую полезную работу и оценить её отдельно;
• unknown — данных недостаточно или они противоречат друг другу, поэтому дорогостоящую связанную фазу начинать нельзя.

Оценка детерминирована: при одинаковых входах результат и коды причин одинаковы. Базовый резерв составляет не меньше 8192 токенов или 5% окна, а затем растёт с ценой восстановления. Результат также содержит знаковый estimate_margin_tokens: для go это запас на рост оценки, для defer — приблизительный дефицит. Сам Runway не придумывает стоимость работы и не подменяет инженерное суждение агента; он делает предпосылки и арифметику видимыми.

Телеметрия только для точного треда

get_context_usage читает ограниченный хвост локальной истории Codex для явно переданного канонического UUID активного треда. Он возвращает счётчики и метаданные свежести, но не промпты, ответы, имена файлов, секреты, сырые записи или фрагменты лога. Это снимок последнего записанного запроса, а не живая память процесса и не счётчик биллинга.

Инструмент принципиально не выбирает самый свежий лог, не ищет сессию по рабочему каталогу и не принимает запасной идентификатор. Точный UUID должен прийти из доверенного runtime-контекста. Если окно неизвестно, история обрезана, после compaction ещё нет нового надёжного измерения или нужный тред нельзя однозначно определить, неопределённость сохраняется в ответе. Runway не восстанавливает отсутствующие бюджеты из процентов и не выдаёт наблюдения о compaction за знание скрытого порога.

Рабочий цикл без постоянного опроса

Поставляемый вместе с сервером skill задаёт порядок работы. Агент определяет целую кандидатную фазу, проверяет состояние контрольной точки, при необходимости восстанавливает её, оценивает смысловую свежесть, получает новую телеметрию и только затем вызывает assess_runway. Одного чтения счётчиков недостаточно: preflight завершён лишь после оценки конкретной фазы.

Успешное решение действует как аренда на неизменившиеся предпосылки, а не как таймер. Повторная оценка нужна, когда вырос ожидаемый объём, восстановление стало дороже, ответ инструмента оказался неожиданно большим или неограниченным, изменилась цель либо область работы, владение перешло другому агенту или checkout, либо был замечен compaction. Открытую повторяющуюся работу Runway предлагает делить на ограниченные пакеты и оценивать по мере исчерпания их бюджета — не после каждого мелкого действия.

Контрольные точки тоже обновляются по событиям. Новый существенный факт, решение, завершённая мутация, смена владения, блокер или следующий шаг немедленно делают состояние грязным. Его нужно записать до следующего вызова, который заметно увеличит контекст, до делегирования или дорогой подфазы; накапливать известные существенные изменения до «удобного момента» нельзя. Незначительные и независимо восстанавливаемые обновления можно объединять, пока восстановление остаётся дешёвым.

После настоящей границы контекста прежнее решение больше не действует. Агент читает сохранённое состояние, сверяет изменяемые факты с репозиторием и инструментами, получает свежую телеметрию и отдельно оценивает следующую фазу.

Приватное состояние для продолжения

Контрольная точка хранится не в рабочем дереве, а в локальном каталоге данных Codex. Пространство имён образуют канонический корень checkout и точный UUID треда. Поэтому связанные Git worktree не смешивают состояние даже при общей служебной директории, а один checkout не смешивает разные разговоры.

Формат намеренно короткий и структурированный: цель, ограничения пользователя, завершённая работа, существенные выводы и решения, владение изменениями, выполненные проверки, блокеры, точный следующий шаг и следующая кандидатная фаза. История разговора, полные выводы инструментов, окружение, rollout-записи и учётные данные в этот контракт не входят. Восстановленный текст считается недоверенным историческим состоянием: он не может выдать новые полномочия или отменить текущие инструкции.

Путь выбирает сервер, а не агент. Записи ограничены по размеру, защищены приватными правами, блокировкой, проверками символических ссылок и атомарной заменой. Обновление использует монотонную ревизию и compare-and-swap: при конфликте агент должен перечитать состояние и согласовать изменения, а не затереть более новую запись.

Пять MCP-инструментов

В версии v0.4.2 один локальный stdio-сервер предоставляет ровно пять инструментов:

• get_context_usage — читает ограниченный снимок использования контекста точного треда;
• assess_runway — оценивает заданную агентом фазу по явным предпосылкам;
• checkpoint_status — разрешает пространство имён checkout и треда и проверяет наличие состояния;
• checkpoint_read — возвращает проверенную структурированную контрольную точку;
• checkpoint_write — атомарно создаёт или обновляет её с compare-and-swap.

Первые четыре операции не изменяют состояние. checkpoint_write — единственная записывающая и неидемпотентная операция. JSON CLI предоставляет команды assess и usage, а чистое ядро оценки доступно также через Python API. Транспорта для контрольных точек в CLI намеренно нет: эти операции остаются в MCP, поэтому промежуточный JSON-файл и отдельный subprocess-runner больше не нужны.

Установка и граница доверия

Рекомендуемый установщик разворачивает MCP-сервер и соответствующий skill одним согласованным комплектом. Он работает без sudo, проверяет SHA-256 опубликованного wheel, создаёт версионированное пользовательское окружение, ставит зафиксированный хешами набор бинарных зависимостей, выполняет smoke-проверки и транзакционно обновляет только принадлежащие пакету конфигурацию и skill. Посторонние настройки сохраняются, а неоднозначное владение, изменённые управляемые файлы, конфликт области или неверная контрольная сумма приводят к отказу.

Глобальная установка доступна всем проектам текущего пользователя. Локальная ограничена одним уже доверенным Git checkout и требует явного подтверждения этого факта. Установщик не выдаёт проекту доверие и не меняет настройки доверия. Сам сервер работает с файловыми правами запустившего его пользователя; аннотации MCP описывают поведение, но не служат механизмом авторизации или многопользовательской изоляции.

Для запуска нужен Python 3.13 или новее; поддерживаемая и тестируемая матрица выпуска — 3.13–3.14. Основная среда — локальный Codex со stdio MCP-клиентом на Linux. После установки может потребоваться перезапуск Codex или IDE, чтобы текущий клиент перечитал регистрацию сервера и skill.

Как проект пришёл к версии 0.4.2

Версия v0.3.0 добавила приватные контрольные точки для продолжения после границы контекста и начала отдельно показывать реальные наблюдения compaction, не пытаясь вычислить по ним скрытый порог. В v0.4.0 хранение стало частью того же MCP-сервера: три checkpoint-инструмента заменили CLI-команды, subprocess-runner и временный JSON-поток. Пространство имён сменилось на пару «checkout + точный тред», появились атомарные CAS-обновления, знаковый запас оценки и событийная модель аренды. Этот переход намеренно не переносит контрольные точки v0.3.0 и не содержит слоя совместимости.

В v0.4.1 правило непрерывности стало строже: любое существенное изменение состояния нужно сохранить до следующей операции, способной заметно увеличить контекст. v0.4.2 меняет только статическую иллюстрацию и компоновку README; поведение runtime и схема из пяти MCP-инструментов остались прежними.

Что остаётся за пределами проекта

Codex Runway не определяет активный тред, не читает живые счётчики из памяти процесса, не предсказывает и не запускает compaction. Он не оценивает фазу вместо агента, не определяет смысловую свежесть контрольной точки, не планирует работу агентов и не заставляет клиента исполнять рекомендованное решение.

У проекта нет веб-интерфейса, демона, фонового опроса, облачного сервиса или хука жизненного цикла хоста. Его граница уже: локально получить ограниченные данные точного треда, детерминированно проверить одну фазу и безопасно сохранить минимум состояния, необходимый для продолжения.