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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions docs/reference/required-work-context.md
Original file line number Diff line number Diff line change
Expand Up @@ -331,13 +331,13 @@ large for one page, the linked remainder contains its full details and the
suggested alternatives. The selection commands use the original Turn identity.

Native ready decisions from `quota should-run` and saved `quota context-project`
can link two reads when boundary detail pushes controls past the serialized
can link two reads when Goal or Todo scope details push controls past the serialized
first page budget. When those controls fit, the ordinary reader keeps its cursor.
Read `first_read_command` for the decision, stop conditions and required reads.
If `remaining_read_command` is present,
follow it and its cursor before work, even when the opening reports EOF. It
starts with the complete current write scope and any checkpointed approval
entries. The opening shows the current approval counts and active scope summary.
If `remaining_read_command` is present, follow it and its cursor before work,
even when the opening reports EOF. The remainder supplies deferred Goal write
scopes, checkpointed approval entries and the selected Todo's requested write
scopes. The opening shows the current approval counts and active scope summary.
The remainder can refer to other fully observed, unchanged fields. If the
observation is lost, its same-capture fallback restores the full remainder.

Expand Down Expand Up @@ -372,8 +372,8 @@ presentation changes neither admission nor the explicit off view.
控制信息超出序列化后的首页预算,导航可给出两段读取。控制信息能放进首页时,沿用普通游标。
先用 `first_read_command` 取得决策、停止条件和必读项。如果给出
`remaining_read_command`,即使首段已到 EOF,也要在开工前沿该命令及其游标读完。
续读从完整的当前写入范围和已记录的审批条目开始,两段绑定同一份捕获。首段保留当前审批
数量和生效范围摘要。
续读提供延后交付的 Goal 写入范围、已记录的审批条目及选中 Todo 的请求写入范围。
两段绑定同一份捕获。首段保留当前审批数量和生效范围摘要。
续读可引用其他已完整送达且未变化的字段。观察失效时,从同一捕获恢复完整续段。

准入检查要求先切换到独立工作树时,首读保留迁移指引和当前决策控制信息。
Expand Down
63 changes: 42 additions & 21 deletions loopx/control_plane/quota/progressive_context.ts
Original file line number Diff line number Diff line change
Expand Up @@ -763,8 +763,10 @@ export function prepareProgressiveContext(request: JsonObject, plan?: JsonObject
return contextProjectionChanges(source, {context: required.context, projected: required.projected}, values, undefined, true);
}

type InitialOpeningSplit = {controls: Map<string, string[]>; details: string[]; linkedDetail: string};

function prepareInitialOpening(context: JsonObject, groups: ReturnType<typeof initialContextReadGroups>,
scope?: Path): {boundary: string; detail: string; controls: string[]; checkpointEntries?: string} | undefined {
scope?: Path): InitialOpeningSplit | undefined {
const cli = jsonObject(jsonObject(context.interaction_contract)?.cli_channel);
const candidate = "/selected_todo";
if (cli?.selection_required === true && groups.opening.includes(candidate)) {
Expand All @@ -777,31 +779,50 @@ function prepareInitialOpening(context: JsonObject, groups: ReturnType<typeof in
const index = groups.remaining.indexOf(control);
if (index >= 0) groups.opening.push(...groups.remaining.splice(index, 1));
}
return {boundary: candidate, detail: candidate, controls: []};
return {controls: new Map([[candidate, []]]), details: [candidate], linkedDetail: candidate};
}
if (!scope) return undefined;
const parent = scope.slice(0, -1), detail = scope.at(-1)!;
const body = jsonObject(at(context, parent)), boundary = pointer(parent);
if (!groups.opening.includes(boundary) || !body
|| !Array.isArray(body[detail]) || !body[detail].length) return undefined;
const controls = new Map<string, string[]>();
const details: string[] = [];
let linkedDetail: string | undefined;
if (groups.opening.includes(boundary) && body && Array.isArray(body[detail]) && body[detail].length) {
const boundaryControls = Object.keys(body).filter(key => key !== detail).map(key => pointer([...parent, key]));
linkedDetail = pointer(scope);
details.push(linkedDetail);
controls.set(boundary, boundaryControls);
const checkpointPath = [...parent, "checkpointed_boundary_authority"];
const checkpoint = jsonObject(at(context, checkpointPath));
if (checkpoint?.schema_version === "checkpointed_boundary_authority_v0"
&& Array.isArray(checkpoint.active_write_scope) && Number.isSafeInteger(checkpoint.active_count)
&& Number.isSafeInteger(checkpoint.inactive_count) && Array.isArray(checkpoint.entries)
&& checkpoint.entries.length) {
// Keep the current approval summary in the opening. Read the exact
// entries and write scope from the same capture before work.
const checkpointIndex = boundaryControls.indexOf(pointer(checkpointPath));
boundaryControls.splice(checkpointIndex, 1, ...Object.keys(checkpoint).filter(key => key !== "entries")
.map(key => pointer([...checkpointPath, key])));
details.push(pointer([...checkpointPath, "entries"]));
}
}
const selected = jsonObject(context.selected_todo), requested = "required_write_scopes";
const scopes = selected?.[requested];
if (groups.opening.includes(candidate) && selected?.schema_version === "quota_selected_todo_v0"
&& Array.isArray(scopes) && scopes.length && scopes.every(value => typeof value === "string" && value)) {
controls.set(candidate, Object.keys(selected).filter(key => key !== requested)
.map(key => pointer(["selected_todo", key])));
// Current requested scopes need this read even when the Goal's exact
// write scope can carry forward from an earlier observation.
linkedDetail = pointer(["selected_todo", requested]);
details.push(linkedDetail);
}
if (!linkedDetail) return undefined;
// Current readiness belongs with the decision. Reorder only the new pinned
// reader, so an explicit historical initial-read cursor still replays.
const preparation = groups.remaining.indexOf("/interaction_contract/cli_channel/execution_preparation");
if (preparation >= 0) groups.opening.push(...groups.remaining.splice(preparation, 1));
const controls = Object.keys(body).filter(key => key !== detail).map(key => pointer([...parent, key]));
const checkpointPath = [...parent, "checkpointed_boundary_authority"];
const checkpoint = jsonObject(at(context, checkpointPath));
const opening = {boundary, detail: pointer(scope), controls};
if (checkpoint?.schema_version !== "checkpointed_boundary_authority_v0"
|| !Array.isArray(checkpoint.active_write_scope) || !Number.isSafeInteger(checkpoint.active_count)
|| !Number.isSafeInteger(checkpoint.inactive_count) || !Array.isArray(checkpoint.entries)
|| !checkpoint.entries.length) return opening;
// Keep the current approval summary in the opening. The exact entries and
// write scope are both required from the same capture before work.
const checkpointIndex = controls.indexOf(pointer(checkpointPath));
controls.splice(checkpointIndex, 1, ...Object.keys(checkpoint).filter(key => key !== "entries")
.map(key => pointer([...checkpointPath, key])));
return {...opening, checkpointEntries: pointer([...checkpointPath, "entries"])};
return {controls, details, linkedDetail};
}

/** Invocation-local navigation, not captured input or a read/retention receipt.
Expand All @@ -818,16 +839,16 @@ function nativeContextReadPlan(context: JsonObject, pointers: string[],
let {opening, remaining} = groups;
if (openingSplit) {
// The reader chooses the split using the actual serialized opening.
opening = opening.flatMap(field => field === openingSplit.boundary ? openingSplit.controls : [field]);
remaining = [openingSplit.detail, ...(openingSplit.checkpointEntries ? [openingSplit.checkpointEntries] : []), ...remaining];
opening = opening.flatMap(field => openingSplit.controls.get(field) ?? [field]);
remaining = [...openingSplit.details, ...remaining];
}
const ordinaryRows = openingSplit ? (plan.selections as ReadSelection[]).reduce((end, row, index) =>
groups.opening.some(field => field === row.pointer || field.startsWith(row.pointer + "/"))
? index + 1 : end, 0) : undefined;
// Keep the ordinary fallback in the same order as the observed selection.
return {initial: true, plan, ...(opening.length && remaining.length
? {opening: select(opening), remaining: select(remaining)} : {}),
...(openingSplit ? {linked_opening_detail: openingSplit.detail, ordinary_opening_rows: ordinaryRows} : {})};
...(openingSplit ? {linked_opening_detail: openingSplit.linkedDetail, ordinary_opening_rows: ordinaryRows} : {})};
}

export function initialContextReadPointers(context: JsonObject, decisionFields: readonly string[]): string[] {
Expand Down
55 changes: 44 additions & 11 deletions tests/control_plane/test_context_first_read.py
Original file line number Diff line number Diff line change
Expand Up @@ -661,11 +661,13 @@ def test_cli_current_goal_and_action_precede_complete_scoped_preferences(tmp_pat

@pytest.mark.parametrize("warm", [False, True])
@pytest.mark.parametrize("provider", ["file", "sqlite"])
@pytest.mark.parametrize(("scope_count", "page_budget", "checkpoint_count"), [
(165, 12000, 0), (290, 12000, 0), (165, 16000, 0), (290, 12000, 30),
@pytest.mark.parametrize(("scope_count", "page_budget", "checkpoint_count", "requested_count"), [
(165, 12000, 0, 0), (290, 12000, 0, 0), (165, 16000, 0, 0), (290, 12000, 30, 0),
pytest.param(290, 12000, 0, 355, id="large-goal-and-todo-scopes"),
pytest.param(290, 12000, 30, 355, id="large-scopes-with-approvals"),
])
def test_ready_opening_keeps_controls_readable_with_a_large_write_scope(
tmp_path, monkeypatch, provider, warm, scope_count, page_budget, checkpoint_count,
tmp_path, monkeypatch, provider, warm, scope_count, page_budget, checkpoint_count, requested_count,
):
from test_codex_context_lifecycle import deliver, setup
from test_quota_settlement_cli import (
Expand All @@ -683,6 +685,14 @@ def test_ready_opening_keeps_controls_readable_with_a_large_write_scope(
state.write_text(state.read_text().replace("## Next Action", narrative + "\n\n## Next Action", 1))
configuration = json.loads(registry.read_text())
scopes = [f"docs/areas/{index:03d}/fixture-entrypoints/public/**" for index in range(scope_count)]
requested_scopes = [
f"{scopes[index % scope_count][:-2]}section-{index:03d}/**" for index in range(requested_count)
]
if requested_scopes:
state.write_text(state.read_text().replace(
"required_capabilities=shell%2Cfilesystem_read -->",
f"required_capabilities=shell%2Cfilesystem_read required_write_scopes={','.join(requested_scopes)} -->",
))
if scope_count == 165:
assert len(json.dumps(scopes, separators=(",", ":")).encode()) < 8192
coordination = configuration["goals"][0]["coordination"]
Expand Down Expand Up @@ -751,23 +761,31 @@ def read(command):
rows = json.loads(Path(prior_ref["path"]).read_bytes())["interaction_contract"]["agent_channel"]["work_context"]["sources"]
index = next(i for i, source in enumerate(rows) if source["source"] == "goal_state")
body_pointer = f"/interaction_contract/agent_channel/work_context/sources/{index}/content/text"
prior_pages, prior_facts = read(prior["recovery"]["command"] + " --select " + body_pointer)
prior_read = prior["recovery"]["command"] + " --select " + body_pointer
if requested_scopes:
prior_read += " --select /goal_boundary/write_scope"
prior_pages, prior_facts = read(prior_read)
assert narrative in prior_facts[body_pointer]
if requested_scopes:
assert prior_facts["/goal_boundary/write_scope"] == scopes
deliver(journal, event, prior_pages)
cli("refresh-state", *binding, "--turn-instance-id", "wide-prior", "--classification", "fixture_verified",
"--delivery-batch-scale", "implementation", "--delivery-outcome", "outcome_progress",
"--delivery-boundary", "in_flight_continuation", "--no-global-sync", "--suppress-external-sinks")
cli("quota", "spend-slot", *binding, "--turn-instance-id", "wide-prior",
"--slots", "1", "--source", "heartbeat", "--execute")
scopes = [*scopes[:-1], "docs/areas/current-fixture-scope/**"]
configuration["goals"][0]["coordination"]["write_scope"] = scopes
registry.write_text(json.dumps(configuration))
if not requested_scopes:
scopes = [*scopes[:-1], "docs/areas/current-fixture-scope/**"]
configuration["goals"][0]["coordination"]["write_scope"] = scopes
registry.write_text(json.dumps(configuration))

view = capture("wide-ready")
_, source_ref = read_context_read_reference(view["recovery"]["reference_file"])
path = Path(source_ref["path"])
raw = path.read_bytes()
source = json.loads(raw)
if requested_scopes:
assert source["selected_todo"]["required_write_scopes"] == requested_scopes
pages, opening = read(view["first_read_command"])
if page_budget == 16000:
# A paged body is not itself a reason to add a second reader. The
Expand All @@ -793,7 +811,12 @@ def read(command):
assert opening["/interaction_contract/cli_channel/execution_preparation/state"] == "ready"
assert opening["/goal_boundary/requires_parent_approval"] == ["publish"]
assert opening["/goal_boundary/stop_condition"] == source["goal_boundary"]["stop_condition"]
required_reads = "/interaction_contract/agent_channel/required_reads"
assert opening[required_reads] == source["interaction_contract"]["agent_channel"]["required_reads"]
assert "/goal_boundary/write_scope" not in opening
if requested_scopes:
assert "/selected_todo/required_write_scopes" not in opening
assert opening["/selected_todo/text"] == source["selected_todo"]["text"]
authority = "/goal_boundary/checkpointed_boundary_authority"
if checkpoint_count:
assert opening[authority + "/active_count"] == checkpoint_count // 2
Expand All @@ -804,7 +827,11 @@ def read(command):
deliver(journal, event, pages)

pages, remaining = read(view["remaining_read_command"])
assert len(pages) > 1 and remaining["/goal_boundary/write_scope"] == scopes
assert len(pages) > 1
if requested_scopes:
assert remaining["/selected_todo/required_write_scopes"] == requested_scopes
if not (warm and requested_scopes):
assert remaining["/goal_boundary/write_scope"] == scopes
if checkpoint_count:
entries = source["goal_boundary"]["checkpointed_boundary_authority"]["entries"]
assert len(entries) == checkpoint_count
Expand All @@ -818,16 +845,22 @@ def leaves(values):
if not isinstance(value, (dict, list)) or not value}
assert not opening.keys() & remaining.keys()
if warm:
assert body_pointer in pages[0]["previously_delivered_fields"] and body_pointer not in remaining
assert "/goal_boundary/write_scope" not in pages[0]["previously_delivered_fields"]
assert leaves(opening | remaining) == {key: value for key, value in leaves(ordinary).items() if key != body_pointer}
expected_reuse = {body_pointer}
if requested_scopes:
expected_reuse.add("/goal_boundary/write_scope")
assert set(pages[0]["previously_delivered_fields"]) == expected_reuse
assert leaves(opening | remaining) == {
key: value for key, value in leaves(ordinary).items()
if not any(key == reused or key.startswith(reused + "/") for reused in expected_reuse)
}
deliver(journal, event, pages)
assert "/goal_boundary/write_scope" in codex_context._state(journal)["consumed_pointers"]
codex_context.codex_context_hook(str(journal), {**event, "hook_event_name": "PostCompact"})
recovery_pages, restored = read(view["remaining_read_command"])
assert "previously_delivered_fields" not in recovery_pages[0]
assert not opening.keys() & restored.keys()
assert leaves(opening | restored) == leaves(ordinary)
assert restored["/goal_boundary/write_scope"] == scopes
else:
assert leaves(opening | remaining) == leaves(ordinary)
assert path.read_bytes() == raw and hashlib.sha256(raw).hexdigest() == source_ref["sha256"]
Expand Down
Loading