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
22 changes: 22 additions & 0 deletions docs/quota-allocation.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,28 @@ depending on the executor:

## Goal Review Cadence

Fresh autonomous replan work shares the Goal's compute window. Once
`spent_slots >= allowed_slots`, its extra allowance is **zero**: `quota should-run`
returns the existing typed `throttled_skip` action rather than admitting a
replan wakeup. A pending replan remains pending until rolling-window accounting
restores allowance or the owner increases the existing compute budget. This
also applies when a focus or external wait masks the exhausted window. Replan
still precedes monitor quiet and lane waits while compute remains available.
Recovery of a positively admitted replan keeps its original Goal, Agent, Turn
and obligation when the window later fills. Verified writeback still uses the
original settlement plan, including qualified no-debit closeouts. If the
spend owner rejects the debit because the window is full, retry that same
settlement when allowance returns. Owner Stop and zero compute pause
automatic execution.

新的自主重规划与 Goal 共用算力窗口。`spent_slots >= allowed_slots` 时,额外额度为
**零**;`quota should-run` 使用现有的 typed `throttled_skip`,不再为待处理的重规划
唤醒模型。等待滚动窗口恢复额度,或 owner 提高已有算力预算后重新判断;focus 或
外部等待不会豁免这一限制。有剩余额度时,重规划仍优先于 monitor quiet 和 lane wait。
已有准入收据的重规划在额度用尽后仍按原 Goal、Agent、Turn 和义务恢复;已验证的
写回沿原结算计划收尾,仍支持符合条件的免扣额收尾。扣额责任方因窗口已满拒绝扣额时,
等额度恢复后重试同一笔结算。Owner Stop 和零算力暂停自动执行。

The product and benchmark runners default to review after **6 settled effective
work Turns** in both standard and fine-grained modes. This changes the previous
product threshold of five Turns and benchmark threshold of three Turns. Review
Expand Down
7 changes: 7 additions & 0 deletions loopx/control_plane/quota/decision_summary.py
Original file line number Diff line number Diff line change
Expand Up @@ -265,6 +265,7 @@ def resolve_quota_run_decision(
goal_frontier_projection: dict[str, Any] | None,
task_orchestration_contract: dict[str, Any] | None,
receipt_bound_replan_phase: ReceiptBoundReplayPhase | None = None,
receipt_bound_replan_execution_pending: bool = False,
) -> QuotaRunDecision:
"""Apply the ordered final guards for one quota run decision."""

Expand All @@ -289,6 +290,8 @@ def resolve_quota_run_decision(
"self_repair_allowed": self_repair_allowed,
"repair_effective_action": str(repair_action or ""),
"state": state, "reason": reason,
"quota_allowed_slots": str(quota["allowed_slots"]) if quota.get("allowed_slots") is not None else None,
"quota_spent_slots": str(quota["spent_slots"]) if quota.get("spent_slots") is not None else None,
"quota_focus_wait": bool(quota.get("focus_wait")),
"capability_gate": _guard_strings(capability_gate, ("action", "reason")),
"capability_monitor_fallback": bool(capability_monitor_fallback),
Expand All @@ -297,6 +300,10 @@ def resolve_quota_run_decision(
"automation_prompt_upgrade_required": automation_prompt_upgrade_required,
"replan_required": replan_required,
"replan_applies": bool(scope.get("applies")),
"replan_execution_pending": (
receipt_bound_replan_execution_pending
and (replan_obligation or {}).get("selection_binding") == "heartbeat_receipt"
),
"replan_settlement_pending": (
receipt_bound_replan_phase is ReceiptBoundReplayPhase.SETTLEMENT_PENDING
and (replan_obligation or {}).get("selection_binding") == "heartbeat_receipt"
Expand Down
10 changes: 10 additions & 0 deletions loopx/control_plane/quota/heartbeat_receipt_identity.ts
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,16 @@ export function heartbeatReceiptFactFromEvent(
};
}

/** Read positive autonomous replan admission from an effective guard receipt. */
export function admitsAutonomousReplan(event: JsonObject, fact: HeartbeatReceiptFact): boolean {
const guard = heartbeatReceiptDetails(event);
const obligationId = normalizeHeartbeatReplanObligationId(guard.semantic_replan_obligation_id);
return fact.settlement_effect_id !== null && obligationId !== null
&& (fact.todo_id !== null || obligationId === fact.replan_obligation_id)
&& guard.interaction_mode === "autonomous_replan" && guard.ok === true && guard.should_run === true
&& guard.must_attempt_work === true && guard.delivery_allowed === false && guard.quiet_noop_allowed === false;
}

/**
* Resolve the settlement binding a persisted receipt declares.
*
Expand Down
10 changes: 7 additions & 3 deletions loopx/control_plane/quota/live_decision.py
Original file line number Diff line number Diff line change
Expand Up @@ -56,10 +56,14 @@ def _receipt_bound_guard_fields(
guard = getattr(readback, "semantic_replan_guard", None)
receipt = getattr(readback, "heartbeat_receipt", None) or {}
identity = readback.identity.value if readback is not None else None
guard_scoped = bool(
obligation_id and isinstance(guard, Mapping) and guard.get("scope") == "turn_guard"
and guard.get("selected_obligation_id") == obligation_id
)
return {
"receipt_bound_replan_guard_scoped": bool(
obligation_id and isinstance(guard, Mapping) and guard.get("scope") == "turn_guard"
and guard.get("selected_obligation_id") == obligation_id
"receipt_bound_replan_guard_scoped": guard_scoped,
"receipt_bound_replan_execution_pending": bool(
guard_scoped and readback and readback.replan_execution_pending
Comment thread
huangruiteng marked this conversation as resolved.
Resolved
),
"receipt_bound_guard_recorded_at": receipt.get("recorded_at"),
"receipt_bound_guard_turn_instance_id": identity.turn_instance_id if identity is not None else None,
Expand Down
12 changes: 1 addition & 11 deletions loopx/control_plane/quota/prior_turn_closeout.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,9 @@ import type { JsonObject } from "../effect_program.ts";
import { EffectRuntimeRequestError } from "../effect_runtime_errors.ts";
import { jsonObject } from "../runtime_decode.ts";
import {
admitsAutonomousReplan,
heartbeatReceiptBinding,
heartbeatReceiptDetails,
heartbeatReceiptFactFromEvent,
normalizeHeartbeatReplanObligationId,
selectEffectiveHeartbeatReceipt,
type HeartbeatReceiptBinding,
type HeartbeatReceiptFact,
Expand Down Expand Up @@ -56,15 +55,6 @@ function candidate(
};
}

function admitsAutonomousReplan(event: JsonObject, fact: HeartbeatReceiptFact): boolean {
const guard = heartbeatReceiptDetails(event);
const obligationId = normalizeHeartbeatReplanObligationId(guard.semantic_replan_obligation_id);
return fact.settlement_effect_id !== null && obligationId !== null
&& (fact.todo_id !== null || obligationId === fact.replan_obligation_id)
&& guard.interaction_mode === "autonomous_replan" && guard.ok === true && guard.should_run === true
&& guard.must_attempt_work === true && guard.delivery_allowed === false && guard.quiet_noop_allowed === false;
}

/**
* Select prior Turns eligible for closeout readback. A Todo-bound replan
* carries the Todo settlement identity and a separate semantic obligation.
Expand Down
28 changes: 27 additions & 1 deletion loopx/control_plane/quota/run_decision.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,16 @@ interface RunFacts {
state: string;
reason: string;
quota_focus_wait: boolean;
quota_allowed_slots: bigint | null;
quota_spent_slots: bigint | null;
capability_gate: JsonObject | null;
capability_monitor_fallback: boolean;
workspace_guard: JsonObject | null;
automation_prompt_upgrade: JsonObject | null;
automation_prompt_upgrade_required: boolean;
replan_required: boolean;
replan_applies: boolean;
replan_execution_pending: boolean;
replan_settlement_pending: boolean;
goal_health_ok: boolean;
inbox_reply_due: boolean;
Expand Down Expand Up @@ -63,13 +66,17 @@ function decodeRunFacts(params: JsonObject): RunFacts {
repair_effective_action: text(params.repair_effective_action, "repair_effective_action"),
state: text(params.state, "state"), reason: text(params.reason, "reason"),
quota_focus_wait: requireBoolean(params.quota_focus_wait, "quota_focus_wait"),
quota_allowed_slots: quotaCount(params.quota_allowed_slots, "quota_allowed_slots"),
quota_spent_slots: quotaCount(params.quota_spent_slots, "quota_spent_slots"),
capability_gate: optionalRecord(params.capability_gate, "capability_gate"),
capability_monitor_fallback: requireBoolean(params.capability_monitor_fallback, "capability_monitor_fallback"),
workspace_guard: optionalRecord(params.workspace_guard, "workspace_guard"),
automation_prompt_upgrade: optionalRecord(params.automation_prompt_upgrade, "automation_prompt_upgrade"),
automation_prompt_upgrade_required: requireBoolean(params.automation_prompt_upgrade_required, "automation_prompt_upgrade_required"),
replan_required: requireBoolean(params.replan_required, "replan_required"),
replan_applies: requireBoolean(params.replan_applies, "replan_applies"),
replan_execution_pending: params.replan_execution_pending === undefined ? false
: requireBoolean(params.replan_execution_pending, "replan_execution_pending"),
replan_settlement_pending: params.replan_settlement_pending === undefined ? false
: requireBoolean(params.replan_settlement_pending, "replan_settlement_pending"),
goal_health_ok: requireBoolean(params.goal_health_ok, "goal_health_ok"),
Expand All @@ -88,6 +95,14 @@ function nonNegativeCount(value: unknown, label: string): number {
return Number(value);
}

function quotaCount(value: unknown, label: string): bigint | null {
if (value === null || value === undefined) return null;
// Decimal transport preserves Python's integer precision without rounding quota boundaries.
if (typeof value !== "string" || !/^\d+$/.test(value))
throw new EffectRuntimeRequestError(`${label} must be a non-negative integer string`);
return BigInt(value);
}

function guardReason(guard: JsonObject | null, fallback: string): string {
return (guard ? text(guard.reason ?? "", "guard.reason") : "") || fallback;
}
Expand Down Expand Up @@ -139,8 +154,19 @@ function quotaEffectiveAction(facts: RunFacts, decision: RunDecision): string {

function applyGoalOverrides(facts: RunFacts, decision: RunDecision): void {
const inboxPriority = facts.inbox_reply_due || facts.inbox_material_review_due;
decision.replan_decision_allowed = !inboxPriority && facts.replan_required && facts.replan_applies
const replanSelected = !inboxPriority && facts.replan_required && facts.replan_applies
&& facts.goal_health_ok && !facts.workspace_guard && !facts.automation_prompt_upgrade_required;
const quotaExhausted = facts.state === "throttled" || (facts.quota_allowed_slots !== null
&& facts.quota_spent_slots !== null && facts.quota_spent_slots >= facts.quota_allowed_slots);
const budgetAllowsReplan = !quotaExhausted || facts.replan_execution_pending || facts.replan_settlement_pending;
decision.replan_decision_allowed = replanSelected && budgetAllowsReplan;
if (replanSelected && !budgetAllowsReplan) {
clearExecutionLanes(decision);
decision.should_run = false;
decision.effective_action = EffectiveAction.THROTTLED_SKIP;
decision.reason = "compute window exhausted; fresh replan has zero extra allowance; "
+ "wait until the window resets or the owner raises the compute budget";
}
if (decision.replan_decision_allowed) {
if (facts.replan_settlement_pending) {
// A covered frontier can stop new work before its original receipt has
Expand Down
2 changes: 2 additions & 0 deletions loopx/control_plane/quota/settlement.py
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,7 @@ class QuotaSettlementReadback:
native_child_admission: dict[str, Any] | None = None
heartbeat_reentry_qualification: dict[str, Any] | None = None
successor_replan_pending: bool = False
replan_execution_pending: bool = False


def render_owed_host_command(argv: list[str]) -> str:
Expand Down Expand Up @@ -547,6 +548,7 @@ def read_heartbeat_settlement(
native_child_admission=_optional_readback_record(payload.get("native_child_admission")),
heartbeat_reentry_qualification=_optional_readback_record(payload.get("heartbeat_reentry_qualification")),
successor_replan_pending=payload.get("successor_replan_pending") is True,
replan_execution_pending=payload.get("replan_execution_pending") is True,
spend_run=_optional_readback_record(payload.get("spend_run")),
heartbeat_receipt=_optional_readback_record(payload.get("heartbeat_receipt")),
writeback_event=_optional_readback_record(payload.get("writeback_event")),
Expand Down
3 changes: 3 additions & 0 deletions loopx/control_plane/quota/settlement_readback.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ import {
type RefreshRetryRequest,
} from "./refresh_recovery.ts";
import {
admitsAutonomousReplan,
heartbeatReceiptDetails as details,
heartbeatReceiptFactFromEvent,
normalizeHeartbeatReplanObligationId as normalizeReplanObligationId,
Expand Down Expand Up @@ -1430,6 +1431,8 @@ function readQuotaSettlementFromRequest(
completion_event: includeRecords ? completionEvent : null,
monitor_phase: monitorPhase,
replay_phase: replayPhase,
replan_execution_pending: replayPhase === "open" &&
admitsAutonomousReplan(heartbeatReceipt, heartbeatReceiptFactFromEvent(heartbeatReceipt)),
successor_replan_pending: replayPhase === "open" &&
heartbeatReceipt.status === "successor_replan_required" &&
receiptDetails.should_run === true && receiptDetails.delivery_allowed === false,
Expand Down
2 changes: 2 additions & 0 deletions loopx/control_plane/quota/should_run.py
Original file line number Diff line number Diff line change
Expand Up @@ -566,6 +566,7 @@ def build_quota_should_run(
receipt_bound_terminal_phase: ReceiptBoundTerminalPhase | None = None,
receipt_bound_replan_obligation_id: str | None = None,
receipt_bound_replan_guard_scoped: bool = False,
receipt_bound_replan_execution_pending: bool = False,
receipt_bound_successor_replan: bool = False,
receipt_bound_guard_recorded_at: str | None = None,
receipt_bound_guard_turn_instance_id: str | None = None,
Expand Down Expand Up @@ -663,6 +664,7 @@ def build_quota_should_run(
receipt_bound_replay_phase=receipt_bound_replay_phase,
receipt_bound_replan_obligation_id=receipt_bound_replan_obligation_id,
receipt_bound_replan_guard_scoped=receipt_bound_replan_guard_scoped,
receipt_bound_replan_execution_pending=receipt_bound_replan_execution_pending,
receipt_bound_successor_replan=receipt_bound_successor_replan,
authoritative_fallback_todo_items=authoritative_fallback_todo_items,
replan_explore_reader=tracked_replan_explore_reader,
Expand Down
1 change: 1 addition & 0 deletions loopx/control_plane/quota/should_run_packet.py
Original file line number Diff line number Diff line change
Expand Up @@ -935,6 +935,7 @@ def _resolve_quota_should_run_route(
registered_agent_ids=prepared.registered_agent_ids,
goal_frontier_projection=prepared.goal_frontier_projection,
task_orchestration_contract=prepared.task_orchestration_contract,
receipt_bound_replan_execution_pending=prepared.receipt_bound_replan_execution_pending,
receipt_bound_replan_phase=(
prepared.receipt_bound_replay_phase
if prepared.receipt_bound_todo_id is None
Expand Down
3 changes: 3 additions & 0 deletions loopx/control_plane/quota/should_run_prepare.py
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,7 @@ class _QuotaDecisionPreparation:
action_selection_qualification: dict[str, Any] | None
receipt_bound_monitor_phase: ReceiptBoundMonitorPhase | None
receipt_bound_replay_phase: ReceiptBoundReplayPhase | None
receipt_bound_replan_execution_pending: bool
user_todo_summary: dict[str, Any] | None
agent_todo_summary: dict[str, Any] | None
agent_todo_planning_source_items: list[dict[str, Any]]
Expand Down Expand Up @@ -750,6 +751,7 @@ def _prepare_quota_should_run_item(
receipt_bound_replay_phase: ReceiptBoundReplayPhase | None,
receipt_bound_replan_obligation_id: str | None,
receipt_bound_replan_guard_scoped: bool = False,
receipt_bound_replan_execution_pending: bool = False,
receipt_bound_successor_replan: bool = False,
authoritative_fallback_todo_items: FallbackTodoSource = None,
replan_explore_reader: Callable[[str, str | None], Mapping[str, Any] | None] | None = None,
Expand Down Expand Up @@ -1109,6 +1111,7 @@ def _prepare_quota_should_run_item(
action_selection_qualification=None,
receipt_bound_monitor_phase=receipt_bound_monitor_phase,
receipt_bound_replay_phase=receipt_bound_replay_phase,
receipt_bound_replan_execution_pending=receipt_bound_replan_execution_pending,
user_todo_summary=user_todo_summary,
agent_todo_summary=agent_todo_summary,
agent_todo_planning_source_items=agent_todo_planning_source_items,
Expand Down
2 changes: 2 additions & 0 deletions loopx/quota.py
Original file line number Diff line number Diff line change
Expand Up @@ -1078,6 +1078,7 @@ def build_quota_should_run(
receipt_bound_terminal_phase: ReceiptBoundTerminalPhase | None = None,
receipt_bound_replan_obligation_id: str | None = None,
receipt_bound_replan_guard_scoped: bool = False,
receipt_bound_replan_execution_pending: bool = False,
receipt_bound_successor_replan: bool = False,
receipt_bound_guard_recorded_at: str | None = None,
receipt_bound_guard_turn_instance_id: str | None = None,
Expand Down Expand Up @@ -1122,6 +1123,7 @@ def read_explore_context(read_goal_id: str, read_agent_id: str | None) -> dict[s
receipt_bound_terminal_phase=receipt_bound_terminal_phase,
receipt_bound_replan_obligation_id=receipt_bound_replan_obligation_id,
receipt_bound_replan_guard_scoped=receipt_bound_replan_guard_scoped,
receipt_bound_replan_execution_pending=receipt_bound_replan_execution_pending,
receipt_bound_successor_replan=receipt_bound_successor_replan,
receipt_bound_guard_recorded_at=receipt_bound_guard_recorded_at,
receipt_bound_guard_turn_instance_id=receipt_bound_guard_turn_instance_id,
Expand Down
21 changes: 16 additions & 5 deletions tests/control_plane/test_effect_turn_live_quota_decision.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,15 +33,26 @@
GOAL_ID = "effect-interpreter-fixture"


@pytest.mark.parametrize("selected", ["replan-1111111111111111", "replan-2222222222222222"])
def test_receipt_guard_fields_use_the_typed_identity_and_guard(selected: str) -> None:
@pytest.mark.parametrize(
("guard_matches", "execution_pending", "expected_pending"),
[(True, True, True), (True, False, False), (False, True, False)],
ids=["matching-open", "matching-not-pending", "different-obligation"],
)
def test_receipt_guard_fields_use_the_typed_identity_and_guard(
guard_matches: bool, execution_pending: bool, expected_pending: bool,
) -> None:
obligation = "replan-1111111111111111"
selected = obligation if guard_matches else "replan-2222222222222222"
fields = _receipt_bound_guard_fields(SimpleNamespace(
semantic_replan_guard={"scope": "turn_guard", "selected_obligation_id": selected},
identity=SimpleNamespace(value=SimpleNamespace(turn_instance_id="original-turn")),
heartbeat_receipt={"recorded_at": "2026-08-01T00:00:00Z", "run_id": "other-turn",
"details": {"semantic_replan_obligation_id": "replan-1111111111111111"}},
successor_replan_pending=False), "replan-1111111111111111")
assert fields["receipt_bound_replan_guard_scoped"] is (selected == "replan-1111111111111111")
"details": {"semantic_replan_obligation_id": obligation}},
successor_replan_pending=False,
replan_execution_pending=execution_pending,
), obligation)
assert fields["receipt_bound_replan_guard_scoped"] is guard_matches
assert fields["receipt_bound_replan_execution_pending"] is expected_pending
assert fields["receipt_bound_guard_turn_instance_id"] == "original-turn"
assert fields["receipt_bound_guard_recorded_at"] == "2026-08-01T00:00:00Z"

Expand Down
Loading
Loading