Long-running work accumulates material: the original goal, later constraints, attempted routes, failed experiments and current progress. Sending everything again on each continuation repeats more and more content; keeping only a summary can make the original basis of a decision difficult to recover.
Long-running work accumulates material: the original goal, later constraints, attempted routes, failed experiments and current progress. Sending everything again on each continuation repeats more and more content; keeping only a summary can make the original basis of a decision difficult to recover.
LoopX's context delivery separates these jobs: preserve complete sources, read the facts needed for the current decision, expand supporting material around questions, and reuse unchanged structures exactly within a valid compaction cycle.
-
This article describes the native Codex path in released LoopX 2.2.0. Supported POSIX Codex App/SSH sessions and new benchmark heartbeat trials default to context delivery; saved off remains effective and explicit off is available. When enabled, complete content is saved first and the Agent receives a reading entrypoint for current facts. See the 2.2.0 release notes for publication and validation scope. The synthetic measurements below retain their original source and experimental conditions.
-
Think of a capture as a complete book. An index locates its chapters; a JSON Pointer addresses a place inside it. Progressive reading determines how deeply to open the material now. Differential delivery determines what can be reused on the next continuation.
+
The core native Codex path ships in LoopX 2.2.0. Supported POSIX Codex App/SSH sessions and new benchmark heartbeat trials default to context delivery; saved off remains effective and explicit off is available. When enabled, complete content is saved first and the Agent receives a reading entrypoint for current facts. See the 2.2.0 release notes for publication and validation scope.
+
Think of a capture as a complete saved snapshot, like a book whose edition is fixed. An index locates its chapters; a JSON Pointer addresses a place inside it. Progressive reading determines how deeply to open the material now. Differential delivery determines what can be reused on the next continuation.
+
This November 8 revision also follows the first-read, staged-scope, transport and numeric-fidelity changes merged after 2.2.0, checked at source 611019243e. Those sections describe that source snapshot, not an upgrade already installed everywhere. The original teaching measurements and archived research results below retain their earlier versions and conditions.
Follow one task: give an assistant voice input
Suppose an assistant needs to understand a voice note and reply in its original chat. Its complete material contains the goal, provider constraints, privacy requirements, acceptance and a long discussion of alternatives. This is a teaching example; the example program below generates the complete data in an isolated directory.
capture.json
@@ -114,6 +115,9 @@
See requirements first, then open their evidence
The implementation returns supporting_material_pointer, locating the outcome in the original capture. Call that returned prefix $P: append /requirements/2/agent_review/note for the explanation, or /requirements/2/agent_review/evidence_refs for evidence references. Use this capture's prefix rather than copying an array position from another file.
After assembling the voice task into the existing typed acceptance structure, its complete original capture is 57,014 bytes and necessary view 5,107 bytes. All 10 requirement descriptions remain complete, together with unmet/stale/independent-verification facts. The original 57,014 bytes also remain intact. Supporting history and long explanations have exact expansion addresses.
Relationship navigation can suggest which outcomes to inspect first using task dependencies, shared acceptance, sources and evidence. Incomplete relationships widen scope, and contrary evidence from other routes stays accessible. Navigation helps order reading; the Agent still determines what affects this decision.
+
Read scope before the decision that depends on it
+
The voice integration also has a timing question: when must the Agent inspect every allowed write path? In the November source, selection and ordinary claim preparation can replace a long write_scope list with an exact expansion address in the original capture. Stops and approval requirements remain directly visible. If choosing the speech adapter depends on whether its files may be edited, the Agent must open that scope before choosing. The ready decision supplies the complete current scope; claiming the task still checks ownership and scope atomically.
+
This changes when detail is read. It neither grants permission nor removes a required check. The regression uses 220 synthetic paths to exercise a long scope list; that is a stress fixture, not 220 product rules. Reading the list adds a call when it is needed, and the ready-stage list remains complete. Scope change and validation · checked implementation.
Share exact records within one delivery
A task can appear in both current work and a queue summary. Repeating an identical complete record adds no fact.
The native necessary view can retain one complete task and reference it elsewhere:
@@ -188,9 +192,36 @@
When enabled, the default output is a reading entrypoint
A continuation reference pins its selection: follow its next_command to EOF and return to the original recovery reference to change Pointers. Very small budgets may retain the explicit file/digest interface. The teaching measurements above use that compatible interface and retain their original conditions.
+
The first response has to arrive complete
+
A short command can return a large response. For the voice task, the first read must deliver the current decision, required reads and a way to continue. If the tool truncates the response, the Agent can lose the instruction for recovering the missing material as well.
+
The November source therefore budgets the complete serialized JSON response in UTF-8 bytes, including quoting, page metadata and navigation. --page-bytes limits content bytes; --max-page-output-bytes limits the whole response. With no explicit output budget, generated linked first reads and attached native context-project --initial-read pages use a 12,000-byte fallback. Ordinary bulk/recovery readers and the saved task-selection recipe retain their existing budgets.
+
When the complete starting selection needs multiple pages, the attached reader tries an independently complete opening containing the decision and read obligations. It uses that opening only if the entire response fits; the rest stays required through remaining_read_command and its page cursors. A cursor is the returned byte offset for continuing the same selection. If the opening cannot fit, ordinary same-capture pagination remains available. For a missing or unwritable context store, recovery likewise retains the original capture.
+
# Explicit budgets on a current returned reader reference:
+loopx --format json quota context-read \
+ --reference-file "$RECOVERY_READER_REFERENCE" \
+ --select "$POINTER_A" --select "$POINTER_B" \
+ --page-bytes 12000 --max-page-output-bytes 12000
+
+
These two limits can have the same value while the returned content is smaller: framing takes space too. Twelve thousand bytes is a fallback for an unknown tool boundary, not a universal optimum or a guarantee that the host retains those bytes in later model input. Smaller pages may require more calls and repeated framing. After truncation, recover the affected range from the same capture with a suitable explicit budget; do not repeat task admission or external work. First-read change and validation · checked reader.
What was saved, and what the model has read
The delta codec answers: can the verified old file reconstruct the exact current file? The native captured_file path verifies the complete saved baseline, version and scope. It does not require the model to have read the old file, reached a selected page’s EOF or sent an ACK. Each baseline is itself a complete version, so the model need not replay a chain of deltas first.
Progressive reading answers a different question: which facts does this decision need? In the voice illustration, suppose the next continuation adds sample 3 while the privacy constraint remains unchanged. Consider a missed-read counterexample: the Agent skipped the required privacy constraint, or can no longer establish it after compaction. Before sending audio externally, it must recover /goal/constraints through the current entrypoint and honor the existing authorization boundary. It can read that fact directly, without first draining the old baseline. A saved file or an unchanged field does not replace the necessary read.
+
Count the trips and the copies, too
+
Some delivery cost occurs before the model sees anything. The Python CLI asks the TypeScript owner to prepare a view and receives its response. Each such request and reply is a local process round trip, also called an internal RPC. A CLI command can make several of these trips.
+
For an already verified saved capture, the November source can return the first selection directly with progressive delivery on and cycle deltas off. The selection already names the needed facts; precomputing a root index first adds an unnecessary trip. Review, writeback instructions and recovery still point to the same original decision.
+
The author’s fixed synthetic SQLite sequence in #8298 covers the first selection, review and writeback-contract reads. Its report at 775394bd8d, integrated with 94b91e48aa, records:
+
+
Measure
Before
After
+
+
CLI calls
4
3
+
Internal RPCs
5
4
+
RPC transport
326,204 B
271,741 B
+
Selected first-read content
8,046 B
8,046 B
+
Complete CLI stdout
32,846 B
33,060 B
+
+
One fewer command did not make every layer smaller. The selected content was unchanged, and navigation made stdout slightly larger. These are the author’s process measurements, not a new performance run on this article’s source snapshot or a model-token result.
+
A second duplication occurred inside a response: full native delivery sent the same projected body as both typed edits and delivery.context. The producer now sends it once across the Effect bridge, and the Python adapter reconstructs the ordinary full shape. Delta still carries its own edits. In #8285’s author record, the affected SQLite response fell from 53,999 to 38,225 B; the sequence including the guard, native hook, a rejected hash and same-capture retry fell from 1,021,975 to 1,006,203 B. Stage outputs and call counts matched. Producer · adapter.
+
Both changes remove repeated transport while retaining the task’s requirements. Their end-to-end value still depends on later reads, recovery, actual model input and cache use, output, elapsed time and accepted work. Local wire bytes cannot stand in for those costs.
Recover missing context while preserving the original work
After host compaction, a subsequent work Turn builds a new complete baseline. Original goals, requirements and sources remain available for necessary reads.
If compaction, missing pages or truncated output interrupt an unfinished Turn, recover missing facts from its original capture while retaining task, effect and settlement identity. If a voice result was already sent but its receipt was lost, recovering context must not become sending the result again.
@@ -201,6 +232,9 @@
Recover missing context while preserving the original work
Paged content: follow next_command with capture digest, selection digest and byte cursor; combine contiguous content in order. Selection EOF covers only that selection.
Unknown or inapplicable structures: retain complete content and original read obligations rather than guessing which prose can be hidden.
+
A shorter view must preserve the original values
+
File integrity alone does not guarantee that every projected value survived a language boundary. A staged read reproduced in November turned the integer 9007199254740993 into 9007199254740992. Two distinct acceptance records could then appear identical and share one reference. The raw capture could remain unchanged while the returned facts were wrong.
+
The saved native path now avoids an unnecessary replan projection for ordinary decisions and applies presentation edits to original source values when replanning is needed. The staged replan reader likewise restores original numbers, preserving integers, integral floats and negative zero. Distinct records get distinct references; an ambiguous historical reference is rejected with a route back to review, while an unambiguous one still resolves. Explicit page windows also reach the saved reader through its existing validation. These are correctness and recovery changes merged in #8319 and #8324, with synthetic public-CLI regressions; they do not establish model comprehension or task-level savings.
Continuity and recovery
One valid cycle: complete baseline → changed facts and delta → exact reconstruction.
New cycle or known continuity loss: complete current source → read necessary facts again.
An unfinished Turn retains its original capture, work and settlement identity. Reading recovery does not repeat external effects.
What the measurements establish
The example separates three mechanisms: avoid repeatedly moving history not currently needed, combine reads that belong together, and avoid retransmitting unchanged verified structures. Complete sources, requirements and recovery connect them.
@@ -226,12 +260,12 @@
Multi-task and layered ablation: benefit chain and bo
ANN 18h: Explore · Context off
5,766 QPS (+0.2%)
-
Peaked at 11.37h; repeated full-context delivery consumed main-session budget
+
Peaked at 11.37h; input accounting is reported separately below
ANN 18h: Explore · Context on
6,020 QPS (+4.6%)
-
Peaked at 14.43h; progressive reads and cycle deltas preserved late-stage headroom
+
Peaked at 14.43h; this run's later peak does not isolate the cause
ANN 18h: Explore · Context on + Stride
@@ -256,7 +290,7 @@
Multi-task and layered ablation: benefit chain and bo
Initial baseline establishment and staged discovery add upfront overhead that only amortizes over longer horizons
+
Baseline establishment and staged discovery add upfront work; later amortization is not guaranteed by this early window
Counterexample 3: Historical Grid (lower is better)
@@ -265,7 +299,7 @@
Multi-task and layered ablation: benefit chain and bo
-
This dual-track audit shows why control-packet byte reduction (−74.25% / −38.54%) must not be equated with whole-episode model token savings (−12.07% uncached, −7.46% total), nor used to hide early-window indexing overhead (4.05× in the first 2 hours) or cross-task counterexamples. Context Delivery’s practical value lies in slowing context bloat across 10–18 hour runs so that, together with Stride, preserved attention converts into effective late-stage experiments (see EdgeBench late-stage breakthroughs and five-arm attribution).
+
This dual-track audit shows why control-packet byte reduction (−74.25% / −38.54%) must not be equated with whole-episode model token savings (−12.07% uncached, −7.46% total), nor used to hide early-window indexing overhead (4.05× in the first 2 hours) or cross-task counterexamples. The reported ANN runs contain both lower input totals and later useful experiments. That observation motivates testing whether context delivery helps sustain long research, but does not by itself attribute the outcome to saved attention, separate every interaction with Stride, or establish a gain on another task. The November source changes above were not treatments in these archived runs. See EdgeBench late-stage breakthroughs and five-arm attribution for the original research context.
2.2.0 ships complete sources, file entrypoints, batch selection, index depth, applicable acceptance layering, exact sharing, cycle deltas and recovery. Broader decision-stage candidate, preference and Explore delivery and consistency across all entrypoints remain unfinished. Disable in Settings → This machine → Capabilities → Differential context → Codex; saved off survives upgrade. A command or new benchmark trial can use --context-delivery off. Trials do not inherit the machine switch, and existing frozen trials are not rewritten. Under the default policy, ordinary CLI, unsupported hosts and non-heartbeat benchmarks retain their full paths; an explicit unsupported on request is rejected. Unavailable hooks use full delivery. Saving configuration, actual installation and model adoption remain separate checks.
Read the same material yourself
example.py generates this complete synthetic voice task and invokes the existing reader, progressive projection and delta owners. It checks selected values, directory addresses, all ten requirements, shared references and complete recovery. It registers no Goal, admits or settles no Turn, and calls no model or speech service.
One voice task explains JSON Pointers, batched selection, index depth, complete requirements, exact sharing and compaction-cycle deltas, paired with ANN 18h (7,159 vs 5,753 QPS) layered byte/token ablations and early-window/cross-task counterexamples.
One voice task explains progressive reads, complete first responses, scope checks, exact reuse and recovery. Follow the process costs separately from archived ANN results and their early-window and cross-task counterexamples.
