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
2 changes: 2 additions & 0 deletions loopx/cli_commands/todo.py
Original file line number Diff line number Diff line change
Expand Up @@ -686,6 +686,8 @@ def handle_todo_command(
claim_only=True,
manage_execution=(args.agent_id is not None and args.agent_id == args.claimed_by
and args.task_lease_idempotency_key is None and args.task_lease_expected_version is None),
allow_settled_execution_switch=(args.agent_id is not None and args.agent_id == args.claimed_by
and args.task_lease_idempotency_key is None and args.task_lease_expected_version is None),
claim_operation_id=args.claim_operation_id,
task_lease_idempotency_key=args.task_lease_idempotency_key,
task_lease_expected_version=args.task_lease_expected_version,
Expand Down
146 changes: 139 additions & 7 deletions loopx/control_plane/coordination/claim_execution.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@ import {leaseEpoch, leaseVersion, leaseIsActive, normalizeTtl, type LeaseRecord}
import {sameLeaseWorkspace, type LeaseWorkspace} from "../work_items/task_lease_workspace.ts";
import {leaseWriteRepository} from "../work_items/task_lease_repository.ts";
import {evaluateTaskLeaseAcquireDecision, materializeTaskLeaseAcquire} from "../work_items/task_lease_acquire_decision.ts";
import {decideTaskLeaseLifecycle, materializeTaskLeaseLifecycle} from "../work_items/task_lease_lifecycle_decision.ts";
import {decideTaskLeaseLifecycle, materializeTaskLeaseLifecycle,
releasedTaskLeaseRecord} from "../work_items/task_lease_lifecycle_decision.ts";
import {normalizeTodoRepository} from "../todos/work_requirements.ts";

export function claimExecutionReference(id: unknown, key: unknown, version: unknown): string | undefined {
if (id == null) return undefined;
Expand All @@ -26,6 +28,47 @@ type ExecutionInput = {goal_id: string; todo_id: string; actor_agent_id: string

export type ClaimWorkspaceObserver = (writeScopes: readonly string[]) => Promise<LeaseWorkspace>;

export const SETTLED_EXECUTION_SWITCH_PROOF_SCHEMA =
"todo_settled_execution_switch_proof_v0";

export interface ClaimExecutionSwitchProof extends JsonObject {
readonly schema_version: typeof SETTLED_EXECUTION_SWITCH_PROOF_SCHEMA;
readonly goal_id: string;
readonly source_todo_id: string;
readonly target_todo_id: string;
readonly agent_id: string;
readonly source_lease_idempotency_key: string;
readonly source_lease_version: number;
readonly source_lease_epoch: number;
readonly settlement_identity: JsonObject;
}

export type ClaimExecutionSwitchVerifier = (input: {
readonly goal_id: string;
readonly source_todo_id: string;
readonly target_todo_id: string;
readonly agent_id: string;
readonly source_lease_idempotency_key: string;
readonly source_lease_version: number;
readonly source_lease_epoch: number;
}) => Promise<ClaimExecutionSwitchProof>;

export interface PreparedClaimExecution {
readonly lease: LeaseRecord;
readonly changed: boolean;
readonly overlapAdvisories?: JsonObject[];
readonly releasedSourceLease?: LeaseRecord;
readonly switchProof?: ClaimExecutionSwitchProof;
}

export class ClaimExecutionSwitchRejected extends AuthorityStoreProtocolError {
readonly reasonCode: string;
constructor(reasonCode: string, message: string) {
super(message);
this.reasonCode = reasonCode;
}
}

/** A diagnostic distinction, never permission to renew or adopt another grant. */
export class ClaimExecutionUnavailable extends AuthorityStoreProtocolError {
readonly sameExecutionExpired: boolean;
Expand Down Expand Up @@ -99,8 +142,10 @@ export function maintainClaimExecution(head: JsonObject, input: ExecutionInput,
* transfer grant). Expired execution is reclaimable without the old process;
* acquisition still validates scope, eligibility and generation under one CAS. */
export async function prepareClaimExecution(head: JsonObject,
input: ExecutionInput & {operation_id: string; claimed_by: string},
observeWorkspace?: ClaimWorkspaceObserver): Promise<{lease: LeaseRecord; changed: boolean; overlapAdvisories?: JsonObject[]}> {
input: ExecutionInput & {operation_id: string; claimed_by: string;
allow_settled_execution_switch?: boolean},
observeWorkspace?: ClaimWorkspaceObserver,
verifySettledSwitch?: ClaimExecutionSwitchVerifier): Promise<PreparedClaimExecution> {
const index = indexCoordinationProjection(head, input.goal_id);
const facts = canonicalTaskLeaseAcquireFacts(index, input.goal_id, input.todo_id, input.registered_agents, input.now);
const current = facts.current;
Expand All @@ -121,14 +166,101 @@ export async function prepareClaimExecution(head: JsonObject,
owner: input.claimed_by, operation_id: input.operation_id})}`,
expected_version: current ? leaseVersion(current) : 0, ttl_seconds: normalizeTtl(null),
write_scopes: writeScopes, ...(workspace ? {write_workspace: workspace} : {})};
const decision = evaluateTaskLeaseAcquireDecision({handoff_mode: String(head.handoff_mode),
let decisionOtherLeases = facts.other_leases;
let decision = evaluateTaskLeaseAcquireDecision({handoff_mode: String(head.handoff_mode),
registered_agents: [...input.registered_agents], ...facts,
// Claim admission has already authorized this assignment. Acquire and the
// Todo owner change commit together; the old assignment is not a new gate.
todo: facts.todo === null ? null : {...facts.todo, claimed_by: input.claimed_by}, command});
let releasedSourceLease: LeaseRecord | undefined;
let switchProof: ClaimExecutionSwitchProof | undefined;
if (decision.outcome === "conflict" && decision.code === "write_scope_conflict" &&
input.allow_settled_execution_switch === true) {
if (!verifySettledSwitch) {
throw new ClaimExecutionSwitchRejected(
"settled_execution_switch_settlement_unavailable",
"Settled execution switch requires authoritative Turn settlement readback",
);
}
if (decision.conflict_indexes.length !== 1) {
throw new ClaimExecutionSwitchRejected(
"settled_execution_switch_ambiguous_source",
"Settled execution switch requires exactly one conflicting source execution",
);
}
const sourceIndex = decision.conflict_indexes[0]!;
const sourceFact = facts.other_leases[sourceIndex];
if (!sourceFact || sourceFact.owner !== input.claimed_by ||
!sourceFact.active || !sourceFact.effective) {
throw new ClaimExecutionSwitchRejected(
"settled_execution_switch_source_mismatch",
"Settled execution switch cannot release another Agent or an ineffective execution",
);
}
const sourceTodo = index.todos.get(sourceFact.todo_id);
const targetRepository = normalizeTodoRepository(todo.task_repository);
const sourceRepository = normalizeTodoRepository(sourceTodo?.task_repository);
if (targetRepository === null || sourceRepository === null ||
targetRepository.toLowerCase() !== sourceRepository.toLowerCase()) {
throw new ClaimExecutionSwitchRejected(
"settled_execution_switch_repository_mismatch",
"Settled execution switch requires source and target Todos in the same declared repository",
);
}
const sourceRaw = index.leases.get(sourceFact.todo_id);
if (!sourceRaw) {
throw new ClaimExecutionSwitchRejected(
"settled_execution_switch_source_missing",
"Settled execution switch source lease disappeared",
);
}
const sourceLease = canonicalTaskLease(
sourceRaw,
input.goal_id,
sourceFact.todo_id,
);
switchProof = await verifySettledSwitch({
goal_id: input.goal_id,
source_todo_id: sourceFact.todo_id,
target_todo_id: input.todo_id,
agent_id: input.claimed_by,
source_lease_idempotency_key: String(sourceLease.idempotency_key),
source_lease_version: leaseVersion(sourceLease),
source_lease_epoch: leaseEpoch(sourceLease),
});
if (switchProof.schema_version !== SETTLED_EXECUTION_SWITCH_PROOF_SCHEMA ||
switchProof.goal_id !== input.goal_id ||
switchProof.source_todo_id !== sourceFact.todo_id ||
switchProof.target_todo_id !== input.todo_id ||
switchProof.agent_id !== input.claimed_by ||
switchProof.source_lease_idempotency_key !== sourceLease.idempotency_key ||
switchProof.source_lease_version !== leaseVersion(sourceLease) ||
switchProof.source_lease_epoch !== leaseEpoch(sourceLease) ||
switchProof.settlement_identity === null ||
typeof switchProof.settlement_identity !== "object") {
throw new ClaimExecutionSwitchRejected(
"settled_execution_switch_proof_mismatch",
"Settled execution switch proof does not match the requested handoff",
);
}
const remaining = facts.other_leases.filter((_, index) => index !== sourceIndex);
decisionOtherLeases = remaining;
decision = evaluateTaskLeaseAcquireDecision({
handoff_mode: String(head.handoff_mode),
registered_agents: [...input.registered_agents],
...facts,
other_leases: remaining,
todo: facts.todo === null ? null : {...facts.todo, claimed_by: input.claimed_by},
command,
});
if (decision.outcome === "apply") {
releasedSourceLease = releasedTaskLeaseRecord(sourceLease, input.now);
}
}
if (decision.outcome !== "apply") throw new AuthorityStoreProtocolError(`Task claim execution rejected: ${decision.code}`);
const overlapAdvisories = (decision.overlap_advisory_indexes ?? []).map(index => ({
todo_id: facts.other_leases[index].todo_id, owner: facts.other_leases[index].owner ?? null,
write_scopes: facts.other_leases[index].write_scopes, reason: "independent_worktree_integration_overlap"}));
return {lease: materializeTaskLeaseAcquire(input, command, decision, input.now), changed: true, overlapAdvisories};
todo_id: decisionOtherLeases[index].todo_id, owner: decisionOtherLeases[index].owner ?? null,
write_scopes: decisionOtherLeases[index].write_scopes, reason: "independent_worktree_integration_overlap"}));
return {lease: materializeTaskLeaseAcquire(input, command, decision, input.now),
changed: true, overlapAdvisories, releasedSourceLease, switchProof};
}
6 changes: 6 additions & 0 deletions loopx/control_plane/coordination/local_authority.py
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,7 @@ def claim_canonical_todo_if_promoted(
task_lease_idempotency_key: str | None = None,
task_lease_expected_version: int | None = None,
manage_execution: bool = False,
allow_settled_execution_switch: bool = False,
project: Path | None = None,
state_file: Path | None = None,
) -> dict[str, Any]:
Expand Down Expand Up @@ -191,6 +192,11 @@ def claim_canonical_todo_if_promoted(
else f"todo-claim:{goal_id}:{todo_id}:{uuid4().hex}"
),
**({"manage_execution": True} if manage_execution else {}),
**(
{"allow_settled_execution_switch": True}
if allow_settled_execution_switch
else {}
),
**({"write_worktree": str(worktree)} if worktree is not None else {}),
"lease_request": (
{
Expand Down
15 changes: 14 additions & 1 deletion loopx/control_plane/coordination/local_authority_runtime.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import {requirePromotionRegisteredAgents} from "./shadow_registry_source.ts";
import {verifySettledExecutionSwitch} from "./settled_execution_switch.ts";
import {verifyReentrySettlement} from "./todo_terminal_reentry.ts";
import {readPromotionReceipt, commitPromotionAndReadBack} from './promotion_receipt.ts';
import {reviewedPromotionPlan, promotionPlanDigest, decodeReviewedPromotionOperation, REVIEWED_PROMOTION_OPERATION_RESULT_SCHEMA} from './reviewed_promotion_plan.ts';
Expand Down Expand Up @@ -1058,6 +1059,12 @@ export async function claimLocalCoordinationTodo(
}
if (Object.hasOwn(input, "manage_execution") && input.schema_version !== LOCAL_COORDINATION_TODO_MANAGED_CLAIM_REQUEST_SCHEMA)
throw new TypeError("Managed execution requires claim request v2");
if (Object.hasOwn(input, "allow_settled_execution_switch") &&
(input.schema_version !== LOCAL_COORDINATION_TODO_MANAGED_CLAIM_REQUEST_SCHEMA ||
input.manage_execution !== true ||
typeof input.allow_settled_execution_switch !== "boolean")) {
throw new TypeError("Settled execution switch requires a managed claim boolean");
}
const worktree = input.write_worktree;
if (worktree !== undefined && (input.schema_version !== LOCAL_COORDINATION_TODO_MANAGED_CLAIM_REQUEST_SCHEMA ||
input.manage_execution !== true || typeof worktree !== "string" || !isAbsolute(worktree))) {
Expand Down Expand Up @@ -1111,9 +1118,15 @@ export async function claimLocalCoordinationTodo(
operation_id: requireAuthorityStoreId(input.operation_id, "operation id"),
lease_request: leaseRequest,
...(input.manage_execution === undefined ? {} : {manage_execution: input.manage_execution as boolean}),
...(input.allow_settled_execution_switch === undefined ? {} : {
allow_settled_execution_switch: input.allow_settled_execution_switch as boolean,
}),
dry_run: input.dry_run === true,
now: claimObservedAt(input.observed_at),
}, authoritySourcesCurrent, claimWorkspaceObserver(worktree));
}, authoritySourcesCurrent, claimWorkspaceObserver(worktree),
input.allow_settled_execution_switch === true
? request => verifySettledExecutionSwitch(root, request)
: undefined);
return {
...result,
source_authority: sourceAuthority,
Expand Down
113 changes: 113 additions & 0 deletions loopx/control_plane/coordination/settled_execution_switch.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
/** Qualify the previous Todo Turn before one explicit managed claim atomically
* releases its overlapping lease and acquires the target execution. */
import {jsonObject} from "../runtime_decode.ts";
import {
QUOTA_SETTLEMENT_READBACK_REQUEST_SCHEMA,
readQuotaSettlementFromSnapshot,
readQuotaSettlementSnapshot,
} from "../quota/settlement_readback.ts";
import {heartbeatReceiptFactFromEvent} from "../quota/heartbeat_receipt_identity.ts";
import {
ClaimExecutionSwitchRejected,
SETTLED_EXECUTION_SWITCH_PROOF_SCHEMA,
type ClaimExecutionSwitchProof,
} from "./claim_execution.ts";

function nonEmpty(value: unknown): string | null {
return typeof value === "string" && value.trim() ? value.trim() : null;
}

/** The newest Turn ever bound to the source Todo must be the settled Turn.
* This prevents an older successful receipt from releasing work while a newer
* source Turn is still open. Reentries of the same Turn do not change order. */
function latestBoundSourceTurn(
events: readonly Record<string, unknown>[],
goalId: string,
agentId: string,
todoId: string,
): string | null {
const ordered: string[] = [];
const seen = new Set<string>();
for (const event of events) {
if (event.event_kind !== "quota_should_run" || event.goal_id !== goalId ||
event.agent_id !== agentId) continue;
const fact = heartbeatReceiptFactFromEvent(event);
const turn = nonEmpty(fact.run_id);
if (fact.todo_id !== todoId || turn === null || seen.has(turn)) continue;
seen.add(turn);
ordered.push(turn);
}
return ordered.at(-1) ?? null;
}

export async function verifySettledExecutionSwitch(
runtimeRoot: string,
input: {
readonly goal_id: string;
readonly source_todo_id: string;
readonly target_todo_id: string;
readonly agent_id: string;
readonly source_lease_idempotency_key: string;
readonly source_lease_version: number;
readonly source_lease_epoch: number;
},
): Promise<ClaimExecutionSwitchProof> {
if (input.source_todo_id === input.target_todo_id) {
throw new ClaimExecutionSwitchRejected(
"settled_execution_switch_same_todo",
"Settled execution switch requires distinct source and target Todos",
);
}
const snapshot = await readQuotaSettlementSnapshot(runtimeRoot, input.goal_id);
const sourceTurn = latestBoundSourceTurn(
snapshot.events,
input.goal_id,
input.agent_id,
input.source_todo_id,
);
if (sourceTurn === null) {
throw new ClaimExecutionSwitchRejected(
"settled_execution_switch_source_turn_missing",
"Settled execution switch requires a durable source Todo Turn binding",
);
}
const readback = readQuotaSettlementFromSnapshot({
schema_version: QUOTA_SETTLEMENT_READBACK_REQUEST_SCHEMA,
runtime_root: runtimeRoot,
goal_id: input.goal_id,
agent_id: input.agent_id,
todo_id: input.source_todo_id,
turn_instance_id: sourceTurn,
replan_obligation_id: null,
infer_turn_instance_id: false,
allow_unbound_binding: false,
}, snapshot);
const identityBundle = jsonObject(readback.identity);
const identityResult = jsonObject(identityBundle?.result);
const identity = jsonObject(identityResult?.value);
const progress = jsonObject(readback.progress);
const settlementOk = jsonObject(jsonObject(readback.settlement)?.payload)?.ok === true;
if (readback.found !== true || !identity || !settlementOk ||
progress?.schema_version !== "quota_settlement_progress_v0" ||
progress.state !== "settled" || identity.goal_id !== input.goal_id ||
identity.agent_id !== input.agent_id ||
identity.todo_id !== input.source_todo_id ||
identity.turn_instance_id !== sourceTurn ||
identity.replan_obligation_id != null) {
throw new ClaimExecutionSwitchRejected(
"settled_execution_switch_unsettled_source",
"Settled execution switch requires the latest source Todo Turn's complete writeback and quota receipts",
);
}
return {
schema_version: SETTLED_EXECUTION_SWITCH_PROOF_SCHEMA,
goal_id: input.goal_id,
source_todo_id: input.source_todo_id,
target_todo_id: input.target_todo_id,
agent_id: input.agent_id,
source_lease_idempotency_key: input.source_lease_idempotency_key,
source_lease_version: input.source_lease_version,
source_lease_epoch: input.source_lease_epoch,
settlement_identity: identity,
};
}
Loading
Loading