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
21 changes: 21 additions & 0 deletions docs/architecture/rfcs/monorepo-distribution-split-v0.md
Original file line number Diff line number Diff line change
Expand Up @@ -407,6 +407,27 @@ retained core capability (D2).
recovery semantics from the unified controller/executor design. Required
reads and source completeness remain binding.

A Worker launched by a built-in Host receives task requirements, scoped
authority, and the original read route. Todo-authoring directions and the
ordinary delivery mode's quota spend instructions stay with the outer executor
in the complete captured contract. Work, repair, and stop conditions remain
available to the Worker. Unconfigured memory recall and empty pre-turn
observations expose their current scoped status in this view. Their full
receipts stay in the original capture, with observations, failures, required
reads and unfamiliar data still delivered when present.

Work context carries the selected task, scoped User Todos and their read
provenance. For both registered Todo read formats, the field dictionary stays
with the canonical Todo reader. Existing captures remain available under
their original digests.

An ordinary admitted task presents its work, scope and validation to the Worker.
Matching ready lease preparations stay with launch and settlement. Unready,
inconsistent and unfamiliar preparations remain visible.
Operators read release readiness and completed-work maintenance through
quota/status or the original capture. Task context omits these maintenance
directions.

Context reuse must be invalidated by relevant source/requirement revisions,
session generation changes, compaction or lost acknowledgements. A smaller
packet cannot be treated as proof the executor has the prior context. Recover
Expand Down
14 changes: 14 additions & 0 deletions docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -281,6 +281,20 @@ capability 包直接采用现有 `extension.toml` 契约,不做扩展。唯一
4. **提供上下文:** 为所选工作和 executor 渲染现有受治理工作契约,复用统一 Controller/Executor
设计的首次完整、后续差量与恢复语义。Required reads 和来源完整性仍有约束力。

内置 Host 启动的 Worker 收到任务要求、权限范围和原始依据的读取路径。Todo 写入指令
和普通执行模式的扣额说明留在外层执行器持有的完整 capture 中。Worker 仍能读取工作、
修复和停止条件。未配置的记忆召回和没有结果的启动前观察只向 Worker 提供带作用域的
当前状态,完整回执留在原始 capture 中。有实际结果、失败、必读材料或未知字段时,
Worker 仍会收到对应内容。

工作上下文携带选中的任务、作用域内的 User Todo 和读取依据。两种已登记的 Todo 读取
格式都把字段表留在 canonical Todo 读取入口。已有 capture 仍可按原摘要读取。

普通任务准入后,Worker 收到当前任务、范围与验证要求。完全一致的就绪租约记录留在
启动和结算入口,未就绪、有差异或格式未知的记录仍在任务视图中可见。
操作方通过 quota/status 或原始 capture 读取发布资格和已完成工作的维护提醒。
任务上下文省略这些维护指令。

相关来源/要求版本变化、Session generation 变化、compaction 或 ACK 丢失时,必须使上下文复用失效。
不能因为 packet 更小,就认为 executor 已掌握前文。连续性未知时走所属契约的恢复路径。
Capability 指令仅在适用时提供;authority 不能从 prompt 文字推导。
Expand Down
24 changes: 23 additions & 1 deletion docs/reference/protocols/loopx-turn-v0.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,20 @@ the effect projection, scheduler/automation execution data and
`interaction_contract.cli_channel` remain with the outer executor. The model
view resolves existing replan authoring and Explore guidance references before
hiding their outer owner, preserving the original scalar values and text.
Operators can read release readiness and completed Todo archive warnings in
quota/status and the original capture. The built-in Worker view omits these
maintenance directions.
Recognized unconfigured recall keeps its Goal, Agent and disabled status.
Known empty pre-turn observations keep their hook, capability and status.
The full readbacks stay with the executor. Available context, failed
observations, required reads and extended readbacks reach the Worker intact.
Work-context delivery keeps scoped Todo records, their provider revision and
record digest. The canonical Todo reader supplies the field dictionary for
both registered read formats. Unknown formats retain their supplied metadata.
For ordinary admitted work, matching recognized ready lease preparations stay
with the launcher and settlement reader. The Worker retains the admitted task,
scope, required reads and validation conditions. Unready, differing and
extended preparations stay in the task view.
The model receives the original `source_decision_hash`, reader references and
`source_schema_version`; that hash commits the original source, not the task
view. Inline task context does not require a filesystem read of a private
Expand All @@ -115,7 +129,15 @@ their renderer.
范围、执行要求和未知新增信息。来源绑定、effect projection、scheduler/automation
执行数据及 `interaction_contract.cli_channel` 留在外层执行器。
来源中指向外层 owner 的 replan 编写和 Explore 指导引用在隐藏该 owner 前展开,
保留原始标量和文本。模型仍收到原始
保留原始标量和文本。操作方在 quota/status 和原始 capture 中读取发布资格和已完成
Todo 归档提醒。内置 Worker 视图省略这两条维护指令。能识别的未配置召回保留
Goal、Agent 和停用状态。已知的空观察
保留钩子、能力和状态。完整回执留在外层执行器。有可用上下文、观察失败、必需读取
或扩展回执时,Worker 仍收到完整内容。工作上下文保留作用域内的 Todo、读取版本和记录摘要。
两种已登记格式的字段表由 canonical Todo 读取入口提供,未知格式保留其元数据。
普通任务准入后,完全一致且可识别的就绪租约记录留在启动和结算入口。Worker 保留已准入
任务、范围、必需读取与验证条件。未就绪、有差异或带扩展字段的记录继续交付给 Worker。
模型仍收到原始
`source_decision_hash`、reader 引用和 `source_schema_version`;该 hash 绑定原始
来源,不绑定任务视图。已内联的任务上下文不要求 sandbox 读取不可访问的私有 capture,
缺少必需证据仍暂停依赖该证据的工作。此呈现不是 adapter 请求,也不授予权限、结算或
Expand Down
36 changes: 28 additions & 8 deletions loopx/control_plane/capability_hooks.ts
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,10 @@ const TURN_START_RESULT_FIELDS = new Set([
"provider_payload_returned",
"error_code",
]);
const TURN_START_OBSERVATION_FLAGS = [
"agent_read_required", "external_reads_performed", "external_writes_performed",
"local_private_state_mutated", "private_content_returned", "provider_payload_returned",
];
const POST_WRITEBACK_REGISTRATION_FIELDS = new Set([
"schema_version",
"hook_id",
Expand Down Expand Up @@ -555,14 +559,7 @@ export function validateTurnStartHookInvocation(input: {
if (observationCount < 0 || observationCount > 10_000) {
throw new Error("turn-start hook observation_count is invalid");
}
for (const field of [
"agent_read_required",
"external_reads_performed",
"external_writes_performed",
"local_private_state_mutated",
"private_content_returned",
"provider_payload_returned",
]) {
for (const field of TURN_START_OBSERVATION_FLAGS) {
const uncertainEffect = result[field] === null &&
["failed", "partial", "unavailable"].includes(status) &&
["external_reads_performed", "local_private_state_mutated"].includes(field);
Expand Down Expand Up @@ -660,6 +657,29 @@ export function projectTurnStartUnavailableContext(value: unknown): JsonObject |
};
}

/** Keep current empty/not-applicable observations visible without their effect receipts. */
export function projectEmptyTurnStartObservations(value: unknown): JsonObject | null {
const dispatch = jsonObject(value);
if (!dispatch || Object.keys(dispatch).length !== 7 ||
dispatch.schema_version !== "loopx_turn_start_capability_hook_dispatch_v1" ||
dispatch.phase !== "turn_start" || !Array.isArray(dispatch.results) ||
dispatch.registered_count !== dispatch.results.length || dispatch.invoked_count !== dispatch.results.length ||
!Array.isArray(dispatch.required_reads) || dispatch.required_reads.length !== 0 ||
!Array.isArray(dispatch.failures) || dispatch.failures.length !== 0) return null;
const results: JsonObject[] = [];
for (const raw of dispatch.results) {
const row = jsonObject(raw);
if (!row || Object.keys(row).length !== TURN_START_RESULT_FIELDS.size ||
row.schema_version !== TURN_START_HOOK_RESULT_SCHEMA_VERSION || row.phase !== "turn_start" ||
typeof row.hook_id !== "string" || typeof row.capability_id !== "string" ||
(row.status !== "empty" && row.status !== "not_applicable") ||
row.observation_count !== 0 || row.error_code !== null ||
!TURN_START_OBSERVATION_FLAGS.every(flag => row[flag] === false)) return null;
results.push({hook_id: row.hook_id, capability_id: row.capability_id, status: row.status});
}
return {results};
}

export function validatePostWritebackHookRegistration(
value: unknown,
): JsonObject & {
Expand Down
3 changes: 2 additions & 1 deletion loopx/control_plane/quota/context_delivery.ts
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,8 @@ export function compactTodoContextSource(content: JsonObject): JsonObject {
}
const authority = jsonObject(content.authority_read);
const model = jsonObject(authority?.todo_read_model);
if (model?.schema_version === COORDINATION_STATE_CONTRACT.todo_read_record.schema_version
if (model && (model.schema_version === COORDINATION_STATE_CONTRACT.todo_read_record.schema_version
|| model.schema_version === COORDINATION_STATE_CONTRACT.todo_domain_record.schema_version)
&& Array.isArray(model.contract_fields)
&& model.contract_fields.every(field => typeof field === "string")) {
const {contract_fields: _dictionary, ...metadata} = model;
Expand Down
85 changes: 82 additions & 3 deletions loopx/control_plane/quota/turn_envelope.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import {EXECUTION_PREPARATION_SCHEMA_VERSION} from "../work_items/execution_preparation.ts";
import {EXECUTION_PREPARATION_SCHEMA_VERSION, isKnownReadyLeasePreparation} from "../work_items/execution_preparation.ts";
import {capturedContextSelection} from "./context_selection.ts";
import {contextReadSectionDigests, initialContextReadPointers, prepareProgressiveContext, prepareProgressiveContextDelivery,
progressiveContextPlan, scopedReplanYardstickReversal,
Expand Down Expand Up @@ -30,7 +30,7 @@ import {
type JsonObject,
} from "../effect_program.ts";
import { EffectRuntimeRequestError } from "../effect_runtime_errors.ts";
import { projectTurnStartUnavailableContext } from "../capability_hooks.ts";
import { projectEmptyTurnStartObservations, projectTurnStartUnavailableContext } from "../capability_hooks.ts";
import { jsonObject, requireBoolean, requireJsonObject, requireNonEmptyString, requireStringLiteral,
sourceNumberTokens } from "../runtime_decode.ts";
import { projectPendingCapabilityIntent } from "../work_items/pending_capability_intent.ts";
Expand Down Expand Up @@ -1867,19 +1867,98 @@ export function completeHostSource(request: JsonObject): {decision: JsonObject;
return {decision, projection};
}

/** Collapse the unconfigured recall readback. Known active, failed and extended
* records still carry their full context. This only classifies presentation. */
function disabledRewardMemoryView(value: unknown): JsonObject | null {
const readback = jsonObject(value);
const experiment = jsonObject(readback?.experiment);
const route = jsonObject(experiment?.config_runtime_route);
if (!readback || readback.status !== "disabled" || !experiment || !route ||
typeof readback.goal_id !== "string" || typeof readback.agent_id !== "string" ||
typeof route.registry_role !== "string" || typeof route.runtime_scope !== "string" ||
!Array.isArray(experiment.host_coverage)) return null;
const coverage = experiment.host_coverage;
if (!coverage.every(value => {
const host = jsonObject(value);
return host && Object.keys(host).length === 3 && typeof host.host_id === "string" &&
typeof host.automatic_recall === "string" && typeof host.automatic_ingest === "string";
})) return null;
const {goal_id, agent_id, status} = readback;
const expected = {
schema_version: "agent_turn_recall_v0", ok: true, status, goal_id, agent_id,
surface_id: "agent_workflow.turn_admission", host_wiring: "agent_turn_admission",
reason_code: null, context: null, automatic_recall: false, provider_call_count: 0,
fail_open: true, provider_failure_is_user_gate: false, grants_new_action_authority: false,
quota_spend_performed: false, external_writes_performed: false, suppress_external_sinks: true,
experiment: {
schema_version: "reward_memory_experiment_status_v1", ok: true, status, goal_id, agent_id,
experimental: false, enabled: false, available: false, configured_for_agent: false,
config_pointer_registered: false, automatic_ingest: false, automatic_recall: false,
fail_open: true, external_writes_performed: false, host_coverage: coverage,
config_runtime_route: {
schema_version: "reward_memory_config_runtime_route_v0", registry_source: "invoked_registry",
registry_role: route.registry_role, runtime_scope: route.runtime_scope, goal_source: "registry.goals",
config_source: "goal_repo_relative_config_pointer", readback_status: "not_attempted",
exact_readback_verified: false,
},
},
};
return isDeepStrictEqual(value, expected) ? {status, goal_id, agent_id} : null;
}

/** Task presentation is derived only after full-source validation. Keep task
* facts (including unknown additions) and original scalar carriers intact;
* scheduler/effect instructions remain with the outer executor. This view is
* not a replacement source or a permission/settlement contract. */
function hostModelContextChanges(decision: JsonObject): JsonObject {
const context = {...decision};
// Maintenance warnings are actionable in the operator's quota/status view.
for (const field of ["schema_version", "contract_binding", "projection_envelope",
"scheduler_hint", "automation_cadence_readback", "automation_liveness",
"scheduler_execution_context"]) {
"scheduler_execution_context", "promotion_readiness_warning", "completed_todo_archive_warning"]) {
delete context[field];
}
// Todo-authoring directions belong to the outer executor. Preserve other
// fields because task context may depend on future additions.
const writeHint = object(decision.todo_write_hint);
const hintCount = Object.keys(writeHint).length;
for (const key of ["rule", "section", "agent_todo_command_template",
"user_action_command_template", "user_gate_command_template"]) {
if (typeof writeHint[key] === "string") delete writeHint[key];
}
const retainedHints = Object.keys(writeHint).length;
if (retainedHints !== hintCount) {
if (retainedHints) context.todo_write_hint = writeHint;
else delete context.todo_write_hint;
}
const heartbeat = object(decision.heartbeat_recommendation);
// Other modes can include read, repair or wait conditions inside spend_policy.
if (decision.normal_delivery_allowed === true &&
heartbeat.recommended_mode === "steering_audit_then_one_step" &&
typeof heartbeat.spend_policy === "string") {
delete heartbeat.spend_policy;

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 保留普通工作段的范围说明

内置 Host 用已验证的完整 v1 来源启动普通 steering_audit_then_one_step 工作段。 原 capture 保留模式及范围说明。当前 Worker 收到同一个模式名,但用于区分工作段和一次操作的说明消失。 把工作规模说明交给现有 Worker 执行指导,外层继续持有扣额规则。沿当前已签名任务和 execution_profile 确定规模,复用现有来源。 在 File 和 SQLite 中捕获已装 Core 实际发给 Worker 的普通输入,同时检查扣额规则与三条写命令退到外层、工作规模说明仍可见、原 capture 和一次结算完整。

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 保留普通 Worker 的工作范围说明。两套已装 Core 的原始 capture 都包含范围解释。主干 Worker 也能看到它,候选 Worker 只保留模式名和通用任务字段。 在同一来源上按职责交付普通工作段的规模说明,外层保留扣额政策与 Todo 写入。用已有任务和执行范围 owner 提供 Worker 指导。

context.heartbeat_recommendation = heartbeat;
}
const emptyObservations = projectEmptyTurnStartObservations(decision.turn_start_capability_hook_dispatch);
if (emptyObservations) context.turn_start_capability_hook_dispatch = emptyObservations;
const disabledRecall = disabledRewardMemoryView(decision.reward_memory_recall);
if (disabledRecall) context.reward_memory_recall = disabledRecall;
const interaction = {...object(decision.interaction_contract)};
const agent = object(interaction.agent_channel);
// Start and settlement use the original preparation. Keep unfamiliar
// records and disagreements visible even when the rest of the task is ready.
const preparation = agent.execution_preparation;
if (decision.ok === true && decision.should_run === true &&
decision.normal_delivery_allowed === true && decision.effective_action === EffectiveAction.NORMAL_RUN &&
agent.must_attempt === true && agent.delivery_allowed === true && object(agent.work_context).complete === true &&
object(interaction.user_channel).action_required === false && decision.replan_action_packet == null &&
object(decision.goal_boundary).handoff_mode === "hard_lease" &&
isKnownReadyLeasePreparation(preparation, object(decision.agent_identity).agent_id, selectedWorkTodoId(decision)) &&
isDeepStrictEqual(decision.execution_preparation, preparation) &&
isDeepStrictEqual(object(interaction.cli_channel).execution_preparation, preparation)) {
delete context.execution_preparation;
delete agent.execution_preparation;
}
// The complete source may share task authoring/evidence with its effect
// owner. Resolve those existing references before omitting that owner.
if (Object.hasOwn(agent, "work_context")) interaction.agent_channel = {...agent,
Expand Down
31 changes: 26 additions & 5 deletions loopx/control_plane/work_items/execution_preparation.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
import {isDeepStrictEqual} from "node:util";
import {HANDOFF_MODES} from "../coordination/handoff_mode_vocabulary.ts";
import {HANDOFF_MODE_RETIRED_REASON, retiredHandoffModeRejection} from "../coordination/handoff_mode_policy.ts";
import type {JsonObject} from "../effect_program.ts";
import {EffectRuntimeRequestError} from "../effect_runtime_errors.ts";
import {
jsonObject,
optionalNonEmptyString,
requireBoolean,
requireJsonObject,
Expand Down Expand Up @@ -53,6 +55,29 @@ function claimAction(goalId: string, todoId: string, agentId: string): JsonObjec
};
}

function readyLeasePreparation(base: JsonObject, leaseProof: unknown): JsonObject {
return {...base, state: "ready", delivery_allowed: true,
reason_code: "matching_active_task_lease",
// Capture the admitted generation once. Recovery must not borrow a replacement.
...(leaseProof === undefined ? {} : {lease_proof: leaseProof})};
}

/** The Worker does not need the launcher's lease transaction record after admission. */
export function isKnownReadyLeasePreparation(
value: unknown, agentId: unknown, todoId: string | null,
): boolean {
const record = jsonObject(value);
const proof = jsonObject(record?.lease_proof);
const key = proof?.idempotency_key, version = proof?.expected_version;
if (typeof agentId !== "string" || !agentId || !todoId || typeof key !== "string" ||
!key || key !== key.trim() || typeof version !== "number" ||
!Number.isSafeInteger(version) || version < 1) return false;
return isDeepStrictEqual(record, readyLeasePreparation({
schema_version: EXECUTION_PREPARATION_SCHEMA_VERSION,
todo_id: todoId, agent_id: agentId, handoff_mode: "hard_lease",
}, {idempotency_key: key, expected_version: version}));
}

/** Decide whether the selected Todo can execute under its current hard lease.
*
* This is a read-model decision. It never acquires a lease. A capable Host
Expand Down Expand Up @@ -124,11 +149,7 @@ export function projectExecutionPreparation(value: unknown): JsonObject {
reason_code: "active_lease_owned_by_other_agent", ...(owner ? {owner} : {}),
reason: "The selected Todo has an active lease owned by another agent; do not take over its execution."};
}
return {...base, state: "ready", delivery_allowed: true,
reason_code: "matching_active_task_lease",
// Capture the admitted generation once. Recovery must not borrow a
// replacement lease after the original Host result was produced.
...(active[0].lease_proof === undefined ? {} : {lease_proof: active[0].lease_proof})};
return readyLeasePreparation(base, active[0].lease_proof);
}

const prior = leases[0];
Expand Down
Loading
Loading