From 0ab05307f85aa87430e5f9d1e10a9d353d9f9a3b Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Sun, 22 Nov 2026 00:28:34 +0800 Subject: [PATCH 1/3] feat(context,benchmark): add default-off Stage-then-Swap EpochReset prefetch, Quiet-Turn, and KV/operator telemetry Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- benchmark/runtime/session_observation.py | 103 ++ .../benchmark_toolkit/experiment_board.py | 31 +- .../benchmark_toolkit/study_projection.py | 2 + .../benchmark_toolkit/token_capacity.py | 149 +- loopx/cli_commands/turn_registration.py | 11 + loopx/cli_commands/turn_run_once.py | 2 + .../trajectory_assessment_types.ts | 37 + .../capabilities/trajectory_codex_usage.ts | 145 +- .../quota/native_context_lifecycle.ts | 8 +- loopx/control_plane/quota/stage_then_swap.ts | 656 +++++++++ loopx/control_plane/quota/turn_envelope.py | 73 + loopx/control_plane/quota/turn_envelope.ts | 8 + loopx/control_plane/turn_driver/codex_cli.py | 14 + .../turn_driver/codex_context.py | 33 + .../turn_driver/epoch_prefetch.py | 1218 +++++++++++++++++ .../turn_driver/execution_readback.py | 4 + loopx/control_plane/turn_driver/executor.py | 92 +- .../test_stage_then_swap_quiet_turn.py | 749 ++++++++++ .../content_digest_single_owner.test.ts | 1 + .../stage_then_swap_telemetry.test.ts | 260 ++++ 20 files changed, 3549 insertions(+), 47 deletions(-) create mode 100644 loopx/control_plane/quota/stage_then_swap.ts create mode 100644 loopx/control_plane/turn_driver/epoch_prefetch.py create mode 100644 tests/control_plane/test_stage_then_swap_quiet_turn.py create mode 100644 tests/control_plane_ts/stage_then_swap_telemetry.test.ts diff --git a/benchmark/runtime/session_observation.py b/benchmark/runtime/session_observation.py index b1dd0b3a1c..10979aacb0 100644 --- a/benchmark/runtime/session_observation.py +++ b/benchmark/runtime/session_observation.py @@ -197,6 +197,109 @@ def observe_codex_session_tail( } +def collect_context_policy_telemetry( + runtime_root: Path | None = None, + *, + goal_id: str | None = None, + context_dir: Path | None = None, + usage: dict | None = None, +) -> dict: + """Collect {KeepRaw, FoldToReceipt, EpochReset}, prefetch, quiet-turn, and cold/warm KV telemetry.""" + operator_counts = {"KeepRaw": 0, "FoldToReceipt": 0, "EpochReset": 0} + quiet_turn_skips = 0 + prefetch_latency_ms = 0 + prefetch_bytes = 0 + prefetch_bytes_saved = 0 + round_trips_saved = 0 + seen_receipts: set[str] = set() + + def _consume_prefetch(entry: object) -> None: + nonlocal prefetch_latency_ms, prefetch_bytes, prefetch_bytes_saved, round_trips_saved + if not isinstance(entry, dict): + return + receipt_id = entry.get("receipt_sha256") + if isinstance(receipt_id, str) and receipt_id: + if receipt_id in seen_receipts: + return + seen_receipts.add(receipt_id) + op = entry.get("operator") + if op in operator_counts: + operator_counts[op] += 1 + if isinstance(entry.get("latency_ms"), int) and entry["latency_ms"] >= 0: + prefetch_latency_ms += entry["latency_ms"] + if isinstance(entry.get("retained_bytes"), int) and entry["retained_bytes"] >= 0: + prefetch_bytes += entry["retained_bytes"] + if isinstance(entry.get("bytes_saved"), int) and entry["bytes_saved"] >= 0: + prefetch_bytes_saved += entry["bytes_saved"] + if isinstance(entry.get("round_trips_saved"), int) and entry["round_trips_saved"] >= 0: + round_trips_saved += entry["round_trips_saved"] + + def _consume_quiet(entry: object) -> None: + nonlocal quiet_turn_skips + if isinstance(entry, dict) and entry.get("skipped") is True: + quiet_turn_skips += 1 + + if runtime_root is not None and goal_id: + turns_dir = Path(runtime_root) / "goals" / goal_id / "turns" + if turns_dir.is_dir(): + for path in sorted(turns_dir.glob("*.json")): + try: + journal = json.loads(path.read_text(encoding="utf-8")) + except (OSError, ValueError): + continue + if isinstance(journal, dict): + _consume_prefetch(journal.get("epoch_prefetch")) + _consume_quiet(journal.get("quiet_turn")) + + if context_dir is not None: + session_file = Path(context_dir) / "session.json" + if session_file.is_file(): + try: + session_data = json.loads(session_file.read_text(encoding="utf-8")) + except (OSError, ValueError): + session_data = {} + if isinstance(session_data, dict): + _consume_prefetch(session_data.get("epoch_prefetch")) + _consume_quiet(session_data.get("quiet_turn")) + + cold = {"requests": 0, "uncached_prefix_kv_tokens": 0, "cached_prefix_kv_tokens": 0} + warm = {"requests": 0, "uncached_prefix_kv_tokens": 0, "cached_prefix_kv_tokens": 0} + if isinstance(usage, dict): + coverage = usage.get("request_coverage") + requests = coverage.get("requests") if isinstance(coverage, dict) else None + if isinstance(requests, list): + for req in requests: + if not isinstance(req, dict): + continue + inp = req.get("input_tokens") + cached = req.get("cached_input_tokens") + if not isinstance(inp, int) or not isinstance(cached, int) or inp < cached: + continue + uncached = inp - cached + bucket = cold if (cached == 0 or req.get("cache_regime") == "cold") else warm + bucket["requests"] += 1 + bucket["uncached_prefix_kv_tokens"] += uncached + bucket["cached_prefix_kv_tokens"] += cached + elif isinstance(usage.get("input_tokens"), int) and isinstance(usage.get("cached_input_tokens"), int): + cached = usage["cached_input_tokens"] + uncached = max(0, usage["input_tokens"] - cached) + bucket = cold if cached == 0 else warm + bucket["requests"] = int(usage.get("completed_turns") or 1) + bucket["uncached_prefix_kv_tokens"] = uncached + bucket["cached_prefix_kv_tokens"] = cached + + return { + "schema_version": "loopx_context_policy_telemetry_v0", + "operator_counts": operator_counts, + "quiet_turn_skips": quiet_turn_skips, + "prefetch_latency_ms": prefetch_latency_ms, + "prefetch_bytes": prefetch_bytes, + "prefetch_bytes_saved": prefetch_bytes_saved, + "round_trips_saved": round_trips_saved, + "prefix_kv": {"cold": cold, "warm": warm}, + } + + def main(argv: list[str] | None = None) -> int: """Print one bounded observation for an explicitly selected rollout.""" parser = argparse.ArgumentParser( diff --git a/loopx/capabilities/benchmark_toolkit/experiment_board.py b/loopx/capabilities/benchmark_toolkit/experiment_board.py index 26453c50b2..e5cde4c201 100644 --- a/loopx/capabilities/benchmark_toolkit/experiment_board.py +++ b/loopx/capabilities/benchmark_toolkit/experiment_board.py @@ -17,6 +17,10 @@ build_benchmark_factorial_contrasts, build_benchmark_metric_delta, ) +from .token_capacity import ( + CONTEXT_POLICY_EFFORT_TELEMETRY_FIELDS, + normalize_operator_counts, +) Payload = dict[str, object] PayloadView = Mapping[str, object] @@ -204,25 +208,26 @@ def _countability(value: object) -> dict[str, bool]: return result -def _effort(value: object) -> dict[str, float | int]: +def _effort(value: object) -> Payload: if value in (None, {}): return {} if not isinstance(value, Mapping): raise TypeError("effort must be an object") view = _as_map(value) + int_fields = ( + "duration_ms", + "agent_steps", + "goal_turns", + "token_count", + *CONTEXT_POLICY_EFFORT_TELEMETRY_FIELDS, + ) _reject_unknown_fields( view, - allowed={ - "duration_ms", - "agent_steps", - "goal_turns", - "token_count", - "estimated_cost_usd", - }, + allowed={*int_fields, "estimated_cost_usd", "operator_counts"}, field="effort", ) - result: dict[str, float | int] = {} - for field in ("duration_ms", "agent_steps", "goal_turns", "token_count"): + result: Payload = {} + for field in int_fields: if field in view: result[field] = _non_negative_int(view[field], field=f"effort.{field}") if "estimated_cost_usd" in view: @@ -231,6 +236,12 @@ def _effort(value: object) -> dict[str, float | int]: field="effort.estimated_cost_usd", non_negative=True, ) + if "operator_counts" in view: + result["operator_counts"] = normalize_operator_counts( + view["operator_counts"], + field="effort.operator_counts", + validate_int=lambda v, f: _non_negative_int(v, field=f), + ) return result diff --git a/loopx/capabilities/benchmark_toolkit/study_projection.py b/loopx/capabilities/benchmark_toolkit/study_projection.py index 4c5acbb57b..ed08d392bb 100644 --- a/loopx/capabilities/benchmark_toolkit/study_projection.py +++ b/loopx/capabilities/benchmark_toolkit/study_projection.py @@ -35,6 +35,7 @@ BENCHMARK_RUNTIME_OBSERVATION_SCHEMA_VERSION, build_benchmark_runtime_observation, ) +from .token_capacity import aggregate_context_policy_effort Payload = dict[str, object] PayloadView = Mapping[str, object] @@ -1007,6 +1008,7 @@ def _effort_aggregate(rows: Sequence[PayloadView]) -> Payload: "mean": statistics.fmean(values) if values else None, "median": statistics.median(values) if values else None, } + output.update(aggregate_context_policy_effort(rows)) return output diff --git a/loopx/capabilities/benchmark_toolkit/token_capacity.py b/loopx/capabilities/benchmark_toolkit/token_capacity.py index bcd1cddeb7..3fdc5eb90a 100644 --- a/loopx/capabilities/benchmark_toolkit/token_capacity.py +++ b/loopx/capabilities/benchmark_toolkit/token_capacity.py @@ -1,9 +1,10 @@ from __future__ import annotations import json -from collections.abc import Mapping +from collections.abc import Callable, Mapping, Sequence from datetime import datetime, timedelta from pathlib import Path +import statistics from typing import Any from ...domain_state import default_domain_state_file_path @@ -38,6 +39,73 @@ "evaluator_reserve_tokens_per_minute", "cooldown_seconds", } +_CACHE_REGIMES = {"cold", "warm"} +_CONTEXT_POLICY_OPERATORS = ("KeepRaw", "FoldToReceipt", "EpochReset") +CONTEXT_POLICY_OPERATORS = _CONTEXT_POLICY_OPERATORS +CONTEXT_POLICY_EFFORT_TELEMETRY_FIELDS = ( + "cached_prefix_kv_tokens", + "uncached_prefix_kv_tokens", + "cold_uncached_prefix_kv_tokens", + "cold_cached_prefix_kv_tokens", + "warm_uncached_prefix_kv_tokens", + "warm_cached_prefix_kv_tokens", + "prefetch_latency_ms", + "prefetch_bytes", + "prefetch_bytes_saved", + "quiet_turn_skips", +) + + +def normalize_operator_counts( + value: object, + *, + field: str, + validate_int: Callable[[object, str], int], +) -> dict[str, int]: + """Validate optional context-policy operator counts cleanly across benchmark contracts.""" + if not isinstance(value, Mapping): + raise TypeError(f"{field} must be an object") + _reject_unknown_fields( + value, + allowed=set(_CONTEXT_POLICY_OPERATORS), + field=field, + ) + return { + op: validate_int(value[op], f"{field}.{op}") + for op in _CONTEXT_POLICY_OPERATORS + if op in value + } + + +def aggregate_context_policy_effort(rows: Sequence[Mapping[str, object]]) -> dict[str, object]: + """Aggregate optional context-policy effort telemetry and operator counts when present.""" + output: dict[str, object] = {} + for field in CONTEXT_POLICY_EFFORT_TELEMETRY_FIELDS: + values = [ + float(val) + for row in rows + if isinstance(effort := row.get("effort"), Mapping) + and isinstance(val := effort.get(field), (int, float)) + and not isinstance(val, bool) + ] + if values: + output[field] = { + "denominator": len(values), + "mean": statistics.fmean(values), + "median": statistics.median(values), + } + operator_rows = [ + effort["operator_counts"] + for row in rows + if isinstance(effort := row.get("effort"), Mapping) + and isinstance(effort.get("operator_counts"), Mapping) + ] + if operator_rows: + output["operator_counts"] = { + op: sum(int(ops.get(op, 0)) for ops in operator_rows) + for op in _CONTEXT_POLICY_OPERATORS + } + return output _SAMPLE_FIELDS = { "schema_version", "sample_id", @@ -47,6 +115,12 @@ "uncached_input_tokens", "cached_input_tokens", "output_tokens", + "cache_regime", + "operator_counts", + "quiet_turn_skips", + "prefetch_latency_ms", + "prefetch_bytes", + "prefetch_bytes_saved", } _RESERVATION_FIELDS = { "run_id", @@ -196,6 +270,27 @@ def normalize_benchmark_token_usage_sample( raise ValueError("unmetered samples cannot claim token counts") elif sample["request_count"] == 0 and token_total != 0: raise ValueError("token counts require at least one observed request") + if "cache_regime" in value and value["cache_regime"] is not None: + regime = _token(value.get("cache_regime"), field="cache_regime") + if regime not in _CACHE_REGIMES: + raise ValueError("cache_regime must be cold or warm") + sample["cache_regime"] = regime + if "operator_counts" in value and value["operator_counts"] is not None: + sample["operator_counts"] = normalize_operator_counts( + value["operator_counts"], + field="operator_counts", + validate_int=lambda v, f: _bounded_token_int(v, field=f), + ) + for telemetry_field in ( + "quiet_turn_skips", + "prefetch_latency_ms", + "prefetch_bytes", + "prefetch_bytes_saved", + ): + if telemetry_field in value and value[telemetry_field] is not None: + sample[telemetry_field] = _bounded_token_int( + value[telemetry_field], field=telemetry_field + ) return sample @@ -350,6 +445,57 @@ def _usage_projection( + totals["cached_input_tokens"] + totals["output_tokens"] ) + telemetry: dict[str, Any] = {} + has_regime = any("cache_regime" in item for item in window) + if has_regime: + prefix_kv: dict[str, dict[str, int]] = {} + for regime in ("cold", "warm"): + subset = [item for item in window if item.get("cache_regime") == regime] + prefix_kv[regime] = { + "request_count": sum(item["request_count"] for item in subset), + "uncached_prefix_kv_tokens": sum( + item["uncached_input_tokens"] for item in subset + ), + "cached_prefix_kv_tokens": sum( + item["cached_input_tokens"] for item in subset + ), + } + telemetry["prefix_kv"] = prefix_kv + has_policy = any( + any( + key in item + for key in ( + "operator_counts", + "quiet_turn_skips", + "prefetch_latency_ms", + "prefetch_bytes", + "prefetch_bytes_saved", + ) + ) + for item in window + ) + if has_policy: + op_counts = { + op: sum( + int((item.get("operator_counts") or {}).get(op, 0)) for item in window + ) + for op in _CONTEXT_POLICY_OPERATORS + } + telemetry["context_policy"] = { + "operator_counts": op_counts, + "quiet_turn_skips": sum( + int(item.get("quiet_turn_skips", 0)) for item in window + ), + "prefetch_latency_ms": sum( + int(item.get("prefetch_latency_ms", 0)) for item in window + ), + "prefetch_bytes": sum( + int(item.get("prefetch_bytes", 0)) for item in window + ), + "prefetch_bytes_saved": sum( + int(item.get("prefetch_bytes_saved", 0)) for item in window + ), + } return { "window_seconds": int(_WINDOW.total_seconds()), "window_started_at": (datetime.fromisoformat(observed_at) - _WINDOW) @@ -360,6 +506,7 @@ def _usage_projection( "reason_codes": reason_codes, "sample_count": len(window), **totals, + **telemetry, } diff --git a/loopx/cli_commands/turn_registration.py b/loopx/cli_commands/turn_registration.py index 51cf7d55a3..0ed943b201 100644 --- a/loopx/cli_commands/turn_registration.py +++ b/loopx/cli_commands/turn_registration.py @@ -356,6 +356,17 @@ def register_turn_commands( action="store_true", help="Invoke the host and commit validated writeback/quota effects.", ) + run_once.add_argument( + "--epoch-prefetch-json", + type=json.loads, + default=None, + help="Opt-in Stage-then-Swap EpochReset prefetch configuration JSON (default-off).", + ) + run_once.add_argument( + "--quiet-turn", + action="store_true", + help="Opt-in Quiet-Turn zero-tax skip metadata evaluation when Turn state is unchanged (default-off).", + ) run_once.add_argument("--limit", type=int, default=5) diff --git a/loopx/cli_commands/turn_run_once.py b/loopx/cli_commands/turn_run_once.py index 1008ef95cb..7be454f34c 100644 --- a/loopx/cli_commands/turn_run_once.py +++ b/loopx/cli_commands/turn_run_once.py @@ -915,6 +915,8 @@ def on_managed_start_admitted() -> None: goal_admission.with_launch_decision(current_launch_decision).launch_lifetime, operation="turn_external_host_launch", ) if raw_argv is not None and goal_admission is not None else None), + epoch_prefetch=getattr(args, "epoch_prefetch_json", None), + quiet_turn=bool(getattr(args, "quiet_turn", False)), ) if args.execute: result.update(drain_committed_turn_post_writeback_hooks( diff --git a/loopx/control_plane/capabilities/trajectory_assessment_types.ts b/loopx/control_plane/capabilities/trajectory_assessment_types.ts index 651a6fd461..567e41ce23 100644 --- a/loopx/control_plane/capabilities/trajectory_assessment_types.ts +++ b/loopx/control_plane/capabilities/trajectory_assessment_types.ts @@ -90,6 +90,41 @@ export interface TrajectoryPartialTurnUsage { uncached_input_tokens: number; output_tokens: number} | null; } +export type ContextPolicyOperatorName = 'KeepRaw' | 'FoldToReceipt' | 'EpochReset'; + +export interface ContextPolicyOperatorCounts { + KeepRaw: number; + FoldToReceipt: number; + EpochReset: number; +} + +export interface PrefetchTelemetrySummary { + attempts: number; + latency_ms: number; + output_bytes: number; + bytes_saved: number; + round_trips_saved: number; +} + +export interface PrefixKvRegimeStats { + requests: number; + uncached_prefix_kv_tokens: number; + cached_prefix_kv_tokens: number; +} + +export interface PrefixKvRegimeBreakdown { + cold: PrefixKvRegimeStats; + warm: PrefixKvRegimeStats; +} + +export interface ContextPolicyTelemetry { + schema_version: 'loopx_context_policy_telemetry_v0'; + operator_counts: ContextPolicyOperatorCounts; + quiet_turn_skips: number; + prefetch: PrefetchTelemetrySummary; + prefix_kv?: PrefixKvRegimeBreakdown; +} + export interface TrajectorySolverUsage { session_id: string; method: 'codex_complete_session_counters_v1' | 'codex_observed_session_counters_v1'; incomplete_turn?: TrajectoryPartialTurnUsage | null; @@ -110,6 +145,8 @@ export interface TrajectorySolverUsage { tool_context?: TrajectoryToolContext; /** Whole requests issuing recognized commands, never control-text attribution. */ loopx_requests?: TrajectoryLoopXRequests; + /** Optional context-policy operator, prefetch, quiet-turn, and cold/warm KV regime telemetry. */ + context_policy_telemetry?: ContextPolicyTelemetry; } export type TrajectoryLoopXRequests = {method: 'codex_ordered_loopx_requests_v1'} & ( diff --git a/loopx/control_plane/capabilities/trajectory_codex_usage.ts b/loopx/control_plane/capabilities/trajectory_codex_usage.ts index 17c1a96b16..c1f5d5fbf0 100644 --- a/loopx/control_plane/capabilities/trajectory_codex_usage.ts +++ b/loopx/control_plane/capabilities/trajectory_codex_usage.ts @@ -1,6 +1,12 @@ /** Read-only Codex session adapter for benchmark-toolkit, separate from model judgments. */ import {EffectRuntimeRequestError} from '../effect_runtime_errors.ts'; -import type {TrajectoryPartialTurnUsage, TrajectorySolverUsage} from './trajectory_assessment_types.ts'; +import type { + ContextPolicyOperatorName, + ContextPolicyTelemetry, + PrefixKvRegimeBreakdown, + TrajectoryPartialTurnUsage, + TrajectorySolverUsage, +} from './trajectory_assessment_types.ts'; import {isIdentifiedTurnAbort, reconcileTrajectoryRequests, summarizeTrajectoryLoopXInput} from './trajectory_request_usage.ts'; import {estimateTrajectoryLoopXInput} from './trajectory_input_usage.ts'; import {summarizeTrajectoryToolContext} from './trajectory_tool_context.ts'; @@ -41,6 +47,7 @@ export function summarizeTrajectoryCodexUsage(params: Record): let active: ActiveTurn | null = null, interruptedSeconds = 0; const turns: TrajectorySolverUsage['turns'] = []; const interruptedTurns: TrajectoryPartialTurnUsage[] = []; + const tokenCountDeltas: Array<{input_tokens: number; cached_input_tokens: number}> = []; const started = new Set(); let previousLine = 0; for (const event of rows) { @@ -82,6 +89,9 @@ export function summarizeTrajectoryCodexUsage(params: Record): // Repeated observations are legal. A changed total must represent exactly // the newly observed request, including the first request after zero. if (counterKeys.some(k => delta[k] !== 0) && counterKeys.some(k => delta[k] !== last[k])) return fail('missing usage prefix or counter gap'); + if (counterKeys.some(k => delta[k] !== 0)) { + tokenCountDeltas.push({input_tokens: delta.input_tokens, cached_input_tokens: delta.cached_input_tokens}); + } previous = total; samples++; active.samples++; } else if (p.type === 'task_complete') { if (!active || p.turn_id !== active.turn_id || !active.samples) return fail('unmatched or unmeasured completed Turn'); @@ -105,11 +115,13 @@ export function summarizeTrajectoryCodexUsage(params: Record): const loopxRequests = toolContext?.status === 'unavailable' ? {method: 'codex_ordered_loopx_requests_v1' as const, status: 'unavailable' as const, reason: toolContext.reason} : summarizeTrajectoryLoopXRequests(rows, params.tool_context, requestCoverage); + const contextPolicyTelemetry = summarizeContextPolicyTelemetryIfRequested(rows, params, requestCoverage, tokenCountDeltas); return {session_id: params.session_id, method: observed ? 'codex_observed_session_counters_v1' : 'codex_complete_session_counters_v1', ...(requestCoverage ? {request_coverage: requestCoverage} : {}), ...(loopxInput ? {loopx_input: loopxInput} : {}), ...(toolContext ? {tool_context: toolContext} : {}), ...(loopxRequests ? {loopx_requests: loopxRequests} : {}), + ...(contextPolicyTelemetry ? {context_policy_telemetry: contextPolicyTelemetry} : {}), ...(observed ? {incomplete_turn: incomplete} : {}), ...(interruptedTurns.length ? {interrupted_turns: interruptedTurns} : {}), start, end, completed_turns: turns.length, counter_observations: samples, @@ -126,3 +138,134 @@ export function summarizeTrajectoryCodexUsage(params: Record): 'Elapsed time includes tools and orchestration; it does not measure CPU time or avoidable overhead.', 'Registered operator binding identifies the case; this does not independently prove run provenance.']}; } + +function nonNegativeInt(value: unknown): number { + return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0; +} + +export function summarizeContextPolicyTelemetry(params: { + policy_events?: unknown; + rows?: ReadonlyArray<{type?: unknown; payload?: any}>; + request_coverage?: TrajectorySolverUsage['request_coverage']; + token_count_deltas?: ReadonlyArray<{input_tokens: number; cached_input_tokens: number}>; +}): ContextPolicyTelemetry { + const operator_counts: Record = { + KeepRaw: 0, + FoldToReceipt: 0, + EpochReset: 0, + }; + let quiet_turn_skips = 0; + let attempts = 0; + let latency_ms = 0; + let output_bytes = 0; + let bytes_saved = 0; + let round_trips_saved = 0; + + const eventsList = Array.isArray(params.policy_events) ? params.policy_events : []; + for (const raw of eventsList) { + if (!raw || typeof raw !== 'object' || Array.isArray(raw)) continue; + const item = raw as Record; + const op = item.operator; + if (op === 'KeepRaw' || op === 'FoldToReceipt' || op === 'EpochReset') { + operator_counts[op] += 1; + } + if (item.quiet_turn_skipped === true || item.skipped === true) quiet_turn_skips += 1; + else quiet_turn_skips += nonNegativeInt(item.quiet_turn_skips); + if (item.prefetch_attempted === true || typeof item.latency_ms === 'number' || typeof item.prefetch_latency_ms === 'number') { + attempts += 1; + } + latency_ms += nonNegativeInt(item.latency_ms ?? item.prefetch_latency_ms); + output_bytes += nonNegativeInt(item.output_bytes ?? item.retained_bytes ?? item.prefetch_bytes); + bytes_saved += nonNegativeInt(item.bytes_saved ?? item.prefetch_bytes_saved); + round_trips_saved += nonNegativeInt(item.round_trips_saved); + } + + let prefix_kv: PrefixKvRegimeBreakdown | undefined; + const rows = Array.isArray(params.rows) ? params.rows : []; + const requestRows = rows.filter(r => r?.type === 'token_usage_record' && r.payload && typeof r.payload.usage === 'object'); + if (requestRows.length) { + const cold = {requests: 0, uncached_prefix_kv_tokens: 0, cached_prefix_kv_tokens: 0}; + const warm = {requests: 0, uncached_prefix_kv_tokens: 0, cached_prefix_kv_tokens: 0}; + const compactions = new Set(rows.filter(r => r?.type === 'compacted').map(r => r.payload?.compaction_response_id)); + let nextIsColdRebase = true; + const seen = new Set(); + for (const row of requestRows) { + const p = row.payload!; + if (typeof p.response_id === 'string') { + if (seen.has(p.response_id)) continue; + seen.add(p.response_id); + } + if (compactions.has(p.response_id)) { + nextIsColdRebase = true; + continue; + } + const usage = p.usage as Record; + const inputTokens = nonNegativeInt(usage.input_tokens); + const cachedTokens = nonNegativeInt(usage.cached_input_tokens); + const uncachedTokens = Math.max(0, inputTokens - cachedTokens); + const explicitRegime = p.cache_regime; + const isCold = explicitRegime === 'cold' || (explicitRegime !== 'warm' && (cachedTokens === 0 || nextIsColdRebase)); + const target = isCold ? cold : warm; + target.requests += 1; + target.uncached_prefix_kv_tokens += uncachedTokens; + target.cached_prefix_kv_tokens += cachedTokens; + nextIsColdRebase = false; + } + prefix_kv = {cold, warm}; + } else if (Array.isArray(params.token_count_deltas) && params.token_count_deltas.length) { + const cold = {requests: 0, uncached_prefix_kv_tokens: 0, cached_prefix_kv_tokens: 0}; + const warm = {requests: 0, uncached_prefix_kv_tokens: 0, cached_prefix_kv_tokens: 0}; + params.token_count_deltas.forEach((delta, index) => { + const inp = nonNegativeInt(delta.input_tokens); + const cached = Math.min(inp, nonNegativeInt(delta.cached_input_tokens)); + const uncached = Math.max(0, inp - cached); + const target = index === 0 || cached === 0 ? cold : warm; + target.requests += 1; + target.uncached_prefix_kv_tokens += uncached; + target.cached_prefix_kv_tokens += cached; + }); + prefix_kv = {cold, warm}; + } else if (params.request_coverage && params.request_coverage.status === 'verified') { + const all = params.request_coverage.all_requests; + const uncached = Math.max(0, all.input_tokens - all.cached_input_tokens); + prefix_kv = { + cold: { + requests: all.cached_input_tokens === 0 ? params.request_coverage.unique_requests : 0, + uncached_prefix_kv_tokens: all.cached_input_tokens === 0 ? uncached : 0, + cached_prefix_kv_tokens: 0, + }, + warm: { + requests: all.cached_input_tokens > 0 ? params.request_coverage.unique_requests : 0, + uncached_prefix_kv_tokens: all.cached_input_tokens > 0 ? uncached : 0, + cached_prefix_kv_tokens: all.cached_input_tokens, + }, + }; + } + return { + schema_version: 'loopx_context_policy_telemetry_v0', + operator_counts, + quiet_turn_skips, + prefetch: {attempts, latency_ms, output_bytes, bytes_saved, round_trips_saved}, + ...(prefix_kv ? {prefix_kv} : {}), + }; +} + +function summarizeContextPolicyTelemetryIfRequested( + rows: ReadonlyArray<{type?: unknown; payload?: any}>, + params: Record, + requestCoverage: TrajectorySolverUsage['request_coverage'], + tokenCountDeltas: ReadonlyArray<{input_tokens: number; cached_input_tokens: number}>, +): ContextPolicyTelemetry | undefined { + const inlineEvents = rows + .filter(r => r?.type === 'loopx_context_policy' && r.payload && typeof r.payload === 'object') + .map(r => r.payload); + const supplied = Array.isArray(params.context_policy) ? params.context_policy : undefined; + const includeKv = params.include_prefix_kv_regimes === true; + if (!supplied && !inlineEvents.length && !includeKv) return undefined; + return summarizeContextPolicyTelemetry({ + policy_events: [...(supplied ?? []), ...inlineEvents], + rows, + request_coverage: requestCoverage, + token_count_deltas: tokenCountDeltas, + }); +} diff --git a/loopx/control_plane/quota/native_context_lifecycle.ts b/loopx/control_plane/quota/native_context_lifecycle.ts index 79c2b6342d..2a66c7817c 100644 --- a/loopx/control_plane/quota/native_context_lifecycle.ts +++ b/loopx/control_plane/quota/native_context_lifecycle.ts @@ -47,8 +47,14 @@ export function updateNativeContextLifecycle(request: JsonObject): JsonObject { const invalidate = () => { // Reset is idempotent while already invalid. Pre/PostCompact and the // subsequent SessionStart(compact) therefore do not rotate three epochs. - if (!state.context_epoch || state.candidate || state.pending || fileEpochCurrent) + if (!state.context_epoch || state.candidate || state.pending || fileEpochCurrent) { + const previousEpoch = state.context_epoch; state.context_epoch = requireNonEmptyString(request.new_epoch, "new native context epoch"); + if (state.context_epoch !== previousEpoch) { + delete state.epoch_prefetch; + delete state.quiet_turn; + } + } delete state.candidate; delete state.pending; delete state.active_call; // retire legacy diagnostic-call binding diff --git a/loopx/control_plane/quota/stage_then_swap.ts b/loopx/control_plane/quota/stage_then_swap.ts new file mode 100644 index 0000000000..89363e7c49 --- /dev/null +++ b/loopx/control_plane/quota/stage_then_swap.ts @@ -0,0 +1,656 @@ +import {createHash} from "node:crypto"; + +import {BARE_SHA256_PATTERN} from "../content_digest.ts"; +import type {JsonObject} from "../effect_program.ts"; +import {EffectRuntimeRequestError} from "../effect_runtime_errors.ts"; +import { + optionalNonEmptyString, + requireBoolean, + requireJsonObject, + requireNonEmptyString, +} from "../runtime_decode.ts"; + +export const STAGE_THEN_SWAP_POLICY_SCHEMA_VERSION = "loopx_stage_then_swap_policy_v0"; +export const EPOCH_PREFETCH_RECEIPT_SCHEMA_VERSION = "loopx_epoch_prefetch_receipt_v0"; +export const QUIET_TURN_METADATA_SCHEMA_VERSION = "loopx_quiet_turn_v0"; +export const CONTEXT_POLICY_OPERATORS = ["KeepRaw", "FoldToReceipt", "EpochReset"] as const; + +export const DEFAULT_PREFETCH_TIMEOUT_MS = 5000; +export const MAX_PREFETCH_TIMEOUT_MS = 60000; +export const DEFAULT_PREFETCH_MAX_OUTPUT_BYTES = 16384; +export const MIN_PREFETCH_MAX_OUTPUT_BYTES = 128; +export const MAX_PREFETCH_MAX_OUTPUT_BYTES = 65536; + +export type ContextPolicyOperator = (typeof CONTEXT_POLICY_OPERATORS)[number]; + +export interface PrefetchSafetyDecision { + allowed: boolean; + reason: string | null; + argv: string[]; + command_sha256: string | null; +} + +export interface NormalizedStageThenSwapPolicy { + schema_version: typeof STAGE_THEN_SWAP_POLICY_SCHEMA_VERSION; + enabled: boolean; + initiator: string; + prefetch_command: string | string[] | null; + timeout_ms: number; + max_output_bytes: number; + min_net_savings_bytes: number | null; + reject_on_truncation: boolean; + replace_exploratory_context: boolean; +} + +const DISALLOWED_SHELL_OPERATORS = new Set([";", "|", "&", "&&", "||", ">", ">>", "<", "<<", "<<<", "(", ")"]); +const READ_ONLY_PROBES = new Set(["cat", "head", "tail", "wc", "ls", "stat", "pwd", "rg", "grep"]); +const GIT_READ_ONLY_SUBCOMMANDS = new Set(["status", "diff", "log", "show", "rev-parse", "ls-files", "grep", "branch"]); +const GIT_MUTATING_BRANCH_FLAGS = new Set(["-d", "-D", "-m", "-M", "-c", "-C", "--delete", "--move", "--copy"]); +const FIND_MUTATING_PREDICATES = new Set(["-exec", "-execdir", "-ok", "-okdir", "-delete", "-fls", "-fprint", "-fprint0", "-fprintf"]); +const LOOPX_READ_ONLY_SUBCOMMANDS = new Set(["status", "doctor", "version"]); +const LOOPX_QUOTA_READ_SUBCOMMANDS = new Set(["context-read", "receipt"]); +const DISALLOWED_LOOPX_FLAGS = new Set(["--execute"]); +const PASSIVE_PLUGIN_INITIATORS = new Set([ + "history_view_policy", + "plugin", + "passive_policy", + "external_policy_plugin", +]); + +function sha256Hex(value: string): string { + return createHash("sha256").update(value, "utf8").digest("hex"); +} + +function optionalObject(value: unknown, label: string): JsonObject | null { + if (value === undefined || value === null) return null; + return requireJsonObject(value, label); +} + +function optionalInt(value: unknown, label: string, min: number, max: number): number | null { + if (value === undefined || value === null) return null; + if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) { + throw new EffectRuntimeRequestError(`${label} must be an integer between ${min} and ${max}`); + } + return value; +} + +function cleanTextList(value: unknown, limit = 32): string[] { + if (!Array.isArray(value)) return []; + const seen = new Set(); + const items: string[] = []; + for (const raw of value) { + let text = ""; + if (typeof raw === "string") text = raw.trim(); + else if (raw && typeof raw === "object") text = JSON.stringify(raw); + if (!text) continue; + const bounded = text.length > 512 ? `${text.slice(0, 509)}...` : text; + if (seen.has(bounded)) continue; + seen.add(bounded); + items.push(bounded); + if (items.length >= limit) break; + } + return items; +} + +export function normalizeStageThenSwapConfig(value: unknown): NormalizedStageThenSwapPolicy { + if (value === undefined || value === null || value === false) { + return { + schema_version: STAGE_THEN_SWAP_POLICY_SCHEMA_VERSION, + enabled: false, + initiator: "turn_driver", + prefetch_command: null, + timeout_ms: DEFAULT_PREFETCH_TIMEOUT_MS, + max_output_bytes: DEFAULT_PREFETCH_MAX_OUTPUT_BYTES, + min_net_savings_bytes: null, + reject_on_truncation: false, + replace_exploratory_context: false, + }; + } + if (typeof value !== "object" || Array.isArray(value)) { + throw new EffectRuntimeRequestError("epoch_prefetch configuration must be an object or boolean"); + } + const config = value as JsonObject; + const enabled = config.enabled === undefined ? false : requireBoolean(config.enabled, "epoch_prefetch.enabled"); + const initiator = optionalNonEmptyString(config.initiator, "epoch_prefetch.initiator") ?? "turn_driver"; + const timeout_ms = + optionalInt(config.timeout_ms, "epoch_prefetch.timeout_ms", 1, MAX_PREFETCH_TIMEOUT_MS) + ?? DEFAULT_PREFETCH_TIMEOUT_MS; + const max_output_bytes = + optionalInt( + config.max_output_bytes, + "epoch_prefetch.max_output_bytes", + MIN_PREFETCH_MAX_OUTPUT_BYTES, + MAX_PREFETCH_MAX_OUTPUT_BYTES, + ) ?? DEFAULT_PREFETCH_MAX_OUTPUT_BYTES; + const min_net_savings_bytes = optionalInt( + config.min_net_savings_bytes, + "epoch_prefetch.min_net_savings_bytes", + 0, + 10_000_000, + ); + const reject_on_truncation = + config.reject_on_truncation === undefined + ? false + : requireBoolean(config.reject_on_truncation, "epoch_prefetch.reject_on_truncation"); + const replace_exploratory_context = + config.replace_exploratory_context === undefined + ? false + : requireBoolean(config.replace_exploratory_context, "epoch_prefetch.replace_exploratory_context"); + + let prefetch_command: string | string[] | null = null; + if (config.prefetch_command !== undefined && config.prefetch_command !== null) { + if (typeof config.prefetch_command === "string") { + prefetch_command = config.prefetch_command; + } else if ( + Array.isArray(config.prefetch_command) + && config.prefetch_command.every((part) => typeof part === "string") + ) { + prefetch_command = [...config.prefetch_command]; + } else { + throw new EffectRuntimeRequestError("epoch_prefetch.prefetch_command must be string or string[]"); + } + } + return { + schema_version: STAGE_THEN_SWAP_POLICY_SCHEMA_VERSION, + enabled, + initiator, + prefetch_command, + timeout_ms, + max_output_bytes, + min_net_savings_bytes, + reject_on_truncation, + replace_exploratory_context, + }; +} + +function parsePosixWords(command: string): {ok: true; argv: string[]} | {ok: false; reason: string} { + if (/[\r\n\0]/.test(command)) return {ok: false, reason: "policy_violation:multiline_or_nul"}; + const argv: string[] = []; + let current = ""; + let inToken = false; + let quote: "'" | '"' | null = null; + for (let i = 0; i < command.length; i += 1) { + const ch = command[i]!; + if (quote === "'") { + if (ch === "'") quote = null; + else current += ch; + continue; + } + if (quote === '"') { + if (ch === '"') { + quote = null; + } else if (ch === "\\") { + if (i + 1 >= command.length) return {ok: false, reason: "policy_violation:dangling_escape"}; + current += command[++i]!; + } else if (ch === "$" || ch === "`") { + return {ok: false, reason: "policy_violation:shell_expansion"}; + } else { + current += ch; + } + continue; + } + if (ch === "'" || ch === '"') { + quote = ch; + inToken = true; + } else if (ch === "\\") { + if (i + 1 >= command.length) return {ok: false, reason: "policy_violation:dangling_escape"}; + current += command[++i]!; + inToken = true; + } else if (/\s/.test(ch)) { + if (inToken) { + argv.push(current); + current = ""; + inToken = false; + } + } else if (";|&><()$ `*?[]{}".includes(ch)) { + return {ok: false, reason: "policy_violation:shell_metacharacter"}; + } else { + current += ch; + inToken = true; + } + } + if (quote !== null) return {ok: false, reason: "policy_violation:unterminated_quote"}; + if (inToken) argv.push(current); + if (!argv.length) return {ok: false, reason: "policy_violation:empty_command"}; + return {ok: true, argv}; +} + +function normalizePrefetchArgv(command: unknown): {ok: true; argv: string[]} | {ok: false; reason: string} { + if (typeof command === "string") { + return parsePosixWords(command.trim()); + } + if (Array.isArray(command)) { + if (!command.length || command.some((part) => typeof part !== "string" || !part)) { + return {ok: false, reason: "policy_violation:empty_command"}; + } + for (const part of command) { + if (/[\r\n\0]/.test(part)) return {ok: false, reason: "policy_violation:multiline_or_nul"}; + if (DISALLOWED_SHELL_OPERATORS.has(part) || part.includes("$(") || part.includes("`")) { + return {ok: false, reason: "policy_violation:shell_metacharacter"}; + } + } + return {ok: true, argv: [...command]}; + } + return {ok: false, reason: "policy_violation:missing_command"}; +} + +function isLoopxReadOnlyArgs(args: readonly string[]): PrefetchSafetyDecision | null { + let cursor = 0; + while (cursor < args.length && args[cursor]!.startsWith("-")) { + const flag = args[cursor]!; + if (DISALLOWED_LOOPX_FLAGS.has(flag)) { + return null; + } + if (["--registry", "--runtime-root", "--format"].includes(flag)) { + cursor += 2; + continue; + } + if (flag.startsWith("--registry=") || flag.startsWith("--runtime-root=") || flag.startsWith("--format=")) { + cursor += 1; + continue; + } + return null; + } + if (args.some((arg) => DISALLOWED_LOOPX_FLAGS.has(arg))) return null; + const remaining = args.slice(cursor); + if (!remaining.length) return null; + if (remaining[0] === "quota") { + const sub = remaining[1]; + if (!sub || !LOOPX_QUOTA_READ_SUBCOMMANDS.has(sub)) return null; + return {allowed: true, reason: null, argv: [], command_sha256: null}; + } + if (remaining[0] === "turn" && remaining[1] === "inspect") { + return {allowed: true, reason: null, argv: [], command_sha256: null}; + } + if (remaining[0] === "todo" && remaining[1] === "list") { + return {allowed: true, reason: null, argv: [], command_sha256: null}; + } + if (remaining[0] === "task-lease" && remaining[1] === "inspect") { + return {allowed: true, reason: null, argv: [], command_sha256: null}; + } + if (LOOPX_READ_ONLY_SUBCOMMANDS.has(remaining[0]!)) { + return {allowed: true, reason: null, argv: [], command_sha256: null}; + } + return null; +} + +export function validatePrefetchCommandSafety(params: { + prefetch_command: unknown; + initiator?: unknown; +}): PrefetchSafetyDecision { + const initiator = typeof params.initiator === "string" && params.initiator.trim() + ? params.initiator.trim() + : "turn_driver"; + if (PASSIVE_PLUGIN_INITIATORS.has(initiator)) { + return { + allowed: false, + reason: "policy_violation:passive_policy_cannot_emit_command", + argv: [], + command_sha256: null, + }; + } + const parsed = normalizePrefetchArgv(params.prefetch_command); + if (!parsed.ok) { + return {allowed: false, reason: parsed.reason, argv: [], command_sha256: null}; + } + const argv = parsed.argv; + const cmdHash = sha256Hex(JSON.stringify(argv)); + const exe = argv[0]!.split(/[/\\]/).pop() ?? ""; + const args = argv.slice(1); + + if (exe === "loopx") { + if (isLoopxReadOnlyArgs(args)?.allowed) { + return {allowed: true, reason: null, argv, command_sha256: cmdHash}; + } + return { + allowed: false, + reason: "policy_violation:loopx_subcommand_not_read_only", + argv, + command_sha256: cmdHash, + }; + } + if (/^python(?:\d+(?:\.\d+)?)?$/.test(exe)) { + if (args[0] === "-m" && (args[1] === "loopx" || args[1] === "loopx.cli" || args[1] === "loopx.entrypoint")) { + if (isLoopxReadOnlyArgs(args.slice(2))?.allowed) { + return {allowed: true, reason: null, argv, command_sha256: cmdHash}; + } + return { + allowed: false, + reason: "policy_violation:loopx_subcommand_not_read_only", + argv, + command_sha256: cmdHash, + }; + } + if (args[0] === "-m" && args[1] === "pytest" && args.includes("--collect-only")) { + return {allowed: true, reason: null, argv, command_sha256: cmdHash}; + } + return { + allowed: false, + reason: "policy_violation:executable_not_read_only_allowlisted", + argv, + command_sha256: cmdHash, + }; + } + if (exe === "git") { + let idx = 0; + while (idx < args.length && (args[idx] === "-C" || args[idx] === "--git-dir" || args[idx] === "--work-tree")) { + idx += 2; + } + const sub = args[idx]; + if (!sub || !GIT_READ_ONLY_SUBCOMMANDS.has(sub)) { + return { + allowed: false, + reason: "policy_violation:git_subcommand_not_read_only", + argv, + command_sha256: cmdHash, + }; + } + if (sub === "branch" && args.slice(idx + 1).some((flag) => GIT_MUTATING_BRANCH_FLAGS.has(flag))) { + return { + allowed: false, + reason: "policy_violation:git_branch_mutation_forbidden", + argv, + command_sha256: cmdHash, + }; + } + return {allowed: true, reason: null, argv, command_sha256: cmdHash}; + } + if (exe === "find") { + if (args.some((arg) => FIND_MUTATING_PREDICATES.has(arg))) { + return { + allowed: false, + reason: "policy_violation:find_mutation_forbidden", + argv, + command_sha256: cmdHash, + }; + } + return {allowed: true, reason: null, argv, command_sha256: cmdHash}; + } + if (READ_ONLY_PROBES.has(exe)) { + if ((exe === "rg" || exe === "grep") && args.some((a) => a === "--pre" || a.startsWith("--pre="))) { + return { + allowed: false, + reason: "policy_violation:probe_preprocessor_forbidden", + argv, + command_sha256: cmdHash, + }; + } + return {allowed: true, reason: null, argv, command_sha256: cmdHash}; + } + return { + allowed: false, + reason: "policy_violation:executable_not_read_only_allowlisted", + argv, + command_sha256: cmdHash, + }; +} + +export function planStageThenSwapPrefetch(rawRequest: JsonObject): JsonObject { + const config = normalizeStageThenSwapConfig(rawRequest.epoch_prefetch); + if (!config.enabled) { + return { + schema_version: STAGE_THEN_SWAP_POLICY_SCHEMA_VERSION, + enabled: false, + eligible: false, + fallback_operator: "KeepRaw", + }; + } + const safety = validatePrefetchCommandSafety({ + prefetch_command: config.prefetch_command, + initiator: config.initiator, + }); + return { + schema_version: STAGE_THEN_SWAP_POLICY_SCHEMA_VERSION, + enabled: true, + eligible: safety.allowed, + safety, + timeout_ms: config.timeout_ms, + max_output_bytes: config.max_output_bytes, + min_net_savings_bytes: config.min_net_savings_bytes, + reject_on_truncation: config.reject_on_truncation, + replace_exploratory_context: config.replace_exploratory_context, + initiator: config.initiator, + fallback_operator: "KeepRaw", + }; +} + +function normalizeSourceRef(raw: unknown): {path: string; sha256: string} | null { + if (raw === undefined || raw === null) return null; + const obj = requireJsonObject(raw, "source_ref"); + const path = requireNonEmptyString(obj.path, "source_ref.path"); + const sha256 = requireNonEmptyString(obj.sha256, "source_ref.sha256"); + if (!BARE_SHA256_PATTERN.test(sha256)) { + throw new EffectRuntimeRequestError("source_ref.sha256 must be a bare sha256 digest"); + } + return {path, sha256}; +} + +export function buildAntiWhitewashingReceiptHeader(params: { + context_epoch: string; + reclaimed_turns: number; + dropped_failures: number; + failure_facts: string[]; + open_obligations: string[]; + exit_code: number | null; + truncated: boolean; + source_ref: {path: string; sha256: string} | null; +}): {header: string; fields: JsonObject} { + const sourceRefText = params.source_ref + ? `${params.source_ref.path} (sha256:${params.source_ref.sha256})` + : "none"; + const fields: JsonObject = { + trust_level: "tool", + context_epoch: params.context_epoch, + reclaimed_turns: params.reclaimed_turns, + dropped_failures: params.dropped_failures, + exit_code: params.exit_code, + truncated: params.truncated, + source_ref: params.source_ref, + failure_facts: params.failure_facts, + open_obligations: params.open_obligations, + }; + const header = [ + "[Stage-then-Swap EpochReset Receipt | trust=tool]", + `context_epoch: ${params.context_epoch}`, + `reclaimed_turns: ${params.reclaimed_turns}`, + `dropped_failures: ${params.dropped_failures}`, + `exit_code: ${params.exit_code === null ? "null" : String(params.exit_code)}`, + `truncated: ${params.truncated ? "true" : "false"}`, + `source_ref: ${sourceRefText}`, + `failure_facts: ${JSON.stringify(params.failure_facts)}`, + `open_obligations: ${JSON.stringify(params.open_obligations)}`, + "--- prefetched_output ---", + ].join("\n"); + return {header, fields}; +} + +export function evaluateEpochPrefetchSwap(rawRequest: JsonObject): JsonObject { + const config = normalizeStageThenSwapConfig(rawRequest.epoch_prefetch); + const context_epoch = requireNonEmptyString(rawRequest.context_epoch, "context_epoch"); + const reclaimed_turns = + optionalInt(rawRequest.reclaimed_turns, "reclaimed_turns", 0, 1_000_000) ?? 0; + const failure_facts = cleanTextList(rawRequest.failure_facts, 32); + const raw_dropped_failures = + optionalInt(rawRequest.dropped_failures, "dropped_failures", 0, 1_000_000) ?? 0; + const dropped_failures = Math.max(raw_dropped_failures, failure_facts.length); + const open_obligations = cleanTextList(rawRequest.open_obligations, 64); + const source_ref = normalizeSourceRef(rawRequest.source_ref); + const baseline_bytes = optionalInt(rawRequest.baseline_bytes, "baseline_bytes", 0, 100_000_000); + const latency_ms = optionalInt(rawRequest.latency_ms, "latency_ms", 0, 3_600_000) ?? 0; + const timed_out = rawRequest.timed_out === undefined + ? false + : requireBoolean(rawRequest.timed_out, "timed_out"); + const truncated = rawRequest.truncated === undefined + ? false + : requireBoolean(rawRequest.truncated, "truncated"); + const exit_code = + rawRequest.exit_code === undefined || rawRequest.exit_code === null + ? null + : optionalInt(rawRequest.exit_code, "exit_code", -128, 255); + const prefetched_output = typeof rawRequest.prefetched_output === "string" + ? rawRequest.prefetched_output + : ""; + const raw_bytes_read = + optionalInt(rawRequest.raw_bytes_read, "raw_bytes_read", 0, 100_000_000) + ?? Buffer.byteLength(prefetched_output, "utf8"); + const retained_bytes = Buffer.byteLength(prefetched_output, "utf8"); + + if (!config.enabled) { + throw new EffectRuntimeRequestError("Stage-then-Swap epoch prefetch is disabled"); + } + + const safety = validatePrefetchCommandSafety({ + prefetch_command: config.prefetch_command, + initiator: config.initiator, + }); + + const {header, fields} = buildAntiWhitewashingReceiptHeader({ + context_epoch, + reclaimed_turns, + dropped_failures, + failure_facts, + open_obligations, + exit_code, + truncated, + source_ref, + }); + const hydrated_text = prefetched_output ? `${header}\n${prefetched_output}` : header; + const hydrated_bytes = Buffer.byteLength(hydrated_text, "utf8"); + const net_savings_bytes = baseline_bytes === null ? null : baseline_bytes - hydrated_bytes; + const minNetSavings = config.min_net_savings_bytes ?? (baseline_bytes === null ? 0 : 1); + + let fallback_reason: string | null = null; + if (!safety.allowed) { + fallback_reason = safety.reason; + } else if (timed_out) { + fallback_reason = "timeout"; + } else if (exit_code === null || exit_code !== 0) { + fallback_reason = "command_failed"; + } else if (config.reject_on_truncation && truncated) { + fallback_reason = "output_truncated"; + } else if (retained_bytes > config.max_output_bytes) { + fallback_reason = "output_overflow"; + } else if (baseline_bytes !== null && (net_savings_bytes ?? -1) < minNetSavings) { + fallback_reason = "negative_net_savings"; + } + + const output_sha256 = sha256Hex(prefetched_output); + if (fallback_reason !== null) { + const errorNote = optionalNonEmptyString(rawRequest.error_observation, "error_observation") + ?? `Prefetch aborted atomically to KeepRaw (${fallback_reason}).`; + const baseReceipt: JsonObject = { + schema_version: EPOCH_PREFETCH_RECEIPT_SCHEMA_VERSION, + operator: "KeepRaw", + status: "fallback_keep_raw", + fallback_reason, + trust_level: "tool", + preserves_raw_state: true, + context_epoch, + command_sha256: safety.command_sha256, + source_ref, + reclaimed_turns: 0, + dropped_failures: 0, + exit_code, + timed_out, + truncated, + raw_bytes_read, + retained_bytes: 0, + baseline_bytes, + hydrated_bytes: baseline_bytes ?? 0, + net_savings_bytes: 0, + bytes_saved: 0, + round_trips_saved: 0, + latency_ms, + header, + header_fields: fields, + preserved_failure_facts: failure_facts, + preserved_open_obligations: open_obligations, + prefetched_output: "", + hydrated_text: null, + output_sha256, + error_observation: errorNote.slice(0, 512), + }; + return { + ...baseReceipt, + receipt_sha256: sha256Hex(JSON.stringify(baseReceipt)), + }; + } + + const bytes_saved = net_savings_bytes !== null && net_savings_bytes > 0 ? net_savings_bytes : 0; + const committedReceipt: JsonObject = { + schema_version: EPOCH_PREFETCH_RECEIPT_SCHEMA_VERSION, + operator: "EpochReset", + status: "committed", + fallback_reason: null, + trust_level: "tool", + preserves_raw_state: false, + context_epoch, + command_sha256: safety.command_sha256, + source_ref, + reclaimed_turns, + dropped_failures, + exit_code, + timed_out: false, + truncated, + raw_bytes_read, + retained_bytes, + baseline_bytes, + hydrated_bytes, + net_savings_bytes, + bytes_saved, + round_trips_saved: 1, + latency_ms, + header, + header_fields: fields, + preserved_failure_facts: failure_facts, + preserved_open_obligations: open_obligations, + prefetched_output, + hydrated_text, + output_sha256, + error_observation: null, + }; + return { + ...committedReceipt, + receipt_sha256: sha256Hex(JSON.stringify(committedReceipt)), + }; +} + +export function evaluateQuietTurn(rawRequest: JsonObject): JsonObject { + const enabled = rawRequest.enabled === undefined ? true : requireBoolean(rawRequest.enabled, "quiet_turn.enabled"); + const quietNoopAllowed = + rawRequest.quiet_noop_allowed === undefined + ? true + : requireBoolean(rawRequest.quiet_noop_allowed, "quiet_noop_allowed"); + const currentStateDigest = optionalNonEmptyString(rawRequest.current_state_digest, "current_state_digest"); + const previousStateDigest = optionalNonEmptyString(rawRequest.previous_state_digest, "previous_state_digest"); + let stateChanged = rawRequest.state_changed === undefined + ? null + : requireBoolean(rawRequest.state_changed, "state_changed"); + if (stateChanged === null) { + if (currentStateDigest !== null && previousStateDigest !== null) { + stateChanged = currentStateDigest !== previousStateDigest; + } else { + stateChanged = true; + } + } + const skipped = enabled && quietNoopAllowed && !stateChanged; + return { + schema_version: QUIET_TURN_METADATA_SCHEMA_VERSION, + enabled, + quiet_noop_allowed: quietNoopAllowed, + state_changed: stateChanged, + skipped, + zero_tax: skipped, + reason: !enabled + ? "disabled" + : !quietNoopAllowed + ? "quiet_noop_disallowed" + : skipped + ? "unchanged_state" + : "state_changed", + context_delivery_skipped: skipped, + prefetch_skipped: skipped, + state_digest: currentStateDigest ?? previousStateDigest ?? null, + operator: skipped ? "KeepRaw" : null, + }; +} diff --git a/loopx/control_plane/quota/turn_envelope.py b/loopx/control_plane/quota/turn_envelope.py index ab55982167..db502837d9 100644 --- a/loopx/control_plane/quota/turn_envelope.py +++ b/loopx/control_plane/quota/turn_envelope.py @@ -511,3 +511,76 @@ def restore_context_delivery( current=dict(current)) result = _turn_envelope_result("context_recovery", **source, source_edits=True) return _apply_context_projection_changes(source, result) + + +def plan_stage_then_swap_prefetch( + *, + epoch_prefetch: Any = None, +) -> dict[str, Any]: + """Validate default-off Stage-then-Swap EpochReset prefetch configuration via TS.""" + return _turn_envelope_result( + "stage_then_swap_plan", + epoch_prefetch=dict(epoch_prefetch) if isinstance(epoch_prefetch, Mapping) else epoch_prefetch, + ) + + +def evaluate_epoch_prefetch_swap( + *, + epoch_prefetch: Mapping[str, Any], + context_epoch: str, + reclaimed_turns: int = 0, + dropped_failures: int = 0, + failure_facts: list[str] | tuple[str, ...] = (), + open_obligations: list[str] | tuple[str, ...] = (), + source_ref: Mapping[str, str] | None = None, + exit_code: int | None = None, + timed_out: bool = False, + truncated: bool = False, + raw_bytes_read: int = 0, + prefetched_output: str = "", + baseline_bytes: int | None = None, + latency_ms: int = 0, + error_observation: str | None = None, +) -> dict[str, Any]: + """Evaluate bounded prefetch output and anti-whitewashing receipt via TS.""" + payload: dict[str, Any] = { + "epoch_prefetch": dict(epoch_prefetch), + "context_epoch": context_epoch, + "reclaimed_turns": reclaimed_turns, + "dropped_failures": dropped_failures, + "failure_facts": list(failure_facts), + "open_obligations": list(open_obligations), + "source_ref": dict(source_ref) if source_ref is not None else None, + "exit_code": exit_code, + "timed_out": timed_out, + "truncated": truncated, + "raw_bytes_read": raw_bytes_read, + "prefetched_output": prefetched_output, + "baseline_bytes": baseline_bytes, + "latency_ms": latency_ms, + } + if error_observation: + payload["error_observation"] = error_observation + return _turn_envelope_result("stage_then_swap_evaluate", **payload) + + +def evaluate_quiet_turn( + *, + enabled: bool = True, + quiet_noop_allowed: bool = True, + state_changed: bool | None = None, + current_state_digest: str | None = None, + previous_state_digest: str | None = None, +) -> dict[str, Any]: + """Evaluate Quiet-Turn zero-tax skip metadata via TS.""" + payload: dict[str, Any] = { + "enabled": enabled, + "quiet_noop_allowed": quiet_noop_allowed, + } + if state_changed is not None: + payload["state_changed"] = state_changed + if current_state_digest is not None: + payload["current_state_digest"] = current_state_digest + if previous_state_digest is not None: + payload["previous_state_digest"] = previous_state_digest + return _turn_envelope_result("quiet_turn_evaluate", **payload) diff --git a/loopx/control_plane/quota/turn_envelope.ts b/loopx/control_plane/quota/turn_envelope.ts index 55ba8de80c..408d275557 100644 --- a/loopx/control_plane/quota/turn_envelope.ts +++ b/loopx/control_plane/quota/turn_envelope.ts @@ -16,6 +16,11 @@ import {omitUnboundExploreResultWriteback, referenceExploreResultDelivery, referenceExploreResultWriteback} from "../capabilities/explore_context_delivery.ts"; import {prepareContextDelivery, restoreContextDelivery} from "./context_delivery.ts"; import {updateNativeContextLifecycle} from "./native_context_lifecycle.ts"; +import { + evaluateEpochPrefetchSwap, + evaluateQuietTurn, + planStageThenSwapPrefetch, +} from "./stage_then_swap.ts"; import {contextProjectionChanges, contextProjectionIdentity, contextProjectionRetainFields, contextSourceIdentity, omitEmptyTaskTodoLanes, projectQuotaDiagnostics, referenceQuotaSummaryLanes, resolveQuotaSummaryLanes, type ProjectionSourceValues} from "./diagnostic_projection.ts"; @@ -2829,6 +2834,9 @@ export function evaluateTurnEnvelope(value: unknown): JsonObject { checkedContextPresentationPlan(request), readyWriteScope(requireJsonObject(request.context, "current projection"))); } if (operation === "native_context_lifecycle") return updateNativeContextLifecycle(request); + if (operation === "stage_then_swap_plan") return planStageThenSwapPrefetch(request); + if (operation === "stage_then_swap_evaluate") return evaluateEpochPrefetchSwap(request); + if (operation === "quiet_turn_evaluate") return evaluateQuietTurn(request); if (operation === "context_recovery") return restoreContextDelivery(request, LEGACY_QUOTA_CONTEXT_FIELDS); if (operation === "bind_capture") return bindTurnDecisionCapture(request); if (operation === "scoped_settlement_identity") return {identity: turnEnvelopeScopedSettlementIdentity( diff --git a/loopx/control_plane/turn_driver/codex_cli.py b/loopx/control_plane/turn_driver/codex_cli.py index ff093b0d5d..508e5ac20d 100644 --- a/loopx/control_plane/turn_driver/codex_cli.py +++ b/loopx/control_plane/turn_driver/codex_cli.py @@ -471,6 +471,20 @@ def _render_prompt(request: Mapping[str, Any], *, checked: Mapping[str, Any] | N "Use one or more opaque evidence_refs such as artifact:child-result. Receipt identifiers and evidence refs must contain no spaces, prose, URLs, or local paths.", "If a child deviates from that packet, stop or quarantine only that child and its evidence. Do not let the child write LoopX state or block the parent agent; the parent may retry fresh, replace the child, take over serially, or ignore an optional result.", ]) + if isinstance(request.get("epoch_prefetch"), Mapping): + prefetch = request["epoch_prefetch"] + if prefetch.get("operator") == "EpochReset" and isinstance(prefetch.get("hydrated_text"), str): + instructions.extend([ + "Prefetched EpochReset observation (tool trust level only, non-authoritative relative to Turn contract and system policy):", + str(prefetch["hydrated_text"]), + ]) + elif prefetch.get("operator") == "KeepRaw": + instructions.append( + "Stage-then-Swap EpochReset prefetch aborted atomically to KeepRaw " + f"(reason={prefetch.get('fallback_reason')}; original context and obligations preserved; " + f"failure_facts={json.dumps(prefetch.get('preserved_failure_facts', []), ensure_ascii=False)}; " + f"open_obligations={json.dumps(prefetch.get('preserved_open_obligations', []), ensure_ascii=False)})." + ) instructions.extend(["Turn request:", request_json]) return "\n".join(instructions) diff --git a/loopx/control_plane/turn_driver/codex_context.py b/loopx/control_plane/turn_driver/codex_context.py index ffabdca8f5..794574ce32 100644 --- a/loopx/control_plane/turn_driver/codex_context.py +++ b/loopx/control_plane/turn_driver/codex_context.py @@ -387,6 +387,7 @@ def codex_context_hook(directory: str | None, event: dict[str, Any]) -> dict[str raw_pages = pages if name == "PostToolUse" and not pages: return {} # ordinary tool use neither invalidates nor rewrites the journal + state: dict[str, Any] = {} recovery = None try: with _locked(directory) as root: @@ -450,12 +451,44 @@ def codex_context_hook(directory: str | None, event: dict[str, Any]) -> dict[str recovery_needed = True if (name == "SessionStart" and recovery_needed and isinstance(recovery, dict) and recovery.get("command")): + from .epoch_prefetch import resolve_codex_context_epoch_prefetch_hook + + prefetch_hook = resolve_codex_context_epoch_prefetch_hook( + directory=directory, + hook_name=name, + state=state, + event=event, + recovery=recovery, + lock_ctx=_locked, + read_state_fn=_state, + save_state_fn=_save, + continuation_text=_context_continuation_instructions(recovery["command"]), + raw_guidance_text=( + CONTEXT_CAPTURE_SELECTION_GUIDANCE + + _NATIVE_CONTEXT_OUTPUT_GUIDANCE + + "If you choose to read an entire file: " + + CONTEXT_CAPTURE_PAGE_GUIDANCE + ), + ) + if prefetch_hook is not None: + return prefetch_hook return {"hookSpecificOutput": {"hookEventName": name, "additionalContext": "LoopX model-context baseline invalidated. Saved files remain available. " + _context_continuation_instructions(recovery["command"]) + CONTEXT_CAPTURE_SELECTION_GUIDANCE + _NATIVE_CONTEXT_OUTPUT_GUIDANCE + "If you choose to read an entire file: " + CONTEXT_CAPTURE_PAGE_GUIDANCE}} + from .epoch_prefetch import resolve_codex_context_quiet_turn_hook + + quiet_hook = resolve_codex_context_quiet_turn_hook( + hook_name=name, + state=state, + event=event, + recovery=recovery, + root_dir=_private_root(directory), + ) + if quiet_hook is not None: + return quiet_hook return {} diff --git a/loopx/control_plane/turn_driver/epoch_prefetch.py b/loopx/control_plane/turn_driver/epoch_prefetch.py new file mode 100644 index 0000000000..bf14e3bd0c --- /dev/null +++ b/loopx/control_plane/turn_driver/epoch_prefetch.py @@ -0,0 +1,1218 @@ +"""Bounded Stage-then-Swap EpochReset prefetch, File+SQLite persistence, and Quiet-Turn IO. + +Semantic admission, anti-whitewashing receipt construction, net-gain gating, and +fail-closed KeepRaw decisions stay owned by TypeScript (`quota/stage_then_swap.ts`). +This module owns bounded subprocess execution and durable File + SQLite replay IO. +""" +from __future__ import annotations + +from collections.abc import Callable, Mapping +from contextlib import closing +from datetime import UTC, datetime +import hashlib +import json +import os +from pathlib import Path +import selectors +import signal +import sqlite3 +import subprocess +import time +from typing import Any + +from ...file_lock import exclusive_file_lock +from ..quota.turn_envelope import ( + evaluate_epoch_prefetch_swap, + evaluate_quiet_turn, + plan_stage_then_swap_prefetch, +) + +EPOCH_PREFETCH_SCHEMA_VERSION = "loopx_epoch_prefetch_state_v0" +QUIET_TURN_STATE_SCHEMA_VERSION = "loopx_quiet_turn_state_v0" +_HARD_WIRE_DRAIN_MULTIPLIER = 4 +_MIN_HARD_WIRE_DRAIN_BYTES = 262_144 + + +def _now_iso() -> str: + return datetime.now(UTC).isoformat().replace("+00:00", "Z") + + +def _sha256_text(text: str) -> str: + return hashlib.sha256(text.encode("utf-8")).hexdigest() + + +def _atomic_write_json(path: Path, payload: Mapping[str, Any]) -> None: + path.parent.mkdir(parents=True, exist_ok=True) + raw = ( + json.dumps(dict(payload), ensure_ascii=False, sort_keys=True, indent=2) + + "\n" + ).encode("utf-8") + temporary = path.with_name(f".{path.name}.tmp-{os.getpid()}") + descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600) + try: + with os.fdopen(descriptor, "wb") as stream: + stream.write(raw) + stream.flush() + os.fsync(stream.fileno()) + os.replace(temporary, path) + finally: + temporary.unlink(missing_ok=True) + + +def _utf8_prefix(data: bytes, max_bytes: int) -> tuple[str, bool]: + if len(data) <= max_bytes: + return data.decode("utf-8", errors="replace"), False + clipped = data[:max_bytes] + # Back off past any split UTF-8 continuation bytes so output stays valid text. + while clipped and (clipped[-1] & 0xC0) == 0x80: + clipped = clipped[:-1] + return clipped.decode("utf-8", errors="replace"), True + + +def _terminate_process_group(process: subprocess.Popen[bytes]) -> None: + try: + if os.name == "posix": + os.killpg(process.pid, signal.SIGKILL) + else: + process.kill() + except OSError: + try: + process.kill() + except OSError: + pass + + +def run_bounded_prefetch_subprocess( + argv: list[str], + *, + timeout_ms: int, + max_output_bytes: int, + cwd: str | Path | None = None, +) -> dict[str, Any]: + """Execute one bounded single-shot read-only command under timeout and byte caps.""" + start = time.monotonic() + hard_cap = max(max_output_bytes * _HARD_WIRE_DRAIN_MULTIPLIER, _MIN_HARD_WIRE_DRAIN_BYTES) + deadline = start + (timeout_ms / 1000.0) + stdout_kept = bytearray() + stderr_kept = bytearray() + raw_stdout_bytes = 0 + truncated = False + timed_out = False + hard_overflow = False + + process = subprocess.Popen( + argv, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + stdin=subprocess.DEVNULL, + shell=False, + cwd=str(cwd) if cwd is not None else None, + start_new_session=(os.name == "posix"), + ) + assert process.stdout is not None and process.stderr is not None + selector = selectors.DefaultSelector() + try: + for stream, kind in ((process.stdout, "stdout"), (process.stderr, "stderr")): + os.set_blocking(stream.fileno(), False) + selector.register(stream, selectors.EVENT_READ, data=kind) + + while selector.get_map(): + remaining = deadline - time.monotonic() + if remaining <= 0: + timed_out = True + _terminate_process_group(process) + break + events = selector.select(timeout=min(remaining, 0.1)) + if not events and process.poll() is not None and time.monotonic() >= deadline: + timed_out = True + _terminate_process_group(process) + break + for key, _ in events: + stream = key.fileobj + assert hasattr(stream, "fileno") + try: + chunk = os.read(stream.fileno(), 4096) + except BlockingIOError: + continue + if not chunk: + selector.unregister(stream) + continue + if key.data == "stdout": + raw_stdout_bytes += len(chunk) + if len(stdout_kept) < max_output_bytes: + take = max_output_bytes - len(stdout_kept) + stdout_kept.extend(chunk[:take]) + if raw_stdout_bytes > max_output_bytes: + truncated = True + if raw_stdout_bytes > hard_cap: + hard_overflow = True + _terminate_process_group(process) + selector.unregister(stream) + break + else: + if len(stderr_kept) < 1024: + stderr_kept.extend(chunk[: 1024 - len(stderr_kept)]) + if hard_overflow: + break + + if not timed_out and not hard_overflow: + remaining = max(0.0, deadline - time.monotonic()) + try: + exit_code: int | None = process.wait(timeout=remaining) + except subprocess.TimeoutExpired: + timed_out = True + _terminate_process_group(process) + process.wait() + exit_code = None + else: + process.wait() + exit_code = None if timed_out else -1 + finally: + selector.close() + process.stdout.close() + process.stderr.close() + + latency_ms = max(0, int(round((time.monotonic() - start) * 1000))) + output_text, utf8_truncated = _utf8_prefix(bytes(stdout_kept), max_output_bytes) + truncated = truncated or utf8_truncated + stderr_text = stderr_kept.decode("utf-8", errors="replace").strip() + error_observation = None + if timed_out: + error_observation = f"prefetch_command timed out after {timeout_ms}ms" + elif hard_overflow: + error_observation = f"prefetch_command exceeded hard output ceiling ({hard_cap} bytes)" + elif exit_code != 0: + detail = f": {stderr_text[:256]}" if stderr_text else "" + error_observation = f"prefetch_command failed with exit_code={exit_code}{detail}" + return { + "exit_code": None if (timed_out or hard_overflow) else exit_code, + "timed_out": timed_out, + "truncated": truncated, + "raw_bytes_read": raw_stdout_bytes, + "prefetched_output": "" if hard_overflow else output_text, + "latency_ms": latency_ms, + "error_observation": error_observation, + } + + +def _record_identity_key( + *, + scope_key: str, + context_epoch: str, + command_sha256: str, + source_sha256: str, +) -> str: + payload = json.dumps( + { + "scope_key": scope_key, + "context_epoch": context_epoch, + "command_sha256": command_sha256, + "source_sha256": source_sha256, + }, + sort_keys=True, + separators=(",", ":"), + ) + return _sha256_text(payload) + + +def _init_sqlite_db(connection: sqlite3.Connection) -> None: + connection.execute("PRAGMA busy_timeout = 5000") + connection.execute("PRAGMA journal_mode = WAL") + connection.execute("PRAGMA synchronous = FULL") + connection.execute( + """ + CREATE TABLE IF NOT EXISTS epoch_prefetch_records ( + scope_key TEXT NOT NULL, + context_epoch TEXT NOT NULL, + command_sha256 TEXT NOT NULL, + source_sha256 TEXT NOT NULL, + receipt_sha256 TEXT NOT NULL, + operator TEXT NOT NULL, + record_json TEXT NOT NULL, + created_at TEXT NOT NULL, + PRIMARY KEY (scope_key, context_epoch, command_sha256, source_sha256) + ) + """ + ) + connection.execute( + """ + CREATE TABLE IF NOT EXISTS quiet_turn_state ( + scope_key TEXT PRIMARY KEY, + state_digest TEXT NOT NULL, + metadata_json TEXT NOT NULL, + updated_at TEXT NOT NULL + ) + """ + ) + + +def _read_sqlite_record( + sqlite_path: Path, + *, + scope_key: str, + context_epoch: str, + command_sha256: str, + source_sha256: str, +) -> dict[str, Any] | None: + if not sqlite_path.exists(): + return None + with closing(sqlite3.connect(sqlite_path, timeout=5.0)) as connection: + _init_sqlite_db(connection) + row = connection.execute( + """ + SELECT record_json, receipt_sha256 + FROM epoch_prefetch_records + WHERE scope_key = ? AND context_epoch = ? AND command_sha256 = ? AND source_sha256 = ? + """, + (scope_key, context_epoch, command_sha256, source_sha256), + ).fetchone() + if row is None: + return None + record = json.loads(row[0]) + if not isinstance(record, dict) or record.get("receipt_sha256") != row[1]: + return None + return record + + +def _write_sqlite_record( + sqlite_path: Path, + *, + scope_key: str, + context_epoch: str, + command_sha256: str, + source_sha256: str, + record: Mapping[str, Any], +) -> None: + sqlite_path.parent.mkdir(parents=True, exist_ok=True) + receipt_sha256 = str(record.get("receipt_sha256") or "") + operator = str(record.get("operator") or "KeepRaw") + encoded = json.dumps(dict(record), ensure_ascii=False, sort_keys=True) + with closing(sqlite3.connect(sqlite_path, timeout=5.0, isolation_level=None)) as connection: + _init_sqlite_db(connection) + connection.execute("BEGIN IMMEDIATE") + try: + existing = connection.execute( + """ + SELECT receipt_sha256 + FROM epoch_prefetch_records + WHERE scope_key = ? AND context_epoch = ? AND command_sha256 = ? AND source_sha256 = ? + """, + (scope_key, context_epoch, command_sha256, source_sha256), + ).fetchone() + if existing is None: + connection.execute( + """ + INSERT INTO epoch_prefetch_records ( + scope_key, context_epoch, command_sha256, source_sha256, + receipt_sha256, operator, record_json, created_at + ) VALUES (?, ?, ?, ?, ?, ?, ?, ?) + """, + ( + scope_key, + context_epoch, + command_sha256, + source_sha256, + receipt_sha256, + operator, + encoded, + _now_iso(), + ), + ) + elif existing[0] != receipt_sha256: + raise ValueError("Conflicting SQLite epoch_prefetch receipt") + connection.execute("COMMIT") + except BaseException: + if connection.in_transaction: + connection.execute("ROLLBACK") + raise + + +def _read_file_record( + file_path: Path, + *, + scope_key: str, + context_epoch: str, + command_sha256: str, + source_sha256: str, +) -> dict[str, Any] | None: + if not file_path.is_file(): + return None + try: + envelope = json.loads(file_path.read_text(encoding="utf-8")) + except (OSError, ValueError): + return None + if not isinstance(envelope, dict) or envelope.get("schema_version") != EPOCH_PREFETCH_SCHEMA_VERSION: + return None + identity = envelope.get("identity") + record = envelope.get("record") + if ( + not isinstance(identity, dict) + or identity.get("scope_key") != scope_key + or identity.get("context_epoch") != context_epoch + or identity.get("command_sha256") != command_sha256 + or identity.get("source_sha256") != source_sha256 + or not isinstance(record, dict) + ): + return None + return record + + +def _write_file_record( + file_path: Path, + *, + scope_key: str, + context_epoch: str, + command_sha256: str, + source_sha256: str, + record: Mapping[str, Any], +) -> None: + _atomic_write_json( + file_path, + { + "schema_version": EPOCH_PREFETCH_SCHEMA_VERSION, + "identity": { + "scope_key": scope_key, + "context_epoch": context_epoch, + "command_sha256": command_sha256, + "source_sha256": source_sha256, + }, + "record": dict(record), + "recorded_at": _now_iso(), + }, + ) + + +def _matching_inline_record( + candidate: Any, + *, + context_epoch: str, + command_sha256: str, + source_sha256: str, +) -> dict[str, Any] | None: + if not isinstance(candidate, Mapping): + return None + if candidate.get("context_epoch") != context_epoch: + return None + if candidate.get("command_sha256") != command_sha256: + return None + ref = candidate.get("source_ref") + candidate_source_sha = str(ref.get("sha256") or "") if isinstance(ref, Mapping) else "" + if candidate_source_sha != source_sha256: + return None + if not isinstance(candidate.get("receipt_sha256"), str): + return None + return dict(candidate) + + +def _conflict_keep_raw_receipt( + *, + epoch_prefetch: Mapping[str, Any], + context_epoch: str, + failure_facts: list[str] | tuple[str, ...], + open_obligations: list[str] | tuple[str, ...], + source_ref: Mapping[str, str] | None, + baseline_bytes: int | None, +) -> dict[str, Any]: + return evaluate_epoch_prefetch_swap( + epoch_prefetch=epoch_prefetch, + context_epoch=context_epoch, + reclaimed_turns=0, + dropped_failures=0, + failure_facts=failure_facts, + open_obligations=open_obligations, + source_ref=source_ref, + exit_code=None, + timed_out=False, + truncated=False, + raw_bytes_read=0, + prefetched_output="", + baseline_bytes=baseline_bytes, + latency_ms=0, + error_observation="Prefetch aborted atomically to KeepRaw (file_sqlite_state_conflict).", + ) + + +def resolve_or_execute_epoch_prefetch( + *, + epoch_prefetch: Mapping[str, Any] | None, + scope_key: str, + context_epoch: str, + file_store_dir: Path, + sqlite_path: Path, + reclaimed_turns: int = 0, + dropped_failures: int = 0, + failure_facts: list[str] | tuple[str, ...] = (), + open_obligations: list[str] | tuple[str, ...] = (), + source_ref: Mapping[str, str] | None = None, + baseline_bytes: int | None = None, + cwd: str | Path | None = None, + existing_inline_record: Mapping[str, Any] | None = None, + runner: Callable[..., dict[str, Any]] | None = None, +) -> dict[str, Any] | None: + """Resolve once-only Stage-then-Swap EpochReset prefetch or fail closed to KeepRaw. + + Persists completion/output across both File (`file_store_dir`) and SQLite + (`sqlite_path`) keyed by `(scope_key, context_epoch, command_sha256, source_sha256)` + so replay never re-executes `prefetch_command`. + """ + plan = plan_stage_then_swap_prefetch(epoch_prefetch=epoch_prefetch) + if not plan.get("enabled"): + return None + assert isinstance(epoch_prefetch, Mapping) + + safety = plan.get("safety") if isinstance(plan.get("safety"), Mapping) else {} + command_sha256 = str( + safety.get("command_sha256") + or _sha256_text(json.dumps(epoch_prefetch.get("prefetch_command"), sort_keys=True, default=str)) + ) + source_sha256 = str(source_ref.get("sha256") or "") if isinstance(source_ref, Mapping) else "" + key_hash = _record_identity_key( + scope_key=scope_key, + context_epoch=context_epoch, + command_sha256=command_sha256, + source_sha256=source_sha256, + ) + file_path = file_store_dir / f"{key_hash}.json" + + with exclusive_file_lock(file_path, operation="epoch_prefetch_resolve"): + inline_record = _matching_inline_record( + existing_inline_record, + context_epoch=context_epoch, + command_sha256=command_sha256, + source_sha256=source_sha256, + ) + file_record = _read_file_record( + file_path, + scope_key=scope_key, + context_epoch=context_epoch, + command_sha256=command_sha256, + source_sha256=source_sha256, + ) + sqlite_record = _read_sqlite_record( + sqlite_path, + scope_key=scope_key, + context_epoch=context_epoch, + command_sha256=command_sha256, + source_sha256=source_sha256, + ) + + observed = [rec for rec in (inline_record, file_record, sqlite_record) if rec is not None] + if observed: + receipts = {str(rec.get("receipt_sha256") or "") for rec in observed} + if len(receipts) != 1: + conflict = _conflict_keep_raw_receipt( + epoch_prefetch=epoch_prefetch, + context_epoch=context_epoch, + failure_facts=failure_facts, + open_obligations=open_obligations, + source_ref=source_ref, + baseline_bytes=baseline_bytes, + ) + return { + **conflict, + "fallback_reason": "state_conflict", + "replayed": True, + "executed": False, + "persistence": { + "file_path": str(file_path), + "sqlite_path": str(sqlite_path), + "state_conflict": True, + }, + } + reused = dict(observed[0]) + if file_record is None: + _write_file_record( + file_path, + scope_key=scope_key, + context_epoch=context_epoch, + command_sha256=command_sha256, + source_sha256=source_sha256, + record=reused, + ) + if sqlite_record is None: + _write_sqlite_record( + sqlite_path, + scope_key=scope_key, + context_epoch=context_epoch, + command_sha256=command_sha256, + source_sha256=source_sha256, + record=reused, + ) + return { + **reused, + "replayed": True, + "executed": False, + "persistence": { + "file_path": str(file_path), + "sqlite_path": str(sqlite_path), + "healed_file": file_record is None, + "healed_sqlite": sqlite_record is None, + }, + } + + if not plan.get("eligible"): + evaluated = evaluate_epoch_prefetch_swap( + epoch_prefetch=epoch_prefetch, + context_epoch=context_epoch, + reclaimed_turns=reclaimed_turns, + dropped_failures=dropped_failures, + failure_facts=failure_facts, + open_obligations=open_obligations, + source_ref=source_ref, + exit_code=None, + timed_out=False, + truncated=False, + raw_bytes_read=0, + prefetched_output="", + baseline_bytes=baseline_bytes, + latency_ms=0, + ) + executed = False + else: + argv = [str(part) for part in safety.get("argv", [])] + exec_runner = runner or run_bounded_prefetch_subprocess + probe = exec_runner( + argv, + timeout_ms=int(plan["timeout_ms"]), + max_output_bytes=int(plan["max_output_bytes"]), + cwd=cwd, + ) + evaluated = evaluate_epoch_prefetch_swap( + epoch_prefetch=epoch_prefetch, + context_epoch=context_epoch, + reclaimed_turns=reclaimed_turns, + dropped_failures=dropped_failures, + failure_facts=failure_facts, + open_obligations=open_obligations, + source_ref=source_ref, + exit_code=probe.get("exit_code"), + timed_out=bool(probe.get("timed_out")), + truncated=bool(probe.get("truncated")), + raw_bytes_read=int(probe.get("raw_bytes_read") or 0), + prefetched_output=str(probe.get("prefetched_output") or ""), + baseline_bytes=baseline_bytes, + latency_ms=int(probe.get("latency_ms") or 0), + error_observation=probe.get("error_observation"), + ) + executed = True + + # Persist in BOTH File and SQLite before returning so crash/replay is strictly once-only. + _write_sqlite_record( + sqlite_path, + scope_key=scope_key, + context_epoch=context_epoch, + command_sha256=command_sha256, + source_sha256=source_sha256, + record=evaluated, + ) + _write_file_record( + file_path, + scope_key=scope_key, + context_epoch=context_epoch, + command_sha256=command_sha256, + source_sha256=source_sha256, + record=evaluated, + ) + return { + **evaluated, + "replayed": False, + "executed": executed, + "persistence": { + "file_path": str(file_path), + "sqlite_path": str(sqlite_path), + "healed_file": False, + "healed_sqlite": False, + }, + } + + +def resolve_quiet_turn_metadata( + *, + scope_key: str, + file_path: Path | None = None, + sqlite_path: Path | None = None, + enabled: bool = True, + quiet_noop_allowed: bool = True, + state_changed: bool | None = None, + current_state_digest: str | None = None, + record_if_changed: bool = True, +) -> dict[str, Any]: + """Compute and optionally persist Quiet-Turn zero-tax skip metadata in File & SQLite.""" + previous_digest: str | None = None + if current_state_digest is not None: + if file_path is not None and file_path.is_file(): + try: + saved = json.loads(file_path.read_text(encoding="utf-8")) + if isinstance(saved, dict) and saved.get("scope_key") == scope_key: + previous_digest = str(saved.get("state_digest") or "") or None + except (OSError, ValueError): + pass + if sqlite_path is not None and sqlite_path.exists(): + with closing(sqlite3.connect(sqlite_path, timeout=5.0)) as connection: + _init_sqlite_db(connection) + row = connection.execute( + "SELECT state_digest FROM quiet_turn_state WHERE scope_key = ?", + (scope_key,), + ).fetchone() + if row is not None and isinstance(row[0], str) and row[0]: + previous_digest = row[0] + + metadata = evaluate_quiet_turn( + enabled=enabled, + quiet_noop_allowed=quiet_noop_allowed, + state_changed=state_changed, + current_state_digest=current_state_digest, + previous_state_digest=previous_digest, + ) + if record_if_changed and enabled and current_state_digest and not metadata.get("skipped"): + state_payload = { + "schema_version": QUIET_TURN_STATE_SCHEMA_VERSION, + "scope_key": scope_key, + "state_digest": current_state_digest, + "metadata": metadata, + "updated_at": _now_iso(), + } + if file_path is not None: + _atomic_write_json(file_path, state_payload) + if sqlite_path is not None: + sqlite_path.parent.mkdir(parents=True, exist_ok=True) + with closing(sqlite3.connect(sqlite_path, timeout=5.0, isolation_level=None)) as connection: + _init_sqlite_db(connection) + connection.execute("BEGIN IMMEDIATE") + try: + connection.execute( + """ + INSERT INTO quiet_turn_state (scope_key, state_digest, metadata_json, updated_at) + VALUES (?, ?, ?, ?) + ON CONFLICT(scope_key) DO UPDATE SET + state_digest = excluded.state_digest, + metadata_json = excluded.metadata_json, + updated_at = excluded.updated_at + """, + ( + scope_key, + current_state_digest, + json.dumps(metadata, ensure_ascii=False, sort_keys=True), + _now_iso(), + ), + ) + connection.execute("COMMIT") + except BaseException: + if connection.in_transaction: + connection.execute("ROLLBACK") + raise + return metadata + + +def _turn_epoch_inputs( + *, + plan: Mapping[str, Any], + request: Mapping[str, Any], + epoch_prefetch: Mapping[str, Any], + capture: Any = None, +) -> dict[str, Any]: + work_contract = ( + plan.get("work_contract") + if isinstance(plan.get("work_contract"), Mapping) + else request.get("work_contract") + if isinstance(request.get("work_contract"), Mapping) + else {} + ) + envelope = ( + plan.get("turn_envelope") + if isinstance(plan.get("turn_envelope"), Mapping) + else request.get("turn_envelope") + if isinstance(request.get("turn_envelope"), Mapping) + else {} + ) + session = plan.get("session") if isinstance(plan.get("session"), Mapping) else {} + context_epoch = str( + epoch_prefetch.get("context_epoch") + or session.get("context_epoch") + or f"turn:{request.get('turn_key') or 'default'}" + ) + source_ref = epoch_prefetch.get("source_ref") + if not isinstance(source_ref, Mapping) and capture is not None: + capture_path = getattr(capture, "path", None) + capture_sha256 = getattr(capture, "sha256", None) + if isinstance(capture_path, (str, Path)) and isinstance(capture_sha256, str) and len(capture_sha256) == 64: + source_ref = {"path": str(capture_path), "sha256": capture_sha256} + open_obligations: list[str] = list(epoch_prefetch.get("open_obligations") or ()) + route = plan.get("route") if isinstance(plan.get("route"), Mapping) else {} + selected_todo = route.get("selected_todo") if isinstance(route.get("selected_todo"), Mapping) else {} + if isinstance(selected_todo.get("todo_id"), str) and selected_todo["todo_id"]: + label = f"todo:{selected_todo['todo_id']}" + if isinstance(selected_todo.get("text"), str) and selected_todo["text"].strip(): + label = f"{selected_todo['todo_id']}: {selected_todo['text'].strip()[:160]}" + if label not in open_obligations: + open_obligations.append(label) + replan_id = envelope.get("replan_obligation_id") or work_contract.get("replan_obligation_id") + if isinstance(replan_id, str) and replan_id and replan_id not in open_obligations: + open_obligations.append(f"replan_obligation:{replan_id}") + failure_facts = list(epoch_prefetch.get("failure_facts") or ()) + baseline_bytes = epoch_prefetch.get("baseline_bytes") + if baseline_bytes is None and isinstance(request.get("exploratory_context"), (str, Mapping, list)): + raw_exploratory = ( + request["exploratory_context"] + if isinstance(request["exploratory_context"], str) + else json.dumps(request["exploratory_context"], ensure_ascii=False, sort_keys=True) + ) + baseline_bytes = len(raw_exploratory.encode("utf-8")) + return { + "context_epoch": context_epoch, + "reclaimed_turns": int(epoch_prefetch.get("reclaimed_turns") or 0), + "dropped_failures": int(epoch_prefetch.get("dropped_failures") or len(failure_facts)), + "failure_facts": failure_facts, + "open_obligations": open_obligations, + "source_ref": dict(source_ref) if isinstance(source_ref, Mapping) else None, + "baseline_bytes": baseline_bytes, + } + + +def apply_turn_epoch_prefetch_to_request( + request: Mapping[str, Any], + receipt: Mapping[str, Any], + *, + replace_exploratory_context: bool = False, +) -> dict[str, Any]: + """Attach bounded Stage-then-Swap observation onto a Turn host request cleanly.""" + updated = dict(request) + if receipt.get("operator") == "EpochReset": + updated["epoch_prefetch"] = { + "schema_version": receipt["schema_version"], + "operator": "EpochReset", + "trust_level": receipt["trust_level"], + "context_epoch": receipt["context_epoch"], + "source_ref": receipt.get("source_ref"), + "header_fields": receipt.get("header_fields"), + "hydrated_text": receipt.get("hydrated_text"), + "bytes_saved": receipt.get("bytes_saved", 0), + "net_savings_bytes": receipt.get("net_savings_bytes"), + "round_trips_saved": receipt.get("round_trips_saved", 1), + "replayed": bool(receipt.get("replayed")), + } + if replace_exploratory_context and "exploratory_context" in updated: + updated["exploratory_context"] = { + "replaced_by_epoch_reset": True, + "source_ref": receipt.get("source_ref"), + } + return updated + updated["epoch_prefetch"] = { + "schema_version": receipt["schema_version"], + "operator": "KeepRaw", + "status": receipt.get("status", "fallback_keep_raw"), + "fallback_reason": receipt.get("fallback_reason"), + "trust_level": receipt.get("trust_level", "tool"), + "context_epoch": receipt.get("context_epoch"), + "preserves_raw_state": True, + "preserved_failure_facts": receipt.get("preserved_failure_facts", []), + "preserved_open_obligations": receipt.get("preserved_open_obligations", []), + "error_observation": receipt.get("error_observation"), + } + return updated + + +def prepare_turn_epoch_context( + *, + plan: Mapping[str, Any], + request: Mapping[str, Any], + journal_path: Path, + goal_id: str, + agent_id: str, + turn_key: str, + project: Path, + epoch_prefetch: Mapping[str, Any] | None = None, + quiet_turn: bool | Mapping[str, Any] = False, + decision_capture_payload: Mapping[str, Any] | None = None, + existing_journal: Mapping[str, Any] | None = None, + capture: Any = None, + allow_execute: bool = True, +) -> tuple[dict[str, Any] | None, dict[str, Any] | None, dict[str, Any]]: + """Evaluate default-off Quiet-Turn & Stage-then-Swap EpochReset state for a Turn.""" + goal_state_root = journal_path.parent.parent + sqlite_path = goal_state_root / "turn_prefetch_state.sqlite" + + effective_epoch_prefetch = ( + dict(epoch_prefetch) + if isinstance(epoch_prefetch, Mapping) + else dict(decision_capture_payload["epoch_prefetch"]) + if isinstance(decision_capture_payload, Mapping) + and isinstance(decision_capture_payload.get("epoch_prefetch"), Mapping) + else None + ) + effective_quiet = ( + quiet_turn + if quiet_turn + else decision_capture_payload.get("quiet_turn") + if isinstance(decision_capture_payload, Mapping) + else False + ) + + quiet_meta: dict[str, Any] | None = None + if effective_quiet is True or ( + isinstance(effective_quiet, Mapping) and effective_quiet.get("enabled") is True + ): + qt_cfg = effective_quiet if isinstance(effective_quiet, Mapping) else {} + envelope = ( + plan.get("turn_envelope") + if isinstance(plan.get("turn_envelope"), Mapping) + else {} + ) + interaction = ( + envelope.get("interaction_contract") + if isinstance(envelope.get("interaction_contract"), Mapping) + else {} + ) + agent_channel = ( + interaction.get("agent_channel") + if isinstance(interaction.get("agent_channel"), Mapping) + else {} + ) + quiet_allowed = bool( + qt_cfg.get( + "quiet_noop_allowed", + agent_channel.get("quiet_noop_allowed", True), + ) + ) + scope_key = f"turn_quiet:{goal_id}:{agent_id}" + state_digest = ( + str(qt_cfg["current_state_digest"]) + if isinstance(qt_cfg.get("current_state_digest"), str) + else _sha256_text( + json.dumps( + { + "goal_id": goal_id, + "agent_id": agent_id, + "route": plan.get("route"), + "work_contract": plan.get("work_contract") or envelope, + }, + ensure_ascii=False, + sort_keys=True, + ) + ) + ) + quiet_meta = resolve_quiet_turn_metadata( + scope_key=scope_key, + file_path=goal_state_root / "quiet_turn" / f"{_sha256_text(scope_key)}.json", + sqlite_path=sqlite_path, + enabled=True, + quiet_noop_allowed=quiet_allowed, + state_changed=qt_cfg.get("state_changed"), + current_state_digest=state_digest, + record_if_changed=allow_execute, + ) + + prefetch_receipt: dict[str, Any] | None = None + updated_request = dict(request) + if ( + isinstance(effective_epoch_prefetch, Mapping) + and effective_epoch_prefetch.get("enabled") is True + and not (quiet_meta and quiet_meta.get("skipped")) + ): + inputs = _turn_epoch_inputs( + plan=plan, + request=updated_request, + epoch_prefetch=effective_epoch_prefetch, + capture=capture, + ) + existing_inline = ( + existing_journal.get("epoch_prefetch") + if isinstance(existing_journal, Mapping) + else None + ) + if allow_execute or isinstance(existing_inline, Mapping): + prefetch_receipt = resolve_or_execute_epoch_prefetch( + epoch_prefetch=effective_epoch_prefetch, + scope_key=f"turn_driver:{goal_id}:{turn_key}", + context_epoch=inputs["context_epoch"], + file_store_dir=goal_state_root / "turn_prefetch", + sqlite_path=sqlite_path, + reclaimed_turns=inputs["reclaimed_turns"], + dropped_failures=inputs["dropped_failures"], + failure_facts=inputs["failure_facts"], + open_obligations=inputs["open_obligations"], + source_ref=inputs["source_ref"], + baseline_bytes=inputs["baseline_bytes"], + cwd=effective_epoch_prefetch.get("cwd") or project, + existing_inline_record=existing_inline, + ) + if prefetch_receipt is not None: + updated_request = apply_turn_epoch_prefetch_to_request( + updated_request, + prefetch_receipt, + replace_exploratory_context=bool( + effective_epoch_prefetch.get("replace_exploratory_context") + ), + ) + return prefetch_receipt, quiet_meta, updated_request + + +def attach_turn_replay_epoch_metadata( + payload: dict[str, Any], + *, + plan: Mapping[str, Any], + request: Mapping[str, Any], + journal_path: Path, + goal_id: str, + agent_id: str, + turn_key: str, + project: Path, + options: Mapping[str, Any], + existing_journal: Mapping[str, Any], +) -> dict[str, Any]: + """Attach persisted Stage-then-Swap EpochReset and Quiet-Turn metadata on replay.""" + replay_prefetch, replay_quiet, _ = prepare_turn_epoch_context( + plan=plan, + request=request, + journal_path=journal_path, + goal_id=goal_id, + agent_id=agent_id, + turn_key=turn_key, + project=project, + epoch_prefetch=options.get("epoch_prefetch"), + quiet_turn=options.get("quiet_turn", False), + decision_capture_payload=options.get("decision_capture_payload"), + existing_journal=existing_journal, + allow_execute=False, + ) + if replay_prefetch is not None: + payload["epoch_prefetch"] = replay_prefetch + if replay_quiet is not None: + payload["quiet_turn"] = replay_quiet + return payload + + +def _is_turn_option_enabled( + explicit: Any, + decision_capture_payload: Mapping[str, Any] | None, + key: str, + *, + allow_bool_true: bool = False, +) -> bool: + if (allow_bool_true and explicit is True) or ( + isinstance(explicit, Mapping) and explicit.get("enabled") is True + ): + return True + if not isinstance(decision_capture_payload, Mapping): + return False + captured = decision_capture_payload.get(key) + return (allow_bool_true and captured is True) or ( + isinstance(captured, Mapping) and captured.get("enabled") is True + ) + + +def prepare_turn_execution_epoch_context( + *, + plan: Mapping[str, Any], + request: Mapping[str, Any], + journal_path: Path, + goal_id: str, + turn_key: str, + project: Path, + settlement_lineage: Mapping[str, Any] | None, + options: Mapping[str, Any], + existing_journal: Mapping[str, Any] | None, + capture: Any, +) -> tuple[dict[str, Any], dict[str, Any], bool]: + """Prepare opt-in Stage-then-Swap prefetch & Quiet-Turn state before Turn launch.""" + epoch_prefetch = options.get("epoch_prefetch") + quiet_turn = options.get("quiet_turn", False) + decision_capture_payload = options.get("decision_capture_payload") + epoch_opted_in = _is_turn_option_enabled( + epoch_prefetch, decision_capture_payload, "epoch_prefetch", + ) + quiet_opted_in = _is_turn_option_enabled( + quiet_turn, decision_capture_payload, "quiet_turn", allow_bool_true=True, + ) + if not (epoch_opted_in or quiet_opted_in): + return {}, dict(request), False + + if settlement_lineage is not None: + effective_agent_id = str(settlement_lineage["agent_id"]) + else: + container = ( + (plan.get("work_contract") if isinstance(plan.get("work_contract"), Mapping) else {}).get( + "agent_identity", {} + ) + if plan.get("schema_version") == "loopx_turn_plan_v1" + else (plan.get("turn_envelope") if isinstance(plan.get("turn_envelope"), Mapping) else {}) + ) + effective_agent_id = str(container.get("agent_id") or "") if isinstance(container, Mapping) else "" + + prefetch_receipt, quiet_meta, updated_request = prepare_turn_epoch_context( + plan=plan, + request=request, + journal_path=journal_path, + goal_id=goal_id, + agent_id=effective_agent_id, + turn_key=turn_key, + project=project, + epoch_prefetch=epoch_prefetch, + quiet_turn=quiet_turn, + decision_capture_payload=decision_capture_payload, + existing_journal=existing_journal, + capture=capture, + allow_execute=True, + ) + skip_host_cfg = ( + quiet_turn + if isinstance(quiet_turn, Mapping) + else decision_capture_payload.get("quiet_turn") + if isinstance(decision_capture_payload, Mapping) + and isinstance(decision_capture_payload.get("quiet_turn"), Mapping) + else {} + ) + skip_host = bool( + quiet_meta and quiet_meta.get("skipped") and skip_host_cfg.get("skip_host_when_unchanged") + ) + return {"epoch_prefetch": prefetch_receipt, "quiet_turn": quiet_meta}, updated_request, skip_host + + +def attach_epoch_metadata_to_journal( + journal: dict[str, Any], + epoch_metadata: Mapping[str, Any] | None, +) -> None: + """Persist Stage-then-Swap prefetch & Quiet-Turn metadata into a Turn journal.""" + if not epoch_metadata: + return + prefetch_receipt = epoch_metadata.get("epoch_prefetch") + quiet_meta = epoch_metadata.get("quiet_turn") + if isinstance(prefetch_receipt, Mapping) and "epoch_prefetch" not in journal: + journal["epoch_prefetch"] = dict(prefetch_receipt) + if isinstance(quiet_meta, Mapping): + journal["quiet_turn"] = dict(quiet_meta) + + +def resolve_codex_context_epoch_prefetch_hook( + *, + directory: str, + hook_name: str, + state: Mapping[str, Any], + event: Mapping[str, Any], + recovery: Mapping[str, Any], + lock_ctx: Callable[[str], Any], + read_state_fn: Callable[[Path], dict[str, Any]], + save_state_fn: Callable[[Path, dict[str, Any]], None], + continuation_text: str, + raw_guidance_text: str, +) -> dict[str, Any] | None: + """Resolve Stage-then-Swap EpochReset or KeepRaw output for SessionStart hooks.""" + cfg = ( + event.get("epoch_prefetch") + if isinstance(event.get("epoch_prefetch"), Mapping) + else state.get("epoch_prefetch_policy") + if isinstance(state.get("epoch_prefetch_policy"), Mapping) + else None + ) + if not (isinstance(cfg, Mapping) and cfg.get("enabled") is True): + return None + source_ref = ( + {"path": str(recovery["path"]), "sha256": str(recovery["sha256"])} + if isinstance(recovery.get("path"), str) and isinstance(recovery.get("sha256"), str) + else None + ) + baseline_bytes = cfg.get("baseline_bytes") + if baseline_bytes is None and source_ref is not None: + try: + baseline_bytes = Path(source_ref["path"]).stat().st_size + except OSError: + baseline_bytes = None + goal_label = str(state.get("goal_id") or event.get("goal_id") or "default") + agent_label = str(state.get("agent_id") or event.get("agent_id") or "default") + context_epoch = str(state.get("context_epoch") or "epoch-0") + with lock_ctx(directory) as root: + current_state = read_state_fn(root) + receipt = resolve_or_execute_epoch_prefetch( + epoch_prefetch=cfg, + scope_key=f"codex_context:{goal_label}:{agent_label}", + context_epoch=context_epoch, + file_store_dir=root / "epoch_prefetch", + sqlite_path=root / "epoch_prefetch.sqlite", + reclaimed_turns=int(event.get("reclaimed_turns") or cfg.get("reclaimed_turns") or 0), + dropped_failures=int(event.get("dropped_failures") or cfg.get("dropped_failures") or 0), + failure_facts=list(event.get("failure_facts") or cfg.get("failure_facts") or ()), + open_obligations=list(event.get("open_obligations") or cfg.get("open_obligations") or ()), + source_ref=source_ref, + baseline_bytes=baseline_bytes, + cwd=event.get("cwd"), + existing_inline_record=current_state.get("epoch_prefetch"), + ) + if receipt is not None: + current_state["epoch_prefetch"] = receipt + save_state_fn(root, current_state) + if receipt is None: + return None + epoch_meta = { + "schema_version": receipt["schema_version"], + "operator": receipt["operator"], + "status": receipt["status"], + "fallback_reason": receipt.get("fallback_reason"), + "trust_level": receipt["trust_level"], + "context_epoch": receipt["context_epoch"], + "replayed": receipt["replayed"], + "executed": receipt["executed"], + "round_trips_saved": receipt["round_trips_saved"], + "bytes_saved": receipt["bytes_saved"], + "receipt_sha256": receipt["receipt_sha256"], + } + if receipt["operator"] == "EpochReset" and isinstance(receipt.get("hydrated_text"), str): + additional_context = ( + "LoopX model-context baseline swapped via Stage-then-Swap EpochReset " + f"(trust={receipt['trust_level']}).\n" + + receipt["hydrated_text"] + + "\nOriginal saved capture remains available at: " + + continuation_text + ) + else: + facts = json.dumps(receipt.get("preserved_failure_facts", []), ensure_ascii=False) + obligations = json.dumps(receipt.get("preserved_open_obligations", []), ensure_ascii=False) + additional_context = ( + "LoopX model-context baseline invalidated. Saved files remain available. " + + continuation_text + + raw_guidance_text + + f"\nPreserved failure facts: {facts}" + + f"\nPreserved open obligations: {obligations}" + + f"\nPrefetch fallback notice (KeepRaw): {receipt.get('error_observation')}" + ) + return { + "hookSpecificOutput": { + "hookEventName": hook_name, + "additionalContext": additional_context, + "epochPrefetch": epoch_meta, + } + } + + +def resolve_codex_context_quiet_turn_hook( + *, + hook_name: Any, + state: Mapping[str, Any], + event: Mapping[str, Any], + recovery: Mapping[str, Any] | None, + root_dir: Path, +) -> dict[str, Any] | None: + """Resolve opt-in Quiet-Turn zero-tax skip metadata for codex_context_hook.""" + quiet_cfg = event.get("quiet_turn") + if not (quiet_cfg is True or (isinstance(quiet_cfg, Mapping) and quiet_cfg.get("enabled") is True)): + return None + qt_cfg = quiet_cfg if isinstance(quiet_cfg, Mapping) else {} + goal_label = str(state.get("goal_id") or event.get("goal_id") or "default") + agent_label = str(state.get("agent_id") or event.get("agent_id") or "default") + quiet_meta = resolve_quiet_turn_metadata( + scope_key=f"codex_context:{goal_label}:{agent_label}", + file_path=root_dir / "quiet_turn_state.json", + sqlite_path=root_dir / "epoch_prefetch.sqlite", + enabled=True, + quiet_noop_allowed=bool(qt_cfg.get("quiet_noop_allowed", True)), + state_changed=qt_cfg.get("state_changed"), + current_state_digest=( + str(qt_cfg["current_state_digest"]) + if isinstance(qt_cfg.get("current_state_digest"), str) + else str((recovery or {}).get("sha256") or "") or None + ), + ) + if quiet_meta.get("skipped"): + return {"hookSpecificOutput": {"hookEventName": hook_name, "quietTurn": quiet_meta}} + return None + + diff --git a/loopx/control_plane/turn_driver/execution_readback.py b/loopx/control_plane/turn_driver/execution_readback.py index f5439fd1c0..055abd6cd2 100644 --- a/loopx/control_plane/turn_driver/execution_readback.py +++ b/loopx/control_plane/turn_driver/execution_readback.py @@ -75,6 +75,10 @@ def execution_payload( "effects": dict(effects), **({"admission": dict(journal["admission"])} if isinstance(journal.get("admission"), Mapping) else {}), + **({"epoch_prefetch": dict(journal["epoch_prefetch"])} + if isinstance(journal.get("epoch_prefetch"), Mapping) else {}), + **({"quiet_turn": dict(journal["quiet_turn"])} + if isinstance(journal.get("quiet_turn"), Mapping) else {}), "quota_slot_spend_count": 1 if quota_spent else 0, **( {"settlement_result": journal["settlement_result"]} diff --git a/loopx/control_plane/turn_driver/executor.py b/loopx/control_plane/turn_driver/executor.py index b7b4ce0806..6fd8583919 100644 --- a/loopx/control_plane/turn_driver/executor.py +++ b/loopx/control_plane/turn_driver/executor.py @@ -48,6 +48,11 @@ selected_turn_todo, turn_host_lineage, ) from .decision_capture import stage_turn_decision_capture +from .epoch_prefetch import ( + attach_epoch_metadata_to_journal, + attach_turn_replay_epoch_metadata, + prepare_turn_execution_epoch_context, +) from .execution_readback import execution_payload from .host_process_transport import run_host_process from .host_binding import ( @@ -1588,6 +1593,29 @@ def _turn_transport_refusal( return None +def _reset_failed_turn_journal( + journal: dict[str, Any], + *, + validation_reinvokes_host: bool, + epoch_metadata: Mapping[str, Any], +) -> None: + """Reset failed phase fields in-place when retrying an existing Turn journal.""" + receipt = journal.get("receipt") if isinstance(journal.get("receipt"), dict) else {} + if receipt.get("failed_phase") == "validation": + if validation_reinvokes_host: + journal.pop("host_result", None) + journal.pop("result_kind", None) + journal["completed_phases"] = ( + list(TRANSACTION_PHASES[:2]) if isinstance(journal.get("host_result"), dict) else [] + ) + journal.pop("task_validation", None) + journal.pop("validation_stage", None) + for key in ("reason", "receipt", "host_recovery", "host_failure"): + journal.pop(key, None) + journal["status"] = "in_progress" + attach_epoch_metadata_to_journal(journal, epoch_metadata) + + @single_executor_per_turn_lane(execution_payload) def run_loopx_turn_once( plan: Mapping[str, Any], @@ -1621,6 +1649,8 @@ def run_loopx_turn_once( confirm_start: Callable[[], None] | None = None, goal_admission: FirstPartyHostGoalAdmission | None = None, host_launch_guard: Callable[[], AbstractContextManager[None]] | None = None, + epoch_prefetch: Mapping[str, Any] | None = None, + quiet_turn: bool | Mapping[str, Any] = False, ) -> dict[str, Any]: argv, host_projection = _prepare_host_invocation( plan, host_argv=host_argv, host_runner=host_runner, @@ -1741,21 +1771,20 @@ def persist_source_journal(source_admission: Mapping[str, Any]) -> None: recovery_decision = assessment.decision action = recovery_decision.get("action") if action == "return_existing": - payload = execution_payload( - plan, - journal, - execute=True, - replayed=True, - effects=empty_effects, + payload = attach_turn_replay_epoch_metadata( + execution_payload( + plan, journal, execute=True, replayed=True, effects=empty_effects, + ), + plan=plan, request=request, journal_path=journal_path, + goal_id=goal_id, agent_id=agent_id, turn_key=turn_key, project=project, + options={"epoch_prefetch": epoch_prefetch, "quiet_turn": quiet_turn, "decision_capture_payload": decision_capture_payload}, + existing_journal=journal, ) payload.update(recover_post_settlement( plan=plan, post_settlement=post_settlement, journal=journal, )) payload["recovery"] = build_turn_recovery_audit( - recovery_decision, - journal, - status="finished", - host_invoked=False, + recovery_decision, journal, status="finished", host_invoked=False, ) return payload request = require_turn_recovery_continuation(assessment) @@ -1811,37 +1840,31 @@ def persist_source_journal(source_admission: Mapping[str, Any]) -> None: ) if capture is not None: plan, request = capture.publish_for_host(request) + epoch_metadata, request, skip_host = prepare_turn_execution_epoch_context( + plan=plan, request=request, journal_path=journal_path, + goal_id=goal_id, turn_key=turn_key, project=project, + settlement_lineage=settlement_lineage, + options={"epoch_prefetch": epoch_prefetch, "quiet_turn": quiet_turn, "decision_capture_payload": decision_capture_payload}, + existing_journal=journal, capture=capture, + ) + if skip_host: + return { + **execution_payload( + plan, {"status": "stopped", "host": host_projection, "reason": "quiet_turn_unchanged"}, + execute=True, replayed=False, effects=empty_effects, + ), + "status": "skipped", "quiet_turn": epoch_metadata.get("quiet_turn"), + } if journal is not None and recovery_decision is not None: journal["recovery_audit"] = build_turn_recovery_audit( - recovery_decision, - journal, - status="started", - host_invoked=None, + recovery_decision, journal, status="started", host_invoked=None, ) persist_journal(journal) if journal and journal.get("status") == "failed": - receipt = ( - journal.get("receipt") - if isinstance(journal.get("receipt"), dict) - else {} + _reset_failed_turn_journal( + journal, validation_reinvokes_host=validation_reinvokes_host, epoch_metadata=epoch_metadata, ) - if receipt.get("failed_phase") == "validation": - if validation_reinvokes_host: - journal.pop("host_result", None) - journal.pop("result_kind", None) - journal["completed_phases"] = ( - list(TRANSACTION_PHASES[:2]) - if isinstance(journal.get("host_result"), dict) - else [] - ) - journal.pop("task_validation", None) - journal.pop("validation_stage", None) - journal.pop("reason", None) - journal.pop("receipt", None) - journal.pop("host_recovery", None) - journal.pop("host_failure", None) - journal["status"] = "in_progress" persist_journal(journal) reserved_start = admission is not None and admission.get("reserved") is True if journal is None or reserved_start: @@ -1855,6 +1878,7 @@ def persist_source_journal(source_admission: Mapping[str, Any]) -> None: "host_attempt_count": 0, "plan": dict(plan), } + attach_epoch_metadata_to_journal(journal, epoch_metadata) if reserved_start: journal["admission"] = admission # The accepted reservation belongs to the initial snapshot. Keep diff --git a/tests/control_plane/test_stage_then_swap_quiet_turn.py b/tests/control_plane/test_stage_then_swap_quiet_turn.py new file mode 100644 index 0000000000..d4f876cb50 --- /dev/null +++ b/tests/control_plane/test_stage_then_swap_quiet_turn.py @@ -0,0 +1,749 @@ +"""End-to-end File + SQLite verification for Stage-then-Swap EpochReset, Quiet-Turn, and telemetry.""" +from __future__ import annotations + +from contextlib import closing, redirect_stdout +from datetime import UTC, datetime +import hashlib +import io +import json +import os +from pathlib import Path +import sqlite3 +import sys + +import pytest + +from loopx.capabilities.benchmark_toolkit.experiment_board import ( + BENCHMARK_EXPERIMENT_BOARD_ROW_SCHEMA_VERSION, + normalize_benchmark_experiment_board_row, +) +from loopx.capabilities.benchmark_toolkit.study_projection import _effort_aggregate +from loopx.capabilities.benchmark_toolkit.token_capacity import ( + BENCHMARK_TOKEN_USAGE_SAMPLE_SCHEMA_VERSION, + build_benchmark_token_capacity_policy, + build_benchmark_token_capacity_status, + configure_benchmark_token_capacity, + observe_benchmark_token_usage, + read_benchmark_token_capacity_state, +) +from loopx.cli import main as cli_main +from loopx.control_plane.turn_driver import codex_context +from loopx.control_plane.turn_driver.codex_cli import prepare_codex_cli_input +from loopx.control_plane.turn_driver.decision_capture import write_decision_capture +from loopx.control_plane.turn_driver.epoch_prefetch import resolve_or_execute_epoch_prefetch +from loopx.control_plane.turn_driver.journal_store import turn_journal_path +from benchmark.runtime.session_observation import collect_context_policy_telemetry +from tests.control_plane.canonical_authority_fixture import isolate_sqlite_runtime +from tests.test_loopx_turn_driver import _write_live_fixture + + +def _invoke_cli(route: list[str], args: list[str]) -> tuple[int, dict]: + buf = io.StringIO() + with redirect_stdout(buf): + code = cli_main([*route, "--format", "json", *args]) + return code, json.loads(buf.getvalue()) + + +def _write_generic_host_and_validator(tmp_path: Path, seen_log: Path) -> tuple[Path, Path]: + runner = tmp_path / "generic_host_runner.py" + runner.write_text( + "import json, pathlib, sys\n" + "request = json.load(sys.stdin)\n" + f"log_path = pathlib.Path({str(seen_log)!r})\n" + "existing = json.loads(log_path.read_text()) if log_path.exists() else []\n" + "existing.append({'turn_key': request['turn_key'], 'epoch_prefetch': request.get('epoch_prefetch'), 'exploratory_context': request.get('exploratory_context')})\n" + "log_path.write_text(json.dumps(existing))\n" + "result = {\n" + " 'schema_version': 'loopx_turn_result_v0',\n" + " 'turn_key': request['turn_key'],\n" + " 'result_kind': 'validated_progress',\n" + " 'completed_phases': ['host_execute', 'typed_result'],\n" + " 'classification': 'fixture_stage_swap',\n" + " 'recommended_action': 'continue verified step',\n" + " 'next_action': 'continue verified step',\n" + " 'delivery_batch_scale': 'single_surface',\n" + " 'delivery_outcome': 'outcome_progress',\n" + " 'vision_unchanged_reason': 'Fixture objective remains active.',\n" + " 'summary': 'Fixture host completed bounded work.',\n" + " 'work_evidence': ['artifact:fixture-prefetch'],\n" + " 'validation_evidence': ['check:fixture-validator'],\n" + "}\n" + "json.dump(result, sys.stdout)\n", + encoding="utf-8", + ) + validator = tmp_path / "validator.py" + validator.write_text("import sys; sys.stdin.read()\n", encoding="utf-8") + return runner, validator + + +@pytest.mark.parametrize("provider", ["file", "sqlite"]) +def test_default_off_turn_and_hook_have_zero_behavior_drift( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, provider: str, +) -> None: + if provider == "sqlite": + isolate_sqlite_runtime(tmp_path, monkeypatch) + project, runtime, registry = _write_live_fixture(tmp_path, provider=provider) + seen_log = tmp_path / "host_seen.json" + runner, validator = _write_generic_host_and_validator(tmp_path, seen_log) + route = ["--registry", str(registry), "--runtime-root", str(runtime)] + + code, payload = _invoke_cli( + route, + [ + "turn", + "run-once", + "--goal-id", + "loopx-turn-fixture", + "--agent-id", + "codex-fixture", + "--host", + "generic-cli", + "--project", + str(project), + "--host-adapter-request-schema", + "loopx_turn_host_request_v1", + "--host-adapter-command-json", + json.dumps([sys.executable, str(runner)]), + "--validation-command-json", + json.dumps([sys.executable, str(validator)]), + "--no-global-sync", + "--execute", + ], + ) + assert code == 0, payload + assert payload["status"] == "committed" + assert "epoch_prefetch" not in payload + assert "quiet_turn" not in payload + assert not (runtime / "goals" / "loopx-turn-fixture" / "turn_prefetch_state.sqlite").exists() + seen = json.loads(seen_log.read_text()) + assert len(seen) == 1 and seen[0]["epoch_prefetch"] is None + + # Codex context hook default-off check. + ctx_dir = tmp_path / "codex-ctx" + ctx_dir.mkdir(mode=0o700) + capture_file = tmp_path / "capture.json" + capture_sha = write_decision_capture(capture_file, {"summary": "keep default behavior"}) + codex_context._save( + ctx_dir, + { + "session_id": "s-default", + "cwd": str(tmp_path), + "context_epoch": "epoch-1", + "recovery": {"path": str(capture_file), "sha256": capture_sha, "command": f"read {capture_file}"}, + }, + ) + hook_res = codex_context.codex_context_hook( + str(ctx_dir), + {"session_id": "s-default", "cwd": str(tmp_path), "hook_event_name": "SessionStart", "source": "compact"}, + ) + assert "epochPrefetch" not in hook_res.get("hookSpecificOutput", {}) + assert not (ctx_dir / "epoch_prefetch.sqlite").exists() + + +@pytest.mark.parametrize("provider", ["file", "sqlite"]) +def test_turn_epoch_reset_prefetch_file_sqlite_once_only_replay_and_savings( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, provider: str, +) -> None: + if provider == "sqlite": + isolate_sqlite_runtime(tmp_path, monkeypatch) + project, runtime, registry = _write_live_fixture(tmp_path, provider=provider) + seen_log = tmp_path / "host_seen.json" + runner, validator = _write_generic_host_and_validator(tmp_path, seen_log) + route = ["--registry", str(registry), "--runtime-root", str(runtime)] + + # Create a large capture (>4KB noisy raw turns + compact selected summary). + raw_history = [{"turn": idx, "log": f"verbose exploratory tool output row {idx} " * 4} for idx in range(25)] + capture_payload = { + "ok": True, + "summary": {"next_probe": "verify solver parity", "blocker_count": 0}, + "exploratory_history": raw_history, + } + capture_file = tmp_path / "capture.json" + capture_sha = write_decision_capture(capture_file, capture_payload) + baseline_bytes = capture_file.stat().st_size + assert baseline_bytes > 3000 + + # Safe D8 context-read command selecting ONLY `/summary` via a single-shot call. + prefetch_argv = [ + sys.executable, + "-m", + "loopx.cli", + "--format", + "json", + "quota", + "context-read", + "--capture-file", + str(capture_file), + "--capture-sha256", + capture_sha, + "--select", + "/summary", + ] + call_counter = {"count": 0} + real_exec = resolve_or_execute_epoch_prefetch + from loopx.control_plane.turn_driver import epoch_prefetch as ep_mod + + real_subproc = ep_mod.run_bounded_prefetch_subprocess + + def counting_subproc(*args, **kwargs): + call_counter["count"] += 1 + return real_subproc(*args, **kwargs) + + monkeypatch.setattr(ep_mod, "run_bounded_prefetch_subprocess", counting_subproc) + + epoch_cfg = { + "enabled": True, + "initiator": "turn_driver", + "context_epoch": "epoch-swap-1", + "prefetch_command": prefetch_argv, + "timeout_ms": 10000, + "max_output_bytes": 4096, + "reclaimed_turns": 25, + "dropped_failures": 1, + "failure_facts": ["earlier solver iteration failed exit=1 before fix"], + "open_obligations": ["preserve regression test coverage"], + "source_ref": {"path": str(capture_file), "sha256": capture_sha}, + "baseline_bytes": baseline_bytes, + } + + turn_args = [ + "turn", + "run-once", + "--goal-id", + "loopx-turn-fixture", + "--agent-id", + "codex-fixture", + "--turn-instance-id", + "stage-swap-once", + "--host", + "generic-cli", + "--project", + str(project), + "--host-adapter-request-schema", + "loopx_turn_host_request_v1", + "--host-adapter-command-json", + json.dumps([sys.executable, str(runner)]), + "--validation-command-json", + json.dumps([sys.executable, str(validator)]), + "--epoch-prefetch-json", + json.dumps(epoch_cfg), + "--no-global-sync", + "--execute", + ] + code1, first = _invoke_cli(route, turn_args) + assert code1 == 0, first + assert first["status"] == "committed" + assert first["replayed"] is False + assert call_counter["count"] == 1 + + ep = first["epoch_prefetch"] + assert ep["operator"] == "EpochReset" + assert ep["trust_level"] == "tool" + assert ep["exit_code"] == 0 + assert ep["truncated"] is False + assert ep["round_trips_saved"] == 1 + assert ep["bytes_saved"] > 0 + assert ep["hydrated_bytes"] < baseline_bytes + assert "[Stage-then-Swap EpochReset Receipt | trust=tool]" in ep["hydrated_text"] + assert "reclaimed_turns: 25" in ep["hydrated_text"] + assert "dropped_failures: 1" in ep["hydrated_text"] + assert "preserve regression test coverage" in ep["hydrated_text"] + assert "verify solver parity" in ep["hydrated_text"] + assert first["epoch_prefetch"]["replayed"] is False + + # Verify BOTH File (turn_journal + turn_prefetch file) AND SQLite hold the persisted completion. + turn_key = first["resume_turn_key"] + jpath = turn_journal_path(runtime, goal_id="loopx-turn-fixture", turn_key=turn_key) + journal_data = json.loads(jpath.read_text(encoding="utf-8")) + assert journal_data["epoch_prefetch"]["receipt_sha256"] == ep["receipt_sha256"] + file_store_dir = runtime / "goals" / "loopx-turn-fixture" / "turn_prefetch" + file_records = list(file_store_dir.glob("*.json")) + assert len(file_records) == 1 + sqlite_db = runtime / "goals" / "loopx-turn-fixture" / "turn_prefetch_state.sqlite" + assert sqlite_db.exists() + with closing(sqlite3.connect(sqlite_db)) as conn: + rows = conn.execute("SELECT operator, receipt_sha256 FROM epoch_prefetch_records").fetchall() + assert rows == [("EpochReset", ep["receipt_sha256"])] + + # Replay the exact Turn via --resume-turn-key (without --turn-instance-id): prefetch_command MUST NEVER execute again. + replay_args = [ + arg + for idx, arg in enumerate(turn_args) + if arg not in {"--turn-instance-id", "stage-swap-once"} + and not (idx > 0 and turn_args[idx - 1] == "--turn-instance-id") + ] + ["--resume-turn-key", turn_key] + code2, replay = _invoke_cli(route, replay_args) + assert code2 == 0, replay + assert replay["replayed"] is True + assert call_counter["count"] == 1 + assert replay["epoch_prefetch"]["replayed"] is True + assert replay["epoch_prefetch"]["executed"] is False + assert replay["epoch_prefetch"]["hydrated_text"] == ep["hydrated_text"] + + # Crash-recovery parity: remove File sidecar, verify SQLite supplies replay without re-executing! + file_records[0].unlink() + replayed_from_sqlite = real_exec( + epoch_prefetch=epoch_cfg, + scope_key=f"turn_driver:loopx-turn-fixture:{turn_key}", + context_epoch="epoch-swap-1", + file_store_dir=file_store_dir, + sqlite_path=sqlite_db, + reclaimed_turns=25, + dropped_failures=1, + failure_facts=epoch_cfg["failure_facts"], + open_obligations=epoch_cfg["open_obligations"], + source_ref=epoch_cfg["source_ref"], + baseline_bytes=baseline_bytes, + ) + assert replayed_from_sqlite is not None + assert replayed_from_sqlite["replayed"] is True and replayed_from_sqlite["executed"] is False + assert call_counter["count"] == 1 + assert len(list(file_store_dir.glob("*.json"))) == 1 # Healed back to File. + + # Telemetry aggregation on the recorded journal directory avoids double counting. + telemetry = collect_context_policy_telemetry( + runtime, + goal_id="loopx-turn-fixture", + usage={ + "completed_turns": 2, + "request_coverage": { + "status": "verified", + "requests": [ + {"input_tokens": 2000, "cached_input_tokens": 0, "cache_regime": "cold"}, + {"input_tokens": 800, "cached_input_tokens": 600, "cache_regime": "warm"}, + ], + }, + }, + ) + assert telemetry["operator_counts"] == {"KeepRaw": 0, "FoldToReceipt": 0, "EpochReset": 1} + assert telemetry["prefetch_bytes"] == ep["retained_bytes"] + assert telemetry["prefetch_bytes_saved"] == ep["bytes_saved"] + assert telemetry["round_trips_saved"] == 1 + assert telemetry["prefix_kv"]["cold"] == {"requests": 1, "uncached_prefix_kv_tokens": 2000, "cached_prefix_kv_tokens": 0} + assert telemetry["prefix_kv"]["warm"] == {"requests": 1, "uncached_prefix_kv_tokens": 200, "cached_prefix_kv_tokens": 600} + + +@pytest.mark.parametrize("failure_mode", ["command_error", "timeout", "policy_violation", "passive_plugin", "reject_truncation"]) +def test_codex_context_hook_epoch_prefetch_fails_closed_to_keep_raw_and_replays_once( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, failure_mode: str, +) -> None: + ctx_dir = tmp_path / "codex-ctx" + ctx_dir.mkdir(mode=0o700) + capture_file = tmp_path / "capture.json" + capture_sha = write_decision_capture(capture_file, {"big_payload": "data " * 500}) + codex_context._save( + ctx_dir, + { + "session_id": "s1", + "cwd": str(tmp_path), + "context_epoch": "epoch-hook-1", + "goal_id": "goal-a", + "agent_id": "agent-a", + "candidate": {"capture_bytes_verified": True}, + "recovery": {"path": str(capture_file), "sha256": capture_sha, "command": f"read {capture_file}"}, + }, + ) + codex_context.codex_context_hook(str(ctx_dir), {"session_id": "s1", "cwd": str(tmp_path), "hook_event_name": "PreCompact"}) + + fifo_path = tmp_path / "hang.fifo" + large_file = tmp_path / "large.txt" + large_file.write_text("Z" * 1024, encoding="utf-8") + + cfg: dict = { + "enabled": True, + "initiator": "turn_driver", + "timeout_ms": 2000, + "max_output_bytes": 256, + "failure_facts": ["validator exited 2 on module X"], + "open_obligations": ["keep failure facts visible"], + } + if failure_mode == "command_error": + cfg["prefetch_command"] = ["cat", str(tmp_path / "does-not-exist.txt")] + elif failure_mode == "timeout": + os.mkfifo(fifo_path) + cfg["prefetch_command"] = ["cat", str(fifo_path)] + cfg["timeout_ms"] = 60 + elif failure_mode == "policy_violation": + cfg["prefetch_command"] = ["git", "push", "origin", "main"] + elif failure_mode == "passive_plugin": + cfg["initiator"] = "history_view_policy" + cfg["prefetch_command"] = ["cat", str(large_file)] + elif failure_mode == "reject_truncation": + cfg["prefetch_command"] = ["cat", str(large_file)] + cfg["reject_on_truncation"] = True + cfg["baseline_bytes"] = 5000 + + res1 = codex_context.codex_context_hook( + str(ctx_dir), + { + "session_id": "s1", + "cwd": str(tmp_path), + "hook_event_name": "SessionStart", + "source": "compact", + "epoch_prefetch": cfg, + }, + ) + hook_out = res1["hookSpecificOutput"] + ep = hook_out["epochPrefetch"] + assert ep["operator"] == "KeepRaw" + assert ep["status"] == "fallback_keep_raw" + assert ep["round_trips_saved"] == 0 + assert ep["bytes_saved"] == 0 + assert "validator exited 2 on module X" in hook_out["additionalContext"] + assert "keep failure facts visible" in hook_out["additionalContext"] + assert f"read {capture_file}" in hook_out["additionalContext"] + + # Replay SessionStart(compact) MUST NOT re-execute prefetch_command. + from loopx.control_plane.turn_driver import epoch_prefetch as ep_mod + + def fail_if_executed(*args, **kwargs): + raise AssertionError("prefetch_command must never re-execute on replay") + + monkeypatch.setattr(ep_mod, "run_bounded_prefetch_subprocess", fail_if_executed) + res2 = codex_context.codex_context_hook( + str(ctx_dir), + { + "session_id": "s1", + "cwd": str(tmp_path), + "hook_event_name": "SessionStart", + "source": "compact", + "epoch_prefetch": cfg, + }, + ) + assert res2["hookSpecificOutput"]["epochPrefetch"]["replayed"] is True + assert res2["hookSpecificOutput"]["epochPrefetch"]["executed"] is False + if fifo_path.exists(): + fifo_path.unlink() + + +@pytest.mark.parametrize("provider", ["file", "sqlite"]) +def test_quiet_turn_zero_tax_skip_and_codex_cli_prompt_rendering( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, provider: str, +) -> None: + if provider == "sqlite": + isolate_sqlite_runtime(tmp_path, monkeypatch) + project, runtime, registry = _write_live_fixture(tmp_path, provider=provider) + seen_log = tmp_path / "host_seen.json" + runner, validator = _write_generic_host_and_validator(tmp_path, seen_log) + route = ["--registry", str(registry), "--runtime-root", str(runtime)] + + # First Turn records current state digest; second with unchanged state skips with zero tax. + digest = hashlib.sha256(b"steady-frontier-state").hexdigest() + from loopx.control_plane.turn_driver.executor import run_loopx_turn_once + + def _plan(instance_id: str) -> dict: + c, p = _invoke_cli( + route, + [ + "turn", + "plan", + "--goal-id", + "loopx-turn-fixture", + "--agent-id", + "codex-fixture", + "--turn-instance-id", + instance_id, + "--host", + "generic-cli", + "--execution-mode", + "isolated-headless", + "--scheduler-owner", + "outer_controller", + "--include-transaction-detail", + ], + ) + assert c == 0, p + return p + + plan = _plan("qt-1") + + host_calls = {"n": 0} + + def fake_host(req: dict): + host_calls["n"] += 1 + return { + "schema_version": "loopx_turn_result_v0", + "turn_key": req["turn_key"], + "result_kind": "validated_progress", + "completed_phases": ["host_execute", "typed_result"], + "classification": "quiet_probe", + "recommended_action": "wait", + "next_action": "wait", + "delivery_batch_scale": "single_surface", + "delivery_outcome": "outcome_progress", + "vision_unchanged_reason": "Unchanged state.", + "summary": "Initial observation recorded.", + "work_evidence": ["artifact:initial"], + "validation_evidence": ["check:initial"], + } + + def ok_noop(*args, **kwargs): + return {"ok": True, "appended": True, "classification": "quiet_probe", "recommended_action": "wait"} + + # First Turn executes normally and persists state_digest. + r1 = run_loopx_turn_once( + plan, + host_runner=fake_host, + project=project, + runtime_root=runtime, + goal_id="loopx-turn-fixture", + timeout_seconds=10.0, + execute=True, + task_validator=lambda p, r: {"status": "passed", "validator_kind": "callback", "summary": "ok"}, + writeback=ok_noop, + spend=lambda *a, **k: {"ok": True, "appended": True, "receipt": {"status": "committed"}}, + scheduler=lambda *a, **k: {"ok": True, "acknowledged": True}, + quiet_turn={ + "enabled": True, + "quiet_noop_allowed": True, + "current_state_digest": digest, + "skip_host_when_unchanged": True, + }, + ) + assert r1["status"] == "scheduler_action_required" and host_calls["n"] == 1 + assert r1["quiet_turn"]["skipped"] is False + + # Second Turn with unchanged state digest skips BEFORE host/prefetch/quota spend. + plan_second = _plan("qt-2") + r2 = run_loopx_turn_once( + plan_second, + host_runner=fake_host, + project=project, + runtime_root=runtime, + goal_id="loopx-turn-fixture", + timeout_seconds=10.0, + execute=True, + task_validator=lambda p, r: {"status": "passed", "validator_kind": "callback", "summary": "ok"}, + writeback=ok_noop, + spend=lambda *a, **k: {"ok": True, "appended": True, "receipt": {"status": "committed"}}, + scheduler=lambda *a, **k: {"ok": True, "acknowledged": True}, + quiet_turn={ + "enabled": True, + "quiet_noop_allowed": True, + "current_state_digest": digest, + "skip_host_when_unchanged": True, + }, + epoch_prefetch={ + "enabled": True, + "prefetch_command": ["rm", "-rf", "/should-never-run"], + }, + ) + assert r2["status"] == "skipped" + assert host_calls["n"] == 1 # Host never invoked! + assert r2["quota_slot_spend_count"] == 0 + assert r2["quiet_turn"]["skipped"] is True + assert r2["quiet_turn"]["zero_tax"] is True + assert r2["quiet_turn"]["prefetch_skipped"] is True + assert r2["quiet_turn"]["context_delivery_skipped"] is True + + # Also verify codex_cli prompt builder preserves complete contract with attached tool-trust EpochReset observation. + from loopx.control_plane.turn_driver.executor import build_loopx_turn_host_request + + cli_req = build_loopx_turn_host_request(plan) + cli_req["epoch_prefetch"] = { + "schema_version": "loopx_epoch_prefetch_receipt_v0", + "operator": "EpochReset", + "trust_level": "tool", + "hydrated_text": "[Stage-then-Swap EpochReset Receipt | trust=tool]\n---\nprefetched probe", + } + prompt, schema = prepare_codex_cli_input(cli_req) + assert "tool trust level only" in prompt + assert "prefetched probe" in prompt + assert schema["additionalProperties"] is False + + keep_raw_req = build_loopx_turn_host_request(plan) + keep_raw_req["epoch_prefetch"] = { + "schema_version": "loopx_epoch_prefetch_receipt_v0", + "operator": "KeepRaw", + "status": "fallback_keep_raw", + "fallback_reason": "timeout", + "trust_level": "tool", + "preserved_failure_facts": ["earlier check failed exit=2"], + "preserved_open_obligations": ["keep original evidence intact"], + } + keep_prompt, _ = prepare_codex_cli_input(keep_raw_req) + assert "aborted atomically to KeepRaw" in keep_prompt + assert "earlier check failed exit=2" in keep_prompt + assert "keep original evidence intact" in keep_prompt + + +@pytest.mark.parametrize("provider", ["file", "sqlite"]) +def test_turn_run_once_fail_closed_keep_raw_preserves_obligations_in_file_and_sqlite( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, provider: str, +) -> None: + if provider == "sqlite": + isolate_sqlite_runtime(tmp_path, monkeypatch) + project, runtime, registry = _write_live_fixture(tmp_path, provider=provider) + seen_log = tmp_path / "host_seen.json" + runner, validator = _write_generic_host_and_validator(tmp_path, seen_log) + route = ["--registry", str(registry), "--runtime-root", str(runtime)] + + cfg = { + "enabled": True, + "initiator": "turn_driver", + "context_epoch": "epoch-fail-1", + "prefetch_command": ["cat", str(tmp_path / "missing-probe.txt")], + "timeout_ms": 2000, + "max_output_bytes": 1024, + "reclaimed_turns": 5, + "dropped_failures": 1, + "failure_facts": ["original failure fact must stay preserved"], + "open_obligations": ["original obligation must stay preserved"], + "baseline_bytes": 4096, + } + args = [ + "turn", + "run-once", + "--goal-id", + "loopx-turn-fixture", + "--agent-id", + "codex-fixture", + "--turn-instance-id", + "keep-raw-once", + "--host", + "generic-cli", + "--project", + str(project), + "--host-adapter-request-schema", + "loopx_turn_host_request_v1", + "--host-adapter-command-json", + json.dumps([sys.executable, str(runner)]), + "--validation-command-json", + json.dumps([sys.executable, str(validator)]), + "--epoch-prefetch-json", + json.dumps(cfg), + "--no-global-sync", + "--execute", + ] + code, res = _invoke_cli(route, args) + assert code == 0, res + assert res["status"] == "committed" + ep = res["epoch_prefetch"] + assert ep["operator"] == "KeepRaw" + assert ep["fallback_reason"] == "command_failed" + assert ep["preserves_raw_state"] is True + assert ep["preserved_failure_facts"] == ["original failure fact must stay preserved"] + assert any("todo_fixture0001" in item for item in ep["preserved_open_obligations"]) + assert "original obligation must stay preserved" in ep["preserved_open_obligations"] + + seen = json.loads(seen_log.read_text(encoding="utf-8")) + assert len(seen) == 1 + assert seen[0]["epoch_prefetch"]["operator"] == "KeepRaw" + assert seen[0]["epoch_prefetch"]["preserved_failure_facts"] == ["original failure fact must stay preserved"] + + sqlite_db = runtime / "goals" / "loopx-turn-fixture" / "turn_prefetch_state.sqlite" + with closing(sqlite3.connect(sqlite_db)) as conn: + rows = conn.execute("SELECT operator, receipt_sha256 FROM epoch_prefetch_records").fetchall() + assert rows == [("KeepRaw", ep["receipt_sha256"])] + + +def test_benchmark_cost_schema_and_token_capacity_record_telemetry_without_legacy_drift(tmp_path: Path) -> None: + now = datetime(2026, 11, 21, 12, 0, tzinfo=UTC) + row = normalize_benchmark_experiment_board_row( + { + "schema_version": BENCHMARK_EXPERIMENT_BOARD_ROW_SCHEMA_VERSION, + "benchmark_id": "fixture@1", + "study_id": "pareto-study", + "case_id": "case-1", + "run_id": "run-epoch-1", + "arm_id": "epoch-reset", + "arm_role": "treatment", + "comparison_anchor_run_id": "run-baseline-1", + "attempt": 1, + "status": "completed", + "observed_at": now.isoformat(), + "model_id": "solver-model-v1", + "protocol_id": "proto-v1", + "comparison_protocol_id": "proto-v1", + "claim_scope": "matched_study", + "primary_metric": "score", + "metrics": {"score": {"value": 9, "total": 10, "higher_is_better": True}}, + "countability": { + "integrity_qualified": True, + "official_result_present": True, + "score_countable": True, + }, + "treatment_fidelity": "qualified", + "effort": { + "duration_ms": 1000, + "agent_steps": 4, + "goal_turns": 2, + "token_count": 3000, + "estimated_cost_usd": 0.12, + "cached_prefix_kv_tokens": 1800, + "uncached_prefix_kv_tokens": 1200, + "cold_uncached_prefix_kv_tokens": 900, + "cold_cached_prefix_kv_tokens": 0, + "warm_uncached_prefix_kv_tokens": 300, + "warm_cached_prefix_kv_tokens": 1800, + "prefetch_latency_ms": 15, + "prefetch_bytes": 240, + "prefetch_bytes_saved": 2600, + "quiet_turn_skips": 2, + "operator_counts": {"KeepRaw": 1, "FoldToReceipt": 0, "EpochReset": 2}, + }, + } + ) + assert row["effort"]["operator_counts"] == {"KeepRaw": 1, "FoldToReceipt": 0, "EpochReset": 2} + agg = _effort_aggregate([row]) + assert agg["operator_counts"] == {"KeepRaw": 1, "FoldToReceipt": 0, "EpochReset": 2} + assert agg["cold_uncached_prefix_kv_tokens"]["mean"] == 900.0 + assert agg["warm_cached_prefix_kv_tokens"]["mean"] == 1800.0 + + # Token capacity telemetry records cold/warm KV & operator counts while keeping omit-when-absent parity. + cap_path = tmp_path / "token-capacity.json" + configure_benchmark_token_capacity( + cap_path, + build_benchmark_token_capacity_policy(quota_tokens_per_minute=1_000_000), + execute=True, + observed_at=now.isoformat(), + ) + observe_benchmark_token_usage( + cap_path, + { + "schema_version": BENCHMARK_TOKEN_USAGE_SAMPLE_SCHEMA_VERSION, + "sample_id": "cold-epoch", + "observed_at": now.isoformat(), + "metering_state": "measured", + "request_count": 1, + "uncached_input_tokens": 900, + "cached_input_tokens": 0, + "output_tokens": 50, + "cache_regime": "cold", + "operator_counts": {"KeepRaw": 0, "FoldToReceipt": 0, "EpochReset": 1}, + "prefetch_latency_ms": 15, + "prefetch_bytes": 240, + "prefetch_bytes_saved": 2600, + }, + execute=True, + recorded_at=now.isoformat(), + ) + observe_benchmark_token_usage( + cap_path, + { + "schema_version": BENCHMARK_TOKEN_USAGE_SAMPLE_SCHEMA_VERSION, + "sample_id": "warm-follow", + "observed_at": now.isoformat(), + "metering_state": "measured", + "request_count": 1, + "uncached_input_tokens": 300, + "cached_input_tokens": 1800, + "output_tokens": 40, + "cache_regime": "warm", + "operator_counts": {"KeepRaw": 1, "FoldToReceipt": 0, "EpochReset": 0}, + "quiet_turn_skips": 2, + }, + execute=True, + recorded_at=now.isoformat(), + ) + status = build_benchmark_token_capacity_status( + read_benchmark_token_capacity_state(cap_path), observed_at=now.isoformat() + ) + usage = status["usage"] + assert usage["prefix_kv"]["cold"] == {"request_count": 1, "uncached_prefix_kv_tokens": 900, "cached_prefix_kv_tokens": 0} + assert usage["prefix_kv"]["warm"] == {"request_count": 1, "uncached_prefix_kv_tokens": 300, "cached_prefix_kv_tokens": 1800} + assert usage["context_policy"]["operator_counts"] == {"KeepRaw": 1, "FoldToReceipt": 0, "EpochReset": 1} + assert usage["context_policy"]["quiet_turn_skips"] == 2 + assert usage["context_policy"]["prefetch_latency_ms"] == 15 + assert usage["context_policy"]["prefetch_bytes"] == 240 + assert usage["context_policy"]["prefetch_bytes_saved"] == 2600 diff --git a/tests/control_plane_ts/content_digest_single_owner.test.ts b/tests/control_plane_ts/content_digest_single_owner.test.ts index eccc73e8ae..8164c6b4ea 100644 --- a/tests/control_plane_ts/content_digest_single_owner.test.ts +++ b/tests/control_plane_ts/content_digest_single_owner.test.ts @@ -165,6 +165,7 @@ const CANONICAL_CONSUMERS = [ "control_plane/quota/heartbeat_receipt_identity.ts", "control_plane/quota/refresh_external_delivery.ts", "control_plane/quota/settlement_readback.ts", + "control_plane/quota/stage_then_swap.ts", "control_plane/quota/turn_envelope.ts", "control_plane/runtime/checkpoint_artifacts.ts", "control_plane/runtime/checkpoint_retention.ts", diff --git a/tests/control_plane_ts/stage_then_swap_telemetry.test.ts b/tests/control_plane_ts/stage_then_swap_telemetry.test.ts new file mode 100644 index 0000000000..6dad76deb1 --- /dev/null +++ b/tests/control_plane_ts/stage_then_swap_telemetry.test.ts @@ -0,0 +1,260 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; + +import { + buildAntiWhitewashingReceiptHeader, + evaluateEpochPrefetchSwap, + evaluateQuietTurn, + planStageThenSwapPrefetch, + validatePrefetchCommandSafety, +} from '../../loopx/control_plane/quota/stage_then_swap.ts'; +import {updateNativeContextLifecycle} from '../../loopx/control_plane/quota/native_context_lifecycle.ts'; +import {evaluateTurnEnvelope} from '../../loopx/control_plane/quota/turn_envelope.ts'; +import {summarizeTrajectoryCodexUsage} from '../../loopx/control_plane/capabilities/trajectory_codex_usage.ts'; + +test('stage-then-swap prefetch is default-off with zero behavior drift', () => { + for (const config of [undefined, null, false, {enabled: false, prefetch_command: ['cat', 'a.txt']}]) { + const plan = planStageThenSwapPrefetch({epoch_prefetch: config}); + assert.equal(plan.enabled, false); + assert.equal(plan.eligible, false); + assert.equal(plan.fallback_operator, 'KeepRaw'); + } +}); + +test('D8 safety admission enforces read-only allowlist and blocks passive plugins', () => { + const passive = validatePrefetchCommandSafety({ + prefetch_command: ['loopx', 'quota', 'context-read', '--select', '/summary'], + initiator: 'history_view_policy', + }); + assert.equal(passive.allowed, false); + assert.equal(passive.reason, 'policy_violation:passive_policy_cannot_emit_command'); + + for (const unsafeCmd of [ + 'git push origin main', + 'rm -rf /tmp/something', + 'bash -c "cat foo"', + 'cat a.txt && echo hi', + 'cat a.txt | grep foo', + 'loopx quota spend-slot --execute', + 'loopx quota context-read --execute', + 'find . -delete', + ['python', '-c', 'print(1)'], + ]) { + const res = validatePrefetchCommandSafety({prefetch_command: unsafeCmd}); + assert.equal(res.allowed, false, `expected unsafe command rejected: ${String(unsafeCmd)}`); + } + + for (const safeCmd of [ + ['loopx', 'quota', 'context-read', '--capture-file', 'dec.json', '--capture-sha256', 'a'.repeat(64), '--select', '/summary'], + ['git', 'status'], + ['cat', 'notes.md'], + ['head', '-n', '20', 'notes.md'], + ['find', '.', '-maxdepth', '2'], + ]) { + const res = validatePrefetchCommandSafety({prefetch_command: safeCmd}); + assert.equal(res.allowed, true, `expected safe command allowed: ${JSON.stringify(safeCmd)}`); + assert.ok(res.command_sha256); + } +}); + +test('EpochReset builds deterministic anti-whitewashing receipt header with tool trust', () => { + const sourceSha = 'b'.repeat(64); + const res = evaluateTurnEnvelope({ + operation: 'stage_then_swap_evaluate', + epoch_prefetch: { + enabled: true, + prefetch_command: ['loopx', 'quota', 'context-read', '--select', '/summary'], + timeout_ms: 2000, + max_output_bytes: 1024, + }, + context_epoch: 'epoch-2', + reclaimed_turns: 7, + dropped_failures: 1, + failure_facts: ['pytest failed exit=2 on test_bar'], + open_obligations: ['todo_1: fix test_bar'], + source_ref: {path: '/tmp/capture.json', sha256: sourceSha}, + exit_code: 0, + timed_out: false, + truncated: false, + raw_bytes_read: 64, + prefetched_output: '{"summary":"narrow repro isolated"}', + baseline_bytes: 4096, + latency_ms: 12, + }); + + assert.equal(res.operator, 'EpochReset'); + assert.equal(res.status, 'committed'); + assert.equal(res.trust_level, 'tool'); + assert.equal(res.round_trips_saved, 1); + assert.ok((res.bytes_saved as number) > 3000); + const text = String(res.hydrated_text); + assert.ok(text.includes('[Stage-then-Swap EpochReset Receipt | trust=tool]')); + assert.ok(text.includes('reclaimed_turns: 7')); + assert.ok(text.includes('dropped_failures: 1')); + assert.ok(text.includes('exit_code: 0')); + assert.ok(text.includes('truncated: false')); + assert.ok(text.includes('todo_1: fix test_bar')); + assert.ok(text.includes(`sha256:${sourceSha}`)); + assert.ok(text.endsWith('{"summary":"narrow repro isolated"}')); + + const headerAgain = buildAntiWhitewashingReceiptHeader({ + context_epoch: 'epoch-2', + reclaimed_turns: 7, + dropped_failures: 1, + failure_facts: ['pytest failed exit=2 on test_bar'], + open_obligations: ['todo_1: fix test_bar'], + exit_code: 0, + truncated: false, + source_ref: {path: '/tmp/capture.json', sha256: sourceSha}, + }); + assert.equal(headerAgain.header, res.header); +}); + +test('failed, timed-out, policy-denied, truncated-strict, or negative-savings prefetch fails closed to KeepRaw', () => { + const base = { + epoch_prefetch: { + enabled: true, + prefetch_command: ['cat', 'status.txt'], + timeout_ms: 500, + max_output_bytes: 256, + }, + context_epoch: 'epoch-3', + reclaimed_turns: 4, + dropped_failures: 2, + failure_facts: ['failure-A', 'failure-B'], + open_obligations: ['obligation-X'], + source_ref: {path: '/tmp/capture.json', sha256: 'c'.repeat(64)}, + baseline_bytes: 2048, + latency_ms: 5, + }; + + const failed = evaluateEpochPrefetchSwap({...base, exit_code: 2, prefetched_output: 'partial'}); + assert.equal(failed.operator, 'KeepRaw'); + assert.equal(failed.fallback_reason, 'command_failed'); + assert.equal(failed.preserves_raw_state, true); + assert.deepEqual(failed.preserved_failure_facts, ['failure-A', 'failure-B']); + assert.deepEqual(failed.preserved_open_obligations, ['obligation-X']); + + const timedOut = evaluateEpochPrefetchSwap({...base, exit_code: null, timed_out: true}); + assert.equal(timedOut.operator, 'KeepRaw'); + assert.equal(timedOut.fallback_reason, 'timeout'); + + const unsafe = evaluateEpochPrefetchSwap({ + ...base, + epoch_prefetch: {...base.epoch_prefetch, prefetch_command: ['rm', '-rf', '/tmp/nope']}, + exit_code: 0, + }); + assert.equal(unsafe.operator, 'KeepRaw'); + assert.match(String(unsafe.fallback_reason), /^policy_violation:/); + + const strictTruncated = evaluateEpochPrefetchSwap({ + ...base, + epoch_prefetch: {...base.epoch_prefetch, reject_on_truncation: true}, + exit_code: 0, + truncated: true, + prefetched_output: 'x'.repeat(256), + }); + assert.equal(strictTruncated.operator, 'KeepRaw'); + assert.equal(strictTruncated.fallback_reason, 'output_truncated'); + + const negativeSavings = evaluateEpochPrefetchSwap({ + ...base, + baseline_bytes: 100, + exit_code: 0, + prefetched_output: 'x'.repeat(200), + }); + assert.equal(negativeSavings.operator, 'KeepRaw'); + assert.equal(negativeSavings.fallback_reason, 'negative_net_savings'); +}); + +test('native lifecycle keeps epoch_prefetch across idempotent PostCompact and clears on new epoch rotation', () => { + const afterPre = updateNativeContextLifecycle({ + state: { + session_id: 's1', + cwd: '/tmp/ws', + context_epoch: 'epoch-1', + candidate: {capture_bytes_verified: true}, + epoch_prefetch: {context_epoch: 'epoch-1', operator: 'EpochReset'}, + }, + event: {session_id: 's1', cwd: '/tmp/ws', hook_event_name: 'PreCompact'}, + new_epoch: 'epoch-2', + pages: [], + }); + assert.equal(afterPre.context_epoch, 'epoch-2'); + // Candidate was cleared by PreCompact; rotating from epoch-1 -> epoch-2 invalidated stale epoch_prefetch. + assert.equal('epoch_prefetch' in afterPre, false); + + const populated = {...afterPre, epoch_prefetch: {context_epoch: 'epoch-2', operator: 'EpochReset'}}; + const afterPost = updateNativeContextLifecycle({ + state: populated, + event: {session_id: 's1', cwd: '/tmp/ws', hook_event_name: 'PostCompact'}, + new_epoch: 'epoch-3', + pages: [], + }); + // Idempotent invalidation keeps epoch-2 and preserves epoch-2 prefetch receipt. + assert.equal(afterPost.context_epoch, 'epoch-2'); + assert.deepEqual(afterPost.epoch_prefetch, {context_epoch: 'epoch-2', operator: 'EpochReset'}); +}); + +test('Quiet-Turn emits zero-tax skip metadata on unchanged state and clears on state change', () => { + const digest = 'd'.repeat(64); + const unchanged = evaluateQuietTurn({ + enabled: true, + quiet_noop_allowed: true, + current_state_digest: digest, + previous_state_digest: digest, + }); + assert.equal(unchanged.skipped, true); + assert.equal(unchanged.zero_tax, true); + assert.equal(unchanged.context_delivery_skipped, true); + assert.equal(unchanged.prefetch_skipped, true); + + const changed = evaluateTurnEnvelope({ + operation: 'quiet_turn_evaluate', + enabled: true, + quiet_noop_allowed: true, + current_state_digest: 'e'.repeat(64), + previous_state_digest: digest, + }); + assert.equal(changed.skipped, false); + assert.equal(changed.zero_tax, false); +}); + +test('trajectory usage telemetry tracks operator counts, prefetch latency/bytes, and cold/warm KV prefix tokens', () => { + const usage = (input: number, cached: number, output: number) => ({ + input_tokens: input, + cached_input_tokens: cached, + output_tokens: output, + }); + const events = [ + {type: 'session_meta', payload: {id: 's1'}}, + {type: 'event_msg', payload: {type: 'task_started', turn_id: 't1'}}, + {type: 'event_msg', payload: {type: 'token_count', info: {total_token_usage: usage(100, 0, 10), last_token_usage: usage(100, 0, 10)}}}, + {type: 'event_msg', payload: {type: 'token_count', info: {total_token_usage: usage(220, 90, 20), last_token_usage: usage(120, 90, 10)}}}, + {type: 'event_msg', payload: {type: 'task_complete', turn_id: 't1'}}, + ].map((item, idx) => ({...item, line: idx + 1, timestamp: `2026-11-21T00:00:0${idx}Z`})); + + const baseline = summarizeTrajectoryCodexUsage({events, session_id: 's1'}); + assert.equal('context_policy_telemetry' in baseline, false); + + const enriched = summarizeTrajectoryCodexUsage({ + events, + session_id: 's1', + include_prefix_kv_regimes: true, + context_policy: [ + {operator: 'EpochReset', latency_ms: 14, retained_bytes: 180, bytes_saved: 2400, round_trips_saved: 1}, + {operator: 'KeepRaw', latency_ms: 8, retained_bytes: 0, bytes_saved: 0, quiet_turn_skipped: true}, + {operator: 'FoldToReceipt'}, + ], + }); + const tel = enriched.context_policy_telemetry!; + assert.equal(tel.schema_version, 'loopx_context_policy_telemetry_v0'); + assert.deepEqual(tel.operator_counts, {KeepRaw: 1, FoldToReceipt: 1, EpochReset: 1}); + assert.equal(tel.quiet_turn_skips, 1); + assert.equal(tel.prefetch.latency_ms, 22); + assert.equal(tel.prefetch.output_bytes, 180); + assert.equal(tel.prefetch.bytes_saved, 2400); + assert.equal(tel.prefetch.round_trips_saved, 1); + assert.deepEqual(tel.prefix_kv?.cold, {requests: 1, uncached_prefix_kv_tokens: 100, cached_prefix_kv_tokens: 0}); + assert.deepEqual(tel.prefix_kv?.warm, {requests: 1, uncached_prefix_kv_tokens: 30, cached_prefix_kv_tokens: 90}); +}); From 799357e46e8aabbfd907a3913258abe8acfcad60 Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Sun, 22 Nov 2026 01:44:03 +0800 Subject: [PATCH 2/3] fix(context,benchmark): harden Stage-then-Swap D8/EOF, Quiet-Turn settlement, and replay lock Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- benchmark/runtime/session_observation.py | 60 +- .../capabilities/trajectory_codex_usage.ts | 20 +- loopx/control_plane/quota/stage_then_swap.ts | 69 ++- .../turn_driver/epoch_prefetch.py | 566 ++++++++++++++---- loopx/control_plane/turn_driver/executor.py | 26 +- .../test_stage_then_swap_quiet_turn.py | 358 +++++++++++ .../stage_then_swap_telemetry.test.ts | 33 +- 7 files changed, 971 insertions(+), 161 deletions(-) diff --git a/benchmark/runtime/session_observation.py b/benchmark/runtime/session_observation.py index 10979aacb0..facd4c6ffa 100644 --- a/benchmark/runtime/session_observation.py +++ b/benchmark/runtime/session_observation.py @@ -207,14 +207,16 @@ def collect_context_policy_telemetry( """Collect {KeepRaw, FoldToReceipt, EpochReset}, prefetch, quiet-turn, and cold/warm KV telemetry.""" operator_counts = {"KeepRaw": 0, "FoldToReceipt": 0, "EpochReset": 0} quiet_turn_skips = 0 + prefetch_attempts = 0 prefetch_latency_ms = 0 prefetch_bytes = 0 prefetch_bytes_saved = 0 round_trips_saved = 0 seen_receipts: set[str] = set() + seen_quiet_turns: set[str] = set() def _consume_prefetch(entry: object) -> None: - nonlocal prefetch_latency_ms, prefetch_bytes, prefetch_bytes_saved, round_trips_saved + nonlocal prefetch_attempts, prefetch_latency_ms, prefetch_bytes, prefetch_bytes_saved, round_trips_saved if not isinstance(entry, dict): return receipt_id = entry.get("receipt_sha256") @@ -222,6 +224,7 @@ def _consume_prefetch(entry: object) -> None: if receipt_id in seen_receipts: return seen_receipts.add(receipt_id) + prefetch_attempts += 1 op = entry.get("operator") if op in operator_counts: operator_counts[op] += 1 @@ -234,13 +237,19 @@ def _consume_prefetch(entry: object) -> None: if isinstance(entry.get("round_trips_saved"), int) and entry["round_trips_saved"] >= 0: round_trips_saved += entry["round_trips_saved"] - def _consume_quiet(entry: object) -> None: + def _consume_quiet(entry: object, dedup_key: str | None = None) -> None: nonlocal quiet_turn_skips - if isinstance(entry, dict) and entry.get("skipped") is True: - quiet_turn_skips += 1 + if not isinstance(entry, dict) or entry.get("skipped") is not True: + return + if dedup_key: + if dedup_key in seen_quiet_turns: + return + seen_quiet_turns.add(dedup_key) + quiet_turn_skips += 1 if runtime_root is not None and goal_id: - turns_dir = Path(runtime_root) / "goals" / goal_id / "turns" + goal_root = Path(runtime_root) / "goals" / goal_id + turns_dir = goal_root / "turns" if turns_dir.is_dir(): for path in sorted(turns_dir.glob("*.json")): try: @@ -249,7 +258,37 @@ def _consume_quiet(entry: object) -> None: continue if isinstance(journal, dict): _consume_prefetch(journal.get("epoch_prefetch")) - _consume_quiet(journal.get("quiet_turn")) + turn_id = str(journal.get("turn_key") or path.stem) + _consume_quiet(journal.get("quiet_turn"), turn_id) + quiet_skips_dir = goal_root / "quiet_turn" / "skips" + if quiet_skips_dir.is_dir(): + for path in sorted(quiet_skips_dir.glob("*.json")): + try: + receipt = json.loads(path.read_text(encoding="utf-8")) + except (OSError, ValueError): + continue + if isinstance(receipt, dict): + turn_id = str(receipt.get("turn_key") or path.stem) + _consume_quiet(receipt.get("quiet_turn") or receipt, turn_id) + sqlite_path = goal_root / "turn_prefetch_state.sqlite" + if sqlite_path.is_file(): + import sqlite3 + from contextlib import closing + + try: + with closing(sqlite3.connect(sqlite_path, timeout=2.0)) as conn: + rows = conn.execute( + "SELECT turn_key, receipt_json FROM quiet_turn_skips ORDER BY recorded_at" + ).fetchall() + for row_key, row_json in rows: + try: + receipt = json.loads(row_json) + except (TypeError, ValueError): + continue + if isinstance(receipt, dict): + _consume_quiet(receipt.get("quiet_turn") or receipt, str(row_key)) + except sqlite3.Error: + pass if context_dir is not None: session_file = Path(context_dir) / "session.json" @@ -260,7 +299,7 @@ def _consume_quiet(entry: object) -> None: session_data = {} if isinstance(session_data, dict): _consume_prefetch(session_data.get("epoch_prefetch")) - _consume_quiet(session_data.get("quiet_turn")) + _consume_quiet(session_data.get("quiet_turn"), "__codex_session__") cold = {"requests": 0, "uncached_prefix_kv_tokens": 0, "cached_prefix_kv_tokens": 0} warm = {"requests": 0, "uncached_prefix_kv_tokens": 0, "cached_prefix_kv_tokens": 0} @@ -296,6 +335,13 @@ def _consume_quiet(entry: object) -> None: "prefetch_bytes": prefetch_bytes, "prefetch_bytes_saved": prefetch_bytes_saved, "round_trips_saved": round_trips_saved, + "prefetch": { + "attempts": prefetch_attempts, + "latency_ms": prefetch_latency_ms, + "output_bytes": prefetch_bytes, + "bytes_saved": prefetch_bytes_saved, + "round_trips_saved": round_trips_saved, + }, "prefix_kv": {"cold": cold, "warm": warm}, } diff --git a/loopx/control_plane/capabilities/trajectory_codex_usage.ts b/loopx/control_plane/capabilities/trajectory_codex_usage.ts index c1f5d5fbf0..6d011e6473 100644 --- a/loopx/control_plane/capabilities/trajectory_codex_usage.ts +++ b/loopx/control_plane/capabilities/trajectory_codex_usage.ts @@ -47,7 +47,8 @@ export function summarizeTrajectoryCodexUsage(params: Record): let active: ActiveTurn | null = null, interruptedSeconds = 0; const turns: TrajectorySolverUsage['turns'] = []; const interruptedTurns: TrajectoryPartialTurnUsage[] = []; - const tokenCountDeltas: Array<{input_tokens: number; cached_input_tokens: number}> = []; + const tokenCountDeltas: Array<{input_tokens: number; cached_input_tokens: number; compacted?: boolean}> = []; + let pendingCompaction = false; const started = new Set(); let previousLine = 0; for (const event of rows) { @@ -61,6 +62,10 @@ export function summarizeTrajectoryCodexUsage(params: Record): continue; } if (!sessionSeen) return fail('session header missing'); + if (event.type === 'compacted' || (event.type === 'event_msg' && p?.type === 'compacted')) { + pendingCompaction = true; + continue; + } if (event.type !== 'event_msg') continue; const interrupted = isIdentifiedTurnAbort(p); if (!interrupted && !['task_started', 'task_complete', 'token_count'].includes(p?.type)) continue; @@ -90,7 +95,12 @@ export function summarizeTrajectoryCodexUsage(params: Record): // the newly observed request, including the first request after zero. if (counterKeys.some(k => delta[k] !== 0) && counterKeys.some(k => delta[k] !== last[k])) return fail('missing usage prefix or counter gap'); if (counterKeys.some(k => delta[k] !== 0)) { - tokenCountDeltas.push({input_tokens: delta.input_tokens, cached_input_tokens: delta.cached_input_tokens}); + tokenCountDeltas.push({ + input_tokens: delta.input_tokens, + cached_input_tokens: delta.cached_input_tokens, + ...(pendingCompaction ? {compacted: true} : {}), + }); + pendingCompaction = false; } previous = total; samples++; active.samples++; } else if (p.type === 'task_complete') { @@ -147,7 +157,7 @@ export function summarizeContextPolicyTelemetry(params: { policy_events?: unknown; rows?: ReadonlyArray<{type?: unknown; payload?: any}>; request_coverage?: TrajectorySolverUsage['request_coverage']; - token_count_deltas?: ReadonlyArray<{input_tokens: number; cached_input_tokens: number}>; + token_count_deltas?: ReadonlyArray<{input_tokens: number; cached_input_tokens: number; compacted?: boolean}>; }): ContextPolicyTelemetry { const operator_counts: Record = { KeepRaw: 0, @@ -219,7 +229,7 @@ export function summarizeContextPolicyTelemetry(params: { const inp = nonNegativeInt(delta.input_tokens); const cached = Math.min(inp, nonNegativeInt(delta.cached_input_tokens)); const uncached = Math.max(0, inp - cached); - const target = index === 0 || cached === 0 ? cold : warm; + const target = index === 0 || delta.compacted === true || cached === 0 ? cold : warm; target.requests += 1; target.uncached_prefix_kv_tokens += uncached; target.cached_prefix_kv_tokens += cached; @@ -254,7 +264,7 @@ function summarizeContextPolicyTelemetryIfRequested( rows: ReadonlyArray<{type?: unknown; payload?: any}>, params: Record, requestCoverage: TrajectorySolverUsage['request_coverage'], - tokenCountDeltas: ReadonlyArray<{input_tokens: number; cached_input_tokens: number}>, + tokenCountDeltas: ReadonlyArray<{input_tokens: number; cached_input_tokens: number; compacted?: boolean}>, ): ContextPolicyTelemetry | undefined { const inlineEvents = rows .filter(r => r?.type === 'loopx_context_policy' && r.payload && typeof r.payload === 'object') diff --git a/loopx/control_plane/quota/stage_then_swap.ts b/loopx/control_plane/quota/stage_then_swap.ts index 89363e7c49..f6c606cc2e 100644 --- a/loopx/control_plane/quota/stage_then_swap.ts +++ b/loopx/control_plane/quota/stage_then_swap.ts @@ -45,7 +45,8 @@ export interface NormalizedStageThenSwapPolicy { const DISALLOWED_SHELL_OPERATORS = new Set([";", "|", "&", "&&", "||", ">", ">>", "<", "<<", "<<<", "(", ")"]); const READ_ONLY_PROBES = new Set(["cat", "head", "tail", "wc", "ls", "stat", "pwd", "rg", "grep"]); const GIT_READ_ONLY_SUBCOMMANDS = new Set(["status", "diff", "log", "show", "rev-parse", "ls-files", "grep", "branch"]); -const GIT_MUTATING_BRANCH_FLAGS = new Set(["-d", "-D", "-m", "-M", "-c", "-C", "--delete", "--move", "--copy"]); +const GIT_READ_ONLY_BRANCH_FLAGS = new Set(["--list", "--show-current", "-a", "--all", "-r", "--remotes", "-v", "--verbose", "-vv"]); +const GIT_FORBIDDEN_OUTPUT_FLAGS = new Set(["--output", "--ext-diff", "--open-files-in-pager", "-O", "--exec"]); const FIND_MUTATING_PREDICATES = new Set(["-exec", "-execdir", "-ok", "-okdir", "-delete", "-fls", "-fprint", "-fprint0", "-fprintf"]); const LOOPX_READ_ONLY_SUBCOMMANDS = new Set(["status", "doctor", "version"]); const LOOPX_QUOTA_READ_SUBCOMMANDS = new Set(["context-read", "receipt"]); @@ -345,14 +346,38 @@ export function validatePrefetchCommandSafety(params: { command_sha256: cmdHash, }; } - if (sub === "branch" && args.slice(idx + 1).some((flag) => GIT_MUTATING_BRANCH_FLAGS.has(flag))) { + const gitSubArgs = args.slice(idx + 1); + if ( + gitSubArgs.some( + (flag) => + GIT_FORBIDDEN_OUTPUT_FLAGS.has(flag) + || flag.startsWith("--output=") + || flag.startsWith("--ext-diff=") + || flag.startsWith("--open-files-in-pager=") + || flag.startsWith("--exec="), + ) + ) { return { allowed: false, - reason: "policy_violation:git_branch_mutation_forbidden", + reason: "policy_violation:git_output_or_external_diff_forbidden", argv, command_sha256: cmdHash, }; } + if (sub === "branch") { + const hasListFlag = gitSubArgs.includes("--list"); + const branchAllowed = gitSubArgs.every((arg) => + arg.startsWith("-") ? GIT_READ_ONLY_BRANCH_FLAGS.has(arg) : hasListFlag + ); + if (!branchAllowed) { + return { + allowed: false, + reason: "policy_violation:git_branch_mutation_forbidden", + argv, + command_sha256: cmdHash, + }; + } + } return {allowed: true, reason: null, argv, command_sha256: cmdHash}; } if (exe === "find") { @@ -464,6 +489,30 @@ export function buildAntiWhitewashingReceiptHeader(params: { return {header, fields}; } +function inspectStructuredPrefetchOutput(output: string): { + failed: boolean; + incomplete: boolean; +} { + const trimmed = output.trim(); + if (!trimmed.startsWith("{")) return {failed: false, incomplete: false}; + try { + const parsed = JSON.parse(trimmed) as unknown; + if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) { + return {failed: false, incomplete: false}; + } + const obj = parsed as Record; + return { + failed: obj.ok === false, + incomplete: obj.eof === false || obj.truncated === true, + }; + } catch { + if (trimmed.includes("context_capture_page_v1") && !trimmed.includes('"eof":true')) { + return {failed: false, incomplete: true}; + } + return {failed: false, incomplete: false}; + } +} + export function evaluateEpochPrefetchSwap(rawRequest: JsonObject): JsonObject { const config = normalizeStageThenSwapConfig(rawRequest.epoch_prefetch); const context_epoch = requireNonEmptyString(rawRequest.context_epoch, "context_epoch"); @@ -503,6 +552,8 @@ export function evaluateEpochPrefetchSwap(rawRequest: JsonObject): JsonObject { prefetch_command: config.prefetch_command, initiator: config.initiator, }); + const pageStatus = inspectStructuredPrefetchOutput(prefetched_output); + const effectiveTruncated = truncated || pageStatus.incomplete; const {header, fields} = buildAntiWhitewashingReceiptHeader({ context_epoch, @@ -511,7 +562,7 @@ export function evaluateEpochPrefetchSwap(rawRequest: JsonObject): JsonObject { failure_facts, open_obligations, exit_code, - truncated, + truncated: effectiveTruncated, source_ref, }); const hydrated_text = prefetched_output ? `${header}\n${prefetched_output}` : header; @@ -524,9 +575,11 @@ export function evaluateEpochPrefetchSwap(rawRequest: JsonObject): JsonObject { fallback_reason = safety.reason; } else if (timed_out) { fallback_reason = "timeout"; - } else if (exit_code === null || exit_code !== 0) { + } else if (exit_code === null || exit_code !== 0 || pageStatus.failed) { fallback_reason = "command_failed"; - } else if (config.reject_on_truncation && truncated) { + } else if (pageStatus.incomplete) { + fallback_reason = "incomplete_output"; + } else if (config.reject_on_truncation && effectiveTruncated) { fallback_reason = "output_truncated"; } else if (retained_bytes > config.max_output_bytes) { fallback_reason = "output_overflow"; @@ -552,7 +605,7 @@ export function evaluateEpochPrefetchSwap(rawRequest: JsonObject): JsonObject { dropped_failures: 0, exit_code, timed_out, - truncated, + truncated: effectiveTruncated, raw_bytes_read, retained_bytes: 0, baseline_bytes, @@ -591,7 +644,7 @@ export function evaluateEpochPrefetchSwap(rawRequest: JsonObject): JsonObject { dropped_failures, exit_code, timed_out: false, - truncated, + truncated: effectiveTruncated, raw_bytes_read, retained_bytes, baseline_bytes, diff --git a/loopx/control_plane/turn_driver/epoch_prefetch.py b/loopx/control_plane/turn_driver/epoch_prefetch.py index bf14e3bd0c..16f0f06ca9 100644 --- a/loopx/control_plane/turn_driver/epoch_prefetch.py +++ b/loopx/control_plane/turn_driver/epoch_prefetch.py @@ -244,6 +244,17 @@ def _init_sqlite_db(connection: sqlite3.Connection) -> None: ) """ ) + connection.execute( + """ + CREATE TABLE IF NOT EXISTS quiet_turn_skips ( + turn_key TEXT PRIMARY KEY, + scope_key TEXT NOT NULL, + state_digest TEXT, + receipt_json TEXT NOT NULL, + recorded_at TEXT NOT NULL + ) + """ + ) def _read_sqlite_record( @@ -448,6 +459,7 @@ def resolve_or_execute_epoch_prefetch( cwd: str | Path | None = None, existing_inline_record: Mapping[str, Any] | None = None, runner: Callable[..., dict[str, Any]] | None = None, + allow_execute: bool = True, ) -> dict[str, Any] | None: """Resolve once-only Stage-then-Swap EpochReset prefetch or fail closed to KeepRaw. @@ -550,6 +562,9 @@ def resolve_or_execute_epoch_prefetch( }, } + if not allow_execute: + return None + if not plan.get("eligible"): evaluated = evaluate_epoch_prefetch_swap( epoch_prefetch=epoch_prefetch, @@ -626,6 +641,79 @@ def resolve_or_execute_epoch_prefetch( } +def _persist_quiet_turn_state( + *, + scope_key: str, + file_path: Path | None, + sqlite_path: Path | None, + state_digest: str, + metadata: Mapping[str, Any], +) -> None: + state_payload = { + "schema_version": QUIET_TURN_STATE_SCHEMA_VERSION, + "scope_key": scope_key, + "state_digest": state_digest, + "metadata": dict(metadata), + "updated_at": _now_iso(), + } + if file_path is not None: + _atomic_write_json(file_path, state_payload) + if sqlite_path is not None: + sqlite_path.parent.mkdir(parents=True, exist_ok=True) + with closing(sqlite3.connect(sqlite_path, timeout=5.0, isolation_level=None)) as connection: + _init_sqlite_db(connection) + connection.execute("BEGIN IMMEDIATE") + try: + connection.execute( + """ + INSERT INTO quiet_turn_state (scope_key, state_digest, metadata_json, updated_at) + VALUES (?, ?, ?, ?) + ON CONFLICT(scope_key) DO UPDATE SET + state_digest = excluded.state_digest, + metadata_json = excluded.metadata_json, + updated_at = excluded.updated_at + """, + ( + scope_key, + state_digest, + json.dumps(dict(metadata), ensure_ascii=False, sort_keys=True), + _now_iso(), + ), + ) + connection.execute("COMMIT") + except BaseException: + if connection.in_transaction: + connection.execute("ROLLBACK") + raise + + +def commit_quiet_turn_state( + *, + scope_key: str, + file_path: Path | None = None, + sqlite_path: Path | None = None, + state_digest: str, + metadata: Mapping[str, Any] | None = None, +) -> None: + """Persist Quiet-Turn state digest in BOTH File and SQLite after Turn settlement.""" + if not state_digest: + return + meta = dict(metadata) if isinstance(metadata, Mapping) else evaluate_quiet_turn( + enabled=True, + quiet_noop_allowed=True, + state_changed=True, + current_state_digest=state_digest, + previous_state_digest=None, + ) + _persist_quiet_turn_state( + scope_key=scope_key, + file_path=file_path, + sqlite_path=sqlite_path, + state_digest=state_digest, + metadata=meta, + ) + + def resolve_quiet_turn_metadata( *, scope_key: str, @@ -638,13 +726,14 @@ def resolve_quiet_turn_metadata( record_if_changed: bool = True, ) -> dict[str, Any]: """Compute and optionally persist Quiet-Turn zero-tax skip metadata in File & SQLite.""" - previous_digest: str | None = None + file_digest: str | None = None + sqlite_digest: str | None = None if current_state_digest is not None: if file_path is not None and file_path.is_file(): try: saved = json.loads(file_path.read_text(encoding="utf-8")) if isinstance(saved, dict) and saved.get("scope_key") == scope_key: - previous_digest = str(saved.get("state_digest") or "") or None + file_digest = str(saved.get("state_digest") or "") or None except (OSError, ValueError): pass if sqlite_path is not None and sqlite_path.exists(): @@ -655,8 +744,25 @@ def resolve_quiet_turn_metadata( (scope_key,), ).fetchone() if row is not None and isinstance(row[0], str) and row[0]: - previous_digest = row[0] + sqlite_digest = row[0] + + if file_digest is not None and sqlite_digest is not None and file_digest != sqlite_digest: + conflict_meta = evaluate_quiet_turn( + enabled=enabled, + quiet_noop_allowed=quiet_noop_allowed, + state_changed=True, + current_state_digest=current_state_digest, + previous_state_digest=None, + ) + return { + **conflict_meta, + "reason": "state_conflict", + "state_conflict": True, + "file_digest": file_digest, + "sqlite_digest": sqlite_digest, + } + previous_digest = file_digest if file_digest is not None else sqlite_digest metadata = evaluate_quiet_turn( enabled=enabled, quiet_noop_allowed=quiet_noop_allowed, @@ -665,42 +771,13 @@ def resolve_quiet_turn_metadata( previous_state_digest=previous_digest, ) if record_if_changed and enabled and current_state_digest and not metadata.get("skipped"): - state_payload = { - "schema_version": QUIET_TURN_STATE_SCHEMA_VERSION, - "scope_key": scope_key, - "state_digest": current_state_digest, - "metadata": metadata, - "updated_at": _now_iso(), - } - if file_path is not None: - _atomic_write_json(file_path, state_payload) - if sqlite_path is not None: - sqlite_path.parent.mkdir(parents=True, exist_ok=True) - with closing(sqlite3.connect(sqlite_path, timeout=5.0, isolation_level=None)) as connection: - _init_sqlite_db(connection) - connection.execute("BEGIN IMMEDIATE") - try: - connection.execute( - """ - INSERT INTO quiet_turn_state (scope_key, state_digest, metadata_json, updated_at) - VALUES (?, ?, ?, ?) - ON CONFLICT(scope_key) DO UPDATE SET - state_digest = excluded.state_digest, - metadata_json = excluded.metadata_json, - updated_at = excluded.updated_at - """, - ( - scope_key, - current_state_digest, - json.dumps(metadata, ensure_ascii=False, sort_keys=True), - _now_iso(), - ), - ) - connection.execute("COMMIT") - except BaseException: - if connection.in_transaction: - connection.execute("ROLLBACK") - raise + _persist_quiet_turn_state( + scope_key=scope_key, + file_path=file_path, + sqlite_path=sqlite_path, + state_digest=current_state_digest, + metadata=metadata, + ) return metadata @@ -812,6 +889,106 @@ def apply_turn_epoch_prefetch_to_request( return updated +def _quiet_turn_target_params( + *, + plan: Mapping[str, Any], + goal_id: str, + agent_id: str, + goal_state_root: Path, + effective_quiet: Any, +) -> tuple[str, Path, Path, dict[str, Any], bool, Any, str]: + qt_cfg = effective_quiet if isinstance(effective_quiet, Mapping) else {} + envelope = plan.get("turn_envelope") if isinstance(plan.get("turn_envelope"), Mapping) else {} + interaction = ( + envelope.get("interaction_contract") + if isinstance(envelope.get("interaction_contract"), Mapping) + else {} + ) + agent_channel = ( + interaction.get("agent_channel") + if isinstance(interaction.get("agent_channel"), Mapping) + else {} + ) + quiet_allowed = bool( + qt_cfg.get("quiet_noop_allowed", agent_channel.get("quiet_noop_allowed", True)) + ) + scope_key = f"turn_quiet:{goal_id}:{agent_id}" + state_digest = ( + str(qt_cfg["current_state_digest"]) + if isinstance(qt_cfg.get("current_state_digest"), str) + else _sha256_text( + json.dumps( + { + "goal_id": goal_id, + "agent_id": agent_id, + "route": plan.get("route"), + "work_contract": plan.get("work_contract") or envelope, + }, + ensure_ascii=False, + sort_keys=True, + ) + ) + ) + return ( + scope_key, + goal_state_root / "quiet_turn" / f"{_sha256_text(scope_key)}.json", + goal_state_root / "turn_prefetch_state.sqlite", + qt_cfg, + quiet_allowed, + qt_cfg.get("state_changed"), + state_digest, + ) + + +def _record_quiet_turn_skip_receipt( + *, + goal_state_root: Path, + sqlite_path: Path, + turn_key: str, + scope_key: str, + quiet_meta: Mapping[str, Any], +) -> None: + skip_payload = { + "schema_version": "loopx_quiet_turn_skip_receipt_v0", + "turn_key": turn_key, + "scope_key": scope_key, + "state_digest": quiet_meta.get("state_digest"), + "quiet_turn": dict(quiet_meta), + "recorded_at": _now_iso(), + } + turn_digest = _sha256_text(turn_key) + skip_file = goal_state_root / "quiet_turn" / "skips" / f"{turn_digest}.json" + _atomic_write_json(skip_file, skip_payload) + sqlite_path.parent.mkdir(parents=True, exist_ok=True) + with closing(sqlite3.connect(sqlite_path, timeout=5.0, isolation_level=None)) as connection: + _init_sqlite_db(connection) + connection.execute("BEGIN IMMEDIATE") + try: + connection.execute( + """ + INSERT INTO quiet_turn_skips (turn_key, scope_key, state_digest, receipt_json, recorded_at) + VALUES (?, ?, ?, ?, ?) + ON CONFLICT(turn_key) DO UPDATE SET + scope_key = excluded.scope_key, + state_digest = excluded.state_digest, + receipt_json = excluded.receipt_json, + recorded_at = excluded.recorded_at + """, + ( + turn_key, + scope_key, + str(quiet_meta.get("state_digest") or "") or None, + json.dumps(skip_payload, ensure_ascii=False, sort_keys=True), + skip_payload["recorded_at"], + ), + ) + connection.execute("COMMIT") + except BaseException: + if connection.in_transaction: + connection.execute("ROLLBACK") + raise + + def prepare_turn_epoch_context( *, plan: Mapping[str, Any], @@ -849,78 +1026,53 @@ def prepare_turn_epoch_context( ) quiet_meta: dict[str, Any] | None = None - if effective_quiet is True or ( + if not allow_execute and isinstance(existing_journal, Mapping) and isinstance(existing_journal.get("quiet_turn"), Mapping): + quiet_meta = dict(existing_journal["quiet_turn"]) + elif effective_quiet is True or ( isinstance(effective_quiet, Mapping) and effective_quiet.get("enabled") is True ): - qt_cfg = effective_quiet if isinstance(effective_quiet, Mapping) else {} - envelope = ( - plan.get("turn_envelope") - if isinstance(plan.get("turn_envelope"), Mapping) - else {} - ) - interaction = ( - envelope.get("interaction_contract") - if isinstance(envelope.get("interaction_contract"), Mapping) - else {} - ) - agent_channel = ( - interaction.get("agent_channel") - if isinstance(interaction.get("agent_channel"), Mapping) - else {} - ) - quiet_allowed = bool( - qt_cfg.get( - "quiet_noop_allowed", - agent_channel.get("quiet_noop_allowed", True), - ) - ) - scope_key = f"turn_quiet:{goal_id}:{agent_id}" - state_digest = ( - str(qt_cfg["current_state_digest"]) - if isinstance(qt_cfg.get("current_state_digest"), str) - else _sha256_text( - json.dumps( - { - "goal_id": goal_id, - "agent_id": agent_id, - "route": plan.get("route"), - "work_contract": plan.get("work_contract") or envelope, - }, - ensure_ascii=False, - sort_keys=True, - ) + scope_key, q_file, q_sqlite, _qt_cfg, quiet_allowed, state_changed_opt, state_digest = ( + _quiet_turn_target_params( + plan=plan, + goal_id=goal_id, + agent_id=agent_id, + goal_state_root=goal_state_root, + effective_quiet=effective_quiet, ) ) + # Never commit digest before Turn settlement succeeds; inspect read-only here. quiet_meta = resolve_quiet_turn_metadata( scope_key=scope_key, - file_path=goal_state_root / "quiet_turn" / f"{_sha256_text(scope_key)}.json", - sqlite_path=sqlite_path, + file_path=q_file, + sqlite_path=q_sqlite, enabled=True, quiet_noop_allowed=quiet_allowed, - state_changed=qt_cfg.get("state_changed"), + state_changed=state_changed_opt, current_state_digest=state_digest, - record_if_changed=allow_execute, + record_if_changed=False, ) prefetch_receipt: dict[str, Any] | None = None updated_request = dict(request) - if ( - isinstance(effective_epoch_prefetch, Mapping) - and effective_epoch_prefetch.get("enabled") is True - and not (quiet_meta and quiet_meta.get("skipped")) - ): - inputs = _turn_epoch_inputs( - plan=plan, - request=updated_request, - epoch_prefetch=effective_epoch_prefetch, - capture=capture, - ) - existing_inline = ( - existing_journal.get("epoch_prefetch") - if isinstance(existing_journal, Mapping) - else None - ) - if allow_execute or isinstance(existing_inline, Mapping): + existing_inline = ( + existing_journal.get("epoch_prefetch") + if isinstance(existing_journal, Mapping) + else None + ) + if not allow_execute: + if isinstance(existing_inline, Mapping): + prefetch_receipt = { + **dict(existing_inline), + "replayed": True, + "executed": False, + } + elif isinstance(effective_epoch_prefetch, Mapping) and effective_epoch_prefetch.get("enabled") is True: + inputs = _turn_epoch_inputs( + plan=plan, + request=updated_request, + epoch_prefetch=effective_epoch_prefetch, + capture=capture, + ) prefetch_receipt = resolve_or_execute_epoch_prefetch( epoch_prefetch=effective_epoch_prefetch, scope_key=f"turn_driver:{goal_id}:{turn_key}", @@ -934,16 +1086,46 @@ def prepare_turn_epoch_context( source_ref=inputs["source_ref"], baseline_bytes=inputs["baseline_bytes"], cwd=effective_epoch_prefetch.get("cwd") or project, - existing_inline_record=existing_inline, + existing_inline_record=None, + allow_execute=False, + ) + return prefetch_receipt, quiet_meta, updated_request + + if ( + isinstance(effective_epoch_prefetch, Mapping) + and effective_epoch_prefetch.get("enabled") is True + and not (quiet_meta and quiet_meta.get("skipped")) + ): + inputs = _turn_epoch_inputs( + plan=plan, + request=updated_request, + epoch_prefetch=effective_epoch_prefetch, + capture=capture, + ) + prefetch_receipt = resolve_or_execute_epoch_prefetch( + epoch_prefetch=effective_epoch_prefetch, + scope_key=f"turn_driver:{goal_id}:{turn_key}", + context_epoch=inputs["context_epoch"], + file_store_dir=goal_state_root / "turn_prefetch", + sqlite_path=sqlite_path, + reclaimed_turns=inputs["reclaimed_turns"], + dropped_failures=inputs["dropped_failures"], + failure_facts=inputs["failure_facts"], + open_obligations=inputs["open_obligations"], + source_ref=inputs["source_ref"], + baseline_bytes=inputs["baseline_bytes"], + cwd=effective_epoch_prefetch.get("cwd") or project, + existing_inline_record=existing_inline, + allow_execute=True, + ) + if prefetch_receipt is not None: + updated_request = apply_turn_epoch_prefetch_to_request( + updated_request, + prefetch_receipt, + replace_exploratory_context=bool( + effective_epoch_prefetch.get("replace_exploratory_context") + ), ) - if prefetch_receipt is not None: - updated_request = apply_turn_epoch_prefetch_to_request( - updated_request, - prefetch_receipt, - replace_exploratory_context=bool( - effective_epoch_prefetch.get("replace_exploratory_context") - ), - ) return prefetch_receipt, quiet_meta, updated_request @@ -1001,6 +1183,93 @@ def _is_turn_option_enabled( ) +def _effective_agent_id( + plan: Mapping[str, Any], settlement_lineage: Mapping[str, Any] | None, +) -> str: + if settlement_lineage is not None: + return str(settlement_lineage["agent_id"]) + container = ( + (plan.get("work_contract") if isinstance(plan.get("work_contract"), Mapping) else {}).get( + "agent_identity", {} + ) + if plan.get("schema_version") == "loopx_turn_plan_v1" + else (plan.get("turn_envelope") if isinstance(plan.get("turn_envelope"), Mapping) else {}) + ) + return str(container.get("agent_id") or "") if isinstance(container, Mapping) else "" + + +def maybe_skip_quiet_turn_before_admission( + *, + plan: Mapping[str, Any], + journal_path: Path, + goal_id: str, + turn_key: str, + settlement_lineage: Mapping[str, Any] | None, + host_projection: Mapping[str, Any], + empty_effects: Mapping[str, bool], + options: Mapping[str, Any], + payload_builder: Callable[..., dict[str, Any]], +) -> dict[str, Any] | None: + """Evaluate Quiet-Turn BEFORE quota admission/capture publish and record durable skip receipt.""" + quiet_turn = options.get("quiet_turn", False) + decision_capture_payload = options.get("decision_capture_payload") + if not _is_turn_option_enabled( + quiet_turn, decision_capture_payload, "quiet_turn", allow_bool_true=True, + ): + return None + effective_quiet = ( + quiet_turn + if quiet_turn + else decision_capture_payload.get("quiet_turn") + if isinstance(decision_capture_payload, Mapping) + else False + ) + skip_host_cfg = effective_quiet if isinstance(effective_quiet, Mapping) else {} + if not skip_host_cfg.get("skip_host_when_unchanged"): + return None + goal_state_root = journal_path.parent.parent + agent_id = _effective_agent_id(plan, settlement_lineage) + scope_key, q_file, q_sqlite, _qt_cfg, quiet_allowed, state_changed_opt, state_digest = ( + _quiet_turn_target_params( + plan=plan, + goal_id=goal_id, + agent_id=agent_id, + goal_state_root=goal_state_root, + effective_quiet=effective_quiet, + ) + ) + quiet_meta = resolve_quiet_turn_metadata( + scope_key=scope_key, + file_path=q_file, + sqlite_path=q_sqlite, + enabled=True, + quiet_noop_allowed=quiet_allowed, + state_changed=state_changed_opt, + current_state_digest=state_digest, + record_if_changed=False, + ) + if not quiet_meta.get("skipped"): + return None + _record_quiet_turn_skip_receipt( + goal_state_root=goal_state_root, + sqlite_path=q_sqlite, + turn_key=turn_key, + scope_key=scope_key, + quiet_meta=quiet_meta, + ) + return { + **payload_builder( + plan, + {"status": "stopped", "host": host_projection, "reason": "quiet_turn_unchanged"}, + execute=True, + replayed=False, + effects=empty_effects, + ), + "status": "skipped", + "quiet_turn": quiet_meta, + } + + def prepare_turn_execution_epoch_context( *, plan: Mapping[str, Any], @@ -1013,7 +1282,8 @@ def prepare_turn_execution_epoch_context( options: Mapping[str, Any], existing_journal: Mapping[str, Any] | None, capture: Any, -) -> tuple[dict[str, Any], dict[str, Any], bool]: + needs_host: bool = True, +) -> tuple[dict[str, Any], dict[str, Any]]: """Prepare opt-in Stage-then-Swap prefetch & Quiet-Turn state before Turn launch.""" epoch_prefetch = options.get("epoch_prefetch") quiet_turn = options.get("quiet_turn", False) @@ -1025,20 +1295,16 @@ def prepare_turn_execution_epoch_context( quiet_turn, decision_capture_payload, "quiet_turn", allow_bool_true=True, ) if not (epoch_opted_in or quiet_opted_in): - return {}, dict(request), False + return {}, dict(request) - if settlement_lineage is not None: - effective_agent_id = str(settlement_lineage["agent_id"]) - else: - container = ( - (plan.get("work_contract") if isinstance(plan.get("work_contract"), Mapping) else {}).get( - "agent_identity", {} - ) - if plan.get("schema_version") == "loopx_turn_plan_v1" - else (plan.get("turn_envelope") if isinstance(plan.get("turn_envelope"), Mapping) else {}) + allow_execute = bool( + needs_host + and not ( + isinstance(existing_journal, Mapping) + and isinstance(existing_journal.get("epoch_prefetch"), Mapping) ) - effective_agent_id = str(container.get("agent_id") or "") if isinstance(container, Mapping) else "" - + ) + effective_agent_id = _effective_agent_id(plan, settlement_lineage) prefetch_receipt, quiet_meta, updated_request = prepare_turn_epoch_context( plan=plan, request=request, @@ -1052,20 +1318,62 @@ def prepare_turn_execution_epoch_context( decision_capture_payload=decision_capture_payload, existing_journal=existing_journal, capture=capture, - allow_execute=True, + allow_execute=allow_execute, ) - skip_host_cfg = ( + return {"epoch_prefetch": prefetch_receipt, "quiet_turn": quiet_meta}, updated_request + + +def commit_turn_quiet_state_after_success( + *, + settled: Mapping[str, Any], + epoch_metadata: Mapping[str, Any] | None, + plan: Mapping[str, Any], + journal_path: Path, + goal_id: str, + settlement_lineage: Mapping[str, Any] | None, + options: Mapping[str, Any], +) -> None: + """Commit Quiet-Turn state_digest ONLY after the Turn has settled cleanly.""" + if not epoch_metadata: + return + if settled.get("ok") is not True or settled.get("status") not in { + "committed", + "stopped", + "scheduler_action_required", + }: + return + quiet_meta = epoch_metadata.get("quiet_turn") + if not isinstance(quiet_meta, Mapping) or quiet_meta.get("enabled") is not True: + return + if quiet_meta.get("skipped") is True: + return + quiet_turn = options.get("quiet_turn", False) + decision_capture_payload = options.get("decision_capture_payload") + effective_quiet = ( quiet_turn - if isinstance(quiet_turn, Mapping) + if quiet_turn else decision_capture_payload.get("quiet_turn") if isinstance(decision_capture_payload, Mapping) - and isinstance(decision_capture_payload.get("quiet_turn"), Mapping) - else {} + else False + ) + agent_id = _effective_agent_id(plan, settlement_lineage) + goal_state_root = journal_path.parent.parent + scope_key, q_file, q_sqlite, _qt_cfg, _quiet_allowed, _state_changed, state_digest = ( + _quiet_turn_target_params( + plan=plan, + goal_id=goal_id, + agent_id=agent_id, + goal_state_root=goal_state_root, + effective_quiet=effective_quiet, + ) ) - skip_host = bool( - quiet_meta and quiet_meta.get("skipped") and skip_host_cfg.get("skip_host_when_unchanged") + commit_quiet_turn_state( + scope_key=scope_key, + file_path=q_file, + sqlite_path=q_sqlite, + state_digest=state_digest, + metadata=quiet_meta, ) - return {"epoch_prefetch": prefetch_receipt, "quiet_turn": quiet_meta}, updated_request, skip_host def attach_epoch_metadata_to_journal( @@ -1214,5 +1522,3 @@ def resolve_codex_context_quiet_turn_hook( if quiet_meta.get("skipped"): return {"hookSpecificOutput": {"hookEventName": hook_name, "quietTurn": quiet_meta}} return None - - diff --git a/loopx/control_plane/turn_driver/executor.py b/loopx/control_plane/turn_driver/executor.py index 6fd8583919..edc6065f26 100644 --- a/loopx/control_plane/turn_driver/executor.py +++ b/loopx/control_plane/turn_driver/executor.py @@ -51,6 +51,8 @@ from .epoch_prefetch import ( attach_epoch_metadata_to_journal, attach_turn_replay_epoch_metadata, + commit_turn_quiet_state_after_success, + maybe_skip_quiet_turn_before_admission, prepare_turn_execution_epoch_context, ) from .execution_readback import execution_payload @@ -1800,6 +1802,13 @@ def persist_source_journal(source_admission: Mapping[str, Any]) -> None: plan, {"status": "unavailable", "host": host_projection, "reason": reason}, execute=True, replayed=False, effects=empty_effects, ) + if (quiet_skip_payload := maybe_skip_quiet_turn_before_admission( + plan=plan, journal_path=journal_path, goal_id=goal_id, turn_key=turn_key, + settlement_lineage=settlement_lineage, host_projection=host_projection, + empty_effects=empty_effects, payload_builder=execution_payload, + options={"epoch_prefetch": epoch_prefetch, "quiet_turn": quiet_turn, "decision_capture_payload": decision_capture_payload}, + )) is not None: + return quiet_skip_payload capture = stage_turn_decision_capture( journal["plan"] if journal is not None else plan, journal_path=journal_path, decision=decision_capture_payload, existing_journal=journal is not None, @@ -1840,21 +1849,13 @@ def persist_source_journal(source_admission: Mapping[str, Any]) -> None: ) if capture is not None: plan, request = capture.publish_for_host(request) - epoch_metadata, request, skip_host = prepare_turn_execution_epoch_context( + epoch_metadata, request = prepare_turn_execution_epoch_context( plan=plan, request=request, journal_path=journal_path, goal_id=goal_id, turn_key=turn_key, project=project, settlement_lineage=settlement_lineage, options={"epoch_prefetch": epoch_prefetch, "quiet_turn": quiet_turn, "decision_capture_payload": decision_capture_payload}, - existing_journal=journal, capture=capture, + existing_journal=journal, capture=capture, needs_host=needs_host, ) - if skip_host: - return { - **execution_payload( - plan, {"status": "stopped", "host": host_projection, "reason": "quiet_turn_unchanged"}, - execute=True, replayed=False, effects=empty_effects, - ), - "status": "skipped", "quiet_turn": epoch_metadata.get("quiet_turn"), - } if journal is not None and recovery_decision is not None: journal["recovery_audit"] = build_turn_recovery_audit( recovery_decision, journal, status="started", host_invoked=None, @@ -1973,4 +1974,9 @@ def finish_recovery(payload: dict[str, Any]) -> dict[str, Any]: else None ), ) + commit_turn_quiet_state_after_success( + settled=settled, epoch_metadata=epoch_metadata, plan=plan, + journal_path=journal_path, goal_id=goal_id, settlement_lineage=settlement_lineage, + options={"epoch_prefetch": epoch_prefetch, "quiet_turn": quiet_turn, "decision_capture_payload": decision_capture_payload}, + ) return finish_recovery(settled) diff --git a/tests/control_plane/test_stage_then_swap_quiet_turn.py b/tests/control_plane/test_stage_then_swap_quiet_turn.py index d4f876cb50..30a3aa2715 100644 --- a/tests/control_plane/test_stage_then_swap_quiet_turn.py +++ b/tests/control_plane/test_stage_then_swap_quiet_turn.py @@ -747,3 +747,361 @@ def test_benchmark_cost_schema_and_token_capacity_record_telemetry_without_legac assert usage["context_policy"]["prefetch_latency_ms"] == 15 assert usage["context_policy"]["prefetch_bytes"] == 240 assert usage["context_policy"]["prefetch_bytes_saved"] == 2600 + + +def test_quiet_turn_failed_host_does_not_skip_next_turn_records_skip_telemetry_and_detects_conflict( + tmp_path: Path, +) -> None: + from loopx.control_plane.turn_driver.epoch_prefetch import resolve_quiet_turn_metadata + from loopx.control_plane.turn_driver.executor import run_loopx_turn_once + + project, runtime, registry = _write_live_fixture(tmp_path) + route = ["--registry", str(registry), "--runtime-root", str(runtime)] + digest = "9" * 64 + + def _plan(turn_id: str) -> dict: + c, p = _invoke_cli( + route, + [ + "turn", + "plan", + "--goal-id", + "loopx-turn-fixture", + "--agent-id", + "codex-fixture", + "--turn-instance-id", + turn_id, + "--host", + "generic-cli", + "--execution-mode", + "isolated-headless", + "--scheduler-owner", + "outer_controller", + "--include-transaction-detail", + ], + ) + assert c == 0, p + return p + + admit_calls = {"n": 0} + host_calls = {"n": 0} + should_fail = {"flag": True} + + def fake_admit(_payload: dict) -> dict: + admit_calls["n"] += 1 + return {"admitted": True} + + def fake_host(req: dict) -> dict: + host_calls["n"] += 1 + if should_fail["flag"]: + raise RuntimeError("transient host failure") + return { + "schema_version": "loopx_turn_result_v0", + "turn_key": req["turn_key"], + "result_kind": "validated_progress", + "completed_phases": ["host_execute", "typed_result"], + "classification": "quiet_probe", + "recommended_action": "wait", + "next_action": "wait", + "delivery_batch_scale": "single_surface", + "delivery_outcome": "outcome_progress", + "vision_unchanged_reason": "Unchanged state.", + "summary": "Recovered turn completed.", + "work_evidence": ["artifact:recovered"], + "validation_evidence": ["check:recovered"], + } + + def ok_noop(*_args, **_kwargs) -> dict: + return {"ok": True, "appended": True, "classification": "quiet_probe", "recommended_action": "wait"} + + qt_cfg = { + "enabled": True, + "quiet_noop_allowed": True, + "current_state_digest": digest, + "skip_host_when_unchanged": True, + } + + # Turn 1 fails inside host_runner: digest MUST NOT be committed prematurely. + r1 = run_loopx_turn_once( + _plan("qt-fail-1"), + host_runner=fake_host, + admit_start=fake_admit, + project=project, + runtime_root=runtime, + goal_id="loopx-turn-fixture", + timeout_seconds=10.0, + execute=True, + task_validator=lambda p, r: {"status": "passed", "validator_kind": "callback", "summary": "ok"}, + writeback=ok_noop, + spend=lambda *a, **k: {"ok": True, "appended": True, "receipt": {"status": "committed"}}, + scheduler=lambda *a, **k: {"ok": True, "acknowledged": True}, + quiet_turn=qt_cfg, + ) + assert r1["status"] == "failed" and r1["ok"] is False + assert admit_calls["n"] == 1 and host_calls["n"] == 1 + + # Turn 2 with identical digest executes cleanly (NOT skipped) and commits digest on settlement. + should_fail["flag"] = False + r2 = run_loopx_turn_once( + _plan("qt-ok-2"), + host_runner=fake_host, + admit_start=fake_admit, + project=project, + runtime_root=runtime, + goal_id="loopx-turn-fixture", + timeout_seconds=10.0, + execute=True, + task_validator=lambda p, r: {"status": "passed", "validator_kind": "callback", "summary": "ok"}, + writeback=ok_noop, + spend=lambda *a, **k: {"ok": True, "appended": True, "receipt": {"status": "committed"}}, + scheduler=lambda *a, **k: {"ok": True, "acknowledged": True}, + quiet_turn=qt_cfg, + ) + assert r2["ok"] is True + assert admit_calls["n"] == 2 and host_calls["n"] == 2 + + # Turn 3 with unchanged digest skips BEFORE admit_start() / host_runner and records durable skip receipt. + r3 = run_loopx_turn_once( + _plan("qt-skip-3"), + host_runner=fake_host, + admit_start=fake_admit, + project=project, + runtime_root=runtime, + goal_id="loopx-turn-fixture", + timeout_seconds=10.0, + execute=True, + task_validator=lambda p, r: {"status": "passed", "validator_kind": "callback", "summary": "ok"}, + writeback=ok_noop, + spend=lambda *a, **k: {"ok": True, "appended": True, "receipt": {"status": "committed"}}, + scheduler=lambda *a, **k: {"ok": True, "acknowledged": True}, + quiet_turn=qt_cfg, + ) + assert r3["status"] == "skipped" + assert admit_calls["n"] == 2 # admit_start skipped! + assert host_calls["n"] == 2 + tel = collect_context_policy_telemetry(runtime, goal_id="loopx-turn-fixture") + assert tel["quiet_turn_skips"] == 1 + + # Inject File vs SQLite conflict on quiet_turn_state -> must fail closed (state_changed=True, skipped=False). + goal_root = runtime / "goals" / "loopx-turn-fixture" + q_file = next((goal_root / "quiet_turn").glob("*.json")) + q_payload = json.loads(q_file.read_text(encoding="utf-8")) + q_payload["state_digest"] = "1" * 64 + q_file.write_text(json.dumps(q_payload), encoding="utf-8") + conflict = resolve_quiet_turn_metadata( + scope_key=q_payload["scope_key"], + file_path=q_file, + sqlite_path=goal_root / "turn_prefetch_state.sqlite", + enabled=True, + quiet_noop_allowed=True, + current_state_digest=digest, + record_if_changed=False, + ) + assert conflict["skipped"] is False + assert conflict["state_changed"] is True + assert conflict["reason"] == "state_conflict" + assert conflict["state_conflict"] is True + + +def test_committed_turn_replay_with_altered_epoch_prefetch_never_reexecutes_and_partial_page_keeps_raw( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, +) -> None: + import loopx.control_plane.turn_driver.epoch_prefetch as ep_mod + from loopx.control_plane.turn_driver.executor import run_loopx_turn_once + + project, runtime, registry = _write_live_fixture(tmp_path) + route = ["--registry", str(registry), "--runtime-root", str(runtime)] + probe_a = tmp_path / "probe_a.json" + probe_a.write_text( + json.dumps({"summary": "concise summary", "padding": "z" * 4000}), encoding="utf-8" + ) + probe_b = tmp_path / "probe_b.txt" + probe_b.write_text("completely different command probe", encoding="utf-8") + + # 1) Partial page (eof=false) via real context-read --page-bytes MUST fail closed to KeepRaw. + big_cap = tmp_path / "big_cap.json" + big_raw = json.dumps({"big": "b" * 16000}) + big_cap.write_text(big_raw, encoding="utf-8") + big_sha = hashlib.sha256(big_raw.encode("utf-8")).hexdigest() + partial_receipt = resolve_or_execute_epoch_prefetch( + epoch_prefetch={ + "enabled": True, + "prefetch_command": [ + sys.executable, + "-m", + "loopx.cli", + "--format", + "json", + "quota", + "context-read", + "--capture-file", + str(big_cap), + "--capture-sha256", + big_sha, + "--select", + "/big", + "--page-bytes", + "1600", + ], + "timeout_ms": 10000, + "max_output_bytes": 16384, + }, + scope_key="partial:eof:test", + context_epoch="epoch-partial-1", + file_store_dir=tmp_path / "ep_partial", + sqlite_path=tmp_path / "ep_partial.sqlite", + source_ref={"path": str(big_cap), "sha256": big_sha}, + baseline_bytes=len(big_raw.encode("utf-8")), + cwd=Path.cwd(), + ) + assert partial_receipt is not None + assert partial_receipt["operator"] == "KeepRaw" + assert partial_receipt["fallback_reason"] == "incomplete_output" + assert partial_receipt["truncated"] is True + assert partial_receipt["preserves_raw_state"] is True + assert partial_receipt["round_trips_saved"] == 0 + assert partial_receipt["bytes_saved"] == 0 + + # 2) Replay of committed Turn with ALTERED --epoch-prefetch-json NEVER re-executes prefetch_command. + c, plan = _invoke_cli( + route, + [ + "turn", + "plan", + "--goal-id", + "loopx-turn-fixture", + "--agent-id", + "codex-fixture", + "--turn-instance-id", + "replay-altered-1", + "--host", + "generic-cli", + "--execution-mode", + "isolated-headless", + "--scheduler-owner", + "outer_controller", + "--include-transaction-detail", + ], + ) + assert c == 0, plan + + calls = {"n": 0} + orig_runner = ep_mod.run_bounded_prefetch_subprocess + + def spy_runner(argv, *, timeout_ms, max_output_bytes, cwd=None): + calls["n"] += 1 + return orig_runner(argv, timeout_ms=timeout_ms, max_output_bytes=max_output_bytes, cwd=cwd) + + monkeypatch.setattr(ep_mod, "run_bounded_prefetch_subprocess", spy_runner) + + def ok_host(req: dict) -> dict: + return { + "schema_version": "loopx_turn_result_v0", + "turn_key": req["turn_key"], + "result_kind": "validated_progress", + "completed_phases": ["host_execute", "typed_result"], + "classification": "quiet_probe", + "recommended_action": "wait", + "next_action": "wait", + "delivery_batch_scale": "single_surface", + "delivery_outcome": "outcome_progress", + "vision_unchanged_reason": "Completed.", + "summary": "Committed.", + "work_evidence": ["artifact:committed"], + "validation_evidence": ["check:committed"], + } + + def ok_noop(*_args, **_kwargs) -> dict: + return {"ok": True, "appended": True, "classification": "quiet_probe", "recommended_action": "wait"} + + cfg_a = { + "enabled": True, + "context_epoch": "epoch-replay-lock", + "prefetch_command": ["cat", str(probe_a)], + "baseline_bytes": 16384, + "timeout_ms": 2000, + "max_output_bytes": 8192, + } + cfg_b = { + "enabled": True, + "context_epoch": "epoch-replay-lock", + "prefetch_command": ["cat", str(probe_b)], + "baseline_bytes": 16384, + "timeout_ms": 2000, + "max_output_bytes": 8192, + } + r1 = run_loopx_turn_once( + plan, + host_runner=ok_host, + project=project, + runtime_root=runtime, + goal_id="loopx-turn-fixture", + timeout_seconds=10.0, + execute=True, + task_validator=lambda p, r: {"status": "passed", "validator_kind": "callback", "summary": "ok"}, + writeback=ok_noop, + spend=lambda *a, **k: {"ok": True, "appended": True, "receipt": {"status": "committed"}}, + scheduler=lambda *a, **k: {"ok": True, "acknowledged": True}, + epoch_prefetch=cfg_a, + ) + assert calls["n"] == 1 + assert r1["epoch_prefetch"]["operator"] == "EpochReset" + r2 = run_loopx_turn_once( + plan, + host_runner=ok_host, + project=project, + runtime_root=runtime, + goal_id="loopx-turn-fixture", + timeout_seconds=10.0, + execute=True, + task_validator=lambda p, r: {"status": "passed", "validator_kind": "callback", "summary": "ok"}, + writeback=ok_noop, + spend=lambda *a, **k: {"ok": True, "appended": True, "receipt": {"status": "committed"}}, + scheduler=lambda *a, **k: {"ok": True, "acknowledged": True}, + epoch_prefetch=cfg_b, + ) + assert calls["n"] == 1 + assert r2["epoch_prefetch"]["receipt_sha256"] == r1["epoch_prefetch"]["receipt_sha256"] + + # Also prove CLI return_existing (--resume-turn-key on committed Turn) with altered --epoch-prefetch-json. + seen_log = tmp_path / "cli_seen.json" + runner, validator = _write_generic_host_and_validator(tmp_path, seen_log) + cli_args_a = [ + "turn", + "run-once", + "--goal-id", + "loopx-turn-fixture", + "--agent-id", + "codex-fixture", + "--turn-instance-id", + "cli-replay-altered", + "--host", + "generic-cli", + "--project", + str(project), + "--host-adapter-request-schema", + "loopx_turn_host_request_v1", + "--host-adapter-command-json", + json.dumps([sys.executable, str(runner)]), + "--validation-command-json", + json.dumps([sys.executable, str(validator)]), + "--epoch-prefetch-json", + json.dumps(cfg_a), + "--no-global-sync", + "--execute", + ] + c_a, first_cli = _invoke_cli(route, cli_args_a) + assert c_a == 0 and first_cli["status"] == "committed" + assert calls["n"] == 2 + cli_args_b = [ + arg + for idx, arg in enumerate(cli_args_a) + if arg not in {"--turn-instance-id", "cli-replay-altered", "--epoch-prefetch-json", json.dumps(cfg_a)} + and not (idx > 0 and cli_args_a[idx - 1] in {"--turn-instance-id", "--epoch-prefetch-json"}) + ] + ["--resume-turn-key", first_cli["resume_turn_key"], "--epoch-prefetch-json", json.dumps(cfg_b)] + c_b, replay_cli = _invoke_cli(route, cli_args_b) + assert c_b == 0 and replay_cli["replayed"] is True + assert calls["n"] == 2 # Altered cfg_b MUST NOT re-execute! + assert replay_cli["epoch_prefetch"]["executed"] is False + assert replay_cli["epoch_prefetch"]["replayed"] is True + assert replay_cli["epoch_prefetch"]["receipt_sha256"] == first_cli["epoch_prefetch"]["receipt_sha256"] diff --git a/tests/control_plane_ts/stage_then_swap_telemetry.test.ts b/tests/control_plane_ts/stage_then_swap_telemetry.test.ts index 6dad76deb1..312464bbd5 100644 --- a/tests/control_plane_ts/stage_then_swap_telemetry.test.ts +++ b/tests/control_plane_ts/stage_then_swap_telemetry.test.ts @@ -31,6 +31,13 @@ test('D8 safety admission enforces read-only allowlist and blocks passive plugin for (const unsafeCmd of [ 'git push origin main', + ['git', 'branch', 'evil-branch-created'], + ['git', 'branch', '--track', 'evil', 'main'], + ['git', 'branch', '-u', 'origin/main'], + ['git', 'log', '--output=/tmp/evil-log.txt', '-n', '1'], + ['git', 'diff', '--output', '/tmp/evil-diff.txt'], + ['git', 'show', '--output=/tmp/evil-show.txt', 'HEAD'], + ['git', 'diff', '--ext-diff'], 'rm -rf /tmp/something', 'bash -c "cat foo"', 'cat a.txt && echo hi', @@ -47,6 +54,9 @@ test('D8 safety admission enforces read-only allowlist and blocks passive plugin for (const safeCmd of [ ['loopx', 'quota', 'context-read', '--capture-file', 'dec.json', '--capture-sha256', 'a'.repeat(64), '--select', '/summary'], ['git', 'status'], + ['git', 'branch'], + ['git', 'branch', '--list'], + ['git', 'branch', '--show-current'], ['cat', 'notes.md'], ['head', '-n', '20', 'notes.md'], ['find', '.', '-maxdepth', '2'], @@ -165,6 +175,24 @@ test('failed, timed-out, policy-denied, truncated-strict, or negative-savings pr }); assert.equal(negativeSavings.operator, 'KeepRaw'); assert.equal(negativeSavings.fallback_reason, 'negative_net_savings'); + + const incompletePage = evaluateEpochPrefetchSwap({ + ...base, + exit_code: 0, + truncated: false, + prefetched_output: JSON.stringify({ + ok: true, + schema_version: 'context_capture_page_v1', + eof: false, + content: 'partial-page', + }), + }); + assert.equal(incompletePage.operator, 'KeepRaw'); + assert.equal(incompletePage.fallback_reason, 'incomplete_output'); + assert.equal(incompletePage.truncated, true); + assert.equal(incompletePage.preserves_raw_state, true); + assert.equal(incompletePage.round_trips_saved, 0); + assert.equal(incompletePage.bytes_saved, 0); }); test('native lifecycle keeps epoch_prefetch across idempotent PostCompact and clears on new epoch rotation', () => { @@ -231,6 +259,8 @@ test('trajectory usage telemetry tracks operator counts, prefetch latency/bytes, {type: 'event_msg', payload: {type: 'task_started', turn_id: 't1'}}, {type: 'event_msg', payload: {type: 'token_count', info: {total_token_usage: usage(100, 0, 10), last_token_usage: usage(100, 0, 10)}}}, {type: 'event_msg', payload: {type: 'token_count', info: {total_token_usage: usage(220, 90, 20), last_token_usage: usage(120, 90, 10)}}}, + {type: 'compacted', payload: {reason: 'epoch_reset'}}, + {type: 'event_msg', payload: {type: 'token_count', info: {total_token_usage: usage(300, 130, 25), last_token_usage: usage(80, 40, 5)}}}, {type: 'event_msg', payload: {type: 'task_complete', turn_id: 't1'}}, ].map((item, idx) => ({...item, line: idx + 1, timestamp: `2026-11-21T00:00:0${idx}Z`})); @@ -255,6 +285,7 @@ test('trajectory usage telemetry tracks operator counts, prefetch latency/bytes, assert.equal(tel.prefetch.output_bytes, 180); assert.equal(tel.prefetch.bytes_saved, 2400); assert.equal(tel.prefetch.round_trips_saved, 1); - assert.deepEqual(tel.prefix_kv?.cold, {requests: 1, uncached_prefix_kv_tokens: 100, cached_prefix_kv_tokens: 0}); + // Request 1 (100/0) and post-compacted Request 3 (80/40) both bucket cold; Request 2 (120/90) buckets warm. + assert.deepEqual(tel.prefix_kv?.cold, {requests: 2, uncached_prefix_kv_tokens: 140, cached_prefix_kv_tokens: 40}); assert.deepEqual(tel.prefix_kv?.warm, {requests: 1, uncached_prefix_kv_tokens: 30, cached_prefix_kv_tokens: 90}); }); From 22e1d110a89f8d1995252deb1459fb72af9106a0 Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Sun, 22 Nov 2026 02:39:03 +0800 Subject: [PATCH 3/3] fix(turn-driver): close r3 in-flight journal settlement, git -O flag, and prefix KV telemetry gaps Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- benchmark/runtime/session_observation.py | 62 ++++--- loopx/control_plane/quota/stage_then_swap.ts | 1 + loopx/control_plane/turn_driver/executor.py | 16 +- .../test_stage_then_swap_quiet_turn.py | 160 ++++++++++++++++++ .../stage_then_swap_telemetry.test.ts | 6 + 5 files changed, 217 insertions(+), 28 deletions(-) diff --git a/benchmark/runtime/session_observation.py b/benchmark/runtime/session_observation.py index facd4c6ffa..0186bf7f44 100644 --- a/benchmark/runtime/session_observation.py +++ b/benchmark/runtime/session_observation.py @@ -304,28 +304,46 @@ def _consume_quiet(entry: object, dedup_key: str | None = None) -> None: cold = {"requests": 0, "uncached_prefix_kv_tokens": 0, "cached_prefix_kv_tokens": 0} warm = {"requests": 0, "uncached_prefix_kv_tokens": 0, "cached_prefix_kv_tokens": 0} if isinstance(usage, dict): - coverage = usage.get("request_coverage") - requests = coverage.get("requests") if isinstance(coverage, dict) else None - if isinstance(requests, list): - for req in requests: - if not isinstance(req, dict): - continue - inp = req.get("input_tokens") - cached = req.get("cached_input_tokens") - if not isinstance(inp, int) or not isinstance(cached, int) or inp < cached: - continue - uncached = inp - cached - bucket = cold if (cached == 0 or req.get("cache_regime") == "cold") else warm - bucket["requests"] += 1 - bucket["uncached_prefix_kv_tokens"] += uncached - bucket["cached_prefix_kv_tokens"] += cached - elif isinstance(usage.get("input_tokens"), int) and isinstance(usage.get("cached_input_tokens"), int): - cached = usage["cached_input_tokens"] - uncached = max(0, usage["input_tokens"] - cached) - bucket = cold if cached == 0 else warm - bucket["requests"] = int(usage.get("completed_turns") or 1) - bucket["uncached_prefix_kv_tokens"] = uncached - bucket["cached_prefix_kv_tokens"] = cached + embedded = usage.get("context_policy_telemetry") + embedded_kv = embedded.get("prefix_kv") if isinstance(embedded, dict) else None + if ( + isinstance(embedded_kv, dict) + and isinstance(embedded_kv.get("cold"), dict) + and isinstance(embedded_kv.get("warm"), dict) + ): + for dst, src in ((cold, embedded_kv["cold"]), (warm, embedded_kv["warm"])): + for key in ("requests", "uncached_prefix_kv_tokens", "cached_prefix_kv_tokens"): + val = src.get(key) + if isinstance(val, int) and not isinstance(val, bool) and val >= 0: + dst[key] = val + else: + coverage = usage.get("request_coverage") + requests = coverage.get("requests") if isinstance(coverage, dict) else None + if isinstance(requests, list): + for req in requests: + if not isinstance(req, dict): + continue + inp = req.get("input_tokens") + cached = req.get("cached_input_tokens") + if not isinstance(inp, int) or not isinstance(cached, int) or inp < cached: + continue + uncached = inp - cached + is_cold = ( + cached == 0 + or req.get("cache_regime") == "cold" + or req.get("compacted") is True + ) + bucket = cold if is_cold else warm + bucket["requests"] += 1 + bucket["uncached_prefix_kv_tokens"] += uncached + bucket["cached_prefix_kv_tokens"] += cached + elif isinstance(usage.get("input_tokens"), int) and isinstance(usage.get("cached_input_tokens"), int): + cached = usage["cached_input_tokens"] + uncached = max(0, usage["input_tokens"] - cached) + bucket = cold if cached == 0 else warm + bucket["requests"] = int(usage.get("completed_turns") or 1) + bucket["uncached_prefix_kv_tokens"] = uncached + bucket["cached_prefix_kv_tokens"] = cached return { "schema_version": "loopx_context_policy_telemetry_v0", diff --git a/loopx/control_plane/quota/stage_then_swap.ts b/loopx/control_plane/quota/stage_then_swap.ts index f6c606cc2e..b000ee20e0 100644 --- a/loopx/control_plane/quota/stage_then_swap.ts +++ b/loopx/control_plane/quota/stage_then_swap.ts @@ -351,6 +351,7 @@ export function validatePrefetchCommandSafety(params: { gitSubArgs.some( (flag) => GIT_FORBIDDEN_OUTPUT_FLAGS.has(flag) + || flag.startsWith("-O") || flag.startsWith("--output=") || flag.startsWith("--ext-diff=") || flag.startsWith("--open-files-in-pager=") diff --git a/loopx/control_plane/turn_driver/executor.py b/loopx/control_plane/turn_driver/executor.py index edc6065f26..47e9763a22 100644 --- a/loopx/control_plane/turn_driver/executor.py +++ b/loopx/control_plane/turn_driver/executor.py @@ -1802,12 +1802,16 @@ def persist_source_journal(source_admission: Mapping[str, Any]) -> None: plan, {"status": "unavailable", "host": host_projection, "reason": reason}, execute=True, replayed=False, effects=empty_effects, ) - if (quiet_skip_payload := maybe_skip_quiet_turn_before_admission( - plan=plan, journal_path=journal_path, goal_id=goal_id, turn_key=turn_key, - settlement_lineage=settlement_lineage, host_projection=host_projection, - empty_effects=empty_effects, payload_builder=execution_payload, - options={"epoch_prefetch": epoch_prefetch, "quiet_turn": quiet_turn, "decision_capture_payload": decision_capture_payload}, - )) is not None: + if ( + journal is None + and needs_host + and (quiet_skip_payload := maybe_skip_quiet_turn_before_admission( + plan=plan, journal_path=journal_path, goal_id=goal_id, turn_key=turn_key, + settlement_lineage=settlement_lineage, host_projection=host_projection, + empty_effects=empty_effects, payload_builder=execution_payload, + options={"epoch_prefetch": epoch_prefetch, "quiet_turn": quiet_turn, "decision_capture_payload": decision_capture_payload}, + )) is not None + ): return quiet_skip_payload capture = stage_turn_decision_capture( journal["plan"] if journal is not None else plan, journal_path=journal_path, diff --git a/tests/control_plane/test_stage_then_swap_quiet_turn.py b/tests/control_plane/test_stage_then_swap_quiet_turn.py index 30a3aa2715..00563a3b48 100644 --- a/tests/control_plane/test_stage_then_swap_quiet_turn.py +++ b/tests/control_plane/test_stage_then_swap_quiet_turn.py @@ -1105,3 +1105,163 @@ def ok_noop(*_args, **_kwargs) -> dict: assert replay_cli["epoch_prefetch"]["executed"] is False assert replay_cli["epoch_prefetch"]["replayed"] is True assert replay_cli["epoch_prefetch"]["receipt_sha256"] == first_cli["epoch_prefetch"]["receipt_sha256"] + + +def test_inflight_quiet_turn_settlement_recovery_after_spend_failure_never_skips( + tmp_path: Path, +) -> None: + from loopx.control_plane.turn_driver.epoch_prefetch import commit_quiet_turn_state + from loopx.control_plane.turn_driver.executor import run_loopx_turn_once + + project, runtime, registry = _write_live_fixture(tmp_path) + route = ["--registry", str(registry), "--runtime-root", str(runtime)] + c, plan = _invoke_cli( + route, + [ + "turn", + "plan", + "--goal-id", + "loopx-turn-fixture", + "--agent-id", + "codex-fixture", + "--turn-instance-id", + "qt-inflight-settle", + "--host", + "generic-cli", + "--execution-mode", + "isolated-headless", + "--scheduler-owner", + "outer_controller", + "--include-transaction-detail", + ], + ) + assert c == 0, plan + + digest = hashlib.sha256(b"same-digest-after-host").hexdigest() + qt_cfg = { + "enabled": True, + "quiet_noop_allowed": True, + "current_state_digest": digest, + } + scope_key = "turn_driver:loopx-turn-fixture:codex-fixture" + goal_root = runtime / "goals" / "loopx-turn-fixture" + host_calls = {"n": 0} + spend_calls = {"n": 0} + + def fake_host(req: dict) -> dict: + host_calls["n"] += 1 + return { + "schema_version": "loopx_turn_result_v0", + "turn_key": req["turn_key"], + "result_kind": "validated_progress", + "completed_phases": ["host_execute", "typed_result"], + "classification": "quiet_probe", + "recommended_action": "wait", + "next_action": "wait", + "delivery_batch_scale": "single_surface", + "delivery_outcome": "outcome_progress", + "vision_unchanged_reason": "Unchanged state.", + "summary": "Host completed before transient spend error.", + "work_evidence": ["artifact:inflight"], + "validation_evidence": ["check:inflight"], + } + + def ok_noop(*_a: object, **_k: object) -> dict[str, object]: + return {"ok": True, "appended": True, "classification": "quiet_probe", "recommended_action": "wait"} + + def flaky_spend(*_a: object, **_k: object) -> dict[str, object]: + spend_calls["n"] += 1 + if spend_calls["n"] == 1: + raise RuntimeError("transient spend interruption") + return {"ok": True, "appended": True, "receipt": {"status": "committed"}} + + with pytest.raises(RuntimeError, match="transient spend interruption"): + run_loopx_turn_once( + plan, + host_runner=fake_host, + project=project, + runtime_root=runtime, + goal_id="loopx-turn-fixture", + timeout_seconds=10.0, + execute=True, + task_validator=lambda p, r: {"status": "passed", "validator_kind": "callback", "summary": "ok"}, + writeback=ok_noop, + spend=flaky_spend, + scheduler=lambda *a, **k: {"ok": True, "acknowledged": True, "completed": True}, + quiet_turn=qt_cfg, + ) + assert host_calls["n"] == 1 + assert spend_calls["n"] == 1 + + # Even if quiet_turn_state already records the exact same state_digest on disk + # while this Turn's journal sits in flight waiting on settlement (needs_host=False), + # resuming the in-flight journal MUST finish spend() instead of skipping! + commit_quiet_turn_state( + scope_key=scope_key, + file_path=goal_root / "quiet_turn" / f"{hashlib.sha256(scope_key.encode()).hexdigest()}.json", + sqlite_path=goal_root / "turn_prefetch_state.sqlite", + state_digest=digest, + metadata={"enabled": True}, + ) + r2 = run_loopx_turn_once( + plan, + host_runner=fake_host, + project=project, + runtime_root=runtime, + goal_id="loopx-turn-fixture", + timeout_seconds=10.0, + execute=True, + task_validator=lambda p, r: {"status": "passed", "validator_kind": "callback", "summary": "ok"}, + writeback=ok_noop, + spend=flaky_spend, + spend_resolver=lambda _ref: {"kind": "absent"}, + scheduler=lambda *a, **k: {"ok": True, "acknowledged": True, "completed": True}, + quiet_turn=qt_cfg, + ) + assert host_calls["n"] == 1 + assert spend_calls["n"] == 2 + assert r2["status"] == "committed" and r2["ok"] is True + tel = collect_context_policy_telemetry(runtime, goal_id="loopx-turn-fixture") + assert tel["quiet_turn_skips"] == 0 + + +def test_collect_context_policy_telemetry_prefers_usage_prefix_kv_and_compacted_cold( + tmp_path: Path, +) -> None: + runtime = tmp_path / "runtime" + (runtime / "goals" / "g1").mkdir(parents=True) + # 1) Prefers usage["context_policy_telemetry"]["prefix_kv"] over flat/request fallback + usage_with_cpt = { + "context_policy_telemetry": { + "prefix_kv": { + "cold": {"requests": 2, "uncached_prefix_kv_tokens": 500, "cached_prefix_kv_tokens": 100}, + "warm": {"requests": 3, "uncached_prefix_kv_tokens": 90, "cached_prefix_kv_tokens": 900}, + } + }, + "request_coverage": { + "requests": [{"input_tokens": 100, "cached_input_tokens": 80}], + }, + } + tel = collect_context_policy_telemetry(runtime, goal_id="g1", usage=usage_with_cpt) + assert tel["prefix_kv"] == usage_with_cpt["context_policy_telemetry"]["prefix_kv"] + + # 2) Fallback on request_coverage classifies compacted=True as cold even when cached_input_tokens > 0 + usage_requests = { + "request_coverage": { + "requests": [ + {"input_tokens": 200, "cached_input_tokens": 150, "compacted": True}, + {"input_tokens": 120, "cached_input_tokens": 90, "compacted": False}, + ] + } + } + tel2 = collect_context_policy_telemetry(runtime, goal_id="g1", usage=usage_requests) + assert tel2["prefix_kv"]["cold"] == { + "requests": 1, + "uncached_prefix_kv_tokens": 50, + "cached_prefix_kv_tokens": 150, + } + assert tel2["prefix_kv"]["warm"] == { + "requests": 1, + "uncached_prefix_kv_tokens": 30, + "cached_prefix_kv_tokens": 90, + } diff --git a/tests/control_plane_ts/stage_then_swap_telemetry.test.ts b/tests/control_plane_ts/stage_then_swap_telemetry.test.ts index 312464bbd5..913d058c92 100644 --- a/tests/control_plane_ts/stage_then_swap_telemetry.test.ts +++ b/tests/control_plane_ts/stage_then_swap_telemetry.test.ts @@ -289,3 +289,9 @@ test('trajectory usage telemetry tracks operator counts, prefetch latency/bytes, assert.deepEqual(tel.prefix_kv?.cold, {requests: 2, uncached_prefix_kv_tokens: 140, cached_prefix_kv_tokens: 40}); assert.deepEqual(tel.prefix_kv?.warm, {requests: 1, uncached_prefix_kv_tokens: 30, cached_prefix_kv_tokens: 90}); }); + +test("D8 safety admission rejects attached -O flag on git grep", () => { + const attached = validatePrefetchCommandSafety({prefetch_command: ["git", "grep", "-Otouch /tmp/git-grep-o-poc", "loopx"]}); + assert.equal(attached.allowed, false); + assert.equal(attached.reason, "policy_violation:git_output_or_external_diff_forbidden"); +});