Skip to content
Merged
26 changes: 26 additions & 0 deletions docs/product/runtimes/codex-cli/codex-cli-automation-driver.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,32 @@ and `--host-adapter-command-json ...` for a compatible Trae or
another CLI after its wrapper implements the typed stdin/stdout contract in the
host-neutral protocol.

The built-in Codex result schema accepts `validated_completion` for a fully
delivered selected Todo. After independent validation, the adapter invokes the
existing Todo lifecycle, including its controller-declared validator, before
accountable refresh and one quota debit. It retains the original launch lease
generation in the Turn journal for completion and cached-result recovery;
lease loss or a newer same-Agent generation cannot authorize the old result.
`validated_progress` remains partial progress and never silently completes work.
For a predeclared terminal Todo, closeout after debit uses the original
completion receipt and closes the same Turn.
Goal acceptance remains a separate owner check.

After independent validation, the adapter checks the original Goal's running
authority before settling either result. When the owner stops the Goal during
that validation, the Turn retains its validation checkpoint and leaves the
Todo and quota untouched.

内置 Codex 的结果格式支持 `validated_completion`,用于已满足全部要求的已选 Todo。
独立验证通过后,adapter 先调用现有 Todo 生命周期及 controller 声明的完成验证器,
再写回可核算进展并扣额一次。Turn journal 保留启动时的原租约代次,完成和缓存结果
恢复都使用该代次;租约丢失或同 Agent 的新代次不能授权旧结果。`validated_progress`
仍表示部分进展,不会被静默升级为完成。对于预声明的终态 Todo,扣额后按原完成回执
收尾同一轮 Turn。Goal 验收仍由原 owner 单独检查。

独立验证结束后,adapter 会在结算前重新检查原 Goal 的运行权限。验证期间若 owner
停止 Goal,Turn 保留验证记录,Todo 和额度不变。

That wrapper is deliberately thin: it translates one Turn request into one
bounded Agent CLI invocation, preserves only an opaque local resume handle, and
returns one typed candidate result. LoopX remains responsible for the control
Expand Down
38 changes: 37 additions & 1 deletion loopx/cli_commands/turn_run_once.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
from functools import partial
import sys as _sys
from collections.abc import Callable, Mapping
from contextlib import contextmanager, nullcontext
from pathlib import Path
from typing import TYPE_CHECKING as _TYPE_CHECKING
from typing import Any
Expand Down Expand Up @@ -476,8 +477,29 @@ def terminal_closeout(
effect_ref: str,
) -> dict[str, object]:
require_effect_ref(effect_ref, SettlementStepKind.TERMINAL_CLOSEOUT)
if args.host == "codex-cli":
# Builtin completion has already retired the original lease.
# Verify the exact terminal receipt; never start another completion.
observed = terminal_closeout_resolver(effect_ref)
receipt = observed.get("payload")
if observed.get("kind") == "committed" and isinstance(receipt, dict):
return receipt
return {
"ok": False,
"appended": False,
"reason": observed.get("reason") or "Builtin terminal completion receipt is missing",
}
return todo_completion(result, effect_ref=effect_ref)

def codex_writeback(
result: dict[str, object], *, effect_ref: str,
) -> dict[str, object]:
# Accountable refresh requires durable controller validation even for
# a predeclared terminal Todo. Other hosts keep their existing order.
if result.get("result_kind") == "validated_completion":
return completion_writeback(result, effect_ref=effect_ref)
return writeback(result, effect_ref=effect_ref)

def current_status() -> dict[str, object]:
return collect_turn_status_payload(
args,
Expand Down Expand Up @@ -847,6 +869,19 @@ def settlement_admission():
return request_settlement_lifetime(request_locator, settlement_identity,
registry_path=registry_path, runtime_root=runtime_root, workspace=project)

if args.host == "codex-cli" and goal_admission is not None:
request_lifetime = settlement_admission or nullcontext

@contextmanager
def codex_settlement_admission():
with request_lifetime():
# Independent validation can outlive the running Goal.
# Check the original authority before any settlement effect.
goal_admission.require_running(operation="codex_cli_turn_settle")
yield

settlement_admission = codex_settlement_admission

def on_managed_start_admitted() -> None:
if settlement_identity.request_subject is not None:
require_current_request_operation(request_locator, settlement_identity,
Expand Down Expand Up @@ -898,7 +933,8 @@ def on_managed_start_admitted() -> None:
retry_failed=bool(args.retry_failed_turn),
task_validator=task_validator,
settlement_admission=settlement_admission,
writeback=writeback if args.execute else None,
writeback=(codex_writeback if args.host == "codex-cli" else writeback)
if args.execute else None,
completion_writeback=completion_writeback if args.execute else None,
completion_intent=completion_intent if args.execute else None,
terminal_closeout=terminal_closeout if args.execute else None,
Expand Down
3 changes: 2 additions & 1 deletion loopx/control_plane/turn_driver/codex_cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@
CODEX_STDIO_MCP_SERVER_SCHEMA_VERSION = "codex_stdio_mcp_server_v0"
CODEX_CLI_RESULT_KINDS = (
"validated_progress",
"validated_completion",
"repair_required",
"replan_required",
"user_action_required",
Expand Down Expand Up @@ -395,7 +396,7 @@ def _render_prompt(request: Mapping[str, Any], *, checked: Mapping[str, Any] | N
("Use task_context for the admitted work. Its interaction_contract.agent_channel carries work_context, required_reads and primary_action; the outer adapter retains the complete original source and Core effect instructions. " if complete else ("Use turn_authority as the verified authority for this Turn. " if staged else "Use the TurnEnvelope as the source of truth. "))
+ "Read work_context and remaining required_reads before primary_action; do not repeat fulfilled reads; perform work only when its contract allows it. The selected Todo summary is not its full requirements, and completing that work does not prove Goal completion.",
"Do not write LoopX state, spend quota, or apply scheduler changes; the adapter owns those effects.",
"Return only the schema-constrained result. For validated_progress, repair_required, or replan_required, fill every material field with public-safe evidence.",
"Return only the schema-constrained result. Use validated_completion when the selected Todo's full requirements are met; the adapter runs its declared completion validation and durably completes it before accountable writeback. Use validated_progress for partial work; progress alone never completes a Todo. Neither result proves Goal closure. For validated_progress, validated_completion, repair_required, or replan_required, fill every material field with public-safe evidence.",
"For those material results, preserve the actual delivery_batch_scale and delivery_outcome selected from the signed execution_profile's work and outcome requirements. Return work_evidence and validation_evidence as separate non-empty arrays of short public-safe strings; name the artifact or observed work in the first and the independent command or readback in the second. For legacy requests without execution_profile, use null when evidence is not supplied. For stop results, set both evidence fields to null.",
"For those material results, set path_delta_mode=material_replan and result_kind=replan_required only when this Turn changes a prior assumption, route, scope, acceptance rule, or stops prior work; then provide a complete bounded agent vision packet with goal_path_delta_v0 in agent_vision_json and leave vision_unchanged_reason empty.",
"For routine continuation, retry, successor creation, or no-change replanning, explicitly set path_delta_mode=unchanged. Reuse the current checkpoint with vision_unchanged_reason and empty agent_vision_json, or record new progress/completion evidence in a fresh agent_vision_json packet with path_delta.outcome continue or no_change and empty vision_unchanged_reason.",
Expand Down
Loading
Loading