diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.md index 6e5521ac0a..20adb30b33 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.md @@ -489,6 +489,13 @@ defaults or a new LoopX model loop. Pinned sources are in Appendix C. ## 7. Safety, privacy, and compatibility +Ordinary C1 composition and replay use shared Explore guidance and exact +context references. An empty read with graph and planning disabled returns +the existing disabled view before loading the graph projector. A scoped +Explore read loads Yardstick when its graph is available and the Goal enables +evaluation. Settings, evidence identities, and recovery remain with the +current Goal and Explore owners. + - **Default-off / feature-off parity:** absent `loopx-workspace` or capability packages behave like the existing extension off state (I4). No command silently falls back to another implementation. diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md index 2303929af4..677f8fbaf7 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md @@ -345,6 +345,10 @@ minimal 包含持久 shell、图像读取与 compaction。SDK minimal 还提供 ## 7. 安全、隐私与兼容 +普通 C1 组装和重放沿用 Explore 的共享指引及精确上下文引用。图和规划关闭时, +空读取在加载图投影前返回既有的关闭状态。有范围的 Explore 读取在图可用且 Goal +启用评估时加载 Yardstick。设置、证据身份和恢复继续由当前 Goal 与 Explore 负责。 + - **默认关闭 / 功能关闭一致性:** 缺失 `loopx-workspace` 或 capability 包时,行为等同现有 extension off state(I4)。没有命令会静默回退到另一实现。 - **公开/私有边界:** 不变。`loopx check` 继续扫描每个包;移动文件不改变其扫描类别。 - **旧读者/写者:** import shim(I3)覆盖已建立的公开 Python import。console script 保持名字;`loopx` meta-package 让 `pip install loopx` 在一个 minor 版本内行为完全一致。 diff --git a/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md index 9b0295d724..c4cab9b373 100644 --- a/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md +++ b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md @@ -889,6 +889,11 @@ capability. Disabling removes the extra ordinary-Turn cue and rejects new captures before primary commit, while historical findings and successful exact replays remain readable. +An Explore context read loads the Yardstick projector when the graph is +available and the setting is enabled. Ordinary C1 reads use the shared +guidance and exact references for the captured context. Prior decisions stay +bound to their original source when selected or replayed. + The existing Research finding reader exposes the recorded target, outcome/proxy metrics, source, next action and cost bound. The ordinary task-scoped Explore context projects only that Todo's current target, a short next-choice cue and diff --git a/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md index 2d85b732ff..59952e0a0c 100644 --- a/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md +++ b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md @@ -655,6 +655,9 @@ Explore evidence 可用;开启该设置不启动工作或自动开启其他 ca 关闭后移除普通 Turn 的新增提示,并在主提交前拒绝新 capture;历史 finding 及成功的精确重放仍可读。 +Explore 读取在图可用且设置已开启时加载 Yardstick 投影。普通 C1 使用共享指引和 +精确引用读取捕获的上下文。选中或重放既有决策时仍绑定原始来源。 + 既有 Research finding reader 展示记录的目标、成果/代理指标、来源、下一步和成本边界。 普通 task-scoped Explore context 只投影该 Todo 当前目标、下一选择短提示和反证引用。 既有 question-scoped 扩读命令返回完整决策、精确 profile 的反馈和前次执行归属; diff --git a/loopx/control_plane/capabilities/explore_context_delivery.ts b/loopx/control_plane/capabilities/explore_context_delivery.ts new file mode 100644 index 0000000000..421ad64404 --- /dev/null +++ b/loopx/control_plane/capabilities/explore_context_delivery.ts @@ -0,0 +1,250 @@ +/** Explore guidance and exact references shared by captured and live context. */ +import {isDeepStrictEqual} from "node:util"; +import type {JsonObject} from "../effect_program.ts"; +import {jsonObject, requireJsonObject, requireNonEmptyString, requireStringArray} from "../runtime_decode.ts"; +import {contextSourceIdentity} from "../quota/diagnostic_projection.ts"; + +export function exploreTurnContextBoundary(): JsonObject { + return {read_only: true, changes_configuration: false, writes_evidence: false, + claims_todos: false, starts_agents: false, changes_quota: false}; +} + +/** A disabled opening from the live reader has no graph, plan or page to project. + * Other requests retain the full reader's validation and replay rules. */ +export function projectEmptyExploreTurnContext(params: JsonObject): JsonObject | undefined { + if (params.graph_enabled !== false || jsonObject(params.harness_gate)?.enabled !== false || + (params.result_limit ?? 3) !== 3 || (params.result_offset ?? 0) !== 0 || + params.result_node != null || params.result_revision != null || params.review_pages !== undefined || + params.todo_id != null || + (params.include_finding_digests != null && typeof params.include_finding_digests !== "boolean")) { + return undefined; + } + const projection = jsonObject(params.projection), plan = jsonObject(params.plan); + if (!projection || !plan || Object.keys(projection).length || Object.keys(plan).length) return undefined; + const goal = requireNonEmptyString(params.goal_id, "goal_id"); + const agent = requireNonEmptyString(params.agent_id, "agent_id"); + requireStringArray(params.route, "route"); + return {ok: true, goal_id: goal, agent_id: agent, graph_enabled: false, harness_enabled: false, + graph: null, harness: null, boundary: exploreTurnContextBoundary()}; +} + +export const EXPLORE_RESULT_ATTACHMENT_SCHEMA = "explore_result_attachment_v0"; +export const EXPLORE_PATH_DELTA_ATTACHMENT_SCHEMA = "explore_result_from_path_delta_v0"; +export const EXPLORE_EXECUTION_FROM_FINDING_SCHEMA = "explore_execution_from_finding_v0"; +export const FINDING_EVIDENCE_SELECTION = "finding"; +export const QUESTION_LIMIT = 180; +export const APPLICABILITY_LIMIT = 200; +// The complete scoped finding fits the result-log owner: 160 revision + 200 +// applicability + 320 observation + 1200 interpretation + four labels < 2000. +export const EXPLORE_WRITEBACK_SUMMARY_LIMIT = 2000; +// These clauses constrain evidence collection, route selection or lease lifetime +// before authoring. Keep them in the entry even when attachment syntax is read +// later. The full standalone guidance retains its original order and bytes. +const EXPLORE_BEFORE_WORK = { + openLease: "When execution fencing applies to an open Todo, keep its claimed execution through refresh-state and Explore graph/Todo-link delivery; end that execution only after explore_result_delivery.ok=true. The writeback resolves and checks execution proof internally.", + leaseRecovery: "If execution has ended or expired, re-enter the normal guard and todo claim path before retrying; a stale task reference cannot resume execution.", + completedLease: "When execution fencing applies to a completed Todo, only its existing owner-scoped additive evidence-link exception is permitted. Writeback checks retained execution history internally; this grants no new execution authority.", + deliveryReplay: "An exact replay of already-successful delivery is readback-only and needs no new claim; unfinished delivery still requires current ownership and execution checks.", + optionalFinding: "Routine work needs no attachment; do not invent findings.", + optionalCapture: "Capture is optional, not a settlement obligation.", + negativeEvidence: "A stopped route does not imply refuted status, and a score alone does not prove refutation.", + rawEvidence: "Keep raw logs local.", + measurementConditions: "Attach measurements when an evaluation returns quantitative evidence: include its metric, unit, explicit direction, candidate and result reference. Use the same comparison_scope only for the same task, evaluator, model/resource budget and evaluation conditions; keep distinct workloads or evaluation conditions in their own profiles.", + measurementProvenance: "input_revision identifies the evaluated task/data revision; evaluation_ref identifies the evaluator/scoring protocol version. Keep both stable across candidates only when those conditions are verified unchanged. Put candidate code/artifact revisions in candidate_ref and individual evaluation/submission receipts in evidence_ref, not in the comparison keys. The measurement input revision and evidence reference must match this finding. If comparability is unknown, keep results separate and explain the uncertainty; never invent a shared version to obtain a delta.", + feedbackBeforeWork: "Use null for an unmeasured value. Read measurement_feedback before repeating a measured route: compare the latest recorded candidate with its same-scope best, investigate regressions and retain useful alternatives; a score does not itself close or authorize work.", + inTurnFeedback: "For an open claimed Todo, a result can inform the next action in this Turn: record this same attachment with `loopx explore finding --result-json FILE` and its current Goal, Agent, Todo and Turn. The receipt returns scoped feedback without settling or spending.", + executionEvidence: "When an experiment has execution evidence, attach execution_observation: preserve its exact candidate and input version, planned versus executed method, change reason and measured resources. Missing measurements are null, not zero. A finding source digest is not an executable digest. Result evidence must name the candidate it actually evaluated, including delayed or regressing results; it does not certify current workspace quality or Goal completion.", +}; +export function exploreBeforeWorkGuidance(): string { + return Object.values(EXPLORE_BEFORE_WORK).join(" "); +} +export function exploreInTurnFeedbackGuidance(): string { + return EXPLORE_BEFORE_WORK.inTurnFeedback; +} +/** Shared point-of-use guidance; optional metadata never changes settlement. */ +export function exploreResultWritebackAffordance(): JsonObject { + return { + capability_id: "explore", + option: "--explore-result-json ", + inline_option: "--agent-vision-json ", + inline_field: "explore_result", + attachment_schema: EXPLORE_RESULT_ATTACHMENT_SCHEMA, + required: false, + path_delta_attachment_schema: EXPLORE_PATH_DELTA_ATTACHMENT_SCHEMA, + path_delta_attachment_template: { + schema_version: EXPLORE_PATH_DELTA_ATTACHMENT_SCHEMA, + question: "", applicability: "", input_revision: "", status: "", + }, + linked_question_attachment_template: { + schema_version: EXPLORE_PATH_DELTA_ATTACHMENT_SCHEMA, + node_id: "", input_revision: "", status: "", + }, + optional_question_evolution_example: { + question_update: {status: "resolved"}, + relations: [{to_node: "", edge_type: "depends_on", + summary: ""}], + }, + optional_measurement_example: {measurements: [{metric: "accuracy", value: 0.82, + unit: "ratio", higher_is_better: true, comparison_scope: "validation:fixed-budget-v1", + input_revision: "dataset-v1", evaluation_ref: "evaluator:validation-v1", + candidate_ref: "candidate:revision-2", evidence_ref: "result:validation-2"}]}, + optional_execution_observation_example: {execution_observation: { + schema_version: EXPLORE_EXECUTION_FROM_FINDING_SCHEMA, + candidate_sha256: "a".repeat(64), planned_method_id: "bounded-probe", executed_method_id: "bounded-probe", + change_reason: null, elapsed_seconds: 0.125, limit_seconds: 10, search_iterations: 2, + stop_reason: "iteration_limit", evidence_refs: FINDING_EVIDENCE_SELECTION, + }}, + guidance: [ + "After validating reusable evidence, put explore_result in the vision JSON already submitted with --agent-vision-json.", + EXPLORE_BEFORE_WORK.openLease, + EXPLORE_BEFORE_WORK.leaseRecovery, + EXPLORE_BEFORE_WORK.completedLease, + EXPLORE_BEFORE_WORK.deliveryReplay, + "Prefer path_delta_attachment_template when this same packet contains an evidence-linked path_delta: supply the question, applicability, tested input revision and explicit finding status.", + "For a new question, omit node_id: the hook derives its identity from the exact question and applicability, creates it and links this Todo; no explore node call is needed.", + "To add to a known question, reuse its returned node_id and canonical scope.", + "At a meaningful experimental conclusion or route change, reuse that question and optionally add question_update and relations in this same result; no separate cleanup turn is needed.", + "Use question_update.status=resolved only when the scoped question is answered (including a negative answer), dead_end only for an explicitly stopped route, or exploring/open for remaining work; blocked requires blocked_reason.", + "Keep the answer, scope limits and next discriminating check in the existing interpretation or path_delta; finding status never determines question status.", + "Relations point from this question to an existing same-Goal node and require an evidence-backed summary; temporal order alone establishes neither dependency nor benefit.", + "Only the question's recorded owner may evolve it. Omission preserves the existing question state; preserve its exact title and applicability, and reopen explicitly only when new evidence warrants it.", + "The hook reuses the complete observation and route decision.", + "For an existing question linked to this Todo, use linked_question_attachment_template: omit both question and applicability to reuse its canonical scope.", + "New or unlinked questions still require explicit scope; input_revision and status are never inferred.", + "Choose status explicitly: tentative for unresolved interpretation, insufficient evidence or failed prerequisites; confirmed when evidence supports the stated conclusion within its applicability; refuted when evidence contradicts that conclusion within its applicability. Evidence references, a successful check, a score or a route decision alone do not choose the status.", + "Separate established observations from unresolved broader claims in interpretation; state what remains unknown and the next discriminating check when useful. Revisit the linked question at a meaningful conclusion using question_update; do not keep it open solely because the overall Goal is unfinished, or close it merely because a finding is confirmed.", + "If path_delta also references local files, explicitly select its opaque identifiers with optional evidence_refs; selected refs must occur in this same path_delta.", + "Without a selection, all refs must be opaque identifiers.", + "Otherwise fill attachment_template, inline or via --explore-result-json.", + "Matching sources coalesce; conflicts reject.", + EXPLORE_BEFORE_WORK.optionalFinding, + EXPLORE_BEFORE_WORK.optionalCapture, + EXPLORE_BEFORE_WORK.negativeEvidence, + EXPLORE_BEFORE_WORK.rawEvidence, + EXPLORE_BEFORE_WORK.measurementConditions, + EXPLORE_BEFORE_WORK.measurementProvenance, + "To reuse explicitly verified conditions, optional measurement_context supplies comparison_scope, input_revision and evaluation_ref for observations that omit those fields; conflicting fields reject. CLI finding accepts the same context via --measurement-context-json. This copies declared conditions, not proof of comparability.", + EXPLORE_BEFORE_WORK.feedbackBeforeWork, + EXPLORE_BEFORE_WORK.inTurnFeedback, + EXPLORE_BEFORE_WORK.executionEvidence, + `Use optional_execution_observation_example when the execution used this finding's tested input. Omit the nested input_revision and set its evidence_refs to "${FINDING_EVIDENCE_SELECTION}" only if all finding refs describe this execution, or list the exact opaque subset. Supply the actual candidate and execution facts. A released result still needs its result_ref and matching result_candidate_sha256.`, + `Questions allow ${QUESTION_LIMIT} characters, applicability ${APPLICABILITY_LIMIT}, observations 320, and interpretations 1200. The complete scoped summary is preserved within 2000 characters.`, + ].join(" "), + // Blank evidence fields deliberately fail validation until the caller + // supplies observed facts. Goal/Agent/Todo/Turn bind in ordinary writeback; + // a source-code revision here would not establish the tested input revision. + attachment_template: { + schema_version: EXPLORE_RESULT_ATTACHMENT_SCHEMA, + question: "", applicability: "", input_revision: "", + observation: "", interpretation: "", status: "", evidence_refs: [], + }, + }; +} + +/** Reusable evidence and instructions in this owner's read model. Current + * selection, eligibility, source revisions and pagination stay outside this + * split. Exact array edits retain every change, including its status, + * provenance and applicability; no timestamp or revision is normalized away. */ +export function exploreReusableContextPaths(content: JsonObject = {}): (string | number)[][] { + return [ + ...["recent_nodes", "recent_findings", "writeback_results", "measurement_feedback", "work_measurements", "work_yardsticks", "work_yardstick_capture", + "path_delta_attachment_template", "linked_question_attachment_template", + "optional_question_evolution_example", "optional_execution_observation_example", "result_writeback_guidance", + "result_attachment_template", "optional_measurement_example", "measurement_guidance", + "record_node_template", "record_finding_template", "guidance", + "result_writeback_option", "result_writeback_inline_option", "result_writeback_inline_field", + "result_attachment_schema", "path_delta_attachment_schema"].map(key => ["graph", key]), + ["harness", "guidance"], ["harness", "link_evidence_template"], + // The branch's identity, selection, status and resume facts stay fresh. + // Its evidence audit is a read model, not an eligibility or execution grant. + ...["selected_branches", "comparison_candidates", "rejected_candidates", "frontier"].flatMap(lane => { + const branches = (content.harness as JsonObject | undefined)?.[lane]; + return Array.isArray(branches) ? branches.flatMap((branch, index) => + branch !== null && typeof branch === "object" && !Array.isArray(branch) + && typeof branch.todo_id === "string" && branch.todo_id + ? [["harness", lane, index, "typed_evidence_audit"]] : []) : []; + }), + ]; +} + +/** The same authoring projection is used inline and by the captured writer. */ +export function resultWritebackFields(writeback: JsonObject): JsonObject { + return { + result_writeback_option: writeback.option, + result_writeback_inline_option: writeback.inline_option, + result_writeback_inline_field: writeback.inline_field, + result_attachment_schema: writeback.attachment_schema, + path_delta_attachment_schema: writeback.path_delta_attachment_schema, + path_delta_attachment_template: writeback.path_delta_attachment_template, + linked_question_attachment_template: writeback.linked_question_attachment_template, + optional_question_evolution_example: writeback.optional_question_evolution_example, + optional_execution_observation_example: writeback.optional_execution_observation_example, + result_writeback_guidance: writeback.guidance, + result_attachment_template: writeback.attachment_template, + optional_measurement_example: writeback.optional_measurement_example, + }; +} + +/** Reference only exact, recognized authoring already delivered by the captured + * settlement plan. Unknown/custom guidance stays inline: no prose classification + * or migration of old obligations to a later phase. Evidence and paging stay put. + */ +function withoutCurrentResultWriteback(content: JsonObject, attachment: JsonObject): JsonObject | null { + const rawGraph = content.graph; + if (content.ok !== true || content.graph_enabled !== true || !rawGraph || typeof rawGraph !== "object" || Array.isArray(rawGraph) || + attachment.capability_id !== "explore" || attachment.guidance !== exploreResultWritebackAffordance().guidance) return null; + const graph = requireJsonObject(rawGraph, "Explore graph"); + const fields = resultWritebackFields(attachment); + if (Object.entries(fields).some(([key, value]) => value === undefined || !isDeepStrictEqual(graph[key], value))) return null; + const retained = {...graph}; + for (const key of Object.keys(fields)) delete retained[key]; + return retained; +} + +export function referenceExploreResultWriteback(content: JsonObject, attachment: JsonObject, read: string): JsonObject { + const retained = withoutCurrentResultWriteback(content, attachment); + return retained === null ? content : {...content, graph: {...retained, + result_writeback_guidance: exploreBeforeWorkGuidance(), result_writeback_read: read}}; +} + +/** A pure replan has no admitted Todo for refresh-state's result attachment. + * Preserve evidence collection obligations and the independent graph commands; + * do not advertise unusable authoring or invent a later attachment authority. + * The caller must establish the autonomous settlement binding first. + */ +export function omitUnboundExploreResultWriteback(content: JsonObject): JsonObject { + const retained = withoutCurrentResultWriteback(content, exploreResultWritebackAffordance()); + return retained === null ? content : {...content, graph: {...retained, + result_writeback_guidance: exploreBeforeWorkGuidance() + + " The refresh-state Explore attachment requires an admitted Todo and is unavailable for this pure replan. " + + "The independent graph record commands remain available for reusable evidence."}}; +} + +/** Only the final display shares the successful hook's identical input. The + * complete attachment stays inline; durable intents and retry inputs never change. */ +export function referenceExploreResultDelivery(source: JsonObject, numberTokens?: unknown): JsonObject { + const attachment = jsonObject(source.explore_result), delivery = jsonObject(source.explore_result_delivery); + const hook = jsonObject(delivery?.hook); + if (attachment?.schema_version !== EXPLORE_RESULT_ATTACHMENT_SCHEMA || + Object.hasOwn(attachment, "attachment_ref") || delivery?.ok !== true || + delivery.retryable !== false || delivery.primary_committed !== true || + hook?.schema_version !== "loopx_post_writeback_capability_hook_dispatch_v0" || + hook.phase !== "post_writeback" || !Array.isArray(hook.failures) || hook.failures.length || + !Array.isArray(hook.intents)) return source; + const identity = contextSourceIdentity(source, numberTokens); + const original = identity(attachment, ["explore_result"]); + const reference = {attachment_ref: "$.explore_result"}; + if (Buffer.byteLength(JSON.stringify({attachment})) <= Buffer.byteLength(JSON.stringify(reference))) return source; + let changed = false; + const intents = hook.intents.map((value, index) => { + const intent = jsonObject(value), payload = jsonObject(intent?.payload); + if (intent?.schema_version !== "loopx_capability_intent_v0" || + intent.intent_kind !== "explore.result_ingestion" || !payload || + Object.hasOwn(payload, "attachment_ref") || !jsonObject(payload.attachment) || + identity(payload.attachment, ["explore_result_delivery", "hook", "intents", index, "payload", "attachment"]) !== original) return value; + const {attachment: _duplicate, ...other} = payload; + changed = true; + return {...intent, payload: {...other, ...reference}}; + }); + return changed ? {...source, explore_result_delivery: {...delivery, hook: {...hook, intents}}} : source; +} diff --git a/loopx/control_plane/capabilities/explore_result_writeback.ts b/loopx/control_plane/capabilities/explore_result_writeback.ts index b516801b05..83ccb9dc56 100644 --- a/loopx/control_plane/capabilities/explore_result_writeback.ts +++ b/loopx/control_plane/capabilities/explore_result_writeback.ts @@ -3,126 +3,14 @@ import {createHash} from "node:crypto"; import type {JsonObject} from "../effect_program.ts"; import {EffectRuntimeRequestError} from "../effect_runtime_errors.ts"; import {jsonObject, requireJsonObject, requireNonEmptyString, requireStringArray, requireStringLiteral} from "../runtime_decode.ts"; -import {contextSourceIdentity} from "../quota/diagnostic_projection.ts"; +import {APPLICABILITY_LIMIT, EXPLORE_EXECUTION_FROM_FINDING_SCHEMA, EXPLORE_PATH_DELTA_ATTACHMENT_SCHEMA, + EXPLORE_RESULT_ATTACHMENT_SCHEMA, FINDING_EVIDENCE_SELECTION, QUESTION_LIMIT} from "./explore_context_delivery.ts"; import {normalizeGoalPathDelta} from "../goals/vision_checkpoint.ts"; import {EXPLORE_EXECUTION_OBSERVATION_SCHEMA, normalizeExploreExecutionObservation} from "./explore_execution_observation.ts"; import {isExploreEvidenceRef} from "./explore_evidence_ref.ts"; import {normalizeWorkYardstickDecision} from "../work_items/yardstick_decision.ts"; import {normalizeExploreMeasurements} from "./explore_measurements.ts"; -export const EXPLORE_RESULT_ATTACHMENT_SCHEMA = "explore_result_attachment_v0"; -export const EXPLORE_PATH_DELTA_ATTACHMENT_SCHEMA = "explore_result_from_path_delta_v0"; -const EXPLORE_EXECUTION_FROM_FINDING_SCHEMA = "explore_execution_from_finding_v0"; -const FINDING_EVIDENCE_SELECTION = "finding"; -const QUESTION_LIMIT = 180; -const APPLICABILITY_LIMIT = 200; -// The complete scoped finding fits the result-log owner: 160 revision + 200 -// applicability + 320 observation + 1200 interpretation + four labels < 2000. -export const EXPLORE_WRITEBACK_SUMMARY_LIMIT = 2000; -// These clauses constrain evidence collection, route selection or lease lifetime -// before authoring. Keep them in the entry even when attachment syntax is read -// later. The full standalone guidance retains its original order and bytes. -const EXPLORE_BEFORE_WORK = { - openLease: "When execution fencing applies to an open Todo, keep its claimed execution through refresh-state and Explore graph/Todo-link delivery; end that execution only after explore_result_delivery.ok=true. The writeback resolves and checks execution proof internally.", - leaseRecovery: "If execution has ended or expired, re-enter the normal guard and todo claim path before retrying; a stale task reference cannot resume execution.", - completedLease: "When execution fencing applies to a completed Todo, only its existing owner-scoped additive evidence-link exception is permitted. Writeback checks retained execution history internally; this grants no new execution authority.", - deliveryReplay: "An exact replay of already-successful delivery is readback-only and needs no new claim; unfinished delivery still requires current ownership and execution checks.", - optionalFinding: "Routine work needs no attachment; do not invent findings.", - optionalCapture: "Capture is optional, not a settlement obligation.", - negativeEvidence: "A stopped route does not imply refuted status, and a score alone does not prove refutation.", - rawEvidence: "Keep raw logs local.", - measurementConditions: "Attach measurements when an evaluation returns quantitative evidence: include its metric, unit, explicit direction, candidate and result reference. Use the same comparison_scope only for the same task, evaluator, model/resource budget and evaluation conditions; keep distinct workloads or evaluation conditions in their own profiles.", - measurementProvenance: "input_revision identifies the evaluated task/data revision; evaluation_ref identifies the evaluator/scoring protocol version. Keep both stable across candidates only when those conditions are verified unchanged. Put candidate code/artifact revisions in candidate_ref and individual evaluation/submission receipts in evidence_ref, not in the comparison keys. The measurement input revision and evidence reference must match this finding. If comparability is unknown, keep results separate and explain the uncertainty; never invent a shared version to obtain a delta.", - feedbackBeforeWork: "Use null for an unmeasured value. Read measurement_feedback before repeating a measured route: compare the latest recorded candidate with its same-scope best, investigate regressions and retain useful alternatives; a score does not itself close or authorize work.", - inTurnFeedback: "For an open claimed Todo, a result can inform the next action in this Turn: record this same attachment with `loopx explore finding --result-json FILE` and its current Goal, Agent, Todo and Turn. The receipt returns scoped feedback without settling or spending.", - executionEvidence: "When an experiment has execution evidence, attach execution_observation: preserve its exact candidate and input version, planned versus executed method, change reason and measured resources. Missing measurements are null, not zero. A finding source digest is not an executable digest. Result evidence must name the candidate it actually evaluated, including delayed or regressing results; it does not certify current workspace quality or Goal completion.", -}; -export function exploreBeforeWorkGuidance(): string { - return Object.values(EXPLORE_BEFORE_WORK).join(" "); -} -export function exploreInTurnFeedbackGuidance(): string { - return EXPLORE_BEFORE_WORK.inTurnFeedback; -} -/** Shared point-of-use guidance; optional metadata never changes settlement. */ -export function exploreResultWritebackAffordance(): JsonObject { - return { - capability_id: "explore", - option: "--explore-result-json ", - inline_option: "--agent-vision-json ", - inline_field: "explore_result", - attachment_schema: EXPLORE_RESULT_ATTACHMENT_SCHEMA, - required: false, - path_delta_attachment_schema: EXPLORE_PATH_DELTA_ATTACHMENT_SCHEMA, - path_delta_attachment_template: { - schema_version: EXPLORE_PATH_DELTA_ATTACHMENT_SCHEMA, - question: "", applicability: "", input_revision: "", status: "", - }, - linked_question_attachment_template: { - schema_version: EXPLORE_PATH_DELTA_ATTACHMENT_SCHEMA, - node_id: "", input_revision: "", status: "", - }, - optional_question_evolution_example: { - question_update: {status: "resolved"}, - relations: [{to_node: "", edge_type: "depends_on", - summary: ""}], - }, - optional_measurement_example: {measurements: [{metric: "accuracy", value: 0.82, - unit: "ratio", higher_is_better: true, comparison_scope: "validation:fixed-budget-v1", - input_revision: "dataset-v1", evaluation_ref: "evaluator:validation-v1", - candidate_ref: "candidate:revision-2", evidence_ref: "result:validation-2"}]}, - optional_execution_observation_example: {execution_observation: { - schema_version: EXPLORE_EXECUTION_FROM_FINDING_SCHEMA, - candidate_sha256: "a".repeat(64), planned_method_id: "bounded-probe", executed_method_id: "bounded-probe", - change_reason: null, elapsed_seconds: 0.125, limit_seconds: 10, search_iterations: 2, - stop_reason: "iteration_limit", evidence_refs: FINDING_EVIDENCE_SELECTION, - }}, - guidance: [ - "After validating reusable evidence, put explore_result in the vision JSON already submitted with --agent-vision-json.", - EXPLORE_BEFORE_WORK.openLease, - EXPLORE_BEFORE_WORK.leaseRecovery, - EXPLORE_BEFORE_WORK.completedLease, - EXPLORE_BEFORE_WORK.deliveryReplay, - "Prefer path_delta_attachment_template when this same packet contains an evidence-linked path_delta: supply the question, applicability, tested input revision and explicit finding status.", - "For a new question, omit node_id: the hook derives its identity from the exact question and applicability, creates it and links this Todo; no explore node call is needed.", - "To add to a known question, reuse its returned node_id and canonical scope.", - "At a meaningful experimental conclusion or route change, reuse that question and optionally add question_update and relations in this same result; no separate cleanup turn is needed.", - "Use question_update.status=resolved only when the scoped question is answered (including a negative answer), dead_end only for an explicitly stopped route, or exploring/open for remaining work; blocked requires blocked_reason.", - "Keep the answer, scope limits and next discriminating check in the existing interpretation or path_delta; finding status never determines question status.", - "Relations point from this question to an existing same-Goal node and require an evidence-backed summary; temporal order alone establishes neither dependency nor benefit.", - "Only the question's recorded owner may evolve it. Omission preserves the existing question state; preserve its exact title and applicability, and reopen explicitly only when new evidence warrants it.", - "The hook reuses the complete observation and route decision.", - "For an existing question linked to this Todo, use linked_question_attachment_template: omit both question and applicability to reuse its canonical scope.", - "New or unlinked questions still require explicit scope; input_revision and status are never inferred.", - "Choose status explicitly: tentative for unresolved interpretation, insufficient evidence or failed prerequisites; confirmed when evidence supports the stated conclusion within its applicability; refuted when evidence contradicts that conclusion within its applicability. Evidence references, a successful check, a score or a route decision alone do not choose the status.", - "Separate established observations from unresolved broader claims in interpretation; state what remains unknown and the next discriminating check when useful. Revisit the linked question at a meaningful conclusion using question_update; do not keep it open solely because the overall Goal is unfinished, or close it merely because a finding is confirmed.", - "If path_delta also references local files, explicitly select its opaque identifiers with optional evidence_refs; selected refs must occur in this same path_delta.", - "Without a selection, all refs must be opaque identifiers.", - "Otherwise fill attachment_template, inline or via --explore-result-json.", - "Matching sources coalesce; conflicts reject.", - EXPLORE_BEFORE_WORK.optionalFinding, - EXPLORE_BEFORE_WORK.optionalCapture, - EXPLORE_BEFORE_WORK.negativeEvidence, - EXPLORE_BEFORE_WORK.rawEvidence, - EXPLORE_BEFORE_WORK.measurementConditions, - EXPLORE_BEFORE_WORK.measurementProvenance, - "To reuse explicitly verified conditions, optional measurement_context supplies comparison_scope, input_revision and evaluation_ref for observations that omit those fields; conflicting fields reject. CLI finding accepts the same context via --measurement-context-json. This copies declared conditions, not proof of comparability.", - EXPLORE_BEFORE_WORK.feedbackBeforeWork, - EXPLORE_BEFORE_WORK.inTurnFeedback, - EXPLORE_BEFORE_WORK.executionEvidence, - `Use optional_execution_observation_example when the execution used this finding's tested input. Omit the nested input_revision and set its evidence_refs to "${FINDING_EVIDENCE_SELECTION}" only if all finding refs describe this execution, or list the exact opaque subset. Supply the actual candidate and execution facts. A released result still needs its result_ref and matching result_candidate_sha256.`, - `Questions allow ${QUESTION_LIMIT} characters, applicability ${APPLICABILITY_LIMIT}, observations 320, and interpretations 1200. The complete scoped summary is preserved within 2000 characters.`, - ].join(" "), - // Blank evidence fields deliberately fail validation until the caller - // supplies observed facts. Goal/Agent/Todo/Turn bind in ordinary writeback; - // a source-code revision here would not establish the tested input revision. - attachment_template: { - schema_version: EXPLORE_RESULT_ATTACHMENT_SCHEMA, - question: "", applicability: "", input_revision: "", - observation: "", interpretation: "", status: "", evidence_refs: [], - }, - }; -} - const FIELDS = ["schema_version", "node_id", "question", "applicability", "input_revision", "observation", "interpretation", "status", "evidence_refs", "question_update", "relations", "execution_observation", "measurements", "measurement_context", "work_yardstick_decision"]; // Reuse the persisted Explore node/edge vocabulary, distinct from finding status. @@ -364,32 +252,3 @@ export function produceExploreResultIntent(params: JsonObject): JsonObject { idempotency_key: `explore-result:${key}`, source_receipt_id: source, payload: {attachment}, requested_write_scope: []}}; } - -/** Only the final display shares the successful hook's identical input. The - * complete attachment stays inline; durable intents and retry inputs never change. */ -export function referenceExploreResultDelivery(source: JsonObject, numberTokens?: unknown): JsonObject { - const attachment = jsonObject(source.explore_result), delivery = jsonObject(source.explore_result_delivery); - const hook = jsonObject(delivery?.hook); - if (attachment?.schema_version !== EXPLORE_RESULT_ATTACHMENT_SCHEMA || - Object.hasOwn(attachment, "attachment_ref") || delivery?.ok !== true || - delivery.retryable !== false || delivery.primary_committed !== true || - hook?.schema_version !== "loopx_post_writeback_capability_hook_dispatch_v0" || - hook.phase !== "post_writeback" || !Array.isArray(hook.failures) || hook.failures.length || - !Array.isArray(hook.intents)) return source; - const identity = contextSourceIdentity(source, numberTokens); - const original = identity(attachment, ["explore_result"]); - const reference = {attachment_ref: "$.explore_result"}; - if (Buffer.byteLength(JSON.stringify({attachment})) <= Buffer.byteLength(JSON.stringify(reference))) return source; - let changed = false; - const intents = hook.intents.map((value, index) => { - const intent = jsonObject(value), payload = jsonObject(intent?.payload); - if (intent?.schema_version !== "loopx_capability_intent_v0" || - intent.intent_kind !== "explore.result_ingestion" || !payload || - Object.hasOwn(payload, "attachment_ref") || !jsonObject(payload.attachment) || - identity(payload.attachment, ["explore_result_delivery", "hook", "intents", index, "payload", "attachment"]) !== original) return value; - const {attachment: _duplicate, ...other} = payload; - changed = true; - return {...intent, payload: {...other, ...reference}}; - }); - return changed ? {...source, explore_result_delivery: {...delivery, hook: {...hook, intents}}} : source; -} diff --git a/loopx/control_plane/capabilities/explore_turn_context.ts b/loopx/control_plane/capabilities/explore_turn_context.ts index edf8e85c3d..284ecca4a9 100644 --- a/loopx/control_plane/capabilities/explore_turn_context.ts +++ b/loopx/control_plane/capabilities/explore_turn_context.ts @@ -1,5 +1,4 @@ /** Compact Explore read model. Existing Graph/Harness owners retain all gates. */ -import {isDeepStrictEqual} from "node:util"; import {createHash} from "node:crypto"; import type {JsonObject} from "../effect_program.ts"; import {EffectRuntimeRequestError} from "../effect_runtime_errors.ts"; @@ -7,89 +6,13 @@ import {requireInteger, requireJsonObject, requireNonEmptyString, requireStringA import {parseTodoTimestampMicros} from "../runtime_timestamp.ts"; import {PLANNING_TODO_ID} from "../work_items/planning_relations.ts"; -import {EXPLORE_WRITEBACK_SUMMARY_LIMIT, exploreBeforeWorkGuidance, exploreInTurnFeedbackGuidance, exploreResultWritebackAffordance} from "./explore_result_writeback.ts"; +import {EXPLORE_WRITEBACK_SUMMARY_LIMIT, exploreBeforeWorkGuidance, exploreInTurnFeedbackGuidance, + exploreResultWritebackAffordance, exploreTurnContextBoundary, resultWritebackFields} from "./explore_context_delivery.ts"; import {EXPLORE_RESULT_PAGE_MAX, normalizeExploreResultPages} from "./explore_result_page.ts"; -import {projectWorkMeasurementFacts, projectWorkYardstickCue, workYardstickTodos, WORK_YARDSTICK_DECISION_SCHEMA} from "../work_items/yardstick_decision.ts"; import {projectExploreMeasurementFeedback, type ExploreMeasurementPoint} from "./explore_measurements.ts"; -/** Reusable evidence and instructions in this owner's read model. Current - * selection, eligibility, source revisions and pagination stay outside this - * split. Exact array edits retain every change, including its status, - * provenance and applicability; no timestamp or revision is normalized away. */ -export function exploreReusableContextPaths(content: JsonObject = {}): (string | number)[][] { - return [ - ...["recent_nodes", "recent_findings", "writeback_results", "measurement_feedback", "work_measurements", "work_yardsticks", "work_yardstick_capture", - "path_delta_attachment_template", "linked_question_attachment_template", - "optional_question_evolution_example", "optional_execution_observation_example", "result_writeback_guidance", - "result_attachment_template", "optional_measurement_example", "measurement_guidance", - "record_node_template", "record_finding_template", "guidance", - "result_writeback_option", "result_writeback_inline_option", "result_writeback_inline_field", - "result_attachment_schema", "path_delta_attachment_schema"].map(key => ["graph", key]), - ["harness", "guidance"], ["harness", "link_evidence_template"], - // The branch's identity, selection, status and resume facts stay fresh. - // Its evidence audit is a read model, not an eligibility or execution grant. - ...["selected_branches", "comparison_candidates", "rejected_candidates", "frontier"].flatMap(lane => { - const branches = (content.harness as JsonObject | undefined)?.[lane]; - return Array.isArray(branches) ? branches.flatMap((branch, index) => - branch !== null && typeof branch === "object" && !Array.isArray(branch) - && typeof branch.todo_id === "string" && branch.todo_id - ? [["harness", lane, index, "typed_evidence_audit"]] : []) : []; - }), - ]; -} - -/** The same authoring projection is used inline and by the captured writer. */ -function resultWritebackFields(writeback: JsonObject): JsonObject { - return { - result_writeback_option: writeback.option, - result_writeback_inline_option: writeback.inline_option, - result_writeback_inline_field: writeback.inline_field, - result_attachment_schema: writeback.attachment_schema, - path_delta_attachment_schema: writeback.path_delta_attachment_schema, - path_delta_attachment_template: writeback.path_delta_attachment_template, - linked_question_attachment_template: writeback.linked_question_attachment_template, - optional_question_evolution_example: writeback.optional_question_evolution_example, - optional_execution_observation_example: writeback.optional_execution_observation_example, - result_writeback_guidance: writeback.guidance, - result_attachment_template: writeback.attachment_template, - optional_measurement_example: writeback.optional_measurement_example, - }; -} - -/** Reference only exact, recognized authoring already delivered by the captured - * settlement plan. Unknown/custom guidance stays inline: no prose classification - * or migration of old obligations to a later phase. Evidence and paging stay put. - */ -function withoutCurrentResultWriteback(content: JsonObject, attachment: JsonObject): JsonObject | null { - const rawGraph = content.graph; - if (content.ok !== true || content.graph_enabled !== true || !rawGraph || typeof rawGraph !== "object" || Array.isArray(rawGraph) || - attachment.capability_id !== "explore" || attachment.guidance !== exploreResultWritebackAffordance().guidance) return null; - const graph = requireJsonObject(rawGraph, "Explore graph"); - const fields = resultWritebackFields(attachment); - if (Object.entries(fields).some(([key, value]) => value === undefined || !isDeepStrictEqual(graph[key], value))) return null; - const retained = {...graph}; - for (const key of Object.keys(fields)) delete retained[key]; - return retained; -} - -export function referenceExploreResultWriteback(content: JsonObject, attachment: JsonObject, read: string): JsonObject { - const retained = withoutCurrentResultWriteback(content, attachment); - return retained === null ? content : {...content, graph: {...retained, - result_writeback_guidance: exploreBeforeWorkGuidance(), result_writeback_read: read}}; -} - -/** A pure replan has no admitted Todo for refresh-state's result attachment. - * Preserve evidence collection obligations and the independent graph commands; - * do not advertise unusable authoring or invent a later attachment authority. - * The caller must establish the autonomous settlement binding first. - */ -export function omitUnboundExploreResultWriteback(content: JsonObject): JsonObject { - const retained = withoutCurrentResultWriteback(content, exploreResultWritebackAffordance()); - return retained === null ? content : {...content, graph: {...retained, - result_writeback_guidance: exploreBeforeWorkGuidance() + - " The refresh-state Explore attachment requires an admitted Todo and is unavailable for this pure replan. " + - "The independent graph record commands remain available for reusable evidence."}}; -} +type YardstickProjection = Pick; function rows(value: unknown): JsonObject[] { return Array.isArray(value) ? value.map(item => requireJsonObject(item, "Explore row")) : []; @@ -164,13 +87,18 @@ function prioritizeLinkedResults(results: JsonObject[], refs: Set, fallb return [...counterexamples, ...linked.filter(row => !reserved.has(row)), ...fallbackResults.filter(row => !refs.has(String(row.node_id ?? "")))]; } -export function projectExploreTurnContext(params: JsonObject): JsonObject { +export function projectExploreTurnContext(params: JsonObject, yardstick?: YardstickProjection): JsonObject { const goal = requireNonEmptyString(params.goal_id, "goal_id"); const agent = requireNonEmptyString(params.agent_id, "agent_id"); const route = requireStringArray(params.route, "route"); const gate = requireJsonObject(params.harness_gate, "harness_gate"); const graph = params.graph_enabled === true; const harness = gate.enabled === true; + const yardstickEnabled = graph && params.yardstick_enabled === true; + const evaluation = yardstickEnabled ? yardstick : undefined; + if (yardstickEnabled && !evaluation) { + throw new EffectRuntimeRequestError("The selected Yardstick projection is unavailable"); + } let todoId: string | null = null; let focusedRefs = new Set(); if ((graph || harness) && params.todo_id != null) { @@ -306,7 +234,7 @@ export function projectExploreTurnContext(params: JsonObject): JsonObject { try { const replay = projectExploreTurnContext({...params, todo_id: page.todo_id, focus_todo: matches[0], review_pages: undefined, result_offset: page.offset, - result_limit: page.limit, result_revision: page.revision}); + result_limit: page.limit, result_revision: page.revision}, evaluation); const found = (replay.graph as JsonObject).writeback_results as JsonObject[]; const choices = replay.harness as JsonObject | null; return [{...page, finding_refs: found.map(row => row.finding_id), @@ -338,34 +266,34 @@ export function projectExploreTurnContext(params: JsonObject): JsonObject { ...(resultNode == null ? [] : ["--result-node", resultNode]), ) : null; const writeback = exploreResultWritebackAffordance(); - const workTodos = workYardstickTodos({...params, todo_id: todoId}); - const currentWorkCues = workTodos.map(todo => projectWorkYardstickCue({enabled: true, goal_id: goal, agent_id: agent, todo_id: todo.todo_id, + const workTodos = evaluation?.workYardstickTodos({...params, todo_id: todoId}) ?? []; + const currentWorkCues = evaluation ? workTodos.map(todo => evaluation.projectWorkYardstickCue({enabled: true, goal_id: goal, agent_id: agent, todo_id: todo.todo_id, findings: findings.filter(row => (todo.explore_result_node_refs as unknown[] ?? []).includes(row.node_id)), cited_sources: params.yardstick_sources, measurement_feedback: measurementFeedback})) - .filter((cue): cue is JsonObject => cue !== null); + .filter((cue): cue is JsonObject => cue !== null) : []; const workCues = currentWorkCues.filter(cue => resultNode === null || cue.node_id === resultNode); // A first decision may use measurements recorded before any Yardstick // declaration. Reuse exact-profile feedback through canonical question links; // those links do not establish which Todo executed a shared finding. - const workMeasurements = workTodos.flatMap(todo => { + const workMeasurements = evaluation ? workTodos.flatMap(todo => { if (todo.status !== "open" || currentWorkCues.some(cue => (cue.binding as JsonObject).todo_id === todo.todo_id)) return []; const linked = new Set(requireStringArray(todo.explore_result_node_refs ?? [], "Explore task question refs")); const available = measurementFeedback.filter(row => linked.has(row.node_id)); - const facts = projectWorkMeasurementFacts(String(todo.todo_id), available, + const facts = evaluation.projectWorkMeasurementFacts(String(todo.todo_id), available, command("turn-context", "--agent-id", agent, "--todo-id", String(todo.todo_id), "--result-limit", "20")); return facts ? [facts] : []; - }); + }) : []; return { ok: true, goal_id: goal, agent_id: agent, graph_enabled: graph, harness_enabled: harness, ...(todoId === null ? {} : {todo_id: todoId}), ...(reviewPages ? {review_pages: reviewPages} : {}), graph: graph ? { counts: projection.counts ?? {}, - ...(params.yardstick_enabled === true ? { - work_yardstick_capture: {optional: true, field: "work_yardstick_decision", schema_version: WORK_YARDSTICK_DECISION_SCHEMA, + ...(evaluation ? { + work_yardstick_capture: {optional: true, field: "work_yardstick_decision", schema_version: evaluation.WORK_YARDSTICK_DECISION_SCHEMA, guidance: "Before a proxy would discard a viable candidate or redirect work, check agreement with the accepted outcome in this scope. When agreement is unknown or the signals disagree, use one bounded accepted-outcome comparison if available within the existing constraints. At a meaningful target, yardstick or method change, optionally record that decision and its counterevidence in the same Todo's Explore result. Cite its prior_finding_id (null initially); omit the attachment when the decision is unchanged. Read the task-scoped Explore context for the template and omitted decisions." + (todoId === null ? "" : " " + exploreInTurnFeedbackGuidance()), - template: {schema_version: WORK_YARDSTICK_DECISION_SCHEMA, + template: {schema_version: evaluation.WORK_YARDSTICK_DECISION_SCHEMA, target: {summary: "", scope: "", acceptance_ref: ""}, authoritative: {metric: "", unit: "", higher_is_better: true, comparison_scope: "", input_revision: "", evaluation_ref: ""}, proxy: null, counterevidence_refs: [], next_action: {method_id: "", reason: "", cost_bound: ""}, prior_finding_id: null}}, @@ -451,7 +379,6 @@ export function projectExploreTurnContext(params: JsonObject): JsonObject { link_evidence_template: [...route, "todo", "update", "--goal-id", goal, "--agent-id", agent, "--todo-id", "", "--explore-result-node-ref", ""], guidance: "Before choosing an experiment, compare its question with linked findings and the active frontier. Explain which evidence supports changing or retaining the route, and what the next probe can distinguish. Refutation is scoped evidence, not a permanent ban: a retry can test changed conditions or uncertainty. Link relevant existing nodes to the Todo; missing links mean unknown evidence, not a clean route. With one candidate or no active frontier, form useful alternatives only when evidence warrants them. Record results on the same hypothesis and adopt the decision through the ordinary task step or successor. These are decision guidelines, not a new writeback gate or permission to spawn. Read the full planner/summary when this bounded view is insufficient; normal quota, claim and lease admission still applies.", } : null, - boundary: {read_only: true, changes_configuration: false, writes_evidence: false, - claims_todos: false, starts_agents: false, changes_quota: false}, + boundary: exploreTurnContextBoundary(), }; } diff --git a/loopx/control_plane/capability_hooks.ts b/loopx/control_plane/capability_hooks.ts index e7cc90a1bb..9f3676b130 100644 --- a/loopx/control_plane/capability_hooks.ts +++ b/loopx/control_plane/capability_hooks.ts @@ -21,8 +21,7 @@ import { import { projectRepositoryDeliveryGate } from "./work_items/repository_delivery.ts"; import { projectPendingCapabilityIntent } from "./work_items/pending_capability_intent.ts"; -import {exploreResultWritebackAffordance} from "./capabilities/explore_result_writeback.ts"; -import {exploreReusableContextPaths} from "./capabilities/explore_turn_context.ts"; +import {exploreResultWritebackAffordance, exploreReusableContextPaths} from "./capabilities/explore_context_delivery.ts"; import {agentPreferenceReusableContextPaths} from "./capabilities/agent_preferences.ts"; /** The registered owner selects reusable read-model subtrees. Unknown hooks diff --git a/loopx/control_plane/effect_runtime_handlers.ts b/loopx/control_plane/effect_runtime_handlers.ts index 1b2a3eb1ea..de697283f5 100644 --- a/loopx/control_plane/effect_runtime_handlers.ts +++ b/loopx/control_plane/effect_runtime_handlers.ts @@ -849,7 +849,15 @@ export function createEffectRuntimeHandlers( ["explore.measurements.normalize", lazyHandler(() => import("./capabilities/explore_measurements.ts"), ({normalizeExploreMeasurementsRequest}) => normalizeExploreMeasurementsRequest)], ["explore.result.evolution", lazyHandler(() => import("./capabilities/explore_result_writeback.ts"), ({planExploreQuestionEvolution}) => planExploreQuestionEvolution)], ["explore.result.intent", lazyHandler(() => import("./capabilities/explore_result_writeback.ts"), ({produceExploreResultIntent}) => produceExploreResultIntent)], - ["explore.turn_context", lazyHandler(() => import("./capabilities/explore_turn_context.ts"), ({projectExploreTurnContext}) => projectExploreTurnContext)], + ["explore.turn_context", lazyHandler(() => import("./capabilities/explore_context_delivery.ts"), + ({projectEmptyExploreTurnContext}) => async params => { + const empty = projectEmptyExploreTurnContext(params); + if (empty !== undefined) return empty; + const {projectExploreTurnContext} = await import("./capabilities/explore_turn_context.ts"); + const yardstick = params.graph_enabled === true && params.yardstick_enabled === true + ? await import("./work_items/yardstick_decision.ts") : undefined; + return projectExploreTurnContext(params, yardstick); + })], ["explore.research.normalize", lazyHandler(() => import("./capabilities/explore_research.ts"), ({normalizeResearchObservation}) => normalizeResearchObservation)], ["explore.research.validate_attribution", lazyHandler(() => import("./capabilities/explore_research.ts"), ({validateResearchAttribution}) => validateResearchAttribution)], ["explore.research.validate_execution", lazyHandler(() => import("./capabilities/explore_research_execution.ts"), ({validateResearchExecution}) => validateResearchExecution)], diff --git a/loopx/control_plane/quota/turn_envelope.ts b/loopx/control_plane/quota/turn_envelope.ts index ea50115021..6b7af0e118 100644 --- a/loopx/control_plane/quota/turn_envelope.ts +++ b/loopx/control_plane/quota/turn_envelope.ts @@ -11,13 +11,13 @@ import {isDeepStrictEqual} from "node:util"; import {authorityUnicodeCompare} from "../coordination/authority_store_codec.ts"; import { inflateSync } from "node:zlib"; import { BARE_SHA256_PATTERN, ENVELOPED_SHA256_PATTERN } from "../content_digest.ts"; -import {omitUnboundExploreResultWriteback, referenceExploreResultWriteback} from "../capabilities/explore_turn_context.ts"; +import {omitUnboundExploreResultWriteback, referenceExploreResultDelivery, + referenceExploreResultWriteback} from "../capabilities/explore_context_delivery.ts"; import {prepareContextDelivery, restoreContextDelivery} from "./context_delivery.ts"; import {updateNativeContextLifecycle} from "./native_context_lifecycle.ts"; import {contextProjectionChanges, contextProjectionIdentity, contextProjectionRetainFields, contextSourceIdentity, projectQuotaDiagnostics, referenceQuotaSummaryLanes, resolveQuotaSummaryLanes, type ProjectionSourceValues} from "./diagnostic_projection.ts"; -import {referenceExploreResultDelivery} from "../capabilities/explore_result_writeback.ts"; import {completeCliSettlementChannel} from "./settlement_plan.ts"; import {REPLAN_SETTLEMENT_CONTRACT_SCHEMA} from "../work_items/replan_settlement.ts"; diff --git a/tests/control_plane_ts/effect_runtime_handler_loading.test.ts b/tests/control_plane_ts/effect_runtime_handler_loading.test.ts index 25d7a01fae..f4feec452b 100644 --- a/tests/control_plane_ts/effect_runtime_handler_loading.test.ts +++ b/tests/control_plane_ts/effect_runtime_handler_loading.test.ts @@ -2,6 +2,53 @@ import assert from "node:assert/strict"; import {spawnSync} from "node:child_process"; import test from "node:test"; +test("Explore reads load Yardstick only for enabled graph evidence", () => { + const entry = new URL("../../loopx/control_plane/effect_runtime_handlers.ts", import.meta.url).href; + const script = ` + import assert from "node:assert/strict"; + import {registerHooks} from "node:module"; + let loads = 0, graphLoads = 0; + registerHooks({load(url, context, next) { + if (url.endsWith("/work_items/yardstick_decision.ts")) loads++; + if (url.endsWith("/capabilities/explore_turn_context.ts")) graphLoads++; + return next(url, context); + }}); + const {createEffectRuntimeHandlers, dispatchEffectRuntimeMethod} = await import(${JSON.stringify(entry)}); + const handlers = createEffectRuntimeHandlers({fingerprint: "loading-test", requestShutdown() {}}); + const request = {goal_id: "research", agent_id: "worker", route: ["loopx"], + graph_enabled: true, harness_gate: {enabled: false}, + plan: {}, projection: {nodes: [], findings: [], edges: []}}; + const read = options => dispatchEffectRuntimeMethod(handlers, "explore.turn_context", {...request, ...options}); + const disabled = {graph_enabled: false, projection: {}, yardstick_enabled: true}; + assert.deepEqual(await read(disabled), { + ok: true, goal_id: "research", agent_id: "worker", graph_enabled: false, harness_enabled: false, + graph: null, harness: null, boundary: {read_only: true, changes_configuration: false, + writes_evidence: false, claims_todos: false, starts_agents: false, changes_quota: false}, + }); + assert.equal(graphLoads, 0); + assert.equal(loads, 0); + await assert.rejects(read({...disabled, result_offset: 1}), /Continuation requires result_revision/); + const ordinary = await read({}); + assert.equal(ordinary.ok, true); + assert.equal(Object.hasOwn(ordinary.graph, "work_yardstick_capture"), false); + assert.deepEqual(await read({yardstick_enabled: false}), ordinary); + assert.equal((await read({graph_enabled: false, yardstick_enabled: true})).graph, null); + assert.equal(loads, 0); + + const enabled = await read({yardstick_enabled: true}); + assert.equal(enabled.ok, true); + assert.equal(enabled.graph.work_yardstick_capture.optional, true); + assert.equal(enabled.graph.work_yardstick_capture.schema_version, "work_yardstick_decision_v0"); + assert.equal(loads, 1); + assert.deepEqual(await read({yardstick_enabled: true}), enabled); + assert.deepEqual(await read({yardstick_enabled: false}), ordinary); + assert.equal(loads, 1); + `; + const child = spawnSync(process.execPath, ["--no-warnings", "--experimental-strip-types", + "--input-type=module", "-e", script], {encoding: "utf8", timeout: 30_000}); + assert.equal(child.status, 0, child.stderr); +}); + test("coordination claims remain available without terminal research evidence", () => { const entry = new URL("../../loopx/control_plane/effect_runtime_handlers.ts", import.meta.url).href; const fixtures = new URL("./local_promotion_fixture.ts", import.meta.url).href; diff --git a/tests/control_plane_ts/explore_result_writeback.test.ts b/tests/control_plane_ts/explore_result_writeback.test.ts index a926694a00..3083d46ba6 100644 --- a/tests/control_plane_ts/explore_result_writeback.test.ts +++ b/tests/control_plane_ts/explore_result_writeback.test.ts @@ -1,7 +1,8 @@ import assert from "node:assert/strict"; import test from "node:test"; import {normalizeExploreExecutionObservation} from "../../loopx/control_plane/capabilities/explore_execution_observation.ts"; -import {exploreResultWritebackAffordance, normalizeExploreResultAttachment, planExploreQuestionEvolution} from "../../loopx/control_plane/capabilities/explore_result_writeback.ts"; +import {exploreResultWritebackAffordance} from "../../loopx/control_plane/capabilities/explore_context_delivery.ts"; +import {normalizeExploreResultAttachment, planExploreQuestionEvolution} from "../../loopx/control_plane/capabilities/explore_result_writeback.ts"; const attachment = { schema_version: "explore_result_attachment_v0", node_id: "tail-bound", diff --git a/tests/control_plane_ts/explore_turn_context.test.ts b/tests/control_plane_ts/explore_turn_context.test.ts index 8450e1fcc0..35de9ac5e3 100644 --- a/tests/control_plane_ts/explore_turn_context.test.ts +++ b/tests/control_plane_ts/explore_turn_context.test.ts @@ -4,8 +4,10 @@ import test from "node:test"; import type {JsonObject} from "../../loopx/control_plane/effect_program.ts"; import {projectStrideExploreBasis, strideReviewMismatch} from "../../loopx/control_plane/work_items/stride_policy.ts"; import {projectExploreTurnContext} from "../../loopx/control_plane/capabilities/explore_turn_context.ts"; +import * as yardstick from "../../loopx/control_plane/work_items/yardstick_decision.ts"; test("initial work measurement feedback preserves linked scopes without choosing an outcome profile", () => { + const project = (source: JsonObject) => projectExploreTurnContext(source, yardstick); const profile = {metric: "quality", unit: "points", higher_is_better: true, comparison_scope: "inputs:shared", input_revision: "v1", evaluation_ref: "judge:public"}; const finding = (id: string, node: string, order: number, candidate: string, value: number | null, @@ -25,9 +27,9 @@ test("initial work measurement feedback preserves linked scopes without choosing finding("other-unit", "local", 7, "candidate:c", 30, {unit: "percent"}), ]}}; const original = structuredClone(request); - const graph = projectExploreTurnContext(request).graph as JsonObject; + const graph = project(request).graph as JsonObject; assert.match(String(graph.result_writeback_guidance), /loopx explore finding --result-json FILE/); - assert.equal(projectExploreTurnContext({...request, graph_enabled: false}).graph, null); + assert.equal(project({...request, graph_enabled: false}).graph, null); const card = graph.work_measurements[0]; assert.equal(card.todo_id, todo.todo_id); assert.equal(card.measurement_feedback.length, 3); @@ -62,23 +64,23 @@ test("initial work measurement feedback preserves linked scopes without choosing assert.ok(card.details_command.includes("--todo-id") && card.details_command.includes(todo.todo_id)); assert.deepEqual(request, original); for (const enabled of [false, undefined]) { - const off = projectExploreTurnContext({...request, yardstick_enabled: enabled}).graph as JsonObject; + const off = project({...request, yardstick_enabled: enabled}).graph as JsonObject; assert.ok(!Object.hasOwn(off, "work_measurements")); assert.deepEqual(off.measurement_feedback, graph.measurement_feedback); } for (const changes of [{claimed_by: "another"}, {done: true}, {status: "blocked"}, {explore_result_node_refs: []}]) { - const unavailable = projectExploreTurnContext({...request, work_todos: [{...todo, ...changes}]}).graph as JsonObject; + const unavailable = project({...request, work_todos: [{...todo, ...changes}]}).graph as JsonObject; assert.ok(!Object.hasOwn(unavailable, "work_measurements")); } - const scoped = projectExploreTurnContext({...request, result_node: "unlinked"}).graph as JsonObject; + const scoped = project({...request, result_node: "unlinked"}).graph as JsonObject; assert.ok(!Object.hasOwn(scoped, "work_measurements")); - const shared = projectExploreTurnContext({...request, + const shared = project({...request, work_todos: [todo, {...todo, todo_id: "todo_shared"}]}).graph as JsonObject; assert.deepEqual(shared.work_measurements.map(row => row.todo_id), ["todo_current", "todo_shared"]); assert.deepEqual(shared.work_measurements[0].measurement_feedback, shared.work_measurements[1].measurement_feedback); const tied = structuredClone(request); tied.projection.findings[1].measurements[0].value = 10; - const tiedGraph = projectExploreTurnContext(tied).graph as JsonObject; + const tiedGraph = project(tied).graph as JsonObject; const tie = tiedGraph.work_measurements[0].measurement_feedback.find(row => row.node_id === "shared"); assert.equal(tie.best.candidate_ref, "candidate:a"); assert.equal(tie.latest.measurement.candidate_ref, "candidate:b"); @@ -92,7 +94,7 @@ test("initial work measurement feedback preserves linked scopes without choosing proxy: null, counterevidence_refs: [], prior_finding_id: null, next_action: {method_id: "method:retained", reason: "Continue the recorded choice", cost_bound: "Existing budget"}, }}}]}}; - const differentQuestion = projectExploreTurnContext(declared).graph as JsonObject; + const differentQuestion = project(declared).graph as JsonObject; assert.ok(!Object.hasOwn(differentQuestion, "work_measurements")); assert.ok(differentQuestion.measurement_feedback.every(row => row.node_id === "local")); }); diff --git a/tests/control_plane_ts/yardstick_decision.test.ts b/tests/control_plane_ts/yardstick_decision.test.ts index 500fa1fe1d..8803e3f291 100644 --- a/tests/control_plane_ts/yardstick_decision.test.ts +++ b/tests/control_plane_ts/yardstick_decision.test.ts @@ -5,6 +5,7 @@ import {normalizeWorkYardstickDecision, normalizeWorkYardstickCapture, projectWo import {validateWorkYardstickContinuation} from "../../loopx/control_plane/work_items/yardstick_source.ts"; import {normalizeExploreResultAttachment} from "../../loopx/control_plane/capabilities/explore_result_writeback.ts"; import {projectExploreTurnContext} from "../../loopx/control_plane/capabilities/explore_turn_context.ts"; +import * as yardstick from "../../loopx/control_plane/work_items/yardstick_decision.ts"; import {projectExploreMeasurementFeedback} from "../../loopx/control_plane/capabilities/explore_measurements.ts"; const authoritative = {metric: "quality", unit: "points", higher_is_better: true, @@ -305,14 +306,15 @@ test("one optional attachment reaches an ordinary task context without creating const todo = {todo_id: binding.todo_id, role: "agent", claimed_by: "worker", status: "open", explore_result_node_refs: ["question"]}; const params = {goal_id: "research", agent_id: "worker", graph_enabled: true, harness_gate: {enabled: false}, route: ["loopx"], plan: {}, projection: {nodes: [], findings: [finding]}, todo_id: binding.todo_id, focus_todo: todo}; - const off = projectExploreTurnContext(params); + const project = (source: JsonObject) => projectExploreTurnContext(source, yardstick); + const off = project(params); assert.equal(Object.hasOwn(off.graph, "work_yardsticks"), false); - const on = projectExploreTurnContext({...params, yardstick_enabled: true, work_todos: [todo]}); + const on = project({...params, yardstick_enabled: true, work_todos: [todo]}); assert.equal(on.graph.work_yardsticks[0].source_finding_id, finding.finding_id); assert.equal(on.graph.work_yardsticks[0].cue, decision.next_action.reason); assert.equal(Object.hasOwn(on.graph.work_yardsticks[0], "authoritative"), false); assert.deepEqual(on.graph.work_yardsticks[0].counterevidence_refs, finding.evidence_refs); - const detail = projectExploreTurnContext({...params, yardstick_enabled: true, work_todos: [todo], result_node: "question"}); + const detail = project({...params, yardstick_enabled: true, work_todos: [todo], result_node: "question"}); assert.deepEqual(detail.graph.work_yardsticks[0].authoritative, authoritative); assert.deepEqual(on.harness, off.harness); assert.equal(on.graph.work_yardstick_capture.optional, true); @@ -322,12 +324,12 @@ test("one optional attachment reaches an ordinary task context without creating {...proxy, value: 8, candidate_ref: "candidate:b", evidence_ref: "result:screen-b"}, {...proxy, value: 9, candidate_ref: "candidate:a", evidence_ref: "result:screen-a"}, ]}; - const reversedCompact = projectExploreTurnContext({...params, projection: {nodes: [], findings: [measured]}, + const reversedCompact = project({...params, projection: {nodes: [], findings: [measured]}, yardstick_enabled: true, work_todos: [todo]}).graph.work_yardsticks[0]; assert.equal(reversedCompact.comparison_candidate_ref, "candidate:b"); assert.equal(reversedCompact.proxy_order_reversed, true); // Unknown or unowned work cannot adopt a shared question's decision. - assert.equal(Object.hasOwn(projectExploreTurnContext({...params, yardstick_enabled: true, + assert.equal(Object.hasOwn(project({...params, yardstick_enabled: true, work_todos: [{...todo, claimed_by: "peer"}]}).graph, "work_yardsticks"), false); }); diff --git a/tests/test_core_distribution.py b/tests/test_core_distribution.py index f39fae8197..fc571eeaeb 100644 --- a/tests/test_core_distribution.py +++ b/tests/test_core_distribution.py @@ -466,6 +466,34 @@ def _spends(runtime): for line in index.read_text().splitlines()) if index.exists() else 0 +def test_installed_core_ordinary_turn_defers_explore_evaluation(core_python, task, tmp_path, monkeypatch): + from tests.control_plane.canonical_authority_fixture import isolate_sqlite_runtime + + workspace, runtime, _registry, arguments = task + isolated = tmp_path / "loads" + isolated.mkdir() + isolate_sqlite_runtime(isolated, monkeypatch) + trace, observer = isolated / "modules.txt", isolated / "observe.mjs" + observer.write_text("""import {appendFileSync} from "node:fs"; +import {registerHooks} from "node:module"; +const tracked = new Set(["turn_envelope.ts", "yardstick_decision.ts", "explore_result_writeback.ts", + "explore_turn_context.ts", "explore_measurements.ts"]); +registerHooks({load(url, context, next) { + const name = url.split("/").at(-1); + if (tracked.has(name)) appendFileSync(process.env.LOOPX_TEST_MODULE_TRACE, name + "\\n"); + return next(url, context); +}}); +""", encoding="utf-8") + monkeypatch.setenv("LOOPX_TEST_MODULE_TRACE", str(trace)) + monkeypatch.setenv("NODE_OPTIONS", f"{os.environ['NODE_OPTIONS']} --import={observer.as_uri()}") + result = json.loads(_run(core_python, arguments, workspace).stdout) + key = _assert_committed(core_python, workspace, runtime, result) + replay = json.loads(_run(core_python, [*arguments, "--resume-turn-key", key], workspace).stdout) + assert replay["resume_turn_key"] == key + assert not any(replay["effects"][name] for name in ("host_invoked", "state_written", "quota_spent")) + assert set(trace.read_text(encoding="utf-8").splitlines()) == {"turn_envelope.ts"} + + def test_installed_core_goal_lifecycle_preserves_work_and_resumes_execution(core_python, task): workspace, runtime, registry, arguments = task host_started = workspace / "lifecycle-host-started"