diff --git a/docs/reference/protocols/quota-cli-hot-path-compaction-v0.md b/docs/reference/protocols/quota-cli-hot-path-compaction-v0.md index ed02d027e2..8030a685e8 100644 --- a/docs/reference/protocols/quota-cli-hot-path-compaction-v0.md +++ b/docs/reference/protocols/quota-cli-hot-path-compaction-v0.md @@ -29,6 +29,23 @@ TypeScript 上下文 owner 同时约束 `quota context-read --initial-read`。 停止和结算不变;改变的只是起始视图,不是完整 capture 或显式读取。总成本比较须计入 后续索引补读及额外调用;初读字节减少本身不证明保留、理解或收益。 +A prepared native turn with a matching settlement receipt can open a large +batch of suggested outcomes with their IDs, objectives, revisions, and exact +addresses. This applies when the complete suggested bodies exceed the native +first-read window and every suggested outcome has a verified supporting +address. Instead of claiming complete requirements inline, the opening +identifies those omitted outcome parent paths (the parent of each `/id` pointer) +and requires selecting every applicable complete outcome from the current +recovery capture before dependent work. A small batch retains its complete +opening bodies. Explicit initial reads and saved selection references retain +their own read plans. + +原生 Turn 准备就绪后,若结算回执匹配、建议验收项的完整正文超过首读窗口,且各项 +都有核验过的支撑地址,首读先提供各项目标、ID、版本和精确地址。该首读不再声称 +已保留完整要求,而是标明省略的验收父路径(各 `/id` 指针的父路径),并要求在 +依赖工作前沿当前恢复 capture 读取适用验收项的完整正文。小批量仍在首读展开完整 +正文。显式初读和已保存的选择引用沿各自的读取计划运行。 + ## Ownership Boundary Successful JSON `refresh-state` output keeps the complete `explore_result` once. diff --git a/docs/reference/protocols/turn-envelope-v0.md b/docs/reference/protocols/turn-envelope-v0.md index 10198cc56e..0be04ac265 100644 --- a/docs/reference/protocols/turn-envelope-v0.md +++ b/docs/reference/protocols/turn-envelope-v0.md @@ -599,7 +599,7 @@ diagnostic remain unchanged. This is an output qualification, not a full-cost SL The benchmark heartbeat worker verifies a historical `turn_envelope` request against the pinned CLI's v0 response before launching a model. Its read-only preview and eligibility are recorded in the wake receipt. See the [runtime -guide](../../../benchmark/runtime/RUNTIME.md) for supported configurations. +guide](https://github.com/loopx-project/loopx/blob/main/benchmark/runtime/RUNTIME.md) for supported configurations. Model cost, decision quality and long-run adoption require a separately pinned experiment. A capture carries its original read and recovery scope. diff --git a/loopx/cli_commands/quota_capture.py b/loopx/cli_commands/quota_capture.py index ef2c636b09..455afb2bd2 100644 --- a/loopx/cli_commands/quota_capture.py +++ b/loopx/cli_commands/quota_capture.py @@ -111,13 +111,14 @@ def native_context_capture_view(projected: dict[str, Any], directory: Path, *, # Its recovery recipe does not require an extra root index to be planned. stateless_first_read = progressive_enabled and page_attached and captured_recovery is not None - def pin_initial_selection(plan: dict[str, Any]) -> None: + def pin_initial_selection(plan: dict[str, Any], *, opening_context_instruction: str | None = None) -> None: nonlocal initial_read_pointers, initial_read_reference, initial_read_content selections = plan["selections"] initial_read_pointers = [item["pointer"] for item in selections] try: - initial_read_reference, initial_read_content = write_initial_context_read_reference(Path(current["path"]), current["sha256"], - current_document, selections) + initial_read_reference, initial_read_content = write_initial_context_read_reference( + Path(current["path"]), current["sha256"], current_document, selections, + opening_context_instruction=opening_context_instruction) except OSError: # Read-only capture roots keep the existing initial recipe; # metadata is optional and never a read/authority receipt. @@ -146,7 +147,7 @@ def pin_initial_selection(plan: dict[str, Any]) -> None: try: initial, plan = initial_read_plan["initial"], initial_read_plan["plan"] if initial: - pin_initial_selection(plan) + pin_initial_selection(plan, opening_context_instruction=initial_read_plan.get("opening_context_instruction")) else: field_index = _context_index_fields(current_document, plan["selections"][0]["children"]) except (EffectRuntimeRemoteError, EffectRuntimeStartupError): @@ -250,7 +251,8 @@ def project_native_quota_context(payload: dict[str, Any], args: argparse.Namespa capture_directory=capture_directory, goal_id=decision_identity[0], agent_id=decision_identity[1], surface=quota_context_surface(payload), capture_id=capture_id, continuity_generation=getattr(args, "_context_delivery_generation", None), - progressive_enabled=progressive_enabled) + progressive_enabled=progressive_enabled, + max_page_output_bytes=getattr(args, "max_page_output_bytes", None)) recovery = prepared.delivery.get("recovery") view = native_context_capture_view(prepared.delivery, capture_directory, context_directory=directory, progressive_enabled=progressive_enabled, initial_read_plan=prepared.initial_read_plan, diff --git a/loopx/cli_commands/quota_context_reader.py b/loopx/cli_commands/quota_context_reader.py index 7d58b7f6e7..6f67d1a7b9 100644 --- a/loopx/cli_commands/quota_context_reader.py +++ b/loopx/cli_commands/quota_context_reader.py @@ -256,11 +256,17 @@ def _validate_context_page_window(offset: int, size: int, output_limit: int | No def _validate_pinned_selection(selection: dict[str, Any]) -> None: - if (set(selection) - {"present_goal_narrative"} != {"select", "initial_read", "list_fields", "list_depth", "sha256"} + if (set(selection) - {"present_goal_narrative", "opening_context_instruction"} + != {"select", "initial_read", "list_fields", "list_depth", "sha256"} or type(selection["initial_read"]) is not bool or type(selection["list_fields"]) is not bool or ("present_goal_narrative" in selection and ( selection["present_goal_narrative"] is not True or selection["list_fields"] or selection["initial_read"])) + or ("opening_context_instruction" in selection and ( + not isinstance(selection["opening_context_instruction"], str) + or not selection["opening_context_instruction"] + or selection["list_fields"] or selection["initial_read"] + or "/context_details/instruction" not in (selection.get("select") or ()))) or not isinstance(selection["sha256"], str) or BARE_SHA256_PATTERN.fullmatch(selection["sha256"]) is None): raise ValueError("reader selection reference is incomplete or unsupported") @@ -393,7 +399,9 @@ def read_context_capture(args: argparse.Namespace, *, presentation: dict[str, An present_goal_narrative=(pinned_selection.get("present_goal_narrative") is True if pinned_selection is not None else None), selection_paths=reference.get("selection_paths") if pinned_selection is not None else None, - text_append=text_append) + text_append=text_append, + opening_context_instruction=(pinned_selection.get("opening_context_instruction") + if pinned_selection is not None else None)) except ContextSelectionDigestChanged as exc: # A verified file digest only binds bytes. Preserve an explicit # selection or listing, including a receipt-only diagnostic. @@ -720,12 +728,15 @@ def _bounded_initial_read(navigation: dict[str, Any], plan: dict[str, Any], *, digest = plan["capture"]["sha256"] if ordinary_page and _contains_ordinary_opening(ordinary_page["content"], document, plan): return None - opening, content = write_initial_context_read_reference(path, digest, document, plan["opening"]["selections"]) + opening_instruction = plan.get("opening_context_instruction") + opening, content = write_initial_context_read_reference(path, digest, document, plan["opening"]["selections"], + opening_context_instruction=opening_instruction) if len(content) > page_bytes or len(content) >= output_bytes: return None remaining = remaining_reference if remaining is None: - remaining, _ = write_initial_context_read_reference(path, digest, document, plan["remaining"]["selections"]) + remaining, _ = write_initial_context_read_reference(path, digest, document, plan["remaining"]["selections"], + opening_context_instruction=opening_instruction) def command(reference: Path) -> str: return context_capture_read_command(path, digest, page_bytes=page_bytes, diff --git a/loopx/cli_commands/quota_native_context.py b/loopx/cli_commands/quota_native_context.py index bfef3289c7..6648b69825 100644 --- a/loopx/cli_commands/quota_native_context.py +++ b/loopx/cli_commands/quota_native_context.py @@ -278,7 +278,8 @@ def authority_refusal(error: Exception) -> dict[str, Any]: goal_id=args.goal_id, agent_id=args.agent_id, surface="complete_turn" if complete else "quota_packet", capture_id=args.capture_sha256, continuity_generation=getattr(args, "_context_delivery_generation", None), - progressive_enabled=activation["progressive_enabled"], selection_command_args_template=transport, + progressive_enabled=activation["progressive_enabled"], max_page_output_bytes=caller_output_limit, + selection_command_args_template=transport, captured_decision=captured_decision if activation["progressive_enabled"] and (args.initial_read or "sha256" in captured_decision) else None, hook_session=hook_session, saved_capture=True, publication_guard=publication_guard) diff --git a/loopx/control_plane/quota/progressive_context.ts b/loopx/control_plane/quota/progressive_context.ts index 7ade3bce89..c91d5a4def 100644 --- a/loopx/control_plane/quota/progressive_context.ts +++ b/loopx/control_plane/quota/progressive_context.ts @@ -28,6 +28,7 @@ export type ReusableExactBody = {path: Path; sourceIdentity: string}; const MIN_REUSABLE_BODY_BYTES = 1024; const SETTLEMENT_PLAN_PATH = ["interaction_contract", "cli_channel", "settlement_plan"]; const REPLAN_CONTEXT_PATH = ["autonomous_replan_obligation", "replan_context"]; +const COMPLETE_REQUIREMENTS_CLAUSE = "This view retains complete requirements and current review/check states. "; const pointer = (path: Path): string => path.length ? "/" + path.map(key => String(key).replaceAll("~", "~0").replaceAll("/", "~1")).join("/") : ""; const at = (root: unknown, path: Path): unknown => path.reduce((row, key) => @@ -643,7 +644,7 @@ function requiredNativeContext(request: JsonObject, sourceValues: ProjectionSour }) : [], }, instruction: deferred.map(edit => typeof edit.read_instruction === "string" ? edit.read_instruction : "").join("") - + "This view retains complete requirements and current review/check states. " + + COMPLETE_REQUIREMENTS_CLAUSE + "Source history, review reasoning and evidence references are supporting material. " + "Read them from this same immutable capture when a decision, verification or review depends on them. " + "Use the outcome's supporting_material_pointer when shown, or remove /id from its selected JSON pointer. " @@ -738,8 +739,11 @@ export function prepareProgressiveContextDelivery(request: JsonObject, legacyFie // Full native delivery can use that copy; delta still carries its own edits. if (request.source_edits === true && delivery.mode === "full") delete delivery.context; const observe = request.observe_first_read === true && !!jsonObject(required.context.selected_todo)?.todo_id; + const firstReadBytes = jsonObject(request.native_projection)?.initial_read_output_bytes; + const openingBudget = typeof firstReadBytes === "number" && Number.isSafeInteger(firstReadBytes) && firstReadBytes > 0 + ? firstReadBytes : undefined; const groups = observe || request.include_initial_read_plan === true - ? initialContextReadGroups(required.context, decisionFields) : undefined; + ? initialContextReadGroups(required.context, decisionFields, openingBudget) : undefined; const openingSplit = request.include_initial_read_plan === true && groups ? prepareInitialOpening(required.context, groups, exactBody?.path) : undefined; const pointers = groups ? [...groups.opening, ...groups.remaining] : []; @@ -804,12 +808,27 @@ function prepareInitialOpening(context: JsonObject, groups: ReturnType): ${deferredOutcomes.join(", ")}. ` + + "Supporting material below still comes from the original capture in context_details. "; + return instruction.includes(COMPLETE_REQUIREMENTS_CLAUSE) + ? instruction.replace(COMPLETE_REQUIREMENTS_CLAUSE, notice) + : notice + instruction; +} + /** Invocation-local navigation, not captured input or a read/retention receipt. * Decision vocabulary comes from the same owner as standalone initial reads. */ function nativeContextReadPlan(context: JsonObject, pointers: string[], groups: ReturnType, openingSplit?: ReturnType): { initial: boolean; plan: JsonObject; opening?: JsonObject; remaining?: JsonObject; linked_opening_detail?: string; - ordinary_opening_rows?: number; + ordinary_opening_rows?: number; deferred_suggested_outcomes?: string[]; opening_context_instruction?: string; } { if (!pointers.length) return {initial: false, plan: capturedContextSelection({context, select: [""], list_fields: true})}; @@ -824,10 +843,15 @@ function nativeContextReadPlan(context: JsonObject, pointers: string[], 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; + const deferredOutcomes = groups.deferredSuggestedOutcomes ?? []; + const openingInstruction = deferredOutcomes.length && pointers.includes("/context_details/instruction") + ? deferredOutcomesInstruction(context, deferredOutcomes) : 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.detail, ordinary_opening_rows: ordinaryRows} : {}), + ...(deferredOutcomes.length ? {deferred_suggested_outcomes: deferredOutcomes} : {}), + ...(openingInstruction ? {opening_context_instruction: openingInstruction} : {})}; } export function initialContextReadPointers(context: JsonObject, decisionFields: readonly string[]): string[] { @@ -925,8 +949,8 @@ function managerReturnAttention(value: unknown, requiredReads: unknown[]): JsonO return attention; } -function initialContextReadGroups(context: JsonObject, decisionFields: readonly string[]): { - opening: string[]; remaining: string[]; +function initialContextReadGroups(context: JsonObject, decisionFields: readonly string[], openingBudget?: number): { + opening: string[]; remaining: string[]; deferredSuggestedOutcomes?: string[]; } { const object = (value: unknown): JsonObject | undefined => value !== null && typeof value === "object" && !Array.isArray(value) ? value as JsonObject : undefined; @@ -989,6 +1013,7 @@ function initialContextReadGroups(context: JsonObject, decisionFields: readonly include("interaction_contract", "agent_channel", field); const cli = object(interaction.cli_channel), planPath = SETTLEMENT_PLAN_PATH; const plan = object(cli?.settlement_plan); + const readyIdentity = readySettlementIdentity(context, interaction, plan); const deferredReentry = hasBoundDatedTodoReentry(context, interaction, plan); const turnBindingRequired = cli?.turn_binding_required === true; const admissionFields = ["next_cli_actions", "spend_allowed_now", "spend_after_validation", "spend_policy"]; @@ -1083,6 +1108,7 @@ function initialContextReadGroups(context: JsonObject, decisionFields: readonly // before selecting other sources' metadata: complete-parent coalescing keeps // the first selected child's position. Preserve stable order within each group. const hasText = (source: unknown): boolean => typeof object(object(source)?.content)?.text === "string"; + const deferredSuggestedOutcomes: string[] = []; sourceRows.sort((left, right) => Number(hasText(right.source)) - Number(hasText(left.source))); sourceRows.forEach(({source: _source, index}) => { const source = [...work, "sources", index]; @@ -1131,11 +1157,31 @@ function initialContextReadGroups(context: JsonObject, decisionFields: readonly && suggested.every(id => typeof id === "string" && outcomes.filter(value => object(value)?.id === id).length === 1); const expanded = new Set(expand ? suggested as string[] : []); + const outcomesPath = [...source, "content", "goal_acceptance_contract", "outcome_requirements", "outcomes"]; + const canDeferSuggested = openingBudget !== undefined && readyIdentity !== undefined && expanded.size > 0 + && inlineSupportingDetails && details?.outcome_support_from_id === true + && details.path === supportingSource?.path && details.sha256 === supportingSource?.sha256 + && typeof details.command_template === "string" && details.command_template.length > 0; + const referenced = canDeferSuggested && Array.isArray(outcomes) ? outcomes.filter((value, index) => { + const row = object(value); + return typeof row?.id === "string" && expanded.has(row.id) + && row.supporting_material_pointer === pointer([...outcomesPath, index]); + }) : []; + // The whole suggested set must have exact supporting addresses before + // exceeding the native opening window moves its bodies to selected reads. + const deferSuggested = canDeferSuggested && referenced.length === expanded.size + && Buffer.byteLength(JSON.stringify(referenced), "utf8") > openingBudget; if (Array.isArray(outcomes)) outcomes.forEach((_outcome, outcomeIndex) => { - const outcome = [...source, "content", "goal_acceptance_contract", "outcome_requirements", "outcomes", outcomeIndex]; + const outcome = [...outcomesPath, outcomeIndex]; const row = object(_outcome), outcomeId = row?.id; - if (typeof outcomeId === "string" && expanded.has(outcomeId)) { include(...outcome); return; } + const suggested = typeof outcomeId === "string" && expanded.has(outcomeId); + if (suggested && !deferSuggested) { include(...outcome); return; } include(...outcome, "id"); + if (suggested) { + include(...outcome, "objective"); + include(...outcome, "revision"); + deferredSuggestedOutcomes.push(pointer(outcome)); + } // The id selection already carries the same absolute outcome address. // Keep aliases whose source, value or read guidance cannot be verified. if (!(inlineSupportingDetails && details?.outcome_support_from_id === true @@ -1162,7 +1208,7 @@ function initialContextReadGroups(context: JsonObject, decisionFields: readonly // A ready Turn already shows its ordered writeback and spend with their // conditions. Hide only the exact duplicate fallback in this first read; // recovery, legacy readers and the original capture keep both forms. - const repeatsSettlement = readySettlementIdentity(context, interaction, plan) !== undefined + const repeatsSettlement = readyIdentity !== undefined && settlementSteps?.length === 2 && writeback?.kind === "durable_writeback" && spend?.kind === "quota_spend" && templates?.every(command => typeof command === "string" && command.length > 0) && isDeepStrictEqual(cli?.next_cli_actions, templates); @@ -1225,5 +1271,6 @@ function initialContextReadGroups(context: JsonObject, decisionFields: readonly } else if (details && known(details, ["command_template", "path", "sha256"])) { include("context_details"); } else include("context_details", "unread_context_index"); - return {opening, remaining: pointers}; + return {opening, remaining: pointers, + ...(deferredSuggestedOutcomes.length ? {deferredSuggestedOutcomes} : {})}; } diff --git a/loopx/control_plane/turn_driver/codex_context.py b/loopx/control_plane/turn_driver/codex_context.py index 915664912d..ba2a52174b 100644 --- a/loopx/control_plane/turn_driver/codex_context.py +++ b/loopx/control_plane/turn_driver/codex_context.py @@ -22,7 +22,7 @@ context_capture_read_command, ) from .native_context_profile import ( - NATIVE_CONTEXT_PAGE_BYTES, NATIVE_CONTEXT_PAGE_OUTPUT_BYTES, + NATIVE_CONTEXT_FIRST_READ_FALLBACK_BYTES, NATIVE_CONTEXT_PAGE_BYTES, NATIVE_CONTEXT_PAGE_OUTPUT_BYTES, NATIVE_CONTEXT_LARGE_OUTPUT_BYTES, NATIVE_CONTEXT_HISTORY_TOKENS, NATIVE_CONTEXT_OUTPUT_ENV, native_context_page_budget, ) @@ -907,6 +907,7 @@ def prepare_codex_context(payload: dict[str, Any], *, directory: str | None, cap continuity_generation: str | None = None, include_initial_read_plan: bool = True, progressive_enabled: bool | None = None, + max_page_output_bytes: int | None = None, selection_command_args_template: str | None = None, captured_decision: dict[str, str] | None = None, hook_session: str | None = None, @@ -989,6 +990,11 @@ def publish_recovery(reference: dict[str, Any]) -> None: # Legacy direct native callers omitted the presentation option. progressive = progressive_enabled is not False presentation = progressive or selection_command_args_template is not None + first_read_output_bytes = ( + min(output_bytes, max_page_output_bytes) + if max_page_output_bytes is not None and max_page_output_bytes > 0 + else min(output_bytes, NATIVE_CONTEXT_FIRST_READ_FALLBACK_BYTES) + ) try: transaction = prepare_context_delivery(payload, scope=scope, capture_id=capture_id, surface=surface, baseline=request.get("baseline"), @@ -1000,6 +1006,8 @@ def publish_recovery(reference: dict[str, Any]) -> None: if selection_command_args_template is not None else {}), **({"captured_decision": captured_decision} if captured_decision is not None else {}), **({"progressive_enabled": False} if not progressive else {}), + **({"initial_read_output_bytes": first_read_output_bytes} + if include_initial_read_plan and progressive else {}), "command_template": recovery["command"] + " --select ''", } if presentation else None, consumed_pointers=state.get("consumed_pointers"), observe_first_read=progressive) diff --git a/loopx/control_plane/turn_driver/decision_capture.py b/loopx/control_plane/turn_driver/decision_capture.py index 472584e727..137c9c53e7 100644 --- a/loopx/control_plane/turn_driver/decision_capture.py +++ b/loopx/control_plane/turn_driver/decision_capture.py @@ -717,10 +717,17 @@ def _first_read_goal_text(payload: dict[str, Any], path: list[Any], value: Any) return text if text is not None and len(value) - len(text) > len(_GOAL_NARRATIVE_PRESENTATION) + 96 else None +_OPENING_CONTEXT_INSTRUCTION_PRESENTATION = ( + "This native opening omits large suggested outcome bodies; " + "read applicable parent pointers from recovery.command before dependent work." +) + + def _context_selection_bytes(payload: dict[str, Any], selections: list[dict[str, Any]], *, list_fields: bool, list_depth: int | None, present_goal_narrative: bool, - text_append: dict[str, Any] | None = None) -> tuple[bytes, list[str]]: + text_append: dict[str, Any] | None = None, + opening_context_instruction: str | None = None) -> tuple[bytes, list[str]]: """Render TS-verified addresses from the original, digest-checked values.""" if text_append is not None and (list_fields or not isinstance(text_append, dict)): raise ValueError("observed text append requires a selected value") @@ -748,6 +755,10 @@ def _context_selection_bytes(payload: dict[str, Any], selections: list[dict[str, append_rendered = True elif list_fields: views.append({"pointer": pointer, "fields": context_index_fields(payload, item["children"])}) + elif opening_context_instruction is not None and pointer == "/context_details/instruction": + presented.append(pointer) + views.append({"pointer": pointer, "value": opening_context_instruction, + "presentation": _OPENING_CONTEXT_INSTRUCTION_PRESENTATION}) else: text = _first_read_goal_text(payload, path, selected) if present_goal_narrative else None if text is None: @@ -764,26 +775,37 @@ def _context_selection_bytes(payload: dict[str, Any], selections: list[dict[str, def context_selection_binding(select: list[str], *, list_fields: bool, list_depth: int | None, - sha256: str, presented: bool = False) -> dict[str, Any]: + sha256: str, presented: bool = False, + opening_context_instruction: str | None = None) -> dict[str, Any]: return {"select": select, "initial_read": False, "list_fields": list_fields, "list_depth": list_depth, - "sha256": sha256, **({"present_goal_narrative": True} if presented else {})} + "sha256": sha256, **({"present_goal_narrative": True} if presented else {}), + **({"opening_context_instruction": opening_context_instruction} + if opening_context_instruction is not None else {})} def initial_context_selection_bytes(payload: dict[str, Any], selections: list[dict[str, Any]], *, - text_append: dict[str, Any] | None = None) -> tuple[bytes, list[str]]: + text_append: dict[str, Any] | None = None, + opening_context_instruction: str | None = None) -> tuple[bytes, list[str]]: return _context_selection_bytes(payload, selections, list_fields=False, list_depth=None, - present_goal_narrative=True, text_append=text_append) + present_goal_narrative=True, text_append=text_append, + opening_context_instruction=opening_context_instruction) def write_initial_context_read_reference(path: Path, digest: str, payload: dict[str, Any], selections: list[dict[str, Any]], *, - observed_read: dict[str, Any] | None = None) -> tuple[Path, bytes]: + observed_read: dict[str, Any] | None = None, + opening_context_instruction: str | None = None) -> tuple[Path, bytes]: """Pin the shared rendered selection and return its exact rendered bytes.""" text_append = observed_read.get("text_append") if observed_read else None - raw, presented = initial_context_selection_bytes(payload, selections, text_append=text_append) + raw, presented = initial_context_selection_bytes(payload, selections, text_append=text_append, + opening_context_instruction=opening_context_instruction) + instruction_presented = (opening_context_instruction + if opening_context_instruction is not None and "/context_details/instruction" in presented else None) + goal_presented = any(pointer != "/context_details/instruction" for pointer in presented) reference = write_context_read_reference(path, digest, selection=context_selection_binding([item["pointer"] for item in selections], list_fields=False, - list_depth=None, sha256=hashlib.sha256(raw).hexdigest(), presented=bool(presented)), + list_depth=None, sha256=hashlib.sha256(raw).hexdigest(), presented=goal_presented, + opening_context_instruction=instruction_presented), selection_paths=[item["path"] for item in selections], observed_read=observed_read) return reference, raw @@ -814,6 +836,7 @@ def context_selection_view(payload: dict[str, Any], *, select: list[str] | None, present_goal_narrative: bool | None = None, selection_paths: list[list[str | int]] | None = None, text_append: dict[str, Any] | None = None, + opening_context_instruction: str | None = None, ) -> tuple[dict[str, Any], bytes | None, str | None]: """Render the digest-pinned view from a new or previously resolved plan.""" if text_append is not None and (initial_read or list_fields or expected_sha256 is None): @@ -838,7 +861,8 @@ def context_selection_view(payload: dict[str, Any], *, select: list[str] | None, def render(plan: dict[str, Any], present: bool) -> tuple[bytes, str, list[str]]: raw, displayed = _context_selection_bytes(payload, plan["selections"], list_fields=list_fields, - list_depth=list_depth, present_goal_narrative=present, text_append=text_append) + list_depth=list_depth, present_goal_narrative=present, text_append=text_append, + opening_context_instruction=opening_context_instruction) return raw, hashlib.sha256(raw).hexdigest(), displayed raw, digest, displayed = render(plan, presentation) diff --git a/loopx/control_plane/turn_driver/native_context_selection.py b/loopx/control_plane/turn_driver/native_context_selection.py index 9ed47d0b28..728129493b 100644 --- a/loopx/control_plane/turn_driver/native_context_selection.py +++ b/loopx/control_plane/turn_driver/native_context_selection.py @@ -112,7 +112,8 @@ def verified_context_selection( list_depth=selected.get("list_depth") if selected else None, expected_sha256=view_digest, preserve_selection_order=selected is not None and not initial_read, present_goal_narrative=selected.get("present_goal_narrative") is True if selected else None, - selection_paths=selection_paths, text_append=text_append) + selection_paths=selection_paths, text_append=text_append, + opening_context_instruction=selected.get("opening_context_instruction") if selected else None) if selected_raw is None: return None raw = selected_raw diff --git a/loopx/control_plane/turn_driver/native_first_read.py b/loopx/control_plane/turn_driver/native_first_read.py index fecd43424a..9a6706fe3d 100644 --- a/loopx/control_plane/turn_driver/native_first_read.py +++ b/loopx/control_plane/turn_driver/native_first_read.py @@ -15,14 +15,18 @@ def observed_first_read_reference(directory: str, target: dict[str, Any], recove ) -> tuple[dict[str, Any], dict[str, Any] | None] | None: """Pin the reduced view and its ordinary fallback from the same capture.""" initial = initial_read_plan if initial_read_plan and initial_read_plan.get("initial") is True else {} - pinned = _pin_observed_selection(directory, target, recovery, context, plan, initial.get("plan")) + opening_instruction = initial.get("opening_context_instruction") + pinned = _pin_observed_selection(directory, target, recovery, context, plan, initial.get("plan"), + opening_context_instruction=opening_instruction) if pinned is None: return None reference, content = pinned # Keep this preview in the invocation only. A split remainder is pinned # only if the actual output window needs it. opening = ({"path": reference["path"], "content": content, - "reused": plan["reused"], "remaining": plan["linked_remaining"]} + "reused": plan["reused"], "remaining": plan["linked_remaining"], + **({"opening_context_instruction": opening_instruction} + if opening_instruction is not None else {})} if "linked_remaining" in plan and "remaining" in initial else None) if opening is not None and "text_append" in plan: opening["text_append"] = plan["text_append"] @@ -40,13 +44,16 @@ def observed_remaining_read_reference(directory: str, target: dict[str, Any], re if not reused: return None pinned = _pin_observed_selection(directory, target, recovery, context, - {**remaining, "reused": reused}, ordinary_remaining) + {**remaining, "reused": reused}, ordinary_remaining, + opening_context_instruction=opening.get("opening_context_instruction")) return Path(pinned[0]["path"]) if pinned is not None else None def _pin_observed_selection(directory: str, target: dict[str, Any], recovery: dict[str, Any], context: dict[str, Any], plan: dict[str, Any], - ordinary_plan: dict[str, Any] | None) -> tuple[dict[str, Any], bytes] | None: + ordinary_plan: dict[str, Any] | None, *, + opening_context_instruction: str | None = None, + ) -> tuple[dict[str, Any], bytes] | None: try: path, digest = Path(recovery["path"]), recovery["sha256"] observation = {"directory": directory, "target": target, "fields": plan["reused"]} @@ -74,13 +81,14 @@ def _pin_observed_selection(directory: str, target: dict[str, Any], recovery: di selections.extend(replacement) cursor = end selections.extend(ordinary[cursor:]) - fallback, body = write_initial_context_read_reference(path, digest, context, ordinary) + fallback, body = write_initial_context_read_reference(path, digest, context, ordinary, + opening_context_instruction=opening_context_instruction) observation["fallback_reference"] = {"filename": fallback.name, "selection_sha256": hashlib.sha256(body).hexdigest()} if selections is None: return None reference, content = write_initial_context_read_reference(path, digest, context, selections, - observed_read=observation) + observed_read=observation, opening_context_instruction=opening_context_instruction) return ({"path": str(reference), "pointer_bytes": sum(len(key.encode()) + 4 for key in plan["reused"])}, content) except (OSError, ValueError, KeyError, TypeError): return None # The ordinary first read remains available. diff --git a/tests/control_plane/test_context_first_read.py b/tests/control_plane/test_context_first_read.py index 77c90bee54..bf48d1e8ec 100644 --- a/tests/control_plane/test_context_first_read.py +++ b/tests/control_plane/test_context_first_read.py @@ -1251,6 +1251,186 @@ def test_initial_read_uses_current_navigation_without_hiding_peer_constraints(tm assert capture_page_range(page, raw=Path(view["recovery"]["path"]).read_bytes(), digest=page["sha256"]) is None +@pytest.mark.parametrize(("large", "ready", "known_source", "max_page_output_bytes"), [ + (False, True, True, None), + (True, True, True, None), + (True, True, True, 64000), + (True, False, True, None), + (True, True, False, None), +]) +def test_native_ready_opening_bounds_suggested_outcomes( + tmp_path, monkeypatch, navigated_decision, large, ready, known_source, max_page_output_bytes, +): + from test_codex_context_lifecycle import deliver, setup + + event = setup(tmp_path, monkeypatch) + source = navigated_decision + source.update(effective_action="normal_run", should_run=True, normal_delivery_allowed=True) + interaction = source["interaction_contract"] + agent = interaction["agent_channel"] + cli = interaction["cli_channel"] + agent["delivery_allowed"] = True + identity = {"schema_version": "quota_settlement_identity_v0", "effect_id": "original-effect", + "goal_id": "fixture", "agent_id": "author", "todo_id": "todo_current", "turn_instance_id": "original"} + source["heartbeat_receipt"] = {"settlement_identity": identity} + cli["settlement_plan"]["identity"] = identity + cli["execution_preparation"] = {"state": "ready" if ready else "claim_required", "todo_id": "todo_current"} + outcome_source = agent["work_context"]["sources"][0]["content"] + outcomes = outcome_source["goal_acceptance_contract"]["outcome_requirements"]["outcomes"] + for index, outcome in enumerate(outcomes[:2]): + outcome["objective"] = f"Verify the {outcome['id']} obligation." + outcome["sources"] = [{"ref": "fixture:original-evidence", "summary": "Original authority evidence. " * 160}] + if known_source or index == 0: + outcome["requirements"][0].pop("future_required_fact") + if large: + outcome["requirements"][0]["description"] *= 160 + short_opening = large and ready and known_source and max_page_output_bytes is None + directory = tmp_path / "capture" + directory.mkdir(mode=0o700) + prepared = codex_context.prepare_codex_context(source, directory=str(tmp_path), + capture_directory=directory, goal_id="fixture", agent_id="author", surface="quota_packet", + capture_id="first-read-budget", progressive_enabled=True, max_page_output_bytes=max_page_output_bytes) + view = model_context_reference(native_context_capture_view(prepared.delivery, directory, + context_directory=str(tmp_path), initial_read_plan=prepared.initial_read_plan, + max_page_output_bytes=max_page_output_bytes)) + opening_pages = [] + command = view["first_read_command"] + while command: + words = shlex.split(command) + page = json.loads(subprocess.check_output([sys.executable, "-m", "loopx.entrypoint", "--format", "json", + *words[words.index("quota"):]])) + assert page["ok"], page + opening_pages.append(page) + command = page.get("next_command") + assert opening_pages[-1]["eof"] + opening_raw = "".join(page["content"] for page in opening_pages) + opening = selected_context_values(opening_raw) + prefix = "/interaction_contract/agent_channel/work_context/sources/0/content" + outcomes_path = prefix + "/goal_acceptance_contract/outcome_requirements/outcomes" + assert opening[prefix + "/outcome_context"] == outcome_source["outcome_context"] + assert opening["/goal_boundary"] == source["goal_boundary"] + assert opening["/heartbeat_receipt"] == source["heartbeat_receipt"] + assert opening["/interaction_contract/agent_channel/required_reads"] == agent["required_reads"] + assert opening["/interaction_contract/agent_channel/work_context/sources/2/content/todo/note"] == ( + agent["work_context"]["sources"][2]["content"]["todo"]["note"] + ) + for index, original in enumerate(outcomes[:2]): + outcome = f"{outcomes_path}/{index}" + _, detail = read_selection(view["recovery"]["command"] + " --select " + outcome) + assert detail[outcome]["requirements"] == original["requirements"] + if short_opening: + assert outcome not in opening + assert opening[outcome + "/id"] == original["id"] + assert opening[outcome + "/objective"] == original["objective"] + assert opening[outcome + "/revision"] == original["revision"] + else: + assert opening[outcome] == detail[outcome] + if short_opening: + instruction = opening["/context_details/instruction"] + assert "This view retains complete requirements" not in instruction + assert "Before dependent work" in instruction + assert "recovery.command" in instruction and "remove /id" in instruction + assert f"{outcomes_path}/0" in instruction and f"{outcomes_path}/1" in instruction + selection_row = next(row for row in json.loads(opening_raw)["selections"] + if row["pointer"] == "/context_details/instruction") + assert "presentation" in selection_row + + # Native lifecycle observation must verify the presented opening and + # leave omitted parent outcome pointers unconsumed until explicitly read. + deliver(tmp_path, event, opening_pages) + consumed = codex_context._state(tmp_path).get("consumed_pointers", {}) + assert "/context_details/instruction" not in consumed + assert f"{outcomes_path}/0" not in consumed and f"{outcomes_path}/1" not in consumed + + detail_words = shlex.split(view["recovery"]["command"] + " --select " + f"{outcomes_path}/0") + detail_page = json.loads(subprocess.check_output([sys.executable, "-m", "loopx.entrypoint", "--format", "json", + *detail_words[detail_words.index("quota"):]])) + assert detail_page["ok"] and detail_page["eof"] + deliver(tmp_path, event, [detail_page]) + assert f"{outcomes_path}/0" in codex_context._state(tmp_path).get("consumed_pointers", {}) + + # An explicit ordinary initial read and the immutable supporting source + # remain lossless. The shorter plan belongs to this native presentation. + _, cold = read_selection(view["recovery"]["command"] + " --initial-read") + assert cold[outcomes_path + "/0"]["requirements"] == outcomes[0]["requirements"] + assert "This view retains complete requirements" in cold["/context_details/instruction"] + source_command = opening["/context_details/command_template"] + for index, original in enumerate(outcomes[:2]): + address = f"{outcomes_path}/{index}" + _, evidence = read_selection(source_command.replace("", address + "/sources")) + assert evidence[address + "/sources"] == original["sources"] + elif "/context_details/instruction" in opening: + assert "This view retains complete requirements" in opening["/context_details/instruction"] + + +def test_ready_quota_cli_opening_bounds_suggested_outcomes_and_discloses_parents(tmp_path, monkeypatch): + from test_codex_context_lifecycle import setup + from test_quota_settlement_cli import AGENT_ID, GOAL_ID, TODO_ID, _initialize_fixture_authority, _run_cli, _write_fixture + from tests.control_plane.canonical_authority_fixture import isolate_sqlite_runtime + + isolate_sqlite_runtime(tmp_path, monkeypatch) + project, runtime, registry = _write_fixture(tmp_path) + state = project / f".codex/goals/{GOAL_ID}/ACTIVE_GOAL_STATE.md" + state.write_text(state.read_text(encoding="utf-8").replace("status: active-read-only", "status: active"), encoding="utf-8") + registry.write_text(registry.read_text(encoding="utf-8").replace('"active-read-only"', '"active"'), encoding="utf-8") + _initialize_fixture_authority(project, runtime, provider="sqlite", handoff_mode="hard_lease") + code, claim = _run_cli(registry, runtime, "todo", "claim", "--goal-id", GOAL_ID, + "--todo-id", TODO_ID, "--agent-id", AGENT_ID, "--claimed-by", AGENT_ID, cwd=project) + assert code == 0 and claim["ok"], claim + for oid in ("first", "second", "third", "fourth"): + for index in range(3): + document = tmp_path / f"{oid}-{index}.json" + document.write_text(json.dumps({ + "outcome_id": oid, "owner_agent_id": AGENT_ID, "todo_ids": [TODO_ID], + "objective": f"Deliver outcome {oid}.", + "requirements": [{ + "id": f"req-{oid}-{item}", + "description": f"Requirement {oid}-{item}: preserve complete stop conditions, boundary limits, and independent verification evidence before completion.", + } for item in range(25)], + "source": {"ref": f"fixture:{oid}-{index}", "summary": ("Supporting source evidence. " * 14).strip()}, + }), encoding="utf-8") + code, inspected = _run_cli(registry, runtime, "goal-acceptance", "inspect", "--goal-id", GOAL_ID, cwd=project) + assert code == 0 and inspected["ok"], inspected + code, refined = _run_cli(registry, runtime, "goal-acceptance", "refine", "--goal-id", GOAL_ID, + "--agent-id", AGENT_ID, "--document", str(document), + "--expected-provider-revision", inspected["provider_revision"], + "--operation-id", f"op-{oid}-{index}", "--execute", cwd=project) + assert code == 0 and refined["ok"], refined + journal, captures = tmp_path / "native", tmp_path / "captures" + journal.mkdir(mode=0o700) + captures.mkdir(mode=0o700) + setup(journal, monkeypatch) + code, packet = _run_cli(registry, runtime, "quota", "should-run", "--codex-app", + "--context-delivery", "on", "--goal-id", GOAL_ID, "--agent-id", AGENT_ID, + "--todo-id", TODO_ID, "--turn-instance-id", "cli-bounded-opening", + "--codex-context-dir", str(journal), "--decision-output-root", str(captures), cwd=project) + assert code == 0 and packet["ok"], packet + + def read_all(command): + parts = [] + while command: + words = shlex.split(command) + rc, page = _run_cli(registry, runtime, *words[words.index("quota"):], cwd=project) + assert rc == 0 and page["ok"], page + parts.append(page["content"]) + command = page.get("next_command") + return selected_context_values("".join(parts)) + + opening = read_all(packet["first_read_command"]) + key = next(pointer for pointer in opening if pointer.endswith("/id") and "/outcome_requirements/outcomes/" in pointer) + outcomes_path = key.rsplit("/", 2)[0] + first, second = f"{outcomes_path}/0", f"{outcomes_path}/1" + assert first not in opening and second not in opening + assert opening[f"{first}/id"] == "first" and opening[f"{second}/id"] == "second" + instruction = opening["/context_details/instruction"] + assert "This view retains complete requirements" not in instruction + assert "Before dependent work" in instruction and first in instruction and second in instruction + recovered = read_all(packet["recovery"]["command"] + " --select " + first) + assert len(recovered[first]["requirements"]) == 25 + evidence = read_all(opening["/context_details/command_template"].replace("", f"{first}/sources")) + assert len(evidence[f"{first}/sources"]) == 3 + + @pytest.mark.parametrize("field,value", [ ("goal_id", "other-goal"), ("agent_id", "other-agent"), ("todo_id", "other-todo"), ("outcome_revision", 6), ("provider_revision", "older-source"), diff --git a/tests/control_plane_ts/progressive_context.test.ts b/tests/control_plane_ts/progressive_context.test.ts index d37bdfe40a..85666bdccd 100644 --- a/tests/control_plane_ts/progressive_context.test.ts +++ b/tests/control_plane_ts/progressive_context.test.ts @@ -2,7 +2,7 @@ import assert from "node:assert/strict"; import test from "node:test"; import {visionAuthoringContract} from "../../loopx/control_plane/goals/vision_checkpoint.ts"; import {contextReadSectionDigests, initialContextReadPointers, - progressiveContextPlan} from "../../loopx/control_plane/quota/progressive_context.ts"; + prepareProgressiveContextDelivery, progressiveContextPlan} from "../../loopx/control_plane/quota/progressive_context.ts"; import {FULL_OUTCOME_READ_GUIDANCE, PROGRESSIVE_OUTCOME_READ_GUIDANCE} from "../../loopx/control_plane/work_items/interaction_contract.ts"; const outcome = {id: "o", objective: "Keep all requirements.", revision: 1, owner_agent_id: "a", todo_ids: ["t"], @@ -222,3 +222,94 @@ test("first read keeps decision rules and preserves nonstandard Vision obligatio assert.ok(initialContextReadPointers(context, []).includes(base)); } }); + +test("bounded ready opening discloses omitted suggested outcome parents before dependent work", () => { + const identity = {schema_version: "quota_settlement_identity_v0", effect_id: "effect-1", + goal_id: "goal-1", agent_id: "agent-1", todo_id: "todo-1", turn_instance_id: "turn-1"}; + const makeOutcome = (id: string, description: string) => ({ + id, objective: `Verify ${id}.`, revision: 1, owner_agent_id: "agent-1", todo_ids: ["todo-1"], + sources: [{ref: `${id}:evidence`, summary: "Supporting evidence. ".repeat(120)}], + requirements: [{id: `${id}-req`, description, status: "unverified", planning_satisfied: false}], + }); + const baseContext = { + ok: true, goal_id: "goal-1", agent_id: "agent-1", agent_identity: {agent_id: "agent-1"}, + should_run: true, effective_action: "normal_run", normal_delivery_allowed: true, + selected_todo: {todo_id: "todo-1"}, heartbeat_receipt: {settlement_identity: identity}, + interaction_contract: { + schema_version: "loopx_interaction_contract_v0", + agent_channel: {delivery_allowed: true, work_context: {sources: [{ + source: "goal_acceptance", + reason: FULL_OUTCOME_READ_GUIDANCE, + content: { + status: "loaded", ok: true, read_complete: true, decision_read_from_provider: true, + legacy_fallback_used: false, provider_revision: "rev-1", + goal_acceptance_contract: {outcome_requirements: { + schema_version: "loopx_goal_outcomes_v0", current_lifetime: true, revision: 3, + outcomes: [ + makeOutcome("first", "Retain complete requirement A. ".repeat(260)), + makeOutcome("second", "Retain complete requirement B. ".repeat(260)), + makeOutcome("third", "Keep unrelated criterion separate."), + ], + }}, + outcome_context: { + schema_version: "outcome_context_navigation_v1", goal_id: "goal-1", agent_id: "agent-1", + todo_id: "todo-1", outcome_revision: 3, provider_revision: "rev-1", + coverage_complete: true, suggested_outcome_ids: ["first", "second"], + }, + }, + }]}}, + cli_channel: { + execution_preparation: {state: "ready", todo_id: "todo-1"}, + settlement_plan: {schema_version: "quota_settlement_plan_v2", identity, ordered_steps: []}, + }, + }, + }; + const prefix = "/interaction_contract/agent_channel/work_context/sources/0/content/goal_acceptance_contract/outcome_requirements/outcomes"; + const readInitialPlan = (budget: number, captureId: string) => { + const request = { + scope: {goal_id: "goal-1", agent_id: "agent-1", session_id: "session-1", context_epoch: "epoch-1"}, + capture_id: captureId, surface: "quota_packet", + context: baseContext, include_initial_read_plan: true, + native_projection: { + path: "projection.json", sha256: "a".repeat(64), initial_read_output_bytes: budget, + command_template: "loopx --format json quota context-read --capture-file projection.json --capture-sha256 " + "a".repeat(64) + " --select ''", + }, + }; + const {changes} = prepareProgressiveContextDelivery(request, [], ["ok", "goal_id", "effective_action"]) as { + changes: {path: (string | number)[]; from?: (string | number)[]; value?: unknown; remove?: true}[]; + }; + const applied: Record = structuredClone(request); + const get = (root: unknown, path: (string | number)[]) => + path.reduce((node, key) => (node as Record)[key], root); + for (const edit of changes) { + const parent = get(applied, edit.path.slice(0, -1)) as Record; + const key = edit.path.at(-1)!; + if (edit.remove) delete parent[key]; + else parent[key] = structuredClone(edit.from ? get(request, edit.from) : edit.value); + } + return applied.initial_read_plan as { + plan: {selections: {pointer: string}[]}; + deferred_suggested_outcomes?: string[]; + opening_context_instruction?: string; + }; + }; + const initialPlan = readInitialPlan(12000, "cap-1"); + const pointers = initialPlan.plan.selections.map(row => row.pointer); + assert.ok(!pointers.includes(prefix + "/0") && !pointers.includes(prefix + "/1")); + assert.ok(pointers.includes(prefix + "/0/id") && pointers.includes(prefix + "/0/objective") && pointers.includes(prefix + "/0/revision")); + assert.ok(pointers.includes(prefix + "/1/id") && pointers.includes(prefix + "/1/objective") && pointers.includes(prefix + "/1/revision")); + assert.deepEqual(initialPlan.deferred_suggested_outcomes, [prefix + "/0", prefix + "/1"]); + assert.ok(typeof initialPlan.opening_context_instruction === "string"); + assert.ok(!initialPlan.opening_context_instruction.includes("This view retains complete requirements")); + assert.ok(initialPlan.opening_context_instruction.includes("Before dependent work")); + assert.ok(initialPlan.opening_context_instruction.includes(prefix + "/0")); + assert.ok(initialPlan.opening_context_instruction.includes(prefix + "/1")); + assert.ok(initialPlan.opening_context_instruction.includes("recovery.command")); + assert.ok(initialPlan.opening_context_instruction.includes("remove /id")); + + const largerPlan = readInitialPlan(64000, "cap-2"); + const largerPointers = largerPlan.plan.selections.map(row => row.pointer); + assert.ok(largerPointers.includes(prefix + "/0") && largerPointers.includes(prefix + "/1")); + assert.equal(largerPlan.deferred_suggested_outcomes, undefined); + assert.equal(largerPlan.opening_context_instruction, undefined); +});