Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -212,17 +212,17 @@ Scheduler ACK 本身不构成 delivery,不 spend。

### 兼容投影不能改变状态权威 / Compatibility preserves state authority

`app_automation` 与 `codex_app` 是同一 proposal 的宿主投影,不是两个 scheduler
writer。读取优先采用 common state;仅有旧 Codex state 时,保留它经 TS 验证的
`state_key`。两份投影的 backoff、host facts 与 ACK/failure 命令都必须携带同一个键。
否则 common state 的当前 identity/index 会被误写到旧键,触发真实的初始档位冲突;
即使 CAS digest 相等也不代表 proposal 的状态归属正确。

`app_automation` and `codex_app` project one proposal, not two scheduler writers.
Reads prefer common state; a legacy-only Codex installation retains its
TS-validated legacy key. Both projections must carry that same key through
backoff, host facts and ACK/failure commands. Equal CAS digests do not prove that
a proposal belongs to the chosen state scope.
新决策统一使用 `app_automation` 携带调度建议和宿主行动。旧捕获仍可读取其中的
`codex_app`。读取优先采用 common state。仅有旧 Codex state 时,保留 TS 验证过的
`state_key`,并将同一个键贯穿 backoff、host facts 与 ACK/failure 命令。
写回前须校验状态归属及 CAS 摘要,否则可能把已推进的档位写入错误的状态键。

New decisions use `app_automation` for the cadence proposal and Host actions.
Saved captures can still carry `codex_app`. Reads prefer common state. A
legacy-only Codex installation retains the TS-validated state key through
backoff, Host facts, and ACK/failure commands. Before writing, validate the
state scope and CAS digest to keep the recorded progression in its original
state.

兼容 Python API 与手工 Codex CLI 未显式传 `state_key` 时,从当前 packet 取得实际键;
显式键仍须匹配,不得静默改写。Trae 仍只接受 common key。这不是隐式迁移:不能把
Expand Down
4 changes: 2 additions & 2 deletions docs/operations/automation-minimum-interval.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ caller intent, not authentication against other processes sharing the OS user.

For an already bound App turn, inspect its `quota should-run` scheduler packet
using that turn's normal identity and selection contract. Do not create a new
turn solely to observe a timer. `scheduler_hint.app_automation` and its legacy
`codex_app` projection expose the floor, desired RRULE, apply/ACK state and
turn solely to observe a timer. `scheduler_hint.app_automation` exposes the
floor, desired RRULE, apply/ACK state and
`guarantee`. Apply the desired schedule with the App's `automation_update` tool,
preserving task binding, prompt, status and notification preference. Then view
that same automation and compare its actual schedule before running the returned
Expand Down
19 changes: 15 additions & 4 deletions docs/quota-allocation.md
Original file line number Diff line number Diff line change
Expand Up @@ -1798,6 +1798,11 @@ trigger uses a fresh Turn identity to evaluate the live frontier; it never
re-executes or spends for the closed Turn. Native Goal runtimes continue to that
fresh guard instead of blocking the Goal. Explicit Goal stop or quota pause
still takes precedence. Actual fresh-Turn waits retain their existing backoff.
New scheduler decisions expose App cadence, applicability, and follow-up
commands only under `scheduler_hint.app_automation`. This includes shutdown,
minimum-interval waits, and the explicit unavailable state for schedulers owned
outside the App. A saved decision retains its original representation. Older
Codex state still uses its recorded state key when it is the selected authority.
For Codex App and local schedulers, `recommended_interval_minutes` is the next
target interval. For Codex App heartbeats, `recommended_rrule` is emitted only
when `app_automation.stateful_backoff.apply_needed=true`; if the desired RRULE is
Expand All @@ -1823,10 +1828,16 @@ CLI-produced ACK hints bind that argument vector to the exact registry and
effective runtime root that produced `quota should-run`. Hosts must execute the
complete vector; stripping its leading global options can route a
project-launched ACK into project-local scheduler state instead of the shared
control plane. `fallback_hint.cli_args` receives the same registry binding, and
its `--turn-instance-id` value is always the reference the current host shell can
expand: `"${LOOPX_TURN:?}"` on POSIX and `$LOOPX_TURN` on native Windows, so a
PowerShell host does not replay an empty Turn. When the decision is
control plane. `fallback_hint.cli_args` receives the same registry and runtime
root bindings. The bridge reads `scheduler_hint.app_automation` from the
complete decision. It accepts a legacy `codex_app` packet from an earlier CLI
version. An executable-bound guard also passes its selected CLI to the
bridge. When that installation ships an executable POSIX fallback launcher
beside the CLI, the command also names that launcher. For older saved commands
without a runtime root, the registry route supplies it. When the Turn is still
expressed as a shell variable, the
fallback's `--turn-instance-id` uses `"${LOOPX_TURN:?}"` on POSIX and
`$LOOPX_TURN` on native Windows. When the decision is
heartbeat-receipted, ACK, failure, and fallback hints also bind the originating
concrete `turn_instance_id`, and `fallback_hint.route_binding.turn_instance_bound`
records whether that binding is present. The follow-up rebuilds the same
Expand Down
2 changes: 1 addition & 1 deletion examples/agent-diagnose-packet-smoke.py
Original file line number Diff line number Diff line change
Expand Up @@ -357,7 +357,7 @@ def main() -> int:
scheduler_hint = selected["quota_signals"]["scheduler_hint"]
assert scheduler_hint["schema_version"] == "diagnose_scheduler_hint_summary_v0", selected
assert "local_scheduler" not in str(scheduler_hint), scheduler_hint
assert scheduler_hint["codex_app"]["no_spend_for_cadence_change"] is True, scheduler_hint
assert scheduler_hint["app_automation"]["no_spend_for_cadence_change"] is True, scheduler_hint
assert selected["agent_reasoning_checklist"], selected
assert any(
" diagnose " in command and f"--goal-id {GOAL_ID}" in command
Expand Down
26 changes: 14 additions & 12 deletions examples/control_plane/control-plane-integrated-canary-smoke.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
PRIMARY_AGENT_ID = "codex-main-control"
CANARY_TODO_ID = "todo_integrated_canary"
CANARY_TODO_TITLE = "Design bounded status/quota/review-packet/Todo/read-path canary"
DURABLE_NEXT_ACTION = "Keep the fixture-only integrated canary under two minutes."
SUCCESSOR_TODO_TITLE = "Continue integrated canonical successor routing canary"
CONTINUATION_TITLE = "[P1] Continue same-agent canonical continuation through status and quota."
MONITOR_TODO_ID = "todo_integrated_due_monitor"
Expand All @@ -54,7 +55,7 @@ def write_fixture(root: Path) -> tuple[Path, Path, Path]:
"---\n\n"
"# Control Plane Integrated Canary\n\n"
"## Next Action\n\n"
"- Keep the fixture-only integrated canary under two minutes.\n\n"
f"- {DURABLE_NEXT_ACTION}\n\n"
"## Agent Todo\n\n"
"- [ ] [P2] Markdown fallback todo that should lose to the event log.\n"
" <!-- loopx:todo todo_id=todo_markdown_fallback status=open "
Expand Down Expand Up @@ -176,17 +177,17 @@ def find_queue_item(status_payload: dict[str, Any], *, goal_id: str = GOAL_ID) -
def assert_selected_agent_todo(
summary: dict[str, Any],
*,
compact_quota: bool = False,
complete_quota: bool = False,
) -> None:
item_lane = "first_executable_items" if compact_quota else "first_open_items"
item_lane = "first_executable_items" if complete_quota else "first_open_items"
items = summary.get(item_lane) if isinstance(summary.get(item_lane), list) else []
if not items and not compact_quota:
if not items and not complete_quota:
items = summary.get("items") if isinstance(summary.get("items"), list) else []
assert [item.get("todo_id") for item in items] == [CANARY_TODO_ID], summary
item = items[0]
if compact_quota:
if complete_quota:
assert summary["payload_compaction"]["schema_version"] == (
"quota_cli_todo_summary_compaction_v0"
"quota_todo_summary_payload_compaction_v0"
), summary
assert item["text"] == f"[P1] {CANARY_TODO_TITLE}", summary
# The shared diagnostic projection retains each visible record in full.
Expand Down Expand Up @@ -228,7 +229,7 @@ def assert_bounded_delivery_state_machine_bundle(quota_payload: dict[str, Any])
scheduler = quota_payload["scheduler_hint"]
assert scheduler["action"] == "run_now", scheduler
assert scheduler["cadence_class"] == "active_work", scheduler
codex_app = scheduler["codex_app"]
codex_app = scheduler["app_automation"]
assert codex_app["recommended_rrule"] == "FREQ=MINUTELY;INTERVAL=3", scheduler
assert codex_app["no_spend_for_cadence_change"] is True, scheduler
assert codex_app["stateful_backoff"]["apply_needed"] is True, scheduler
Expand Down Expand Up @@ -259,7 +260,7 @@ def assert_scheduler_ack_state_machine(
runtime_root: Path,
quota_payload: dict[str, Any],
) -> dict[str, Any]:
codex_app = quota_payload["scheduler_hint"]["codex_app"]
codex_app = quota_payload["scheduler_hint"]["app_automation"]
backoff = codex_app["stateful_backoff"]
ack_payload = run_cli(
registry_path,
Expand Down Expand Up @@ -300,7 +301,7 @@ def assert_scheduler_ack_state_machine(
AGENT_ID,
"--codex-app",
)
steady_codex_app = steady_payload["scheduler_hint"]["codex_app"]
steady_codex_app = steady_payload["scheduler_hint"]["app_automation"]
assert steady_codex_app["stateful_backoff"]["apply_needed"] is False, steady_payload
assert steady_codex_app["stateful_backoff"]["state_status"] == "same_identity", steady_payload
assert steady_codex_app["host_action"] == "none", steady_payload
Expand Down Expand Up @@ -394,9 +395,9 @@ def assert_todo_completion_successor_state_machine(
assert routed["effective_action"] == "normal_run", routed
assert routed["agent_lane_next_action"]["todo_id"] == successor_id, routed
assert routed["agent_lane_next_action"]["text"] == f"[P1] {SUCCESSOR_TODO_TITLE}", routed
assert "title" not in routed["agent_lane_next_action"], routed
assert routed["agent_lane_next_action"]["title"] == SUCCESSOR_TODO_TITLE, routed
assert routed["agent_lane_next_action"]["preserves_goal_next_action"] is True, routed
assert "active_state_next_action" not in routed, routed
assert routed["active_state_next_action"] == DURABLE_NEXT_ACTION, routed
assert routed["goal_route_hint"]["selected_action_differs_from_durable"] is True, routed
assert routed["goal_route_hint"]["goal_next_action_mutation"] == "none", routed
assert routed["interaction_contract"]["mode"] == "bounded_delivery", routed
Expand Down Expand Up @@ -499,6 +500,7 @@ def assert_due_monitor_poll_state_machine(root: Path, *, provider: str) -> None:
"--codex-app",
)
assert quota_payload["ok"] is True, quota_payload
assert quota_payload["schema_version"] == "loopx_turn_envelope_v1", quota_payload
assert quota_payload["should_run"] is True, quota_payload
assert quota_payload["decision"] == "run", quota_payload
assert quota_payload["effective_action"] == "normal_run", quota_payload
Expand Down Expand Up @@ -790,7 +792,7 @@ def run_fixture_canary(root: Path, *, provider: str) -> None:
assert CANARY_TODO_TITLE in quota_payload["recommended_action"], quota_payload
assert_selected_agent_todo(
quota_payload["agent_todo_summary"],
compact_quota=True,
complete_quota=True,
)
assert_bounded_delivery_state_machine_bundle(quota_payload)
assert_scheduler_ack_state_machine(registry_path, runtime_root, quota_payload)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -454,12 +454,12 @@ def assert_reassignment_scheduler_contract() -> None:
scheduler = quota["scheduler_hint"]
assert scheduler["action"] == "backoff_until_reassigned", scheduler
assert scheduler["cadence_class"] == "agent_scope_wait", scheduler
assert scheduler["codex_app"]["recommended_rrule"] == (
assert scheduler["app_automation"]["recommended_rrule"] == (
"FREQ=MINUTELY;INTERVAL=10"
), scheduler
assert scheduler["codex_app"]["recommended_interval_minutes"] == 10, scheduler
assert scheduler["codex_app"]["stateful_backoff"]["apply_needed"] is True, scheduler
assert scheduler["codex_app"]["no_spend_for_cadence_change"] is True, scheduler
assert scheduler["app_automation"]["recommended_interval_minutes"] == 10, scheduler
assert scheduler["app_automation"]["stateful_backoff"]["apply_needed"] is True, scheduler
assert scheduler["app_automation"]["no_spend_for_cadence_change"] is True, scheduler

packet = build_review_packet(payload, goal_id=GOAL_ID)
assert packet["ok"] is True, packet
Expand Down
4 changes: 2 additions & 2 deletions examples/control_plane/heartbeat-quota-flow-smoke.py
Original file line number Diff line number Diff line change
Expand Up @@ -812,8 +812,8 @@ def main() -> int:
assert first_guard["automation_liveness"]["pause_allowed"] is False, first_guard
assert first_guard["scheduler_hint"]["action"] == "backoff_until_material_transition", first_guard
assert first_guard["scheduler_hint"]["cadence_class"] == "monitor_wait", first_guard
assert first_guard["scheduler_hint"]["codex_app"]["recommended_interval_minutes"] == 15, first_guard
assert first_guard["scheduler_hint"]["codex_app"]["recommended_rrule"] == (
assert first_guard["scheduler_hint"]["app_automation"]["recommended_interval_minutes"] == 15, first_guard
assert first_guard["scheduler_hint"]["app_automation"]["recommended_rrule"] == (
"FREQ=MINUTELY;INTERVAL=15"
), first_guard
reset = first_guard["scheduler_hint"]["reset_policy"]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -291,7 +291,7 @@ def _assert_cross_layer_case(
assert contract["agent_channel"]["quiet_noop_allowed"] is quiet, (name, contract)
assert contract["cli_channel"]["spend_after_validation"] is spend, (name, contract)
assert scheduler_hint["action"] == scheduler, (name, scheduler_hint)
assert scheduler_hint["codex_app"]["recommended_interval_minutes"] == interval, (
assert scheduler_hint["app_automation"]["recommended_interval_minutes"] == interval, (
name,
scheduler_hint,
)
Expand Down
12 changes: 6 additions & 6 deletions examples/control_plane/monitor-poll-writeback-smoke.py
Original file line number Diff line number Diff line change
Expand Up @@ -657,7 +657,7 @@ def assert_material_transition_followup() -> None:
scheduler = handoff["scheduler_hint"]
assert scheduler["action"] == "run_now", scheduler
assert scheduler["cadence_class"] == "active_work", scheduler
assert scheduler["codex_app"]["recommended_rrule"] == "FREQ=MINUTELY;INTERVAL=3", scheduler
assert scheduler["app_automation"]["recommended_rrule"] == "FREQ=MINUTELY;INTERVAL=3", scheduler
contract = handoff["interaction_contract"]
assert contract["agent_channel"]["must_attempt"] is True, contract
assert contract["agent_channel"]["delivery_allowed"] is False, contract
Expand Down Expand Up @@ -1119,7 +1119,7 @@ def assert_cli_monitor_poll_preserves_codex_app_scheduler_context() -> None:
with tempfile.TemporaryDirectory(prefix="loopx-monitor-poll-codex-app-") as tmp:
hints = cli_monitor_poll_scheduler_hints(write_fixture(Path(tmp))[0], "--codex-app")
for scheduler_hint in hints:
assert scheduler_hint["codex_app"]["applicability"] == "applicable", scheduler_hint
assert scheduler_hint["app_automation"]["applicability"] == "applicable", scheduler_hint
assert scheduler_hint["action"] != "repair_scheduler_execution_context", scheduler_hint


Expand All @@ -1132,8 +1132,8 @@ def assert_cli_monitor_poll_preserves_outer_controller_scheduler_context() -> No
execution_context = scheduler_hint["execution_context"]
execution_phase = scheduler_hint["execution_phase"]
assert scheduler_hint["action"] != "repair_scheduler_execution_context", scheduler_hint
assert scheduler_hint["codex_app"]["applicability"] == "not_applicable", scheduler_hint
assert "stateful_backoff" not in scheduler_hint["codex_app"], scheduler_hint
assert scheduler_hint["app_automation"]["applicability"] == "not_applicable", scheduler_hint
assert "stateful_backoff" not in scheduler_hint["app_automation"], scheduler_hint
assert (
execution_context["host_surface"],
execution_context["scheduler_owner"],
Expand Down Expand Up @@ -1161,8 +1161,8 @@ def assert_cli_monitor_poll_invalid_scheduler_context_fails_closed() -> None:
execution_context = scheduler_hint["execution_context"]
execution_phase = scheduler_hint["execution_phase"]
assert scheduler_hint["action"] == "repair_scheduler_execution_context", scheduler_hint
assert scheduler_hint["codex_app"]["applicability"] == "blocked_invalid_context", scheduler_hint
assert "stateful_backoff" not in scheduler_hint["codex_app"], scheduler_hint
assert scheduler_hint["app_automation"]["applicability"] == "blocked_invalid_context", scheduler_hint
assert "stateful_backoff" not in scheduler_hint["app_automation"], scheduler_hint
assert execution_context["valid"] is False, scheduler_hint
assert execution_context["errors"] == [
"outer_controller requires execution_mode=isolated_headless"
Expand Down
Loading
Loading