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
9 changes: 9 additions & 0 deletions docs/reference/required-work-context.md
Original file line number Diff line number Diff line change
Expand Up @@ -503,6 +503,15 @@ cannot be combined with socket handoff. Ordinary callers keep their existing
presentation, and context delivery off keeps its original pending Goal reads.
Unbound staged replans retain their existing review-owned original Goal read.

If complete Turn composition fails after quota admission, the capture contains
the failure and original receipts for `quota context-read`. `quota context-project`
refuses the diagnostic capture. A saved diagnostic carries no executable input
or native claim source. Reconcile the original Turn receipt before recovery.

中文:额度 guard 已准入、完整 Turn 组合随后失败时,capture 保留失败与原回执,
可通过 `quota context-read` 读回。`quota context-project` 会拒绝该诊断
capture,活跃会话的认领来源保持原样。恢复前先核对原 Turn 回执。

After a Host claim, the ready guard uses the private
`--prepared-capture-reference` route. It publishes the complete decision and
returns its writer digest with the fields needed to verify the same Todo and
Expand Down
24 changes: 15 additions & 9 deletions loopx/cli_commands/quota_failure_report.py
Original file line number Diff line number Diff line change
Expand Up @@ -499,19 +499,12 @@ def _bounded_quota_transport_failure(
return result if _failure_output_size(result) <= limit else _compact_quota_failure()


def quota_decision_transport_failure_payload(
def quota_decision_transport_diagnostic(
args: argparse.Namespace,
committed: Mapping[str, object],
error: Exception,
*,
capture_directory: Path | None,
capture_sha256: str | None = None,
) -> dict[str, object]:
"""Report a post-guard failure with the original receipt and capture.

The saved digest, when available, comes from publication rather than
reopening the path to establish a new identity.
"""
"""Keep receipt evidence from a failed delivery without projecting work."""
typed_transport = isinstance(error, QuotaDecisionTransportError)
reason = (
" ".join(str(error).split())[:500] if typed_transport
Expand Down Expand Up @@ -539,6 +532,19 @@ def quota_decision_transport_failure_payload(
if not typed_transport:
failure["error_class"] = type(error).__name__
failure.update(verbose_debug_fields(error, verbose=bool(getattr(args, "verbose", False))))
return failure


def quota_decision_transport_failure_payload(
args: argparse.Namespace,
committed: Mapping[str, object],
error: Exception,
*,
capture_directory: Path | None,
capture_sha256: str | None = None,
) -> dict[str, object]:
"""Report the failure with the digest returned by the capture writer."""
failure = quota_decision_transport_diagnostic(args, committed, error)
limit = getattr(args, "max_page_output_bytes", None) if args.format == "json" else None
reader = getattr(args, "_quota_failure_reader", None)
if limit is not None:
Expand Down
2 changes: 2 additions & 0 deletions loopx/cli_commands/quota_native_context.py
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,8 @@ def project_saved_context_capture(args: argparse.Namespace, *, hook_session: str
_validate_context_page_window(args.offset, args.page_bytes, output_limit)
path, _, payload = _read_capture(args.capture_file, args.capture_sha256,
private=hook_session is not None)
if payload.get("ok") is False:
raise ValueError("The saved capture is diagnostic. Read it with quota context-read.")
identity = payload.get("agent_identity")
receipt = payload.get("heartbeat_receipt")
if (payload.get("ok") is not True or not isinstance(identity, dict) or not isinstance(receipt, dict)
Expand Down
14 changes: 7 additions & 7 deletions loopx/cli_commands/quota_presentation.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,6 @@
def compose_quota_work_contract(payload: dict[str, object], args: argparse.Namespace, *,
scheduler_context: Mapping[str, object] | SchedulerExecutionContextResolution | None,
capture_directory: Path | None,
native_context: bool,
record_capture: Callable[[dict[str, object], str], None] | None = None) -> dict[str, object]:
"""Compose every decided should-run source once before capture and display."""
if args.quota_command != "should-run" or not isinstance(payload.get("interaction_contract"), Mapping):
Expand All @@ -26,15 +25,16 @@ def compose_quota_work_contract(payload: dict[str, object], args: argparse.Names
composed_settlement=True)
except (EffectRuntimeRemoteError, EffectRuntimeStartupError) as exc:
from .quota_capture import capture_decision
from .quota_failure_report import quota_decision_transport_diagnostic

# Admission already happened. Keep its source/receipt; never emit a
# false v1, discard the receipt or rerun the guard to recover context.
error = QuotaDecisionTransportError("Complete Turn context could not be composed.")
# Admission may be durable. Retain its receipts through the existing
# failure projection so saved-context readers cannot deliver the
# unsigned input or register it as a current native claim source.
capture_decision(
capture_directory, payload, args=args, native_context=native_context, record_capture=record_capture,
capture_directory, quota_decision_transport_diagnostic(args, payload, error), record_capture=record_capture,
)
raise QuotaDecisionTransportError(
"Complete Turn context could not be composed. Read the saved original decision and receipt; do not rerun admission."
) from exc
raise error from exc


def project_scheduler_observation(payload: Mapping[str, object]) -> dict[str, object]:
Expand Down
1 change: 0 additions & 1 deletion loopx/cli_commands/quota_result_delivery.py
Original file line number Diff line number Diff line change
Expand Up @@ -323,7 +323,6 @@ def _publish_quota_result(
args,
scheduler_context=scheduler_context,
capture_directory=capture_directory,
native_context=native_context,
record_capture=record_capture,
)
captured_digest = capture_decision(
Expand Down
96 changes: 89 additions & 7 deletions tests/control_plane/test_quota_decision_capture.py
Original file line number Diff line number Diff line change
Expand Up @@ -854,6 +854,87 @@ def test_refused_selection_handoff_is_typed_and_keeps_the_committed_capture(tmp_
assert _heartbeat_receipt_count(runtime, TURN_ID) >= 1


@pytest.mark.parametrize('provider', ['file', 'sqlite'])
@pytest.mark.parametrize('delivery', ['off', 'on'])
def test_failed_complete_composition_captures_only_recovery_evidence(
tmp_path, monkeypatch, capsys, provider, delivery,
):
from loopx.cli import main
from loopx.control_plane.effect_runtime import EffectRuntimeStartupError
from loopx.control_plane.quota import turn_envelope
from loopx.control_plane.turn_driver import codex_context
from tests.control_plane.canonical_authority_fixture import isolate_sqlite_runtime
from tests.control_plane.test_quota_settlement_cli import _spend_run_count

isolate_sqlite_runtime(tmp_path, monkeypatch)
project, runtime, registry = _write_fixture(tmp_path)
project = project.resolve()
monkeypatch.chdir(project)
state = _configure_read_only_todo(project)
mode = 'hard_lease' if delivery == 'on' else 'soft_claim'
initialize_canonical_source_fixture(runtime, GOAL_ID, state_path=state, provider=provider, handoff_mode=mode)
original_state = state.read_bytes()
capture, native = tmp_path / 'failure', tmp_path / 'native'
delivery_args = ['--codex-app', '--context-delivery', delivery]
if delivery == 'on':
native.mkdir(mode=0o700)
session = 'composition-failure-session'
monkeypatch.setenv('CODEX_THREAD_ID', session)
assert codex_context.codex_context_hook(str(native), {
'session_id': session, 'cwd': str(project), 'hook_event_name': 'SessionStart', 'source': 'startup',
}) == {}
delivery_args += ['--codex-context-dir', str(native)]
native_before = {path.name: path.read_bytes() for path in native.glob('*') if path.is_file()}
binding = ['--goal-id', GOAL_ID, '--agent-id', AGENT_ID, '--turn-instance-id', TURN_ID]
captured = []
run_typed = turn_envelope._turn_envelope_result

def interrupt_compose(action, **kwargs):
if action == 'compose_complete':
captured.append(kwargs['payload'])
raise EffectRuntimeStartupError('fixture composition unavailable', diagnostic_code='fixture_unavailable')
return run_typed(action, **kwargs)

with monkeypatch.context() as fault:
fault.setattr(turn_envelope, '_turn_envelope_result', interrupt_compose)
code = main(['--registry', str(registry), '--runtime-root', str(runtime), '--format', 'json',
'quota', 'should-run', *binding, '--todo-id', TODO_ID, *delivery_args, '--decision-output-dir', str(capture)])
failure = json.loads(capsys.readouterr().out)
assert code == 1 and failure['ok'] is False
assert failure['error_code'] == 'quota_decision_transport_failed'
assert len(captured) == 1 and captured[0]['ok'] is True
original_receipt = captured[0]['heartbeat_receipt']
assert failure['heartbeat_receipt'] == original_receipt
assert original_receipt['settlement_identity']['todo_id'] == TODO_ID
if delivery == 'on':
assert captured[0]['execution_preparation']['state'] == 'claim_required'
before_readback = _heartbeat_receipt_count(runtime, TURN_ID)
assert before_readback == 1

saved = capture / 'decision.json'
reference = failure['captured_decision']
assert saved.read_bytes() and reference['sha256'] == sha256(saved.read_bytes()).hexdigest()
code, projection = _run_cli(registry, runtime, 'quota', 'context-project', *binding, *delivery_args,
'--capture-file', reference['path'], '--capture-sha256', reference['sha256'], cwd=project)
assert code == 1 and projection['ok'] is False
assert 'diagnostic' in projection['reason']
diagnostic = json.loads(saved.read_bytes())
assert diagnostic['ok'] is False and diagnostic['should_run'] is False
assert 'interaction_contract' not in diagnostic and 'execution_preparation' not in diagnostic
assert diagnostic['heartbeat_receipt'] == original_receipt
reader = shlex.split(reference['command'])
code, page = _run_cli(registry, runtime, *reader[reader.index('quota'):],
'--select', '/heartbeat_receipt', cwd=project)
assert code == 0 and page['ok'] and page['eof']
assert json.loads(page['content'])['selections'] == [
{'pointer': '/heartbeat_receipt', 'value': original_receipt},
]
assert {path.name: path.read_bytes() for path in native.glob('*') if path.is_file()} == native_before
assert _heartbeat_receipt_count(runtime, TURN_ID) == before_readback
assert _spend_run_count(runtime) == 0
assert state.read_bytes() == original_state


@pytest.mark.parametrize('provider', ['file', 'sqlite'])
@pytest.mark.parametrize('turn_envelope', [False, True])
def test_native_recovery_failure_keeps_original_receipt_and_capture(
Expand All @@ -877,10 +958,7 @@ def test_native_recovery_failure_keeps_original_receipt_and_capture(

def refuse_recovery(payload, **kwargs):
saved = kwargs['capture_directory'] / 'decision.json'
attempts.append(saved.read_bytes())
if turn_envelope:
assert payload['schema_version'] == 'loopx_turn_envelope_v0'
assert 'heartbeat_receipt' not in payload
attempts.append((payload, saved.read_bytes()))
raise QuotaDecisionTransportError(
'Current context recovery could not be published or safely invalidated. '
'Read the saved original decision/receipt; do not rerun admission.'
Expand All @@ -900,15 +978,19 @@ def refuse_recovery(payload, **kwargs):
assert code == 1 and failure['ok'] is False
assert failure['error_code'] == 'quota_decision_transport_failed'
assert failure['status'] == 'decision_transport_failed'
assert failure['reason'].startswith('Current context recovery could not be published')
saved = list(captures.glob('*/decision.json'))
assert len(saved) == len(attempts) == 1
assert saved[0].read_bytes() == attempts[0]
original = json.loads(attempts[0])
projected, raw = attempts[0]
assert saved[0].read_bytes() == raw
original = json.loads(raw)
assert original['ok'] is True
assert projected['schema_version'] == original['schema_version'] == 'loopx_turn_envelope_v1'
assert projected['heartbeat_receipt'] == original['heartbeat_receipt']
assert failure['heartbeat_receipt'] == original['heartbeat_receipt']
assert failure['rollout_event'] == original['rollout_event']
assert failure['captured_decision']['path'] == str(saved[0])
assert failure['captured_decision']['sha256'] == sha256(attempts[0]).hexdigest()
assert failure['captured_decision']['sha256'] == sha256(raw).hexdigest()
assert _heartbeat_receipt_count(runtime, TURN_ID) == 1
assert _spend_run_count(runtime) == 0
assert state.read_bytes() == original_state
Expand Down
Loading