diff --git a/loopx/control_plane/effect_program.ts b/loopx/control_plane/effect_program.ts index 2a2938c9ca..caa1af636a 100644 --- a/loopx/control_plane/effect_program.ts +++ b/loopx/control_plane/effect_program.ts @@ -1,6 +1,6 @@ import {assertActionSelectionConsistency} from "./work_items/action_selection_admission.ts"; import { EffectRuntimeRequestError } from "./effect_runtime_errors.ts"; -import { isStringLiteral, type JsonObject } from "./runtime_decode.ts"; +import { isStringLiteral, pythonString, type JsonObject } from "./runtime_decode.ts"; import { decodeInteractionContract } from "./work_items/interaction_contract.ts"; import { EffectiveAction } from "./quota/effective_action.generated.ts"; import {BARE_SHA256_PATTERN} from "./content_digest.ts"; @@ -258,13 +258,6 @@ function asObject(value: unknown): JsonObject { : {}; } -function pythonString(value: unknown): string { - if (value === null || value === undefined) return "None"; - if (value === true) return "True"; - if (value === false) return "False"; - return String(value); -} - function truthyString(value: unknown): string { return value ? pythonString(value) : ""; } diff --git a/loopx/control_plane/quota/turn_envelope.py b/loopx/control_plane/quota/turn_envelope.py index 7807ffa16e..adfd0c1c35 100644 --- a/loopx/control_plane/quota/turn_envelope.py +++ b/loopx/control_plane/quota/turn_envelope.py @@ -302,12 +302,10 @@ def quota_capability_automation_source(payload: Mapping[str, Any]) -> dict[str, return _turn_envelope_result("capability_automation_source", payload=dict(payload)) -def turn_envelope_replan_settlement_identity( - envelope: Mapping[str, Any], *, turn_instance_id: str | None, +def _turn_settlement_identity( + operation: str, envelope: Mapping[str, Any], *, turn_instance_id: str | None, ) -> dict[str, Any] | None: - result = _turn_envelope_result("replan_settlement_identity", envelope=dict(envelope), - turn_instance_id=turn_instance_id) - identity = result.get("identity") + identity = _turn_envelope_result(operation, envelope=dict(envelope), turn_instance_id=turn_instance_id).get("identity") if identity is None: return None if not isinstance(identity, Mapping): @@ -315,6 +313,12 @@ def turn_envelope_replan_settlement_identity( return dict(identity) +def turn_envelope_replan_settlement_identity( + envelope: Mapping[str, Any], *, turn_instance_id: str | None, +) -> dict[str, Any] | None: + return _turn_settlement_identity("replan_settlement_identity", envelope, turn_instance_id=turn_instance_id) + + def compose_turn_decision( payload: Mapping[str, Any], *, scheduler_execution_context: ( Mapping[str, Any] | SchedulerExecutionContextResolution | None @@ -347,11 +351,7 @@ def assert_complete_turn_decision(payload: Mapping[str, Any]) -> None: def turn_envelope_scoped_settlement_identity( envelope: Mapping[str, Any], *, turn_instance_id: str | None, ) -> dict[str, Any] | None: - identity = _turn_envelope_result("scoped_settlement_identity", envelope=dict(envelope), - turn_instance_id=turn_instance_id).get("identity") - if identity is not None and not isinstance(identity, Mapping): - raise RuntimeError("TypeScript Turn settlement identity must be an object") - return dict(identity) if identity is not None else None + return _turn_settlement_identity("scoped_settlement_identity", envelope, turn_instance_id=turn_instance_id) def build_turn_envelope( @@ -363,19 +363,6 @@ def build_turn_envelope( captured_decision_path: str | None = None, ) -> dict[str, Any]: """Project one full quota decision through the canonical TS transaction.""" - - return _build_turn_projection(payload, - scheduler_execution_context=scheduler_execution_context, - captured_decision_path=captured_decision_path) - - -def _build_turn_projection( - payload: Mapping[str, Any], *, scheduler_execution_context: ( - Mapping[str, Any] | SchedulerExecutionContextResolution | None - ) = None, - captured_decision_path: str | None = None, -) -> dict[str, Any]: - resolution = resolve_scheduler_execution_context(scheduler_execution_context) scheduler_execution_args: object = "" if resolution.ok and resolution.context is not None: diff --git a/loopx/control_plane/quota/turn_envelope.ts b/loopx/control_plane/quota/turn_envelope.ts index acae4d618b..333ed30d62 100644 --- a/loopx/control_plane/quota/turn_envelope.ts +++ b/loopx/control_plane/quota/turn_envelope.ts @@ -1,45 +1,60 @@ -import {EXECUTION_PREPARATION_SCHEMA_VERSION} from "../work_items/execution_preparation.ts"; -import {capturedContextSelection} from "./context_selection.ts"; -import {contextReadSectionDigests, initialContextReadPointers, prepareProgressiveContext, prepareProgressiveContextDelivery, - progressiveContextPlan, scopedReplanYardstickReversal, - type PreparationScopeDetail, type ReusableExactBody} from "./progressive_context.ts"; +import { EXECUTION_PREPARATION_SCHEMA_VERSION } from "../work_items/execution_preparation.ts"; +import { capturedContextSelection } from "./context_selection.ts"; +import { + contextReadSectionDigests, initialContextReadPointers, prepareProgressiveContext, + prepareProgressiveContextDelivery, progressiveContextPlan, scopedReplanYardstickReversal, + type PreparationScopeDetail, type ReusableExactBody, +} from "./progressive_context.ts"; import type { LoopXTurnRouteValue } from "../turn_driver/turn_contract_generated.ts"; -import { EFFECTIVE_ACTIONS, EffectiveAction, type QuotaEffectiveActionValue } from "./effective_action.generated.ts"; -import { AGENT_SCOPE_FRONTIER_ACTIONS } from "../agents/agent_scope_frontier.generated.ts"; -import { createHash } from "node:crypto"; -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, 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, omitEmptyTaskTodoLanes, projectQuotaDiagnostics, referenceQuotaSummaryLanes, resolveQuotaSummaryLanes, - type ProjectionSourceValues} from "./diagnostic_projection.ts"; -import {completeCliSettlementChannel} from "./settlement_plan.ts"; -import {REPLAN_SETTLEMENT_CONTRACT_SCHEMA} from "../work_items/replan_settlement.ts"; - +import { EffectiveAction, type QuotaEffectiveActionValue } from "./effective_action.generated.ts"; +import { ENVELOPED_SHA256_PATTERN } from "../content_digest.ts"; +import { + omitUnboundExploreResultWriteback, referenceExploreResultDelivery, +} from "../capabilities/explore_context_delivery.ts"; +import { prepareContextDelivery, restoreContextDelivery } from "./context_delivery.ts"; +import { updateNativeContextLifecycle } from "./native_context_lifecycle.ts"; import { - interpretQuotaShouldRunPacket, - assertSupportedQuotaPacket, - settlementIdentityFromPlan, - SETTLEMENT_PLAN_SCHEMA_VERSION, - settlementIdentityPayload, - type JsonObject, + contextProjectionChanges, contextSourceIdentity, omitEmptyTaskTodoLanes, projectQuotaDiagnostics, + referenceQuotaSummaryLanes, resolveQuotaSummaryLanes, +} from "./diagnostic_projection.ts"; +import { completeCliSettlementChannel } from "./settlement_plan.ts"; +import { + interpretQuotaShouldRunPacket, assertSupportedQuotaPacket, + settlementIdentityFromPlan, settlementIdentityPayload, type JsonObject, } from "../effect_program.ts"; import { EffectRuntimeRequestError } from "../effect_runtime_errors.ts"; import { projectTurnStartUnavailableContext } from "../capability_hooks.ts"; -import { jsonObject, requireBoolean, requireJsonObject, requireNonEmptyString, requireStringLiteral, - sourceNumberTokens } from "../runtime_decode.ts"; +import { + jsonObject, pythonString, requireBoolean, requireJsonObject, + requireNonEmptyString, requireStringLiteral, sourceNumberTokens, +} from "../runtime_decode.ts"; import { projectPendingCapabilityIntent } from "../work_items/pending_capability_intent.ts"; import { assertActionSelectionConsistency } from "../work_items/action_selection_admission.ts"; -import { INTERACTION_CONTRACT_SCHEMA_VERSION, assertGoalContextDelivered, assertInteractionRequiredReads, - capturedTodoTextSha256, decodeInteractionContract, hasUnboundActionSelection, projectInteractionRequiredReads, - selectedWorkTodo, selectedWorkTodoId, USER_CHANNEL_NOTIFICATION_POLICIES } from "../work_items/interaction_contract.ts"; +import { + INTERACTION_CONTRACT_SCHEMA_VERSION, assertGoalContextDelivered, capturedTodoTextSha256, + hasUnboundActionSelection, projectInteractionRequiredReads, selectedWorkTodo, + selectedWorkTodoId, USER_CHANNEL_NOTIFICATION_POLICIES, +} from "../work_items/interaction_contract.ts"; import { measureTurnEnvelope, TURN_ENVELOPE_SECTION_TARGETS } from "./turn_envelope_budget.ts"; +import { + COMPLETE_TURN_DECISION_VERSION, COMPLETE_TURN_HASH_CODEC, canonicalHash, coldPath, + compactFields, completeSourceHash, decodeTurnSource, decisionSourceHash, + executableCliArgs, isNonEmptyFilePath, object, pickNonNull, pickOwn, scalarString, + shellQuote, text, textList, +} from "./turn_envelope_codec.ts"; +import { + WORK_CONTEXT_GOAL_ACCEPTANCE_REF_PATTERN, type ReplanReadPrecision, bindReplanSuccessorContract, + deferredReplanWriteback, nativeReplanPresentation, referenceCurrentTaskTitle, + referenceExploreGuidance, referenceGoalAcceptance, referenceReplanAuthoring, + referenceVisionContinuation, replanActionPacket, replanAuthoringContract, replanCliView, + replanGoalContext, replanReadCommands, replanReadPrecision, replanView, replanWorkContext, + requiredReads, requireCompleteDecisionSource, requireCompleteTurnDecision, resolveExploreGuidance, + responsePlan, selectedTodo, unboundExploreReplan, userChannel, +} from "./turn_envelope_references.ts"; + export { TURN_ENVELOPE_BUDGET_BYTES } from "./turn_envelope_budget.ts"; +export { COMPLETE_TURN_DECISION_VERSION, decodeTurnSource } from "./turn_envelope_codec.ts"; +export { requireCompleteTurnDecision } from "./turn_envelope_references.ts"; export const TURN_ENVELOPE_SCHEMA_VERSION = "loopx_turn_envelope_v0"; export const CONTRACT_CAPSULE_SCHEMA_VERSION = "loopx_contract_capsule_v0"; @@ -48,13 +63,41 @@ export const ACTION_SIGNATURE_COVERAGE_V0 = "turn_envelope_action_dimensions_v0" export const ACTION_SIGNATURE_COVERAGE_V1 = "turn_envelope_action_dimensions_v1"; export const ACTION_SIGNATURE_COVERAGE_V2 = "turn_envelope_action_dimensions_v2"; export const ACTION_SIGNATURE_COVERAGE_V3 = "turn_envelope_action_dimensions_v3"; +export const ACTION_SIGNATURE_COVERAGE_V4 = "turn_envelope_action_dimensions_v4"; +export const ACTION_SIGNATURE_COVERAGE_V5 = "turn_envelope_action_dimensions_v5"; +export const ACTION_SIGNATURE_COVERAGE = ACTION_SIGNATURE_COVERAGE_V0; // Single owner for the should-run artifact path a child brief points at, so the // legacy field token stays inside this module's retirement budget. export const QUOTA_GOAL_BOUNDARY_ARTIFACT = "quota_should_run.goal_boundary"; - export const SCHEDULER_QUOTA_IDENTITY_KEYS = ["goal_id", "agent_identity.agent_id", "effective_action", "heartbeat_recommendation.recommended_mode", "interaction_contract.mode"]; +const PLANNING_HORIZON_DETAIL_REFS_REF = "$.detail_ref"; + +const ACTIONABLE_WARNING_FIELDS = [ + "state_projection_gap", + "boundary_projection_gap", + "state_action_projection_warning", + "next_action_projection_warning", + "stale_latest_run_warning", + "decision_freshness_warning", +] as const; + +const CONTRACT_CAPSULE_FIELDS: Readonly> = { + interaction_contract: ["schema_version", "mode"], + goal_route_hint: [ + "schema_version", "kind", "route_decision", "preserves_goal_next_action", + "goal_next_action_mutation", + ], + handoff_readiness: [ + "ready", "codex_ready", "handoff_status", "post_handoff_run_seen", + ], + capability_monitor_fallback: [ + "schema_version", "capability_gate_action", "blocked_advancement_count", + "blocked_due_monitor_count", "mode", + ], +}; + export function schedulerQuotaContext(payload: JsonObject) { return { recommended_mode: String(object(payload.heartbeat_recommendation).recommended_mode || ""), @@ -75,6 +118,7 @@ export function monitorHeartbeatDecisionFields(decision: JsonObject): JsonObject // The legacy adapter owns its field names. The codec receives this local binding // from the adapter, never from request data or a second legacy-field reader. const LEGACY_QUOTA_CONTEXT_FIELDS = Object.keys(monitorHeartbeatDecisionFields({})); + /** Keep legacy heartbeat fields at their existing quota projection boundary; * the interaction owner still decides required reads and scheduler arbitration. */ @@ -113,1035 +157,10 @@ function interactionHeartbeatRecommendation(request: JsonObject, arbitration: Js return {heartbeat_recommendation: projected}; } -export const ACTION_SIGNATURE_COVERAGE_V4 = "turn_envelope_action_dimensions_v4"; -export const ACTION_SIGNATURE_COVERAGE_V5 = "turn_envelope_action_dimensions_v5"; -export const ACTION_SIGNATURE_COVERAGE = ACTION_SIGNATURE_COVERAGE_V0; - -const EXECUTABLE_CLI_ARGS_MAX_ITEMS = 64; -const EXECUTABLE_CLI_ARGS_MAX_ITEM_CHARS = 512; -const EXECUTABLE_CLI_ARGS_MAX_TOTAL_CHARS = 2_048; -const PLANNING_HORIZON_DETAIL_REFS_REF = "$.detail_ref"; - -const ACTIONABLE_WARNING_FIELDS = [ - "state_projection_gap", - "boundary_projection_gap", - "state_action_projection_warning", - "next_action_projection_warning", - "stale_latest_run_warning", - "decision_freshness_warning", -] as const; - -const CONTRACT_CAPSULE_FIELDS: Readonly> = { - interaction_contract: ["schema_version", "mode"], - goal_route_hint: [ - "schema_version", "kind", "route_decision", "preserves_goal_next_action", - "goal_next_action_mutation", - ], - handoff_readiness: [ - "ready", "codex_ready", "handoff_status", "post_handoff_run_seen", - ], - capability_monitor_fallback: [ - "schema_version", "capability_gate_action", "blocked_advancement_count", - "blocked_due_monitor_count", "mode", - ], -}; - -function object(value: unknown): JsonObject { - return typeof value === "object" && value !== null && !Array.isArray(value) - ? { ...(value as JsonObject) } - : {}; -} - -type PythonScalar = string | number | boolean | null | undefined; - -function pythonString(value: PythonScalar): string { - if (value === null || value === undefined) return "None"; - if (value === true) return "True"; - if (value === false) return "False"; - return String(value); -} - -function scalarString(value: unknown, label: string, fallback = ""): string { - if (value === null || value === undefined || value === "") return fallback; - if ( - typeof value !== "string" && - typeof value !== "number" && - typeof value !== "boolean" - ) { - throw new EffectRuntimeRequestError(`${label} must be scalar-compatible`); - } - return pythonString(value); -} - -function integer(value: unknown, label: string): number { - if (value === null || value === undefined || value === "") return 0; - if (typeof value === "boolean") return Number(value); - if (typeof value === "number" && Number.isFinite(value)) return Math.trunc(value); - if (typeof value === "string" && /^[+-]?\d+$/u.test(value.trim())) { - return Number.parseInt(value, 10); - } - throw new EffectRuntimeRequestError(`${label} must be integer-compatible`); -} - -function text(value: unknown, limit: number): string | null { - if (value === null || value === undefined) return null; - const compact = scalarString(value, "text value").trim().split(/\s+/u).join(" "); - if (!compact) return null; - if (compact.length <= limit) return compact; - return `${compact.slice(0, Math.max(0, limit - 3)).trimEnd()}...`; -} - -function textList(value: unknown, limit: number, itemLimit = 240): string[] { - if (!Array.isArray(value)) return []; - const result: string[] = []; - for (const item of value) { - const rendered = text(item, itemLimit); - if (!rendered || result.includes(rendered)) continue; - result.push(rendered); - if (result.length >= limit) break; - } - return result; -} - -function executableCliArgs(value: unknown): string[] { - if (!Array.isArray(value) || value.length === 0 || value.length > EXECUTABLE_CLI_ARGS_MAX_ITEMS) { - return []; - } - const result: string[] = []; - let totalChars = 0; - for (const item of value) { - if (typeof item !== "string" || !item || item.length > EXECUTABLE_CLI_ARGS_MAX_ITEM_CHARS) { - return []; - } - totalChars += item.length + 1; - if (totalChars > EXECUTABLE_CLI_ARGS_MAX_TOTAL_CHARS) return []; - result.push(item); - } - return result; -} - -function canonicalValue(value: unknown): unknown { - if (Array.isArray(value)) return value.map(canonicalValue); - if (typeof value !== "object" || value === null) return value; - const source = value as JsonObject; - return Object.fromEntries( - Object.keys(source).sort(authorityUnicodeCompare).map((key) => [key, canonicalValue(source[key])]), - ); -} - -function canonicalHash(value: unknown): string { - return `sha256:${createHash("sha256").update(JSON.stringify(canonicalValue(value)), "utf8").digest("hex")}`; -} - -/** Complete references reuse the checked content binding. Historical captures - * retain their old JSON hash; never rewrite a stored action or Turn key. */ -function decisionSourceHash(payload: JsonObject): string { - if (payload.schema_version !== COMPLETE_TURN_DECISION_VERSION) return canonicalHash(payload); - const digest = object(payload.contract_binding).content_hash; - if (typeof digest !== "string") throw new EffectRuntimeRequestError("complete Turn decision content binding is missing"); - return digest; -} - -type ReplanValueIdentity = (value: unknown, path: (string | number)[]) => string; -type ReplanReadPrecision = { - identity: ReplanValueIdentity; - retain: ReturnType; - equalProjection: (left: JsonObject, right: JsonObject) => boolean; - values: ProjectionSourceValues; -}; - -function replanReadPrecision(source: JsonObject, supplied: unknown): ReplanReadPrecision | undefined { - if (supplied === undefined) return undefined; - const identity = contextSourceIdentity(source, supplied); - const values: ProjectionSourceValues = new WeakMap(); - const projectedIdentity = (view: JsonObject) => contextProjectionIdentity(source, view, supplied, values); - return {identity, values, retain: contextProjectionRetainFields(source, values), - equalProjection: (left, right) => projectedIdentity(left) === projectedIdentity(right)}; -} - -function replanAuthoringContract(payload: JsonObject, precision?: ReplanReadPrecision): JsonObject { - const contract = jsonObject(jsonObject(payload.replan_action_packet)?.writeback_contract) ?? {}; - if (!Object.hasOwn(contract, "vision_authoring_ref")) return contract; - const reference = contract.vision_authoring_ref; - const match = typeof reference === "string" - ? /^\$\.interaction_contract\.cli_channel\.settlement_plan\.ordered_steps\[(0|[1-9]\d*)\]\.vision_authoring$/.exec(reference) : null; - const steps = object(object(object(payload.interaction_contract).cli_channel).settlement_plan).ordered_steps; - const step = object(match && Array.isArray(steps) ? steps[Number(match[1])] : null); - if (Object.hasOwn(contract, "vision_authoring") || step.kind !== "durable_writeback" || - Object.hasOwn(step, "vision_authoring_ref") || !Object.keys(object(step.vision_authoring)).length) { - throw new EffectRuntimeRequestError("Replan authoring reference must resolve to one complete inline durable-writeback owner"); - } - const {vision_authoring_ref: _reference, ...fields} = contract; - const resolved = {...fields, vision_authoring: step.vision_authoring}; - return precision?.retain(resolved, contract) ?? resolved; -} - -function referenceReplanAuthoring(payload: JsonObject, - identity = contextSourceIdentity(payload)): JsonObject { - const packet = object(payload.replan_action_packet); - const contract = object(packet.writeback_contract); - if (Object.hasOwn(contract, "vision_authoring_ref")) { - replanAuthoringContract(payload); - return payload; - } - const authoring = object(contract.vision_authoring); - const steps = object(object(object(payload.interaction_contract).cli_channel).settlement_plan).ordered_steps; - if (!Object.keys(authoring).length || !Array.isArray(steps)) return payload; - const encoded = JSON.stringify(canonicalValue(authoring)); - const source = identity(authoring, ["replan_action_packet", "writeback_contract", "vision_authoring"]); - const index = steps.findIndex((value, index) => { - const step = object(value); - return step.kind === "durable_writeback" && !Object.hasOwn(step, "vision_authoring_ref") && - jsonObject(step.vision_authoring) !== null && - identity(step.vision_authoring, ["interaction_contract", "cli_channel", "settlement_plan", - "ordered_steps", index, "vision_authoring"]) === source; - }); - if (index < 0) return payload; - const reference = `$.interaction_contract.cli_channel.settlement_plan.ordered_steps[${index}].vision_authoring`; - if (Buffer.byteLength(encoded, "utf8") <= Buffer.byteLength(reference, "utf8") + 8) return payload; - delete contract.vision_authoring; - return {...payload, replan_action_packet: {...packet, writeback_contract: { - ...contract, vision_authoring_ref: reference}}}; -} - -function resolveExploreGuidance(payload: JsonObject, context: JsonObject): JsonObject { - if (!Array.isArray(context.sources)) return context; - const steps = object(object(object(payload.interaction_contract).cli_channel).settlement_plan).ordered_steps; - return {...context, sources: context.sources.map(value => { - const source = object(value), content = object(source.content), graph = object(content.graph); - if (source.kind !== "explore_turn_context" || !Object.hasOwn(graph, "result_writeback_guidance_ref")) return value; - const reference = graph.result_writeback_guidance_ref; - const match = typeof reference === "string" - ? /^\$\.interaction_contract\.cli_channel\.settlement_plan\.ordered_steps\[(0|[1-9]\d*)\]\.optional_attachments\[(0|[1-9]\d*)\]\.guidance$/.exec(reference) : null; - const step = object(match && Array.isArray(steps) ? steps[Number(match[1])] : null); - const attachment = object(match && Array.isArray(step.optional_attachments) - ? step.optional_attachments[Number(match[2])] : null); - if (Object.hasOwn(graph, "result_writeback_guidance") || step.kind !== "durable_writeback" || - attachment.capability_id !== "explore" || Object.hasOwn(attachment, "guidance_ref") || - typeof attachment.guidance !== "string" || !attachment.guidance) { - throw new EffectRuntimeRequestError("Explore guidance reference must resolve to one inline durable-writeback Explore attachment"); - } - delete graph.result_writeback_guidance_ref; - return {...source, content: {...content, graph: {...graph, result_writeback_guidance: attachment.guidance}}}; - })}; -} - -/** Existing acceptance carriers only: this is not a general JSON-path codec. - * The loaded work context is preferred, then the complete planning/replan facts. - */ -function acceptanceCarriers(payload: JsonObject) { - // Keep read-only carrier parents attached to their source. The general - // object() helper intentionally returns copies for projection callers. - const carrierObject = (value: unknown): JsonObject => - typeof value === "object" && value !== null && !Array.isArray(value) - ? value as JsonObject : {}; - const carriers: {parent: JsonObject; field: string; path: string; parentPath: (string | number)[]}[] = []; - const sources = carrierObject(carrierObject(carrierObject(payload.interaction_contract).agent_channel).work_context).sources; - if (Array.isArray(sources)) { - const index = sources.findIndex(value => { - const source = carrierObject(value), content = carrierObject(source.content); - return source.source === "goal_acceptance" && - (content.status === undefined || content.status === "loaded") && - Object.keys(carrierObject(content.goal_acceptance_contract)).length > 0; - }); - if (index >= 0) carriers.push({parent: carrierObject(carrierObject(sources[index]).content), - field: "goal_acceptance_contract", - parentPath: ["interaction_contract", "agent_channel", "work_context", "sources", index, "content"], - path: `$.interaction_contract.agent_channel.work_context.sources[${index}].content.goal_acceptance_contract`}); - } - carriers.push( - {parent: carrierObject(carrierObject(payload.planning_horizon).core_goal), field: "acceptance_contract", - parentPath: ["planning_horizon", "core_goal"], - path: "$.planning_horizon.core_goal.acceptance_contract"}, - {parent: carrierObject(carrierObject(carrierObject(payload.autonomous_replan_obligation).replan_context).core_goal), - field: "acceptance_contract", path: "$.autonomous_replan_obligation.replan_context.core_goal.acceptance_contract", - parentPath: ["autonomous_replan_obligation", "replan_context", "core_goal"]}, - {parent: carrierObject(payload.agent_todo_summary), field: "goal_acceptance_contract", - parentPath: ["agent_todo_summary"], - path: "$.agent_todo_summary.goal_acceptance_contract"}, - ); - return carriers; -} - -function inlineAcceptance(payload: JsonObject, reference: unknown): JsonObject { - // Older captures may name any loaded work-context carrier, not only the - // preferred first source chosen for new sharing. - const match = typeof reference === "string" - ? /^\$\.interaction_contract\.agent_channel\.work_context\.sources\[(0|[1-9]\d*)\]\.content\.goal_acceptance_contract$/.exec(reference) : null; - if (match) { - const sources = object(object(object(payload.interaction_contract).agent_channel).work_context).sources; - const source = object(Array.isArray(sources) ? sources[Number(match[1])] : null); - const content = object(source.content); - if (source.source === "goal_acceptance" && - (content.status == null || content.status === "loaded") && - !Object.hasOwn(content, "goal_acceptance_contract_ref") && - Object.keys(object(content.goal_acceptance_contract)).length) { - return object(content.goal_acceptance_contract); - } - } - const carrier = acceptanceCarriers(payload).find(item => item.path === reference); - const value = object(carrier?.parent[carrier.field]); - if (!carrier || Object.hasOwn(carrier.parent, `${carrier.field}_ref`) || !Object.keys(value).length) { - throw new EffectRuntimeRequestError("Goal acceptance reference must resolve to complete inline work context or planning facts"); - } - return value; -} - -function referenceGoalAcceptance(payload: JsonObject, - identity = contextSourceIdentity(payload)): JsonObject { - let result = payload; - // Copy only a changed registered carrier's spine. Retained source objects - // keep their identity for the display-edit transport and original numbers. - const writableParent = (path: (string | number)[]): JsonObject => { - result = {...result}; - let target: Record = result; - for (const key of path) { - const value = target[key]; - target[key] = Array.isArray(value) ? [...value] : {...requireJsonObject(value, "acceptance carrier")}; - target = target[key] as Record; - } - return target; - }; - const owners = new Map(); - const relocated = new Map(); - const carriers = acceptanceCarriers(payload); - for (const {parent, field, path, parentPath} of carriers) { - const value = object(parent[field]); - if (!Object.keys(value).length || Object.hasOwn(parent, `${field}_ref`)) continue; - // Complete canonical JSON distinguishes booleans/numbers, revisions, - // provenance and negative evidence. Never deduplicate a prose summary. - const encoded = identity(value, [...parentPath, field]); - const owner = owners.get(encoded); - if (!owner) owners.set(encoded, path); - else if (Buffer.byteLength(JSON.stringify(canonicalValue(value)), "utf8") > Buffer.byteLength(owner, "utf8") + 8) { - const target = writableParent(parentPath); - delete target[field]; - target[`${field}_ref`] = owner; - relocated.set(path, owner); - } - } - // A historical source can already reference a carrier that was just shared. - // Rebind that exact reference to the retained inline owner, never a chain. - for (const {parent, field, parentPath} of carriers) { - const reference = parent[`${field}_ref`]; - if (typeof reference === "string" && relocated.has(reference)) { - writableParent(parentPath)[`${field}_ref`] = relocated.get(reference); - } - } - return result; -} - -/** One registry for ordinary captured reads and staged replan. Only registered - * acceptance carriers participate; unrelated objects named `outcomes` are not - * sources. Equal content shares a reference, while differing revisions of the - * same outcome retain their complete bodies, including unknown fields. - */ -function indexCapturedAcceptanceOutcomes(payload: JsonObject, indexOutcome: (value: unknown) => string): void { - const carriers = acceptanceCarriers(payload); - // Sharing prefers the first source, but a diagnostic index must cover every - // loaded registered carrier, including different same-id revisions. - const sources = object(object(object(payload.interaction_contract).agent_channel).work_context).sources; - if (Array.isArray(sources)) for (const [index, value] of sources.entries()) { - const source = object(value), content = object(source.content); - if (source.source === "goal_acceptance" && (content.status == null || content.status === "loaded")) { - carriers.push({parent: content, field: "goal_acceptance_contract", path: "", - parentPath: ["interaction_contract", "agent_channel", "work_context", "sources", index, "content"]}); - } - } - for (const {parent, field} of carriers) { - const acceptance = Object.hasOwn(parent, `${field}_ref`) - ? inlineAcceptance(payload, parent[`${field}_ref`]) : object(parent[field]); - if (!Object.keys(acceptance).length) continue; - const requirements = object(acceptance.outcome_requirements); - if (!Object.hasOwn(acceptance, "outcome_requirements")) continue; - if (!Array.isArray(requirements.outcomes)) throw new EffectRuntimeRequestError("captured outcome source is unsupported"); - for (const value of requirements.outcomes) indexOutcome(value); - } -} - -/** Expose existing facts, not another acceptance verdict. Missing values stay - * absent; an Agent's `met` review is not a current independent check. - */ -function capturedOutcomeIndex(outcomes: ReadonlyMap, precision?: ReplanReadPrecision): JsonObject[] { - return [...outcomes].map(([ref, outcome]) => { - const states = new Map(); - if (Array.isArray(outcome.requirements)) for (const value of outcome.requirements) { - const requirement = requireJsonObject(value, "captured outcome requirement"); - const review = jsonObject(requirement.agent_review); - const state = { - ...Object.fromEntries(["status", "planning_satisfied"].filter(key => Object.hasOwn(requirement, key)) - .map(key => [key, requirement[key]])), - ...(Object.hasOwn(requirement, "agent_review") ? {agent_review: review === null - ? requirement.agent_review : Object.fromEntries( - ["conclusion", "basis_current", "independently_verified"].filter(key => Object.hasOwn(review, key)) - .map(key => [key, review[key]]))} : {}), - }; - const key = JSON.stringify(canonicalValue(state)); - const group = states.get(key); - if (group) (group.requirement_ids as unknown[]).push(requirement.id); - else states.set(key, {requirement_ids: [requirement.id], ...state}); - } - const row = {outcome_ref: ref, id: outcome.id, objective: outcome.objective, revision: outcome.revision, - ...Object.fromEntries(["owner_agent_id", "work", ...(Object.hasOwn(outcome, "work") ? [] : ["todo_ids"])].filter(key => Object.hasOwn(outcome, key)) - .map(key => [key, outcome[key]])), - requirement_count: Array.isArray(outcome.requirements) ? outcome.requirements.length : null, - requirement_states: Array.isArray(outcome.requirements) ? [...states.values()] : null}; - return precision?.retain(row, outcome, ["id", "objective", "revision", "owner_agent_id"]) ?? row; - }); -} - -/** Reuse the existing settlement authoring owner, never a summary or a chain. */ - - -/** Same-capture references have one typed settlement owner. Historical readers - * expand before moving work context, so a full-packet path never dangles in a - * staged envelope. Explore's independent read and domain guidance stay intact. */ - -function referenceExploreGuidance(payload: JsonObject): JsonObject { - const interaction = object(payload.interaction_contract), agent = object(interaction.agent_channel); - const context = object(agent.work_context); - resolveExploreGuidance(payload, context); // Validate existing references, including idempotent reads. - if (!Array.isArray(context.sources)) return payload; - const steps = object(object(interaction.cli_channel).settlement_plan).ordered_steps; - if (!Array.isArray(steps)) return payload; - const owners = new Map(); - steps.forEach((value, stepIndex) => { - const step = object(value); - if (step.kind !== "durable_writeback" || !Array.isArray(step.optional_attachments)) return; - step.optional_attachments.forEach((value, attachmentIndex) => { - const attachment = object(value), guidance = attachment.guidance; - if (attachment.capability_id !== "explore" || Object.hasOwn(attachment, "guidance_ref") || - typeof guidance !== "string" || !guidance || owners.has(guidance)) return; - owners.set(guidance, `$.interaction_contract.cli_channel.settlement_plan.ordered_steps[${stepIndex}].optional_attachments[${attachmentIndex}].guidance`); - }); - }); - const sources = context.sources.map(value => { - const source = object(value), content = object(source.content), graph = object(content.graph); - const guidance = graph.result_writeback_guidance; - const reference = typeof guidance === "string" ? owners.get(guidance) : undefined; - if (source.kind !== "explore_turn_context" || typeof guidance !== "string" || !reference || - Buffer.byteLength(JSON.stringify(guidance), "utf8") <= Buffer.byteLength(reference, "utf8") + 8) return value; - delete graph.result_writeback_guidance; - return {...source, content: {...content, graph: {...graph, result_writeback_guidance_ref: reference}}}; - }); - return {...payload, interaction_contract: {...interaction, agent_channel: {...agent, - work_context: {...context, sources}}}}; -} - -/** Keep the complete vision audit once. These existing projection references - * share identical facts only; a channel-specific obligation is never a summary - * of the root. The old display adapter delegates here before adding metadata. */ -function visionAuditReference(audit: JsonObject): JsonObject { - const reference: JsonObject = {projection_ref: "$.vision_continuation_audit"}; - for (const key of ["schema_version", "required", "decision"]) { - if (Object.hasOwn(audit, key)) reference[key] = audit[key]; - } - if (typeof audit.vision_gap_judge === "object" && audit.vision_gap_judge !== null && - !Array.isArray(audit.vision_gap_judge)) { - const judge = object(audit.vision_gap_judge); - reference.vision_gap_judge = {projection_ref: "$.vision_continuation_audit.vision_gap_judge"}; - for (const key of ["done", "decision"]) { - if (Object.hasOwn(judge, key)) (reference.vision_gap_judge as JsonObject)[key] = judge[key]; - } - } - return reference; -} - -function mapNestedVisionAudits(payload: JsonObject, - visit: (audit: JsonObject, path: (string | number)[]) => JsonObject): JsonObject { - const map = (value: unknown, path: (string | number)[]) => { - const parent = object(value), audit = parent.vision_continuation_audit; - if (typeof audit !== "object" || audit === null || Array.isArray(audit)) return value; - return {...parent, vision_continuation_audit: visit(audit as JsonObject, [...path, "vision_continuation_audit"])}; - }; - const rawInteraction = payload.interaction_contract, interaction = object(rawInteraction); - const hasInteraction = typeof rawInteraction === "object" && rawInteraction !== null && !Array.isArray(rawInteraction); - return {...payload, - ...(Object.hasOwn(payload, "goal_frontier_projection") ? { - goal_frontier_projection: map(payload.goal_frontier_projection, ["goal_frontier_projection"])} : {}), - ...(hasInteraction ? {interaction_contract: {...interaction, - ...Object.fromEntries(["agent_channel", "cli_channel"].filter(key => Object.hasOwn(interaction, key)) - .map(key => [key, map(interaction[key], ["interaction_contract", key])]))}} : {})}; -} - -function requireVisionAuditReferences(payload: JsonObject): void { - const owner = object(payload.vision_continuation_audit); - const chained = Object.hasOwn(owner, "projection_ref") || Object.hasOwn(object(owner.vision_gap_judge), "projection_ref"); - if (chained) throw new EffectRuntimeRequestError("Vision audit reference requires a complete inline root owner"); - mapNestedVisionAudits(payload, audit => { - if (Object.hasOwn(audit, "projection_ref") || Object.hasOwn(object(audit.vision_gap_judge), "projection_ref")) { - if (!Object.keys(owner).length || - JSON.stringify(canonicalValue(audit)) !== JSON.stringify(canonicalValue(visionAuditReference(owner)))) { - throw new EffectRuntimeRequestError("Vision audit reference must match its complete inline root owner without conflicting facts"); - } - } - return audit; - }); -} - -function referenceVisionContinuation(payload: JsonObject, - identity = contextSourceIdentity(payload)): JsonObject { - requireVisionAuditReferences(payload); - const owner = object(payload.vision_continuation_audit); - if (!Object.keys(owner).length) return payload; - const encoded = JSON.stringify(canonicalValue(owner)), reference = visionAuditReference(owner); - // A short audit is cheaper inline. Do not create a reference merely to count sharing. - if (Buffer.byteLength(encoded, "utf8") <= Buffer.byteLength(JSON.stringify(reference), "utf8")) return payload; - const source = identity(owner, ["vision_continuation_audit"]); - return mapNestedVisionAudits(payload, (audit, path) => - identity(audit, path) === source ? structuredClone(reference) : audit); -} - -/** The verified current Task is the only owner of a shared lane title. Keep - * the original declaration inline and require exact identity, never a label or - * prefix comparison. The legacy display and complete writer use this owner. */ -function currentTaskTitleOwner(payload: JsonObject): {index: number; todo: JsonObject} | null { - const lane = object(payload.agent_lane_next_action), selected = object(payload.selected_todo); - const context = object(object(object(payload.interaction_contract).agent_channel).work_context); - if (context.complete !== true || context.selected_todo_text_verified !== true || - typeof lane.todo_id !== "string" || !lane.todo_id || selected.todo_id !== lane.todo_id || - !Array.isArray(context.sources)) return null; - const matches = context.sources.map((value, index) => ({source: object(value), index})) - .filter(({source}) => source.source === "selected_todo"); - if (matches.length !== 1) return null; - const {source, index} = matches[0], content = object(source.content), todo = object(content.todo); - if (content.ok !== true || content.matched !== true || content.ambiguous === true || - content.read_complete === false || typeof todo.text !== "string" || - todo.archive_state === "archive" || todo.status === "done" || todo.todo_id !== lane.todo_id) return null; - return {index, todo}; -} - -function requireCurrentTaskTitleReference(payload: JsonObject): void { - const lane = object(payload.agent_lane_next_action); - if (!Object.hasOwn(lane, "title_ref")) return; - const reference = lane.title_ref; - const match = typeof reference === "string" - ? /^\$\.interaction_contract\.agent_channel\.work_context\.sources\[(0|[1-9]\d*)\]\.content\.todo\.(text|title)$/.exec(reference) : null; - const owner = currentTaskTitleOwner(payload); - if (Object.hasOwn(lane, "title") || !match || !owner || owner.index !== Number(match[1]) || - typeof owner.todo[match[2]] !== "string" || !owner.todo[match[2]] || - Object.hasOwn(owner.todo, `${match[2]}_ref`)) { - throw new EffectRuntimeRequestError("Current Task title reference must resolve to the complete verified selected Task"); - } -} - -function referenceCurrentTaskTitle(payload: JsonObject): JsonObject { - const lane = object(payload.agent_lane_next_action), title = lane.title; - // Preserve historical caller-owned references; complete readers validate them - // separately. Display-only omission of a title already in a label stays local. - if (typeof title !== "string" || Object.hasOwn(lane, "title_ref")) return payload; - const owner = currentTaskTitleOwner(payload); - if (!owner) return payload; - for (const field of ["text", "title"]) { - if (owner.todo[field] !== title || Object.hasOwn(owner.todo, `${field}_ref`)) continue; - const reference = `$.interaction_contract.agent_channel.work_context.sources[${owner.index}].content.todo.${field}`; - if (Array.from(JSON.stringify(title)).length <= reference.length + 8) return payload; - delete lane.title; - return {...payload, agent_lane_next_action: {...lane, title_ref: reference}}; - } - return payload; -} - -function compactFields( - value: unknown, - fields: readonly string[], - limits: Readonly> = {}, -): JsonObject { - const source = object(value); - const compact: JsonObject = {}; - for (const field of fields) { - const raw = source[field]; - if (raw === null || raw === undefined) continue; - if (limits[field] !== undefined) { - const rendered = text(raw, limits[field]); - if (rendered) compact[field] = rendered; - } else if (Array.isArray(raw)) { - const values = textList(raw, 6, 140); - if (values.length > 0) compact[field] = values; - } else { - compact[field] = raw; - } - } - return compact; -} - -function selectedTodo(payload: JsonObject, recommendedAction: string | null): JsonObject | null { - const source = object(payload.selected_todo); - if (Object.keys(source).length === 0) return null; - const compact: JsonObject = {}; - for (const field of [ - "todo_id", "priority", "status", "task_class", "action_kind", - "task_repository", "continuation_policy", "claimed_by", "bound_agent", - "goal_bound", "blocks_agent", "unblocks_todo_id", "next_due_at", - "expires_at", "selected_by", "confidence", - "resume_when", "resume_ready", "resume_condition", - ]) { - if (source[field] !== null && source[field] !== undefined) compact[field] = source[field]; - } - const context = object(object(object(payload.interaction_contract).agent_channel).work_context); - if (context.selected_todo_text_verified === true) compact.text_source_verified = true; - // Work declarations can end in acceptance/stop conditions. Keep their exact - // text; a display prefix or case-folded recommendation cannot stand in for it. - const rendered = scalarString(source.text, "selected_todo.text"); - if (rendered && rendered === recommendedAction) { - compact.text_ref = "action.recommended_action"; - } else if (rendered) { - compact.text = rendered; - } - return Object.keys(compact).length > 0 ? compact : null; -} - -/** These reads stay on one captured observation; they never re-enter the guard. */ -function replanReadCommands(payload: JsonObject, path = payload.replan_read_path, - argv: unknown = payload.replan_read_argv ?? ["loopx"], verifiedSourceHash?: string, - captureSha256?: unknown): JsonObject | null { - const packet = object(payload.replan_action_packet); - if (typeof path !== "string" || !path.trim() || path.includes("\0") || payload.ok !== true || - payload.effective_action === EffectiveAction.GOVERNED_CAPABILITY_INTENT || - object(object(payload.interaction_contract).cli_channel).turn_binding_required === true || - !packet.obligation_id || packet.settlement_only === true) return null; - // Retain the renderer's executable across reads. A different ambient LoopX - // may not understand this captured contract. Legacy captures keep their route. - if (!Array.isArray(argv) || !argv.length || argv.some(arg => typeof arg !== "string" || !arg || /[\x00-\x1f]/.test(arg))) { - throw new EffectRuntimeRequestError("captured replan CLI route is malformed"); - } - if (captureSha256 !== undefined && - (typeof captureSha256 !== "string" || !BARE_SHA256_PATTERN.test(captureSha256))) { - throw new EffectRuntimeRequestError("captured replan byte digest is malformed"); - } - const command = `${argv.map(arg => shellQuote(arg as string)).join(" ")} --format json quota replan-view --decision-file ${shellQuote(path)}` + - ` --source-hash ${verifiedSourceHash ?? decisionSourceHash(payload)}` + - (captureSha256 === undefined ? "" : ` --capture-sha256 ${captureSha256}`); - return {review: `${command} --replan-stage review`, writeback: `${command} --replan-stage writeback`, - acceptance: `${command} --replan-stage acceptance`, explore: `${command} --replan-stage explore`}; -} - -/** One entry lens for CLI and Turn. The executor still receives the signed - * identity; authoring and executable settlement commands have one later read. - */ -function deferredReplanWriteback(writeback: JsonObject): JsonObject { - const {settlement_plan: plan, next_cli_actions: actions, ...facts} = writeback; - if (!Object.keys(object(plan)).length && !(Array.isArray(actions) && actions.length)) return writeback; - const identity = object(object(plan).identity); - return {...facts, settlement_read_ref: "$.replan_action_packet.writeback", - ...(Object.keys(identity).length ? {settlement_identity: identity} : {})}; -} - -/** Preserve the captured Goal and work horizon for review and the signed - * executor envelope, indexing cumulative outcome details by exact content. - */ -function replanGoalContext(payload: JsonObject, reads: JsonObject | null, coreRef = "$.core_goal", - precision?: ReplanReadPrecision) { - const context = object(object(payload.autonomous_replan_obligation).replan_context); - const retain = precision?.retain ?? ((view: JsonObject) => view); - function resolvedGoal(value: unknown): JsonObject { - const original = jsonObject(value) ?? {}; - const core = retain({...original}, original); - if (!("acceptance_contract" in core) && "acceptance_contract_ref" in core) { - const acceptance = inlineAcceptance(payload, core.acceptance_contract_ref); - delete core.acceptance_contract_ref; - core.acceptance_contract = acceptance; - } - return core; - } - function capturedOutcomes(core: JsonObject): JsonObject[] { - const requirements = object(object(core.acceptance_contract).outcome_requirements); - return reads && Array.isArray(requirements.outcomes) - ? requirements.outcomes.map(value => requireJsonObject(value, "captured acceptance outcome")) : []; - } - const resolvedCore = resolvedGoal(context.core_goal); - const originalHorizon = jsonObject(payload.planning_horizon) ?? {}; - const horizon = retain({...originalHorizon}, originalHorizon); - const resolvedHorizon = horizon.core_goal ? resolvedGoal(horizon.core_goal) : null; - const coreOutcomes = capturedOutcomes(resolvedCore); - const horizonOutcomes = resolvedHorizon ? capturedOutcomes(resolvedHorizon) : []; - const refs = new Map(); - const legacyGroups = new Map(); - const captured = [...coreOutcomes, ...horizonOutcomes]; - const complete = payload.schema_version === COMPLETE_TURN_DECISION_VERSION; - if (reads && complete) indexCapturedAcceptanceOutcomes(payload, value => { - captured.push(requireJsonObject(value, "captured acceptance outcome")); - return ""; - }); - for (const outcome of captured) { - if (refs.has(outcome)) continue; - const legacy = canonicalHash(outcome); - refs.set(outcome, legacy); - if (precision) { - const group = legacyGroups.get(legacy); - if (group) group.push(outcome); - else legacyGroups.set(legacy, [outcome]); - } - } - // Keep historical references where they identify exactly one outcome. - // When number decoding collapsed different outcomes, index each original - // body and reject the old ambiguous reference on the acceptance stage. - const ambiguous = new Set(); - if (precision) for (const [legacy, group] of legacyGroups) { - if (group.length < 2) continue; - const exact = group.map(outcome => precision.identity(outcome, [])); - if (new Set(exact).size < 2) continue; - ambiguous.add(legacy); - group.forEach((outcome, index) => refs.set(outcome, canonicalHash([legacy, exact[index]]))); - } - const outcomes = new Map(); - for (const [outcome, ref] of refs) outcomes.set(ref, outcome); - function indexedGoal(core: JsonObject, captured: JsonObject[]): JsonObject { - if (!captured.length) return core; - const originalAcceptance = jsonObject(core.acceptance_contract) ?? {}; - const acceptance = retain({...originalAcceptance}, originalAcceptance); - const requirements = jsonObject(acceptance.outcome_requirements) ?? {}; - const {outcomes: _outcomes, ...metadata} = requirements; - delete acceptance.outcome_requirements; - return retain({...core, acceptance_contract: acceptance, - outcome_requirements_index: retain({...metadata, outcome_refs: captured.map(outcome => refs.get(outcome)!)}, - requirements)}, core); - } - const core = indexedGoal(resolvedCore, coreOutcomes); - if (resolvedHorizon) { - const horizonCore = indexedGoal(resolvedHorizon, horizonOutcomes); - if (canonicalHash(horizonCore) === canonicalHash(core) && - (precision?.equalProjection(horizonCore, core) ?? true)) { - delete horizon.core_goal; - horizon.core_goal_ref = coreRef; - } else horizon.core_goal = horizonCore; - } - const acceptanceIndex = outcomes.size ? { - read_action_template: `${reads!.acceptance} --outcome-ref {outcome_ref}`, - outcomes: complete ? capturedOutcomeIndex(outcomes, precision) : [...outcomes].map(([ref, outcome]) => retain({outcome_ref: ref, id: outcome.id, - objective: outcome.objective, revision: outcome.revision, - requirement_count: Array.isArray(outcome.requirements) ? outcome.requirements.length : null}, - outcome, ["id", "objective", "revision"])), - } : null; - return {core, horizon, outcomes, acceptanceIndex, ambiguous}; -} - -/** Applicability of Explore's existing attachment owner, shared by complete - * composition and the historical staged projection. No authority is granted. */ -function unboundExploreReplan(payload: JsonObject, plan: JsonObject): boolean { - const steps = Array.isArray(plan.ordered_steps) ? plan.ordered_steps.map(object) : []; - const attachments = object(steps.find(step => step.kind === "durable_writeback")).optional_attachments; - const explore = Array.isArray(attachments) ? attachments.map(object).filter(row => row.capability_id === "explore") : []; - const identity = object(plan.identity); - return payload.effective_action === EffectiveAction.AUTONOMOUS_REPLAN_REQUIRED && - selectedWorkTodoId(payload) === null && identity.binding_kind === "autonomous_replan" && - identity.replan_obligation_id === object(payload.replan_action_packet).obligation_id && - !identity.todo_id && explore.length === 0; -} - -/** Move only an identical acceptance copy behind the existing captured read. - * Different revisions, other source fields and unavailable context stay intact. - */ -function replanWorkContext(payload: JsonObject, context: JsonObject, reads = replanReadCommands(payload), - identity: ReplanValueIdentity = canonicalHash): JsonObject { - context = resolveExploreGuidance(payload, context); - const corePath = ["autonomous_replan_obligation", "replan_context", "core_goal"]; - const core = object(object(object(payload.autonomous_replan_obligation).replan_context).core_goal); - const acceptance = object(core.acceptance_contract); - if (!reads || !Array.isArray(context.sources)) return context; - const plan = object(object(object(payload.interaction_contract).cli_channel).settlement_plan); - const steps = Array.isArray(plan.ordered_steps) ? plan.ordered_steps.map(object) : []; - const attachments = object(steps.find(step => step.kind === "durable_writeback")).optional_attachments; - const explore = Array.isArray(attachments) ? attachments.map(object).filter(row => row.capability_id === "explore") : []; - const unboundReplan = unboundExploreReplan(payload, plan); - return {...context, sources: context.sources.map((value, index) => { - const source = object(value), content = object(source.content); - if (source.source === "turn_start_capability_hook" && source.hook_id === "explore.turn_context" && - source.capability_id === "explore" && explore.length === 1 && typeof reads.writeback === "string") { - return {...source, content: referenceExploreResultWriteback(content, explore[0], reads.writeback)}; - } - if (unboundReplan && source.source === "turn_start_capability_hook" && - source.hook_id === "explore.turn_context" && source.capability_id === "explore") { - return {...source, content: omitUnboundExploreResultWriteback(content)}; - } - if (!Object.keys(acceptance).length || source.source !== "goal_acceptance" || content.status != null && content.status !== "loaded" || - identity(content.goal_acceptance_contract, - ["interaction_contract", "agent_channel", "work_context", "sources", index, "content", "goal_acceptance_contract"]) - !== identity(acceptance, [...corePath, "acceptance_contract"])) return value; - const {goal_acceptance_contract: _contract, ...metadata} = content; - return {...source, content: {...metadata, context_read: reads.review}}; - })}; -} - -/** Bind successor authoring to the already-decided Turn. This formatting - * owner is shared by complete composition and historical staged reads; it does - * not select work, create a successor or change the settlement plan. - */ -function bindReplanSuccessorContract(value: JsonObject, plan: JsonObject): JsonObject { - const contract = {...value}; - const identity = object(plan.identity); - if (typeof identity.turn_instance_id !== "string") return contract; - const goalRef = object(plan.goal_ref); - contract.successor_binding_args = `--turn-instance-id ${shellQuote(identity.turn_instance_id)}` + - (typeof goalRef.goal_instance_id === "string" ? ` --goal-instance-id ${shellQuote(goalRef.goal_instance_id)}` : ""); - contract.successor_settlement = "If creating a replan successor, include successor_binding_args with its obligation id, then follow the creation receipt's original Turn settlement plan before ending; do not run the successor."; - delete contract.successor_host_action; - if (typeof contract.successor_command === "string") { - contract.successor_command = `${contract.successor_command} ${contract.successor_binding_args}`; - } - return contract; -} - -function replanView(request: JsonObject): JsonObject { - const payload = requireJsonObject(request.payload, "captured replan decision"); - const sourceHash = decisionSourceHash(payload); - if (request.source_hash !== sourceHash || payload.ok !== true) { - throw new EffectRuntimeRequestError("Replan read requires the original successful decision and matching source hash"); - } - // Validate the complete current source before the historical display lens. - if (Object.hasOwn(payload, "schema_version") || Object.hasOwn(payload, "contract_binding")) { - requireCompleteTurnDecision(payload, request.source_number_tokens); - } else requireVisionAuditReferences(payload); - const precision = replanReadPrecision(payload, request.source_number_tokens); - const view = projectReplanView(request, payload, sourceHash, precision); - return precision ? contextProjectionChanges(payload, view, precision.values, {}) : view; -} - -function projectReplanView(request: JsonObject, payload: JsonObject, sourceHash: string, precision?: ReplanReadPrecision): JsonObject { - const retain = precision?.retain ?? ((view: JsonObject) => view); - requireVisionAuditReferences(payload); - const originalContract = replanAuthoringContract(payload, precision); - const packet = jsonObject(payload.replan_action_packet) ?? {}; - const obligation = jsonObject(payload.autonomous_replan_obligation) ?? {}; - const context = jsonObject(obligation.replan_context) ?? {}; - if (!packet.obligation_id || packet.settlement_only === true || packet.obligation_id !== context.obligation_id) { - throw new EffectRuntimeRequestError("Replan read requires a matching decision context"); - } - const common = {ok: true, goal_id: payload.goal_id, agent_id: payload.agent_id ?? object(payload.agent_identity).agent_id, - obligation_id: packet.obligation_id, context_id: context.context_id, source_hash: request.source_hash, - stage: request.stage}; - // A native journal binds its path after planning. The CLI supplies that same - // physical source route without modifying the captured observation or hash. - const path = request.captured_decision_path ?? payload.replan_read_path; - const reads = replanReadCommands(payload, path, payload.replan_read_argv ?? request.reader_argv ?? ["loopx"], - sourceHash, request.capture_sha256); - // The stateless entry already exposes its digest-checked complete context. - // Its writer should not offer a second, unchecked whole-file route. - const sourceRead = reads && request.capture_sha256 === undefined - ? {source_read: `cat -- ${shellQuote(path as string)}`} : {}; - if (request.stage === "acceptance") { - const {outcomes, ambiguous} = replanGoalContext(payload, reads, undefined, precision); - const ref = String(request.outcome_ref); - if (ambiguous.has(ref)) throw new EffectRuntimeRequestError( - "The old captured outcome reference is ambiguous. Read the review stage for the distinct references."); - const outcome = outcomes.get(ref); - if (!outcome) throw new EffectRuntimeRequestError("acceptance read requires an exact captured outcome reference"); - return {...common, outcome_ref: request.outcome_ref, outcome}; - } - if (request.stage === "explore") - return retain({...common, explore_basis: context.explore_basis ?? null}, context, ["explore_basis"]); - if (request.stage === "writeback") { - // Preserve executable shape and all settlement rules; decision advice and - // duplicate context are available in the unchanged full captured source. - const originalStride = jsonObject(packet.stride_control) ?? {}; - const stride = retain({...originalStride}, originalStride); - // The current nested review syntax belongs to authoring, not duplicate - // decision evidence. Top-level required_fields cannot describe that shape. - for (const key of ["decision_followthrough", "explore_basis", "decision_value_review"]) delete stride[key]; - const contract = {...originalContract}; - if (contract.vision_authoring) { - const originalAuthoring = jsonObject(contract.vision_authoring) ?? {}; - const authoring = retain({...originalAuthoring}, originalAuthoring); - delete authoring.minimal_example; - contract.vision_authoring = authoring; - } - const writeback = object(actionProjection(payload, false, precision, sourceHash).writeback); - const plan = object(writeback.settlement_plan); - const boundContract = payload.schema_version === COMPLETE_TURN_DECISION_VERSION - ? contract : bindReplanSuccessorContract(contract, plan); - if (typeof boundContract.successor_command === "string" && typeof object(plan.identity).turn_instance_id === "string") { - // Creation returns the original settlement plan directly. A guard - // reentry would repeat admission/context and can select new work. - writeback.next_cli_actions = [boundContract.successor_command]; - } - const steps = Array.isArray(plan.ordered_steps) ? plan.ordered_steps.map(object) : []; - const refresh = steps.find(step => step.kind === "durable_writeback"); - const spend = steps.find(step => step.kind === "quota_spend"); - const receipt = object(payload.heartbeat_receipt), identity = object(plan.identity); - const cli = object(object(payload.interaction_contract).cli_channel); - const settlement = object(cli.replan_settlement_contract), binding = object(settlement.settlement_binding); - const semantic = object(settlement.semantic_obligation), actions = cli.next_cli_actions; - // Use the captured semantic writer, which already carries the owner's - // authoring arguments. The generic plan template omits those arguments. - // Leave the signed plan and separate recovery actions untouched. - const directWriter = payload.schema_version === COMPLETE_TURN_DECISION_VERSION - && payload.should_run === true && payload.effective_action === EffectiveAction.AUTONOMOUS_REPLAN_REQUIRED - && plan.schema_version === SETTLEMENT_PLAN_SCHEMA_VERSION && identity.binding_kind === "autonomous_replan" - && typeof identity.turn_instance_id === "string" && receipt.turn_instance_id === identity.turn_instance_id - && identity.replan_obligation_id === packet.obligation_id - && ["committed", "upgraded", "replayed"].includes(String(receipt.status)) - && receipt.settlement_binding_owed !== true && isDeepStrictEqual(receipt.settlement_identity, identity) - && settlement.schema_version === REPLAN_SETTLEMENT_CONTRACT_SCHEMA && settlement.single_binding_required === true - && binding.kind === "autonomous_replan" && binding.id === packet.obligation_id - && binding.cli_argument === "--replan-obligation-id" && semantic.kind === "autonomous_replan" - && semantic.settlement_bound === true && semantic.id === packet.obligation_id - && semantic.discharge === "direct_settlement" && cli.spend_after_validation === true - && cli.spend_allowed_now === false && cli.selection_required !== true - && typeof boundContract.successor_command !== "string" - && refresh?.owner === "agent" && spend?.owner === "agent" && typeof spend.command_template === "string" - && Array.isArray(actions) && actions.length === 2 && actions[1] === spend.command_template - && typeof actions[0] === "string" && actions[0].length > 0 - && isDeepStrictEqual(writeback.next_cli_actions, [actions[0]]) - ? actions[0] : undefined; - const settlementCommand = directWriter !== undefined - ? directWriter + " --settle-turn --settlement-receipt" - : typeof refresh?.command_template === "string" ? refresh.command_template + " --settle-turn" : undefined; - return retain({...common, ...sourceRead, writeback_contract: retain(boundContract, originalContract), - required_outcome: packet.required_outcome, allowed_terminal: packet.allowed_terminal, - ...(packet.stride_control ? {stride_control: stride} : {}), - writeback, - ...(settlementCommand === undefined ? {} : { - settlement_command: settlementCommand, - settlement_usage: "After validation, fill this refresh command from the actual result. It follows only the verified owed quota step on this same binding. " + - "Do not also execute a quota step after settled readback; retain the original plan for completion, blocked/no-spend closeout and failure recovery.", - })}, packet, ["required_outcome", "allowed_terminal"]); - } - if (request.stage !== "review") throw new EffectRuntimeRequestError("unsupported replan read stage"); - const {core, horizon, acceptanceIndex} = replanGoalContext(payload, reads, undefined, precision); - const cli = object(object(payload.interaction_contract).cli_channel); - // Index every captured outcome, including differing context/horizon revisions. - // Full-content equality alone shares a row; identical IDs do not erase edits. - const coverage = Array.isArray(context.coverage_ledger) ? context.coverage_ledger.map(value => - jsonObject(value) ?? {}) : []; - const originalFollow = jsonObject(context.decision_followthrough) ?? {}; - const follow = {...originalFollow}; - delete follow.guidance; - const followFields = Object.keys(follow); - if (Object.hasOwn(follow, "recorded_progress_count")) { - follow.observation_count = follow.recorded_progress_count; - delete follow.recorded_progress_count; - retain(follow, originalFollow, followFields.filter(field => field !== "observation_count")); - retain(follow, originalFollow, [["recorded_progress_count", "observation_count"]]); - } else retain(follow, originalFollow, followFields); - const explore = jsonObject(context.explore_basis) ?? {}; - const yardstickCount = Array.isArray(explore.work_yardsticks) ? explore.work_yardsticks.length : 0; - const reversal = reads ? scopedReplanYardstickReversal(payload) : undefined; - const decisionValueReview = jsonObject(jsonObject(packet.stride_control)?.decision_value_review); - const review = retain({...common, - core_goal: core, - planning_guidance: packet.planning_guidance ?? [], - // The staged writer only carries authoring rules. Deliver the captured - // decision advice here so it can inform the choice before writeback. - ...(decisionValueReview ? {decision_value_review: decisionValueReview} : {}), - ...(acceptanceIndex ? {acceptance_index: acceptanceIndex} : {}), - triggers: obligation.triggers, - decision_followthrough: Object.keys(follow).length ? follow : null, - planning_horizon: payload.planning_horizon == null ? null : horizon, - action_portfolio: payload.action_portfolio ?? null, - ...(context.explore_basis ? {capabilities: {explore: retain({ - availability: explore.availability, revision: explore.revision, - ...(Array.isArray(explore.measurement_feedback) && explore.measurement_feedback.length - ? {measurement_count: explore.measurement_feedback.length} : {}), - ...(yardstickCount ? {yardstick_count: yardstickCount} : {}), - ...(reversal ? {work_yardstick_reversal: retain(compactFields(reversal.cue, reversal.fields), reversal.cue)} : {}), - read_action: reads?.explore ?? null, - }, explore, ["availability", "revision"])}} : {}), - evidence: (Array.isArray(context.evidence) ? context.evidence : []).map(value => { - const row = jsonObject(value) ?? {}; - const observation = coverage.find(item => item.fingerprint === row.coverage_ref); - const item = retain({...compactFields(row, ["evidence_ref", "generated_at", "delivery_outcome", "coverage_ref", - "occurrences", "first_observed_at", "read_action"]), - ...(observation ? {result_class: observation.result_class} : {})}, row); - return observation ? retain(item, observation, ["result_class"]) : item; - }), - evidence_count: context.evidence_count, - coverage_count: context.coverage_count, - coverage_truncated: context.coverage_truncated, - omitted_evidence: context.omitted_evidence ?? null, - evidence_read_action_template: context.evidence_read_action_template ?? null, - uncovered_frontier: context.uncovered_frontier, - // Facts and their provenance are the review input. Do not preselect a - // diagnostic method, candidate route or judgment from observation counts. - // A suggested Todo can already be present before the guard binds it. - // Follow the entry's command: its host may already have bound the current - // presentation options after this immutable decision was captured. - next: cli.selection_required === true - ? {selection_required: true, selection_command_ref: "$.interaction_contract.cli_channel.selection_command"} - : {writeback: reads?.writeback ?? null}, - }, context, ["evidence_count", "coverage_count", "coverage_truncated", "omitted_evidence", - "evidence_read_action_template", "uncovered_frontier"]); - retain(review, obligation, ["triggers"]); - return retain(review, packet, ["planning_guidance"]); -} - -function replanActionPacket(payload: JsonObject, reads = replanReadCommands(payload)): JsonObject | null { - const source = object(payload.replan_action_packet); - if (Object.keys(source).length === 0) return null; - const writeback = replanAuthoringContract(payload); - if (reads) return {...compactFields(source, ["schema_version", "decision", "obligation_id", "required_outcome", "allowed_terminal"]), - review: reads.review, writeback: reads.writeback, - guidance: "Read review state and applicable acceptance/evidence; choose the next work, then follow review.next for Todo selection or writeback. Reads grant no authority and require no acknowledgement."}; - const compact = compactFields(source, [ - "schema_version", "decision", "obligation_id", "uncovered_frontier", - "required_outcome", "allowed_terminal", "bounded_frontier", "settlement_only", "successor_todo_id", "stride_control", - ]); - // The typed replan owner supplies bounded instructions; do not truncate their - // authority/stop qualifiers through generic diagnostic compaction. - if (Array.isArray(source.planning_guidance)) compact.planning_guidance = source.planning_guidance; - if (writeback.vision_authoring) compact.writeback_contract = writeback; - return Object.keys(compact).length > 0 ? compact : null; -} - -function userChannel(interaction: JsonObject, payload: JsonObject): JsonObject { - const source = object(interaction.user_channel); - const channel: JsonObject = { - action_required: Boolean(source.action_required ?? payload.action_required), - open_count: integer(payload.open_count, "payload.open_count"), - notify: scalarString(source.notify, "interaction.user_channel.notify", "DONT_NOTIFY"), - }; - const actions = textList(source.actions, 3, 360); - if (actions.length > 0) channel.actions = actions; - const reason = text(source.reason, 360); - if (reason) channel.reason = reason; - return channel; -} - -function responsePlan(interaction: JsonObject): JsonObject | null { - const source = object(interaction.response_plan); - if (Object.keys(source).length === 0) return null; - const plan: JsonObject = {}; - for (const field of ["schema_version", "kind", "decision"]) { - const rendered = text(source[field], 80); - if (rendered) plan[field] = rendered; - } - const actionSequence = textList(source.action_sequence, 8, 80); - if (actionSequence.length > 0) plan.action_sequence = actionSequence; - if (typeof source.silent_wait_allowed === "boolean") { - plan.silent_wait_allowed = source.silent_wait_allowed; - } - return Object.keys(plan).length > 0 ? plan : null; -} - -function requiredReads(interaction: JsonObject, payload: JsonObject): JsonObject[] { - const raw = object(interaction.agent_channel).required_reads - ?? interaction.required_reads ?? payload.required_reads; - const result: JsonObject[] = []; - for (const value of Array.isArray(raw) ? raw : []) { - const item = object(value); - // Required reads are executable obligations, not display summaries. Keep - // every admitted command byte-for-byte, including quoted path whitespace. - const command = scalarString(item.command, "required read command"); - if (!command) continue; - const compact: JsonObject = { command }; - // These are existing obligation coordinates, not provider diagnostics. - // Keep identity and ordering intact, just like the executable command. - for (const field of ["kind", "reason", "source", "ordering", "hook_id", "capability_id"]) { - const value = scalarString(item[field], `required read ${field}`); - if (value) compact[field] = value; - } - if (item.source === "turn_start_capability_hook" && item.prompt_budget_bytes !== undefined) { - compact.prompt_budget_bytes = item.prompt_budget_bytes; - } - result.push(compact); - } - return result; -} - function checkpointedBoundaryAuthority(source: JsonObject): JsonObject | null { const approved = object(source.checkpointed_boundary_authority); const approvedScopes = Array.isArray(approved.active_write_scope) - ? approved.active_write_scope.filter((scope): scope is string => - typeof scope === "string" && scope.length > 0) + ? approved.active_write_scope.filter((scope): scope is string => typeof scope === "string" && scope.length > 0) : []; if (approved.schema_version !== "checkpointed_boundary_authority_v0" || !Number.isInteger(approved.active_count) || Number(approved.active_count) <= 0 || @@ -1156,12 +175,7 @@ export function projectTurnBoundary(payload: JsonObject): JsonObject { rule: scalarString(source.rule, "goal_boundary.rule", "stay_in_scope_or_stop"), }; const adapter = object(source.adapter); - if (Object.keys(adapter).length > 0) { - result.adapter = Object.fromEntries( - ["kind", "status"].filter((field) => adapter[field] !== null && adapter[field] !== undefined) - .map((field) => [field, adapter[field]]), - ); - } + if (Object.keys(adapter).length > 0) result.adapter = pickNonNull(adapter, ["kind", "status"]); // These are resolved restrictions, not display summaries. Preserve literal // paths, every clause and explicit empty lists; budget warnings cannot trim // an approval requirement or turn a path into a different glob. @@ -1192,13 +206,11 @@ export function projectTurnBoundary(payload: JsonObject): JsonObject { if (Object.keys(workspaceGuard).length > 0) result.workspace_guard = workspaceGuard; const capabilityGate = object(payload.capability_gate); if (Object.keys(capabilityGate).length > 0) { - result.capability_gate = Object.fromEntries( - // Current gate facts use required/missing; keep historical field names - // only when supplied by a stored source. Never rebuild the gate here. - ["action", "reason", "required", "missing", "required_capabilities", "missing_capabilities", "owner_action"] - .filter((field) => capabilityGate[field] !== null && capabilityGate[field] !== undefined) - .map((field) => [field, capabilityGate[field]]), - ); + // Current gate facts use required/missing; keep historical field names + // only when supplied by a stored source. Never rebuild the gate here. + result.capability_gate = pickNonNull(capabilityGate, [ + "action", "reason", "required", "missing", "required_capabilities", "missing_capabilities", "owner_action", + ]); } return result; } @@ -1210,38 +222,26 @@ function scheduler(payload: JsonObject, turn: ReturnType 0 - ? appAutomation - : legacyCodexApp; + const sourceApp = Object.keys(appAutomation).length > 0 ? appAutomation : legacyCodexApp; if (Object.keys(sourceApp).length === 0) return result; const sourceRef = Object.keys(appAutomation).length > 0 ? "full_decision.scheduler_hint.app_automation" : "full_decision.scheduler_hint.codex_app"; - const app: JsonObject = {}; - for (const field of [ + const app = pickNonNull(sourceApp, [ "host_surface", "apply", "host_action", "recommended_rrule", "no_spend_for_cadence_change", "execution_interval_policy", "guarantee", - ]) { - if (sourceApp[field] !== null && sourceApp[field] !== undefined) app[field] = sourceApp[field]; - } + ]); const state = object(sourceApp.stateful_backoff); if (Object.keys(state).length > 0) { - const compactState: JsonObject = {}; - for (const field of ["state_key", "current_rrule", "apply_needed", "ack_needed", "state_status"]) { - if (state[field] !== null && state[field] !== undefined) compactState[field] = state[field]; - } + const compactState = pickNonNull(state, ["state_key", "current_rrule", "apply_needed", "ack_needed", "state_status"]); const failure = object(state.host_update_failure); if (Object.keys(failure).length > 0) { - compactState.host_update_failure = Object.fromEntries( - ["target_rrule", "observed_host_rrule", "failure_kind", "failure_count"] - .filter((field) => failure[field] !== null && failure[field] !== undefined) - .map((field) => [field, failure[field]]), - ); + compactState.host_update_failure = pickNonNull(failure, [ + "target_rrule", "observed_host_rrule", "failure_kind", "failure_count", + ]); } app.stateful_backoff = compactState; } @@ -1276,15 +276,11 @@ function scheduler(payload: JsonObject, turn: ReturnType 0) capsule[sourceKey] = compact; } // These source owners provide execution contracts, not display summaries. @@ -1314,26 +308,21 @@ function contractCapsule(payload: JsonObject): JsonObject { // Work qualification is behavioral context, including its outcome and // degradation rules. Display-field filtering must not weaken that contract. const executionProfile = object(payload.execution_profile); - if (Object.keys(executionProfile).length > 0) { - capsule.execution_profile = structuredClone(executionProfile); - } + if (Object.keys(executionProfile).length > 0) capsule.execution_profile = structuredClone(executionProfile); // These existing source fields govern evidence and continuation, rather // than summarize display text. Preserve every clause, order, empty value // and current judge without copying the detailed acceptance-gap ledger. const visionAudit = object(payload.vision_continuation_audit); - const visionContract: JsonObject = {}; - for (const field of [ + const visionContract = structuredClone(pickOwn(visionAudit, [ "schema_version", "required", "agent_id", "decision", "trigger_count", "trigger_kinds", "selected_todo_is_goal_completion", "closeout_allowed_without_evidence", "required_before_closeout", "recommended_action", "vision_gap_judge", "authoritative_evidence_kinds", "not_satisfied_by", - ]) { - if (Object.hasOwn(visionAudit, field)) visionContract[field] = structuredClone(visionAudit[field]); - } + ])); if (Object.keys(visionContract).length > 0) capsule.vision_continuation_audit = visionContract; // Preserve the bounded source diagnosis; the generic capsule list path is // for scalar lists and must not stringify structured component checks. - const diagnostics = object(payload.vision_continuation_audit).outcome_checkpoint_diagnostics; + const diagnostics = visionAudit.outcome_checkpoint_diagnostics; if (Array.isArray(diagnostics) && diagnostics.length > 0) { const audit = object(capsule.vision_continuation_audit); audit.outcome_checkpoint_diagnostics = diagnostics.slice(0, 5).map((value) => { @@ -1381,10 +370,7 @@ function actionProjection(payload: JsonObject, deferSettlement = true, precision const reads = replanReadCommands(payload, payload.replan_read_path, payload.replan_read_argv ?? ["loopx"], verifiedSourceHash); if (payload.schema_version === COMPLETE_TURN_DECISION_VERSION) payload = resolveQuotaSummaryLanes(payload); const agentIdentity = object(payload.agent_identity); - const semanticAgentId = scalarString( - payload.agent_id || agentIdentity.agent_id, - "quota payload agent_id", - ).trim() || null; + const semanticAgentId = scalarString(payload.agent_id || agentIdentity.agent_id, "quota payload agent_id").trim() || null; const turn = interpretQuotaShouldRunPacket(payload, { goal_id: scalarString(payload.goal_id, "quota payload goal_id") || null, agent_id: semanticAgentId, @@ -1411,9 +397,7 @@ function actionProjection(payload: JsonObject, deferSettlement = true, precision selected_todo: selectedTodo(payload, recommendedAction), }; if (capabilityIntent) action.capability_intent = capabilityIntent; - if (turn.observation.action_portfolio !== null) { - action.action_portfolio = { ...turn.observation.action_portfolio }; - } + if (turn.observation.action_portfolio !== null) action.action_portfolio = { ...turn.observation.action_portfolio }; if (turn.observation.planning_horizon !== null) action.planning_horizon = {...turn.observation.planning_horizon}; if (reads && deferSettlement) { const goal = replanGoalContext(payload, reads, "$.action.core_goal", precision); @@ -1462,8 +446,7 @@ function actionProjection(payload: JsonObject, deferSettlement = true, precision const todoId = text(object(item).todo_id, 160); return todoId ? [todoId] : []; }); - writeback.selection_command_ref = - "full_decision.interaction_contract.cli_channel.selection_command"; + writeback.selection_command_ref = "full_decision.interaction_contract.cli_channel.selection_command"; } else if (turnBindingRequired) { writeback.turn_binding_required = true; writeback.next_cli_actions = cliChannel.next_cli_actions; @@ -1524,12 +507,11 @@ function actionProjection(payload: JsonObject, deferSettlement = true, precision function compactPeerActivation(contract: JsonObject, detailRef: string): JsonObject { if (contract.mode !== "task_scoped_peer" || Buffer.byteLength(JSON.stringify(contract), "utf8") <= TURN_ENVELOPE_SECTION_TARGETS.context) return contract; - const summary: JsonObject = {}; - for (const field of ["schema_version", "mode", "coordinator_agent_id", "assignment_key", + const summary = pickOwn(contract, [ + "schema_version", "mode", "coordinator_agent_id", "assignment_key", "execution_scope", "task_selection", "execution_state", "activation_required", - "activation_allowed", "required_capability", "retry_policy", "terminal_outcome", "writeback_owner"]) { - if (field in contract) summary[field] = contract[field]; - } + "activation_allowed", "required_capability", "retry_policy", "terminal_outcome", "writeback_owner", + ]); return { ...summary, delivery: "projected", read_required: true, eligible_peer_count: Array.isArray(contract.eligible_peer_lanes) ? contract.eligible_peer_lanes.length : 0, blocked_peer_count: Array.isArray(contract.blocked_peer_lanes) ? contract.blocked_peer_lanes.length : 0, @@ -1585,8 +567,7 @@ function turnActionProjection(payload: JsonObject, precision?: ReplanReadPrecisi // full-decision JSON path into an envelope where that root does not exist. if (!("acceptance_contract" in core) && "acceptance_contract_ref" in core) { const match = typeof core.acceptance_contract_ref === "string" - ? /^\$\.interaction_contract\.agent_channel\.work_context\.sources\[(0|[1-9]\d*)\]\.content\.goal_acceptance_contract$/.exec(core.acceptance_contract_ref) - : null; + ? WORK_CONTEXT_GOAL_ACCEPTANCE_REF_PATTERN.exec(core.acceptance_contract_ref) : null; const index = match ? Number(match[1]) : -1; const source = object(Array.isArray(sources) ? sources[index] : null); const content = object(source.content); @@ -1670,15 +651,9 @@ export function turnEnvelopeActionSignatureDocument(value: unknown): JsonObject ]) { signature[field] = envelope[field] ?? null; } - if (Object.keys(object(envelope.agent_context)).length > 0) { - signature.agent_context = object(envelope.agent_context); - } - if (Object.keys(object(envelope.work_context)).length > 0) { - signature.work_context = object(envelope.work_context); - } - if (Object.keys(object(responsePlanValue)).length > 0) { - signature.response_plan = { ...object(responsePlanValue) }; - } + if (Object.keys(object(envelope.agent_context)).length > 0) signature.agent_context = object(envelope.agent_context); + if (Object.keys(object(envelope.work_context)).length > 0) signature.work_context = object(envelope.work_context); + if (Object.keys(object(responsePlanValue)).length > 0) signature.response_plan = { ...object(responsePlanValue) }; return signature; } @@ -1689,113 +664,10 @@ export function quotaActionSignatureDocument(value: unknown, supplied?: unknown) ); } -function shellQuote(value: string): string { - if (/^[A-Za-z0-9_@%+=:,./-]+$/u.test(value)) return value; - return `'${value.replaceAll("'", `'"'"'`)}'`; -} - -function commandPrefix(runtimeRoot: unknown, registry?: unknown): string { - const runtimeRootText = scalarString(runtimeRoot, "quota payload runtime_root").trim(); - const registryText = scalarString(registry, "quota payload registry").trim(); - return "loopx" + (registryText ? ` --registry ${shellQuote(registryText)}` : "") + - (runtimeRootText ? ` --runtime-root ${shellQuote(runtimeRootText)}` : ""); -} - -function coldPath( - payload: JsonObject, - agentId: string | null, - schedulerExecutionArgs: string, - capturedDecisionPath?: string, -): JsonObject { - const goalId = scalarString(payload.goal_id, "quota payload goal_id", ""); - const agentArg = agentId ? ` --agent-id ${agentId}` : ""; - const prefix = commandPrefix(payload.runtime_root, payload.registry); - return { - full_decision: capturedDecisionPath ? `cat -- ${shellQuote(capturedDecisionPath)}` : schedulerExecutionArgs - ? `${prefix} --format json quota should-run --goal-id ${goalId}${agentArg}${schedulerExecutionArgs}` - : "rerun the typed quota_guard from the current host packet", - ...(capturedDecisionPath ? { - captured_decision: { - path: capturedDecisionPath, - goal_id: payload.goal_id ?? null, - agent_id: agentId, - turn_instance_id: object(payload.heartbeat_receipt).turn_instance_id ?? null, - source_hash_ref: "$.action_signature.source_decision_hash", - instruction: "Read this saved observation for omitted context. Check ok, Goal/Agent/Turn and source hash before use. " + - "It grants no fresh authority: selection, lease/workspace changes, cancellation or quota revalidation require " + - "the current host guard and a new capture directory. Missing or invalid capture requires recovery, not blind guard replay.", - }, - } : {}), - todo_detail: `${prefix} --format json todo list --goal-id ${goalId}`, - status_detail: `${prefix} --format json status --goal-id ${goalId}`, - }; -} - /** Complete decision composition precedes capture. Domain owners have already * decided admission, work and settlement; this boundary does not decide again. * The v0 envelope remains an internal executor adapter during reader migration. */ -export const COMPLETE_TURN_DECISION_VERSION = "loopx_turn_envelope_v1"; -// Sparse producer metadata is a different identity from the earlier -// experimental all-float binding; its saved contracts need their pinned reader. -const COMPLETE_TURN_HASH_CODEC = "context_source_numbers_v2"; - -function requireCompleteDecisionSource(source: JsonObject): void { - assertSupportedQuotaPacket(source); - // Validate executable semantics with their owner, retaining the original - // object (including optional facts) rather than its normalized decode. - const interaction = decodeInteractionContract(source.interaction_contract); - assertInteractionRequiredReads(interaction.agent_channel.required_reads); - replanAuthoringContract(source); - requireVisionAuditReferences(source); - requireCurrentTaskTitleReference(source); - resolveQuotaSummaryLanes(source); - resolveExploreGuidance(source, object(object(object(source.interaction_contract).agent_channel).work_context)); - // This root field selects execution, unlike optional evidence carried intact - // in the source. Reuse both registered owners; do not inherit the historical - // adapter's unknown-action fallback at the new version boundary. - requireStringLiteral(source.effective_action, - [...EFFECTIVE_ACTIONS, ...AGENT_SCOPE_FRONTIER_ACTIONS], "Turn effective_action"); - for (const {parent, field} of acceptanceCarriers(source)) { - if (!Object.hasOwn(parent, field) && Object.hasOwn(parent, `${field}_ref`)) { - inlineAcceptance(source, parent[`${field}_ref`]); - } - } -} - -function completeSourceHash(value: JsonObject, identity = contextSourceIdentity(value, [])): string { - return `sha256:${createHash("sha256").update(identity(value, []), "utf8").digest("hex")}`; -} - -export function requireCompleteTurnDecision(value: unknown, numberTokens?: unknown): JsonObject { - const decision = requireJsonObject(value, "complete Turn decision"); - if (decision.schema_version !== COMPLETE_TURN_DECISION_VERSION) { - throw new EffectRuntimeRequestError("unsupported complete Turn decision version"); - } - const binding = requireJsonObject(decision.contract_binding, "Turn contract binding"); - if (binding.hash_codec !== COMPLETE_TURN_HASH_CODEC) { - throw new EffectRuntimeRequestError("unsupported complete Turn decision hash codec"); - } - const identity = contextSourceIdentity(decision, numberTokens ?? []); - if (typeof binding.scheduler_execution_args !== "string") { - throw new EffectRuntimeRequestError("Turn scheduler execution binding must be a string"); - } - const unsignedBinding = {...binding}; - delete unsignedBinding.content_hash; - const content = {...decision, contract_binding: unsignedBinding}; - if (binding.content_hash !== completeSourceHash(content, identity)) { - throw new EffectRuntimeRequestError("complete Turn decision content integrity mismatch"); - } - const source = {...decision}; - delete source.schema_version; - delete source.contract_binding; - if (binding.source_decision_hash !== completeSourceHash(source, identity)) { - throw new EffectRuntimeRequestError("complete Turn decision source integrity mismatch"); - } - requireCompleteDecisionSource(source); - return decision; -} - function requireCompleteHostHeader(request: JsonObject, decision: JsonObject): JsonObject { // The versioned model wire has one complete source. The outer executor has // already checked its private effect adapter; a standalone reader validates @@ -1818,8 +690,7 @@ function requireCompleteHostHeader(request: JsonObject, decision: JsonObject): J const captureTurnMatches = Object.hasOwn(captured, "turn_key") ? captured.turn_key === header.turn_key : captured.turn_instance_id === (object(decision.heartbeat_receipt).turn_instance_id ?? null); - if (hasCapture && (typeof captured.path !== "string" || !captured.path.trim() || captured.path.includes("\0") || - !captureTurnMatches || + if (hasCapture && (!isNonEmptyFilePath(captured.path) || !captureTurnMatches || captured.goal_id !== decision.goal_id || captured.agent_id !== object(decision.agent_identity).agent_id || captured.source_hash_ref !== "$.source_decision_hash" || !Object.hasOwn(header, "source_decision_hash"))) { throw new EffectRuntimeRequestError("complete Host request capture binding differs"); @@ -2126,9 +997,7 @@ export function buildTurnEnvelope(value: unknown): JsonObject { const request = requireJsonObject(value, "turn envelope request"); const payload = requireJsonObject(request.payload, "turn envelope payload"); if (typeof request.scheduler_execution_args !== "string") { - throw new EffectRuntimeRequestError( - "turn envelope scheduler_execution_args must be a string", - ); + throw new EffectRuntimeRequestError("turn envelope scheduler_execution_args must be a string"); } if (payload.schema_version === COMPLETE_TURN_DECISION_VERSION) { requireCompleteTurnDecision(payload, request.source_number_tokens); @@ -2138,9 +1007,7 @@ export function buildTurnEnvelope(value: unknown): JsonObject { } const schedulerExecutionArgs = request.scheduler_execution_args; const capturedDecisionPath = request.captured_decision_path; - if (capturedDecisionPath !== undefined && ( - typeof capturedDecisionPath !== "string" || !capturedDecisionPath.trim() || capturedDecisionPath.includes("\0") - )) { + if (capturedDecisionPath !== undefined && !isNonEmptyFilePath(capturedDecisionPath)) { throw new EffectRuntimeRequestError("turn envelope captured_decision_path must be a non-empty file path"); } const agentId = scalarString( @@ -2200,7 +1067,7 @@ function bindTurnDecisionCapture(request: JsonObject): JsonObject { const turnId = scalarString(request.turn_instance_id, "capture Turn identity"); const turnKey = scalarString(request.turn_key, "capture Turn key"); const signature = object(envelope.action_signature); - if (!path.trim() || path.includes("\0") || !turnId.trim() || + if (!isNonEmptyFilePath(path) || !turnId.trim() || !ENVELOPED_SHA256_PATTERN.test(turnKey) || payload.ok !== true || payload.goal_id !== envelope.goal_id || object(payload.agent_identity).agent_id !== envelope.agent_id || @@ -2237,8 +1104,7 @@ function bindTurnDecisionCapture(request: JsonObject): JsonObject { const materialReaders = object(boundDetail.replan_action_packet); return {...completeHeader, detail_ref: { full_decision: boundDetail.full_decision, captured_decision: boundDetail.captured_decision, - ...(materialReaders.review ? {replan_action_packet: Object.fromEntries( - Object.entries(materialReaders).filter(([field]) => ["review", "writeback"].includes(field)))} : {}), + ...(materialReaders.review ? {replan_action_packet: pickOwn(materialReaders, ["review", "writeback"])} : {}), }}; } const bound = {...envelope, detail_ref: boundDetail}; @@ -2395,40 +1261,6 @@ function capturedDecisionSelection(request: JsonObject): JsonObject { requireJsonObject(request.context, "captured context"), INITIAL_CONTEXT_DECISION_FIELDS) : []); } -function replanCliView(payload: JsonObject, identity: ReplanValueIdentity = canonicalHash, - reads = replanReadCommands(payload), precision?: ReplanReadPrecision): JsonObject { - if (!reads) return payload; - const obligation = {...object(payload.autonomous_replan_obligation)}; - delete obligation.replan_context; - const interaction = object(payload.interaction_contract), agent = object(interaction.agent_channel); - const cli = object(interaction.cli_channel); - // Defer only authoring/settlement format, not admission or stop facts. - // This default captured path needs no optional native delta transport. - const goal = replanGoalContext(payload, reads, undefined, precision); - const summary = object(payload.agent_todo_summary); - const originalCore = object(object(object(payload.autonomous_replan_obligation).replan_context).core_goal); - // Reuse the same captured acceptance index for an exact summary copy. - // Otherwise this legacy carrier silently restores the full deferred detail. - // A different revision or an existing summary index remains untouched. - const indexedSummary = goal.core.outcome_requirements_index && - !Object.hasOwn(summary, "outcome_requirements_index") && - identity(summary.goal_acceptance_contract ?? null, ["agent_todo_summary", "goal_acceptance_contract"]) - === identity(originalCore.acceptance_contract ?? null, - ["autonomous_replan_obligation", "replan_context", "core_goal", "acceptance_contract"]) - ? {...summary, goal_acceptance_contract: goal.core.acceptance_contract, - outcome_requirements_index: goal.core.outcome_requirements_index} : summary; - // Review owns the captured planning facts. The entry retains admission, - // current selection and stops; the mandatory reader supplies the complete - // Goal and horizon before the Agent chooses its next work. - const {core_goal: _core, planning_horizon: _horizon, ...entry} = payload; - return {...entry, - ...(indexedSummary !== summary ? {agent_todo_summary: indexedSummary} : {}), - interaction_contract: {...interaction, cli_channel: deferredReplanWriteback(cli), agent_channel: {...agent, - work_context: replanWorkContext(payload, object(agent.work_context), reads, identity)}}, - autonomous_replan_obligation: {...obligation, context_read: reads.review}, - replan_action_packet: replanActionPacket(payload, reads)}; -} - /** Only the exact list can carry forward. Current boundary controls stay inline. */ function readyWriteScope(context: JsonObject): ReusableExactBody | undefined { const interaction = jsonObject(context.interaction_contract); @@ -2498,64 +1330,14 @@ function progressivePreparationScopes(payload: JsonObject): PreparationScopeDeta return scopes; } -function nativeReplanPresentation(request: JsonObject): JsonObject | undefined { - const projection = object(request.native_projection); - const captured = object(projection.captured_decision); - const stateless = captured.path === undefined && projection.replan_reader_argv !== undefined; - const path = stateless ? projection.source_path : captured.path; - if (typeof path !== "string") return undefined; - const source = requireJsonObject(request.context, "captured replan source"); - if (stateless) { - if (projection.sha256 === undefined || request.surface !== "complete_turn" && - (request.surface !== "quota_packet" || Object.hasOwn(source, "schema_version") || - Object.hasOwn(source, "contract_binding"))) return undefined; - // Preserve a bound reversal in the opening, before candidate choice. - if (scopedReplanYardstickReversal(source)) return undefined; - } - const packet = object(source.replan_action_packet); - const review = object(object(source.autonomous_replan_obligation).replan_context); - // Existing staged files are presentation inputs. Do not derive a new source - // hash from them or replace their already pinned reader commands. - if ((!stateless && typeof source.replan_read_path !== "string") || packet.schema_version !== "replan_action_packet_v0" - || typeof packet.obligation_id !== "string" - || packet.obligation_id !== review.obligation_id || packet.review !== undefined - || packet.writeback !== undefined) return undefined; - const precision = replanReadPrecision(request, request.source_number_tokens); - const identity = precision?.identity ?? contextSourceIdentity(request); - const view = replanCliView(source, (value, field) => identity(value, ["context", ...field]), - replanReadCommands(source, path, stateless ? projection.replan_reader_argv : undefined, - undefined, stateless ? projection.sha256 : captured.sha256), precision); - return view === source ? undefined : {staged_context: view, deferred: [], instructions: []}; -} - function contextPresentationPlan(request: JsonObject): JsonObject { const context = requireJsonObject(request.context, "current projection"); return progressiveContextPlan({payload: context, surface: request.surface}, progressivePreparationScopes(context)); } -export function decodeTurnSource(request: JsonObject, inlineField: "payload" | "source"): JsonObject { - const transport = requireJsonObject(request.source_transport, "Turn composition source transport"); - const {encoding, data} = transport; - const maxSourceBytes = 1024 * 1024; - if (Object.hasOwn(request, inlineField) || encoding !== "deflate-base64-json-v0" || - typeof data !== "string" || data.length > maxSourceBytes || - data.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(data)) { - throw new EffectRuntimeRequestError("invalid Turn composition source transport"); - } - let source: unknown; - try { - const compressed = Buffer.from(data, "base64"); - // Inflate may stop at the first stream and silently leave input unread. - // The synchronous info result reports consumed bytes on supported Node versions. - const {buffer, engine} = inflateSync(compressed, - {info: true, maxOutputLength: maxSourceBytes}) as unknown as {buffer: Buffer; engine: {bytesWritten: number}}; - if (engine.bytesWritten !== compressed.length) throw new Error("trailing compressed source data"); - source = JSON.parse(new TextDecoder("utf-8", {fatal: true, ignoreBOM: true}).decode(buffer)); - } catch { - throw new EffectRuntimeRequestError("Turn composition source must be valid compressed JSON within 1 MiB"); - } - return requireJsonObject(source, "complete Turn decision source"); -} +const resolveViewWriteback = ( + payload: JsonObject, precision: ReplanReadPrecision | undefined, verifiedSourceHash: string, +): JsonObject => object(actionProjection(payload, false, precision, verifiedSourceHash).writeback); export function evaluateTurnEnvelope(value: unknown): JsonObject { const request = requireJsonObject(value, "turn envelope request"); @@ -2607,7 +1389,7 @@ export function evaluateTurnEnvelope(value: unknown): JsonObject { recorded_projection: {goal_id: decision.goal_id ?? null, ...turnActionProjection(decision)}, } : {})}; } - if (operation === "replan_view") return replanView(request); + if (operation === "replan_view") return replanView(request, resolveViewWriteback); if (operation === "context_select") return capturedDecisionSelection(request); if (operation === "replan_cli_view") { const payload = requireJsonObject(request.payload, "replan CLI payload"); @@ -2772,12 +1554,8 @@ export function evaluateTurnEnvelope(value: unknown): JsonObject { if (operation === "replan_settlement_identity") return {identity: turnEnvelopeReplanSettlementIdentity( requireJsonObject(request.envelope, "turn_envelope"), request.turn_instance_id, )}; - if (operation === "envelope_signature") { - return turnEnvelopeActionSignatureDocument(request.envelope); - } - if (operation === "quota_signature") { - return quotaActionSignatureDocument(request.payload, request.source_number_tokens); - } + if (operation === "envelope_signature") return turnEnvelopeActionSignatureDocument(request.envelope); + if (operation === "quota_signature") return quotaActionSignatureDocument(request.payload, request.source_number_tokens); throw new EffectRuntimeRequestError("turn envelope operation is unsupported"); } diff --git a/loopx/control_plane/quota/turn_envelope_codec.ts b/loopx/control_plane/quota/turn_envelope_codec.ts new file mode 100644 index 0000000000..4a4af58d7c --- /dev/null +++ b/loopx/control_plane/quota/turn_envelope_codec.ts @@ -0,0 +1,197 @@ +import { createHash } from "node:crypto"; +import { inflateSync } from "node:zlib"; + +import { authorityUnicodeCompare } from "../coordination/authority_store_codec.ts"; +import { contextSourceIdentity } from "./diagnostic_projection.ts"; +import { EffectRuntimeRequestError } from "../effect_runtime_errors.ts"; +import { pythonString, requireJsonObject, type JsonObject } from "../runtime_decode.ts"; + +export const COMPLETE_TURN_DECISION_VERSION = "loopx_turn_envelope_v1"; +// Sparse producer metadata is a different identity from the earlier +// experimental all-float binding; its saved contracts need their pinned reader. +export const COMPLETE_TURN_HASH_CODEC = "context_source_numbers_v2"; + +const EXECUTABLE_CLI_ARGS_MAX_ITEMS = 64; +const EXECUTABLE_CLI_ARGS_MAX_ITEM_CHARS = 512; +const EXECUTABLE_CLI_ARGS_MAX_TOTAL_CHARS = 2_048; + +export function object(value: unknown): JsonObject { + return typeof value === "object" && value !== null && !Array.isArray(value) + ? { ...(value as JsonObject) } + : {}; +} + +export function pickNonNull(source: JsonObject, fields: readonly string[]): JsonObject { + const picked: JsonObject = {}; + for (const field of fields) { + if (source[field] !== null && source[field] !== undefined) picked[field] = source[field]; + } + return picked; +} + +export function pickOwn(source: JsonObject, fields: readonly string[]): JsonObject { + const picked: JsonObject = {}; + for (const field of fields) { + if (Object.hasOwn(source, field)) picked[field] = source[field]; + } + return picked; +} + +export function isNonEmptyFilePath(value: unknown): value is string { + return typeof value === "string" && value.trim().length > 0 && !value.includes("\0"); +} + +export function scalarString(value: unknown, label: string, fallback = ""): string { + if (value === null || value === undefined || value === "") return fallback; + if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") { + throw new EffectRuntimeRequestError(`${label} must be scalar-compatible`); + } + return pythonString(value); +} + +export function integer(value: unknown, label: string): number { + if (value === null || value === undefined || value === "") return 0; + if (typeof value === "boolean") return Number(value); + if (typeof value === "number" && Number.isFinite(value)) return Math.trunc(value); + if (typeof value === "string" && /^[+-]?\d+$/u.test(value.trim())) return Number.parseInt(value, 10); + throw new EffectRuntimeRequestError(`${label} must be integer-compatible`); +} + +export function text(value: unknown, limit: number): string | null { + if (value === null || value === undefined) return null; + const compact = scalarString(value, "text value").trim().split(/\s+/u).join(" "); + if (!compact) return null; + return compact.length <= limit ? compact : `${compact.slice(0, Math.max(0, limit - 3)).trimEnd()}...`; +} + +export function textList(value: unknown, limit: number, itemLimit = 240): string[] { + if (!Array.isArray(value)) return []; + const result: string[] = []; + for (const item of value) { + const rendered = text(item, itemLimit); + if (!rendered || result.includes(rendered)) continue; + result.push(rendered); + if (result.length >= limit) break; + } + return result; +} + +export function compactFields( + value: unknown, fields: readonly string[], limits: Readonly> = {}, +): JsonObject { + const source = object(value); + const compact: JsonObject = {}; + for (const field of fields) { + const raw = source[field]; + if (raw === null || raw === undefined) continue; + if (limits[field] !== undefined) { + const rendered = text(raw, limits[field]); + if (rendered) compact[field] = rendered; + } else if (Array.isArray(raw)) { + const values = textList(raw, 6, 140); + if (values.length > 0) compact[field] = values; + } else compact[field] = raw; + } + return compact; +} + +export function executableCliArgs(value: unknown): string[] { + if (!Array.isArray(value) || value.length === 0 || value.length > EXECUTABLE_CLI_ARGS_MAX_ITEMS) return []; + const result: string[] = []; + let totalChars = 0; + for (const item of value) { + if (typeof item !== "string" || !item || item.length > EXECUTABLE_CLI_ARGS_MAX_ITEM_CHARS) return []; + totalChars += item.length + 1; + if (totalChars > EXECUTABLE_CLI_ARGS_MAX_TOTAL_CHARS) return []; + result.push(item); + } + return result; +} + +export function canonicalValue(value: unknown): unknown { + if (Array.isArray(value)) return value.map(canonicalValue); + if (typeof value !== "object" || value === null) return value; + const source = value as JsonObject; + return Object.fromEntries( + Object.keys(source).sort(authorityUnicodeCompare).map((key) => [key, canonicalValue(source[key])]), + ); +} + +export function canonicalHash(value: unknown): string { + return `sha256:${createHash("sha256").update(JSON.stringify(canonicalValue(value)), "utf8").digest("hex")}`; +} + +export function completeSourceHash(value: JsonObject, identity = contextSourceIdentity(value, [])): string { + return `sha256:${createHash("sha256").update(identity(value, []), "utf8").digest("hex")}`; +} + +/** Complete references reuse the checked content binding. Historical captures + * retain their old JSON hash; never rewrite a stored action or Turn key. */ +export function decisionSourceHash(payload: JsonObject): string { + if (payload.schema_version !== COMPLETE_TURN_DECISION_VERSION) return canonicalHash(payload); + const digest = object(payload.contract_binding).content_hash; + if (typeof digest !== "string") throw new EffectRuntimeRequestError("complete Turn decision content binding is missing"); + return digest; +} + +export function shellQuote(value: string): string { + return /^[A-Za-z0-9_@%+=:,./-]+$/u.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`; +} + +export function commandPrefix(runtimeRoot: unknown, registry?: unknown): string { + const runtimeRootText = scalarString(runtimeRoot, "quota payload runtime_root").trim(); + const registryText = scalarString(registry, "quota payload registry").trim(); + return "loopx" + (registryText ? ` --registry ${shellQuote(registryText)}` : "") + + (runtimeRootText ? ` --runtime-root ${shellQuote(runtimeRootText)}` : ""); +} + +export function coldPath( + payload: JsonObject, agentId: string | null, schedulerExecutionArgs: string, capturedDecisionPath?: string, +): JsonObject { + const goalId = scalarString(payload.goal_id, "quota payload goal_id", ""); + const agentArg = agentId ? ` --agent-id ${agentId}` : ""; + const prefix = commandPrefix(payload.runtime_root, payload.registry); + return { + full_decision: capturedDecisionPath ? `cat -- ${shellQuote(capturedDecisionPath)}` : schedulerExecutionArgs + ? `${prefix} --format json quota should-run --goal-id ${goalId}${agentArg}${schedulerExecutionArgs}` + : "rerun the typed quota_guard from the current host packet", + ...(capturedDecisionPath ? { + captured_decision: { + path: capturedDecisionPath, + goal_id: payload.goal_id ?? null, + agent_id: agentId, + turn_instance_id: object(payload.heartbeat_receipt).turn_instance_id ?? null, + source_hash_ref: "$.action_signature.source_decision_hash", + instruction: "Read this saved observation for omitted context. Check ok, Goal/Agent/Turn and source hash before use. " + + "It grants no fresh authority: selection, lease/workspace changes, cancellation or quota revalidation require " + + "the current host guard and a new capture directory. Missing or invalid capture requires recovery, not blind guard replay.", + }, + } : {}), + todo_detail: `${prefix} --format json todo list --goal-id ${goalId}`, + status_detail: `${prefix} --format json status --goal-id ${goalId}`, + }; +} + +export function decodeTurnSource(request: JsonObject, inlineField: "payload" | "source"): JsonObject { + const transport = requireJsonObject(request.source_transport, "Turn composition source transport"); + const { encoding, data } = transport; + const maxSourceBytes = 1024 * 1024; + if (Object.hasOwn(request, inlineField) || encoding !== "deflate-base64-json-v0" || + typeof data !== "string" || data.length > maxSourceBytes || + data.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(data)) { + throw new EffectRuntimeRequestError("invalid Turn composition source transport"); + } + let source: unknown; + try { + const compressed = Buffer.from(data, "base64"); + // Inflate may stop at the first stream and silently leave input unread. + // The synchronous info result reports consumed bytes on supported Node versions. + const { buffer, engine } = inflateSync(compressed, + { info: true, maxOutputLength: maxSourceBytes }) as unknown as { buffer: Buffer; engine: { bytesWritten: number } }; + if (engine.bytesWritten !== compressed.length) throw new Error("trailing compressed source data"); + source = JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(buffer)); + } catch { + throw new EffectRuntimeRequestError("Turn composition source must be valid compressed JSON within 1 MiB"); + } + return requireJsonObject(source, "complete Turn decision source"); +} diff --git a/loopx/control_plane/quota/turn_envelope_references.ts b/loopx/control_plane/quota/turn_envelope_references.ts new file mode 100644 index 0000000000..b2e4c9bfcc --- /dev/null +++ b/loopx/control_plane/quota/turn_envelope_references.ts @@ -0,0 +1,1002 @@ +import { isDeepStrictEqual } from "node:util"; + +import { AGENT_SCOPE_FRONTIER_ACTIONS } from "../agents/agent_scope_frontier.generated.ts"; +import { omitUnboundExploreResultWriteback, referenceExploreResultWriteback } from "../capabilities/explore_context_delivery.ts"; +import { BARE_SHA256_PATTERN } from "../content_digest.ts"; +import { assertSupportedQuotaPacket, SETTLEMENT_PLAN_SCHEMA_VERSION } from "../effect_program.ts"; +import { EffectRuntimeRequestError } from "../effect_runtime_errors.ts"; +import { jsonObject, requireJsonObject, requireStringLiteral, type JsonObject } from "../runtime_decode.ts"; +import { assertInteractionRequiredReads, decodeInteractionContract, selectedWorkTodoId } from "../work_items/interaction_contract.ts"; +import { REPLAN_SETTLEMENT_CONTRACT_SCHEMA } from "../work_items/replan_settlement.ts"; +import { + contextProjectionChanges, contextProjectionIdentity, contextProjectionRetainFields, + contextSourceIdentity, resolveQuotaSummaryLanes, type ProjectionSourceValues, +} from "./diagnostic_projection.ts"; +import { EFFECTIVE_ACTIONS, EffectiveAction } from "./effective_action.generated.ts"; +import { scopedReplanYardstickReversal } from "./progressive_context.ts"; +import { + COMPLETE_TURN_DECISION_VERSION, COMPLETE_TURN_HASH_CODEC, canonicalHash, canonicalValue, + compactFields, completeSourceHash, decisionSourceHash, integer, isNonEmptyFilePath, + object, pickNonNull, pickOwn, scalarString, shellQuote, text, textList, +} from "./turn_envelope_codec.ts"; + +export const WORK_CONTEXT_GOAL_ACCEPTANCE_REF_PATTERN = + /^\$\.interaction_contract\.agent_channel\.work_context\.sources\[(0|[1-9]\d*)\]\.content\.goal_acceptance_contract$/; + +export type ReplanValueIdentity = (value: unknown, path: (string | number)[]) => string; +export type ReplanReadPrecision = { + identity: ReplanValueIdentity; + retain: ReturnType; + equalProjection: (left: JsonObject, right: JsonObject) => boolean; + values: ProjectionSourceValues; +}; + +export type WritebackResolver = ( + payload: JsonObject, precision: ReplanReadPrecision | undefined, verifiedSourceHash: string, +) => JsonObject; + +export function replanReadPrecision(source: JsonObject, supplied: unknown): ReplanReadPrecision | undefined { + if (supplied === undefined) return undefined; + const identity = contextSourceIdentity(source, supplied); + const values: ProjectionSourceValues = new WeakMap(); + const projectedIdentity = (view: JsonObject) => contextProjectionIdentity(source, view, supplied, values); + return {identity, values, retain: contextProjectionRetainFields(source, values), + equalProjection: (left, right) => projectedIdentity(left) === projectedIdentity(right)}; +} + +export function replanAuthoringContract(payload: JsonObject, precision?: ReplanReadPrecision): JsonObject { + const contract = jsonObject(jsonObject(payload.replan_action_packet)?.writeback_contract) ?? {}; + if (!Object.hasOwn(contract, "vision_authoring_ref")) return contract; + const reference = contract.vision_authoring_ref; + const match = typeof reference === "string" + ? /^\$\.interaction_contract\.cli_channel\.settlement_plan\.ordered_steps\[(0|[1-9]\d*)\]\.vision_authoring$/.exec(reference) : null; + const steps = object(object(object(payload.interaction_contract).cli_channel).settlement_plan).ordered_steps; + const step = object(match && Array.isArray(steps) ? steps[Number(match[1])] : null); + if (Object.hasOwn(contract, "vision_authoring") || step.kind !== "durable_writeback" || + Object.hasOwn(step, "vision_authoring_ref") || !Object.keys(object(step.vision_authoring)).length) { + throw new EffectRuntimeRequestError("Replan authoring reference must resolve to one complete inline durable-writeback owner"); + } + const {vision_authoring_ref: _reference, ...fields} = contract; + const resolved = {...fields, vision_authoring: step.vision_authoring}; + return precision?.retain(resolved, contract) ?? resolved; +} + +export function referenceReplanAuthoring(payload: JsonObject, + identity = contextSourceIdentity(payload)): JsonObject { + const packet = object(payload.replan_action_packet); + const contract = object(packet.writeback_contract); + if (Object.hasOwn(contract, "vision_authoring_ref")) { + replanAuthoringContract(payload); + return payload; + } + const authoring = object(contract.vision_authoring); + const steps = object(object(object(payload.interaction_contract).cli_channel).settlement_plan).ordered_steps; + if (!Object.keys(authoring).length || !Array.isArray(steps)) return payload; + const encoded = JSON.stringify(canonicalValue(authoring)); + const source = identity(authoring, ["replan_action_packet", "writeback_contract", "vision_authoring"]); + const index = steps.findIndex((value, index) => { + const step = object(value); + return step.kind === "durable_writeback" && !Object.hasOwn(step, "vision_authoring_ref") && + jsonObject(step.vision_authoring) !== null && + identity(step.vision_authoring, ["interaction_contract", "cli_channel", "settlement_plan", + "ordered_steps", index, "vision_authoring"]) === source; + }); + if (index < 0) return payload; + const reference = `$.interaction_contract.cli_channel.settlement_plan.ordered_steps[${index}].vision_authoring`; + if (Buffer.byteLength(encoded, "utf8") <= Buffer.byteLength(reference, "utf8") + 8) return payload; + delete contract.vision_authoring; + return {...payload, replan_action_packet: {...packet, writeback_contract: { + ...contract, vision_authoring_ref: reference}}}; +} + +export function resolveExploreGuidance(payload: JsonObject, context: JsonObject): JsonObject { + if (!Array.isArray(context.sources)) return context; + const steps = object(object(object(payload.interaction_contract).cli_channel).settlement_plan).ordered_steps; + return {...context, sources: context.sources.map(value => { + const source = object(value), content = object(source.content), graph = object(content.graph); + if (source.kind !== "explore_turn_context" || !Object.hasOwn(graph, "result_writeback_guidance_ref")) return value; + const reference = graph.result_writeback_guidance_ref; + const match = typeof reference === "string" + ? /^\$\.interaction_contract\.cli_channel\.settlement_plan\.ordered_steps\[(0|[1-9]\d*)\]\.optional_attachments\[(0|[1-9]\d*)\]\.guidance$/.exec(reference) : null; + const step = object(match && Array.isArray(steps) ? steps[Number(match[1])] : null); + const attachment = object(match && Array.isArray(step.optional_attachments) + ? step.optional_attachments[Number(match[2])] : null); + if (Object.hasOwn(graph, "result_writeback_guidance") || step.kind !== "durable_writeback" || + attachment.capability_id !== "explore" || Object.hasOwn(attachment, "guidance_ref") || + typeof attachment.guidance !== "string" || !attachment.guidance) { + throw new EffectRuntimeRequestError("Explore guidance reference must resolve to one inline durable-writeback Explore attachment"); + } + delete graph.result_writeback_guidance_ref; + return {...source, content: {...content, graph: {...graph, result_writeback_guidance: attachment.guidance}}}; + })}; +} + +/** Existing acceptance carriers only: this is not a general JSON-path codec. + * The loaded work context is preferred, then the complete planning/replan facts. + */ +function acceptanceCarriers(payload: JsonObject) { + // Keep read-only carrier parents attached to their source. The general + // object() helper intentionally returns copies for projection callers. + const carrierObject = (value: unknown): JsonObject => + typeof value === "object" && value !== null && !Array.isArray(value) + ? value as JsonObject : {}; + const carriers: {parent: JsonObject; field: string; path: string; parentPath: (string | number)[]}[] = []; + const sources = carrierObject(carrierObject(carrierObject(payload.interaction_contract).agent_channel).work_context).sources; + if (Array.isArray(sources)) { + const index = sources.findIndex(value => { + const source = carrierObject(value), content = carrierObject(source.content); + return source.source === "goal_acceptance" && + (content.status === undefined || content.status === "loaded") && + Object.keys(carrierObject(content.goal_acceptance_contract)).length > 0; + }); + if (index >= 0) carriers.push({parent: carrierObject(carrierObject(sources[index]).content), + field: "goal_acceptance_contract", + parentPath: ["interaction_contract", "agent_channel", "work_context", "sources", index, "content"], + path: `$.interaction_contract.agent_channel.work_context.sources[${index}].content.goal_acceptance_contract`}); + } + carriers.push( + {parent: carrierObject(carrierObject(payload.planning_horizon).core_goal), field: "acceptance_contract", + parentPath: ["planning_horizon", "core_goal"], + path: "$.planning_horizon.core_goal.acceptance_contract"}, + {parent: carrierObject(carrierObject(carrierObject(payload.autonomous_replan_obligation).replan_context).core_goal), + field: "acceptance_contract", path: "$.autonomous_replan_obligation.replan_context.core_goal.acceptance_contract", + parentPath: ["autonomous_replan_obligation", "replan_context", "core_goal"]}, + {parent: carrierObject(payload.agent_todo_summary), field: "goal_acceptance_contract", + parentPath: ["agent_todo_summary"], + path: "$.agent_todo_summary.goal_acceptance_contract"}, + ); + return carriers; +} + +function inlineAcceptance(payload: JsonObject, reference: unknown): JsonObject { + // Older captures may name any loaded work-context carrier, not only the + // preferred first source chosen for new sharing. + const match = typeof reference === "string" ? WORK_CONTEXT_GOAL_ACCEPTANCE_REF_PATTERN.exec(reference) : null; + if (match) { + const sources = object(object(object(payload.interaction_contract).agent_channel).work_context).sources; + const source = object(Array.isArray(sources) ? sources[Number(match[1])] : null); + const content = object(source.content); + if (source.source === "goal_acceptance" && + (content.status == null || content.status === "loaded") && + !Object.hasOwn(content, "goal_acceptance_contract_ref") && + Object.keys(object(content.goal_acceptance_contract)).length) { + return object(content.goal_acceptance_contract); + } + } + const carrier = acceptanceCarriers(payload).find(item => item.path === reference); + const value = object(carrier?.parent[carrier.field]); + if (!carrier || Object.hasOwn(carrier.parent, `${carrier.field}_ref`) || !Object.keys(value).length) { + throw new EffectRuntimeRequestError("Goal acceptance reference must resolve to complete inline work context or planning facts"); + } + return value; +} + +export function referenceGoalAcceptance(payload: JsonObject, + identity = contextSourceIdentity(payload)): JsonObject { + let result = payload; + // Copy only a changed registered carrier's spine. Retained source objects + // keep their identity for the display-edit transport and original numbers. + const writableParent = (path: (string | number)[]): JsonObject => { + result = {...result}; + let target: Record = result; + for (const key of path) { + const value = target[key]; + target[key] = Array.isArray(value) ? [...value] : {...requireJsonObject(value, "acceptance carrier")}; + target = target[key] as Record; + } + return target; + }; + const owners = new Map(); + const relocated = new Map(); + const carriers = acceptanceCarriers(payload); + for (const {parent, field, path, parentPath} of carriers) { + const value = object(parent[field]); + if (!Object.keys(value).length || Object.hasOwn(parent, `${field}_ref`)) continue; + // Complete canonical JSON distinguishes booleans/numbers, revisions, + // provenance and negative evidence. Never deduplicate a prose summary. + const encoded = identity(value, [...parentPath, field]); + const owner = owners.get(encoded); + if (!owner) owners.set(encoded, path); + else if (Buffer.byteLength(JSON.stringify(canonicalValue(value)), "utf8") > Buffer.byteLength(owner, "utf8") + 8) { + const target = writableParent(parentPath); + delete target[field]; + target[`${field}_ref`] = owner; + relocated.set(path, owner); + } + } + // A historical source can already reference a carrier that was just shared. + // Rebind that exact reference to the retained inline owner, never a chain. + for (const {parent, field, parentPath} of carriers) { + const reference = parent[`${field}_ref`]; + if (typeof reference === "string" && relocated.has(reference)) { + writableParent(parentPath)[`${field}_ref`] = relocated.get(reference); + } + } + return result; +} + +/** One registry for ordinary captured reads and staged replan. Only registered + * acceptance carriers participate; unrelated objects named `outcomes` are not + * sources. Equal content shares a reference, while differing revisions of the + * same outcome retain their complete bodies, including unknown fields. + */ +function indexCapturedAcceptanceOutcomes(payload: JsonObject, indexOutcome: (value: unknown) => string): void { + const carriers = acceptanceCarriers(payload); + // Sharing prefers the first source, but a diagnostic index must cover every + // loaded registered carrier, including different same-id revisions. + const sources = object(object(object(payload.interaction_contract).agent_channel).work_context).sources; + if (Array.isArray(sources)) for (const [index, value] of sources.entries()) { + const source = object(value), content = object(source.content); + if (source.source === "goal_acceptance" && (content.status == null || content.status === "loaded")) { + carriers.push({parent: content, field: "goal_acceptance_contract", path: "", + parentPath: ["interaction_contract", "agent_channel", "work_context", "sources", index, "content"]}); + } + } + for (const {parent, field} of carriers) { + const acceptance = Object.hasOwn(parent, `${field}_ref`) + ? inlineAcceptance(payload, parent[`${field}_ref`]) : object(parent[field]); + if (!Object.keys(acceptance).length) continue; + const requirements = object(acceptance.outcome_requirements); + if (!Object.hasOwn(acceptance, "outcome_requirements")) continue; + if (!Array.isArray(requirements.outcomes)) throw new EffectRuntimeRequestError("captured outcome source is unsupported"); + for (const value of requirements.outcomes) indexOutcome(value); + } +} + +/** Expose existing facts, not another acceptance verdict. Missing values stay + * absent; an Agent's `met` review is not a current independent check. + */ +function capturedOutcomeIndex(outcomes: ReadonlyMap, precision?: ReplanReadPrecision): JsonObject[] { + return [...outcomes].map(([ref, outcome]) => { + const states = new Map(); + if (Array.isArray(outcome.requirements)) for (const value of outcome.requirements) { + const requirement = requireJsonObject(value, "captured outcome requirement"); + const review = jsonObject(requirement.agent_review); + const state: JsonObject = { + ...pickOwn(requirement, ["status", "planning_satisfied"]), + ...(Object.hasOwn(requirement, "agent_review") ? {agent_review: review === null + ? requirement.agent_review : pickOwn(review, ["conclusion", "basis_current", "independently_verified"])} : {}), + }; + const key = JSON.stringify(canonicalValue(state)); + const group = states.get(key); + if (group) (group.requirement_ids as unknown[]).push(requirement.id); + else states.set(key, {requirement_ids: [requirement.id], ...state}); + } + const row: JsonObject = {outcome_ref: ref, id: outcome.id, objective: outcome.objective, revision: outcome.revision, + ...pickOwn(outcome, ["owner_agent_id", "work", ...(Object.hasOwn(outcome, "work") ? [] : ["todo_ids"])]), + requirement_count: Array.isArray(outcome.requirements) ? outcome.requirements.length : null, + requirement_states: Array.isArray(outcome.requirements) ? [...states.values()] : null}; + return precision?.retain(row, outcome, ["id", "objective", "revision", "owner_agent_id"]) ?? row; + }); +} + +/** Reuse the existing settlement authoring owner, never a summary or a chain. + * Same-capture references have one typed settlement owner. Historical readers + * expand before moving work context, so a full-packet path never dangles in a + * staged envelope. Explore's independent read and domain guidance stay intact. */ +export function referenceExploreGuidance(payload: JsonObject): JsonObject { + const interaction = object(payload.interaction_contract), agent = object(interaction.agent_channel); + const context = object(agent.work_context); + resolveExploreGuidance(payload, context); // Validate existing references, including idempotent reads. + if (!Array.isArray(context.sources)) return payload; + const steps = object(object(interaction.cli_channel).settlement_plan).ordered_steps; + if (!Array.isArray(steps)) return payload; + const owners = new Map(); + steps.forEach((value, stepIndex) => { + const step = object(value); + if (step.kind !== "durable_writeback" || !Array.isArray(step.optional_attachments)) return; + step.optional_attachments.forEach((value, attachmentIndex) => { + const attachment = object(value), guidance = attachment.guidance; + if (attachment.capability_id !== "explore" || Object.hasOwn(attachment, "guidance_ref") || + typeof guidance !== "string" || !guidance || owners.has(guidance)) return; + owners.set(guidance, `$.interaction_contract.cli_channel.settlement_plan.ordered_steps[${stepIndex}].optional_attachments[${attachmentIndex}].guidance`); + }); + }); + const sources = context.sources.map(value => { + const source = object(value), content = object(source.content), graph = object(content.graph); + const guidance = graph.result_writeback_guidance; + const reference = typeof guidance === "string" ? owners.get(guidance) : undefined; + if (source.kind !== "explore_turn_context" || typeof guidance !== "string" || !reference || + Buffer.byteLength(JSON.stringify(guidance), "utf8") <= Buffer.byteLength(reference, "utf8") + 8) return value; + delete graph.result_writeback_guidance; + return {...source, content: {...content, graph: {...graph, result_writeback_guidance_ref: reference}}}; + }); + return {...payload, interaction_contract: {...interaction, agent_channel: {...agent, + work_context: {...context, sources}}}}; +} + +/** Keep the complete vision audit once. These existing projection references + * share identical facts only; a channel-specific obligation is never a summary + * of the root. The old display adapter delegates here before adding metadata. */ +function visionAuditReference(audit: JsonObject): JsonObject { + const reference: JsonObject = { + projection_ref: "$.vision_continuation_audit", + ...pickOwn(audit, ["schema_version", "required", "decision"]), + }; + if (typeof audit.vision_gap_judge === "object" && audit.vision_gap_judge !== null && + !Array.isArray(audit.vision_gap_judge)) { + reference.vision_gap_judge = { + projection_ref: "$.vision_continuation_audit.vision_gap_judge", + ...pickOwn(object(audit.vision_gap_judge), ["done", "decision"]), + }; + } + return reference; +} + +function mapNestedVisionAudits(payload: JsonObject, + visit: (audit: JsonObject, path: (string | number)[]) => JsonObject): JsonObject { + const map = (value: unknown, path: (string | number)[]) => { + const parent = object(value), audit = parent.vision_continuation_audit; + if (typeof audit !== "object" || audit === null || Array.isArray(audit)) return value; + return {...parent, vision_continuation_audit: visit(audit as JsonObject, [...path, "vision_continuation_audit"])}; + }; + const rawInteraction = payload.interaction_contract, interaction = object(rawInteraction); + const hasInteraction = typeof rawInteraction === "object" && rawInteraction !== null && !Array.isArray(rawInteraction); + return {...payload, + ...(Object.hasOwn(payload, "goal_frontier_projection") ? { + goal_frontier_projection: map(payload.goal_frontier_projection, ["goal_frontier_projection"])} : {}), + ...(hasInteraction ? {interaction_contract: {...interaction, + ...Object.fromEntries(["agent_channel", "cli_channel"].filter(key => Object.hasOwn(interaction, key)) + .map(key => [key, map(interaction[key], ["interaction_contract", key])]))}} : {})}; +} + +export function requireVisionAuditReferences(payload: JsonObject): void { + const owner = object(payload.vision_continuation_audit); + const chained = Object.hasOwn(owner, "projection_ref") || Object.hasOwn(object(owner.vision_gap_judge), "projection_ref"); + if (chained) throw new EffectRuntimeRequestError("Vision audit reference requires a complete inline root owner"); + mapNestedVisionAudits(payload, audit => { + if (Object.hasOwn(audit, "projection_ref") || Object.hasOwn(object(audit.vision_gap_judge), "projection_ref")) { + if (!Object.keys(owner).length || + JSON.stringify(canonicalValue(audit)) !== JSON.stringify(canonicalValue(visionAuditReference(owner)))) { + throw new EffectRuntimeRequestError("Vision audit reference must match its complete inline root owner without conflicting facts"); + } + } + return audit; + }); +} + +export function referenceVisionContinuation(payload: JsonObject, + identity = contextSourceIdentity(payload)): JsonObject { + requireVisionAuditReferences(payload); + const owner = object(payload.vision_continuation_audit); + if (!Object.keys(owner).length) return payload; + const encoded = JSON.stringify(canonicalValue(owner)), reference = visionAuditReference(owner); + // A short audit is cheaper inline. Do not create a reference merely to count sharing. + if (Buffer.byteLength(encoded, "utf8") <= Buffer.byteLength(JSON.stringify(reference), "utf8")) return payload; + const source = identity(owner, ["vision_continuation_audit"]); + return mapNestedVisionAudits(payload, (audit, path) => + identity(audit, path) === source ? structuredClone(reference) : audit); +} + +/** The verified current Task is the only owner of a shared lane title. Keep + * the original declaration inline and require exact identity, never a label or + * prefix comparison. The legacy display and complete writer use this owner. */ +function currentTaskTitleOwner(payload: JsonObject): {index: number; todo: JsonObject} | null { + const lane = object(payload.agent_lane_next_action), selected = object(payload.selected_todo); + const context = object(object(object(payload.interaction_contract).agent_channel).work_context); + if (context.complete !== true || context.selected_todo_text_verified !== true || + typeof lane.todo_id !== "string" || !lane.todo_id || selected.todo_id !== lane.todo_id || + !Array.isArray(context.sources)) return null; + const matches = context.sources.map((value, index) => ({source: object(value), index})) + .filter(({source}) => source.source === "selected_todo"); + if (matches.length !== 1) return null; + const {source, index} = matches[0], content = object(source.content), todo = object(content.todo); + if (content.ok !== true || content.matched !== true || content.ambiguous === true || + content.read_complete === false || typeof todo.text !== "string" || + todo.archive_state === "archive" || todo.status === "done" || todo.todo_id !== lane.todo_id) return null; + return {index, todo}; +} + +export function requireCurrentTaskTitleReference(payload: JsonObject): void { + const lane = object(payload.agent_lane_next_action); + if (!Object.hasOwn(lane, "title_ref")) return; + const reference = lane.title_ref; + const match = typeof reference === "string" + ? /^\$\.interaction_contract\.agent_channel\.work_context\.sources\[(0|[1-9]\d*)\]\.content\.todo\.(text|title)$/.exec(reference) : null; + const owner = currentTaskTitleOwner(payload); + if (Object.hasOwn(lane, "title") || !match || !owner || owner.index !== Number(match[1]) || + typeof owner.todo[match[2]] !== "string" || !owner.todo[match[2]] || + Object.hasOwn(owner.todo, `${match[2]}_ref`)) { + throw new EffectRuntimeRequestError("Current Task title reference must resolve to the complete verified selected Task"); + } +} + +export function referenceCurrentTaskTitle(payload: JsonObject): JsonObject { + const lane = object(payload.agent_lane_next_action), title = lane.title; + // Preserve historical caller-owned references; complete readers validate them + // separately. Display-only omission of a title already in a label stays local. + if (typeof title !== "string" || Object.hasOwn(lane, "title_ref")) return payload; + const owner = currentTaskTitleOwner(payload); + if (!owner) return payload; + for (const field of ["text", "title"]) { + if (owner.todo[field] !== title || Object.hasOwn(owner.todo, `${field}_ref`)) continue; + const reference = `$.interaction_contract.agent_channel.work_context.sources[${owner.index}].content.todo.${field}`; + if (Array.from(JSON.stringify(title)).length <= reference.length + 8) return payload; + delete lane.title; + return {...payload, agent_lane_next_action: {...lane, title_ref: reference}}; + } + return payload; +} + +export function selectedTodo(payload: JsonObject, recommendedAction: string | null): JsonObject | null { + const source = object(payload.selected_todo); + if (Object.keys(source).length === 0) return null; + const compact = pickNonNull(source, [ + "todo_id", "priority", "status", "task_class", "action_kind", + "task_repository", "continuation_policy", "claimed_by", "bound_agent", + "goal_bound", "blocks_agent", "unblocks_todo_id", "next_due_at", + "expires_at", "selected_by", "confidence", + "resume_when", "resume_ready", "resume_condition", + ]); + const context = object(object(object(payload.interaction_contract).agent_channel).work_context); + if (context.selected_todo_text_verified === true) compact.text_source_verified = true; + // Work declarations can end in acceptance/stop conditions. Keep their exact + // text; a display prefix or case-folded recommendation cannot stand in for it. + const rendered = scalarString(source.text, "selected_todo.text"); + if (rendered && rendered === recommendedAction) compact.text_ref = "action.recommended_action"; + else if (rendered) compact.text = rendered; + return Object.keys(compact).length > 0 ? compact : null; +} + +/** These reads stay on one captured observation; they never re-enter the guard. */ +export function replanReadCommands(payload: JsonObject, path = payload.replan_read_path, + argv: unknown = payload.replan_read_argv ?? ["loopx"], verifiedSourceHash?: string, + captureSha256?: unknown): JsonObject | null { + const packet = object(payload.replan_action_packet); + if (!isNonEmptyFilePath(path) || payload.ok !== true || + payload.effective_action === EffectiveAction.GOVERNED_CAPABILITY_INTENT || + object(object(payload.interaction_contract).cli_channel).turn_binding_required === true || + !packet.obligation_id || packet.settlement_only === true) return null; + // Retain the renderer's executable across reads. A different ambient LoopX + // may not understand this captured contract. Legacy captures keep their route. + if (!Array.isArray(argv) || !argv.length || argv.some(arg => typeof arg !== "string" || !arg || /[\x00-\x1f]/.test(arg))) { + throw new EffectRuntimeRequestError("captured replan CLI route is malformed"); + } + if (captureSha256 !== undefined && + (typeof captureSha256 !== "string" || !BARE_SHA256_PATTERN.test(captureSha256))) { + throw new EffectRuntimeRequestError("captured replan byte digest is malformed"); + } + const command = `${argv.map(arg => shellQuote(arg as string)).join(" ")} --format json quota replan-view --decision-file ${shellQuote(path)}` + + ` --source-hash ${verifiedSourceHash ?? decisionSourceHash(payload)}` + + (captureSha256 === undefined ? "" : ` --capture-sha256 ${captureSha256}`); + return {review: `${command} --replan-stage review`, writeback: `${command} --replan-stage writeback`, + acceptance: `${command} --replan-stage acceptance`, explore: `${command} --replan-stage explore`}; +} + +/** One entry lens for CLI and Turn. The executor still receives the signed + * identity; authoring and executable settlement commands have one later read. + */ +export function deferredReplanWriteback(writeback: JsonObject): JsonObject { + const {settlement_plan: plan, next_cli_actions: actions, ...facts} = writeback; + if (!Object.keys(object(plan)).length && !(Array.isArray(actions) && actions.length)) return writeback; + const identity = object(object(plan).identity); + return {...facts, settlement_read_ref: "$.replan_action_packet.writeback", + ...(Object.keys(identity).length ? {settlement_identity: identity} : {})}; +} + +/** Preserve the captured Goal and work horizon for review and the signed + * executor envelope, indexing cumulative outcome details by exact content. + */ +export function replanGoalContext(payload: JsonObject, reads: JsonObject | null, coreRef = "$.core_goal", + precision?: ReplanReadPrecision) { + const context = object(object(payload.autonomous_replan_obligation).replan_context); + const retain = precision?.retain ?? ((view: JsonObject) => view); + function resolvedGoal(value: unknown): JsonObject { + const original = jsonObject(value) ?? {}; + const core = retain({...original}, original); + if (!("acceptance_contract" in core) && "acceptance_contract_ref" in core) { + const acceptance = inlineAcceptance(payload, core.acceptance_contract_ref); + delete core.acceptance_contract_ref; + core.acceptance_contract = acceptance; + } + return core; + } + function capturedOutcomes(core: JsonObject): JsonObject[] { + const requirements = object(object(core.acceptance_contract).outcome_requirements); + return reads && Array.isArray(requirements.outcomes) + ? requirements.outcomes.map(value => requireJsonObject(value, "captured acceptance outcome")) : []; + } + const resolvedCore = resolvedGoal(context.core_goal); + const originalHorizon = jsonObject(payload.planning_horizon) ?? {}; + const horizon = retain({...originalHorizon}, originalHorizon); + const resolvedHorizon = horizon.core_goal ? resolvedGoal(horizon.core_goal) : null; + const coreOutcomes = capturedOutcomes(resolvedCore); + const horizonOutcomes = resolvedHorizon ? capturedOutcomes(resolvedHorizon) : []; + const refs = new Map(); + const legacyGroups = new Map(); + const captured = [...coreOutcomes, ...horizonOutcomes]; + const complete = payload.schema_version === COMPLETE_TURN_DECISION_VERSION; + if (reads && complete) indexCapturedAcceptanceOutcomes(payload, value => { + captured.push(requireJsonObject(value, "captured acceptance outcome")); + return ""; + }); + for (const outcome of captured) { + if (refs.has(outcome)) continue; + const legacy = canonicalHash(outcome); + refs.set(outcome, legacy); + if (precision) { + const group = legacyGroups.get(legacy); + if (group) group.push(outcome); + else legacyGroups.set(legacy, [outcome]); + } + } + // Keep historical references where they identify exactly one outcome. + // When number decoding collapsed different outcomes, index each original + // body and reject the old ambiguous reference on the acceptance stage. + const ambiguous = new Set(); + if (precision) for (const [legacy, group] of legacyGroups) { + if (group.length < 2) continue; + const exact = group.map(outcome => precision.identity(outcome, [])); + if (new Set(exact).size < 2) continue; + ambiguous.add(legacy); + group.forEach((outcome, index) => refs.set(outcome, canonicalHash([legacy, exact[index]]))); + } + const outcomes = new Map(); + for (const [outcome, ref] of refs) outcomes.set(ref, outcome); + function indexedGoal(core: JsonObject, captured: JsonObject[]): JsonObject { + if (!captured.length) return core; + const originalAcceptance = jsonObject(core.acceptance_contract) ?? {}; + const acceptance = retain({...originalAcceptance}, originalAcceptance); + const requirements = jsonObject(acceptance.outcome_requirements) ?? {}; + const {outcomes: _outcomes, ...metadata} = requirements; + delete acceptance.outcome_requirements; + return retain({...core, acceptance_contract: acceptance, + outcome_requirements_index: retain({...metadata, outcome_refs: captured.map(outcome => refs.get(outcome)!)}, + requirements)}, core); + } + const core = indexedGoal(resolvedCore, coreOutcomes); + if (resolvedHorizon) { + const horizonCore = indexedGoal(resolvedHorizon, horizonOutcomes); + if (canonicalHash(horizonCore) === canonicalHash(core) && + (precision?.equalProjection(horizonCore, core) ?? true)) { + delete horizon.core_goal; + horizon.core_goal_ref = coreRef; + } else horizon.core_goal = horizonCore; + } + const acceptanceIndex = outcomes.size ? { + read_action_template: `${reads!.acceptance} --outcome-ref {outcome_ref}`, + outcomes: complete ? capturedOutcomeIndex(outcomes, precision) : [...outcomes].map(([ref, outcome]) => retain({outcome_ref: ref, id: outcome.id, + objective: outcome.objective, revision: outcome.revision, + requirement_count: Array.isArray(outcome.requirements) ? outcome.requirements.length : null}, + outcome, ["id", "objective", "revision"])), + } : null; + return {core, horizon, outcomes, acceptanceIndex, ambiguous}; +} + +/** Applicability of Explore's existing attachment owner, shared by complete + * composition and the historical staged projection. No authority is granted. */ +export function unboundExploreReplan(payload: JsonObject, plan: JsonObject): boolean { + const steps = Array.isArray(plan.ordered_steps) ? plan.ordered_steps.map(object) : []; + const attachments = object(steps.find(step => step.kind === "durable_writeback")).optional_attachments; + const explore = Array.isArray(attachments) ? attachments.map(object).filter(row => row.capability_id === "explore") : []; + const identity = object(plan.identity); + return payload.effective_action === EffectiveAction.AUTONOMOUS_REPLAN_REQUIRED && + selectedWorkTodoId(payload) === null && identity.binding_kind === "autonomous_replan" && + identity.replan_obligation_id === object(payload.replan_action_packet).obligation_id && + !identity.todo_id && explore.length === 0; +} + +/** Move only an identical acceptance copy behind the existing captured read. + * Different revisions, other source fields and unavailable context stay intact. + */ +export function replanWorkContext(payload: JsonObject, context: JsonObject, reads = replanReadCommands(payload), + identity: ReplanValueIdentity = canonicalHash): JsonObject { + context = resolveExploreGuidance(payload, context); + const corePath = ["autonomous_replan_obligation", "replan_context", "core_goal"]; + const core = object(object(object(payload.autonomous_replan_obligation).replan_context).core_goal); + const acceptance = object(core.acceptance_contract); + if (!reads || !Array.isArray(context.sources)) return context; + const plan = object(object(object(payload.interaction_contract).cli_channel).settlement_plan); + const steps = Array.isArray(plan.ordered_steps) ? plan.ordered_steps.map(object) : []; + const attachments = object(steps.find(step => step.kind === "durable_writeback")).optional_attachments; + const explore = Array.isArray(attachments) ? attachments.map(object).filter(row => row.capability_id === "explore") : []; + const unboundReplan = unboundExploreReplan(payload, plan); + return {...context, sources: context.sources.map((value, index) => { + const source = object(value), content = object(source.content); + if (source.source === "turn_start_capability_hook" && source.hook_id === "explore.turn_context" && + source.capability_id === "explore" && explore.length === 1 && typeof reads.writeback === "string") { + return {...source, content: referenceExploreResultWriteback(content, explore[0], reads.writeback)}; + } + if (unboundReplan && source.source === "turn_start_capability_hook" && + source.hook_id === "explore.turn_context" && source.capability_id === "explore") { + return {...source, content: omitUnboundExploreResultWriteback(content)}; + } + if (!Object.keys(acceptance).length || source.source !== "goal_acceptance" || content.status != null && content.status !== "loaded" || + identity(content.goal_acceptance_contract, + ["interaction_contract", "agent_channel", "work_context", "sources", index, "content", "goal_acceptance_contract"]) + !== identity(acceptance, [...corePath, "acceptance_contract"])) return value; + const {goal_acceptance_contract: _contract, ...metadata} = content; + return {...source, content: {...metadata, context_read: reads.review}}; + })}; +} + +/** Bind successor authoring to the already-decided Turn. This formatting + * owner is shared by complete composition and historical staged reads; it does + * not select work, create a successor or change the settlement plan. + */ +export function bindReplanSuccessorContract(value: JsonObject, plan: JsonObject): JsonObject { + const contract = {...value}; + const identity = object(plan.identity); + if (typeof identity.turn_instance_id !== "string") return contract; + const goalRef = object(plan.goal_ref); + contract.successor_binding_args = `--turn-instance-id ${shellQuote(identity.turn_instance_id)}` + + (typeof goalRef.goal_instance_id === "string" ? ` --goal-instance-id ${shellQuote(goalRef.goal_instance_id)}` : ""); + contract.successor_settlement = "If creating a replan successor, include successor_binding_args with its obligation id, then follow the creation receipt's original Turn settlement plan before ending; do not run the successor."; + delete contract.successor_host_action; + if (typeof contract.successor_command === "string") { + contract.successor_command = `${contract.successor_command} ${contract.successor_binding_args}`; + } + return contract; +} + +export function requireCompleteDecisionSource(source: JsonObject): void { + assertSupportedQuotaPacket(source); + // Validate executable semantics with their owner, retaining the original + // object (including optional facts) rather than its normalized decode. + const interaction = decodeInteractionContract(source.interaction_contract); + assertInteractionRequiredReads(interaction.agent_channel.required_reads); + replanAuthoringContract(source); + requireVisionAuditReferences(source); + requireCurrentTaskTitleReference(source); + resolveQuotaSummaryLanes(source); + resolveExploreGuidance(source, object(object(object(source.interaction_contract).agent_channel).work_context)); + // This root field selects execution, unlike optional evidence carried intact + // in the source. Reuse both registered owners; do not inherit the historical + // adapter's unknown-action fallback at the new version boundary. + requireStringLiteral(source.effective_action, + [...EFFECTIVE_ACTIONS, ...AGENT_SCOPE_FRONTIER_ACTIONS], "Turn effective_action"); + for (const {parent, field} of acceptanceCarriers(source)) { + if (!Object.hasOwn(parent, field) && Object.hasOwn(parent, `${field}_ref`)) { + inlineAcceptance(source, parent[`${field}_ref`]); + } + } +} + +export function requireCompleteTurnDecision(value: unknown, numberTokens?: unknown): JsonObject { + const decision = requireJsonObject(value, "complete Turn decision"); + if (decision.schema_version !== COMPLETE_TURN_DECISION_VERSION) { + throw new EffectRuntimeRequestError("unsupported complete Turn decision version"); + } + const binding = requireJsonObject(decision.contract_binding, "Turn contract binding"); + if (binding.hash_codec !== COMPLETE_TURN_HASH_CODEC) { + throw new EffectRuntimeRequestError("unsupported complete Turn decision hash codec"); + } + const identity = contextSourceIdentity(decision, numberTokens ?? []); + if (typeof binding.scheduler_execution_args !== "string") { + throw new EffectRuntimeRequestError("Turn scheduler execution binding must be a string"); + } + const unsignedBinding = {...binding}; + delete unsignedBinding.content_hash; + const content = {...decision, contract_binding: unsignedBinding}; + if (binding.content_hash !== completeSourceHash(content, identity)) { + throw new EffectRuntimeRequestError("complete Turn decision content integrity mismatch"); + } + const source = {...decision}; + delete source.schema_version; + delete source.contract_binding; + if (binding.source_decision_hash !== completeSourceHash(source, identity)) { + throw new EffectRuntimeRequestError("complete Turn decision source integrity mismatch"); + } + requireCompleteDecisionSource(source); + return decision; +} + +export function replanView(request: JsonObject, resolveWriteback: WritebackResolver): JsonObject { + const payload = requireJsonObject(request.payload, "captured replan decision"); + const sourceHash = decisionSourceHash(payload); + if (request.source_hash !== sourceHash || payload.ok !== true) { + throw new EffectRuntimeRequestError("Replan read requires the original successful decision and matching source hash"); + } + // Validate the complete current source before the historical display lens. + if (Object.hasOwn(payload, "schema_version") || Object.hasOwn(payload, "contract_binding")) { + requireCompleteTurnDecision(payload, request.source_number_tokens); + } else requireVisionAuditReferences(payload); + const precision = replanReadPrecision(payload, request.source_number_tokens); + const view = projectReplanView(request, payload, sourceHash, resolveWriteback, precision); + return precision ? contextProjectionChanges(payload, view, precision.values, {}) : view; +} + +function projectReplanView( + request: JsonObject, payload: JsonObject, sourceHash: string, + resolveWriteback: WritebackResolver, precision?: ReplanReadPrecision, +): JsonObject { + const retain = precision?.retain ?? ((view: JsonObject) => view); + requireVisionAuditReferences(payload); + const originalContract = replanAuthoringContract(payload, precision); + const packet = jsonObject(payload.replan_action_packet) ?? {}; + const obligation = jsonObject(payload.autonomous_replan_obligation) ?? {}; + const context = jsonObject(obligation.replan_context) ?? {}; + if (!packet.obligation_id || packet.settlement_only === true || packet.obligation_id !== context.obligation_id) { + throw new EffectRuntimeRequestError("Replan read requires a matching decision context"); + } + const common = {ok: true, goal_id: payload.goal_id, agent_id: payload.agent_id ?? object(payload.agent_identity).agent_id, + obligation_id: packet.obligation_id, context_id: context.context_id, source_hash: request.source_hash, + stage: request.stage}; + // A native journal binds its path after planning. The CLI supplies that same + // physical source route without modifying the captured observation or hash. + const path = request.captured_decision_path ?? payload.replan_read_path; + const reads = replanReadCommands(payload, path, payload.replan_read_argv ?? request.reader_argv ?? ["loopx"], + sourceHash, request.capture_sha256); + // The stateless entry already exposes its digest-checked complete context. + // Its writer should not offer a second, unchecked whole-file route. + const sourceRead = reads && request.capture_sha256 === undefined + ? {source_read: `cat -- ${shellQuote(path as string)}`} : {}; + if (request.stage === "acceptance") { + const {outcomes, ambiguous} = replanGoalContext(payload, reads, undefined, precision); + const ref = String(request.outcome_ref); + if (ambiguous.has(ref)) throw new EffectRuntimeRequestError( + "The old captured outcome reference is ambiguous. Read the review stage for the distinct references."); + const outcome = outcomes.get(ref); + if (!outcome) throw new EffectRuntimeRequestError("acceptance read requires an exact captured outcome reference"); + return {...common, outcome_ref: request.outcome_ref, outcome}; + } + if (request.stage === "explore") + return retain({...common, explore_basis: context.explore_basis ?? null}, context, ["explore_basis"]); + if (request.stage === "writeback") { + // Preserve executable shape and all settlement rules; decision advice and + // duplicate context are available in the unchanged full captured source. + const originalStride = jsonObject(packet.stride_control) ?? {}; + const stride = retain({...originalStride}, originalStride); + // The current nested review syntax belongs to authoring, not duplicate + // decision evidence. Top-level required_fields cannot describe that shape. + for (const key of ["decision_followthrough", "explore_basis", "decision_value_review"]) delete stride[key]; + const contract = {...originalContract}; + if (contract.vision_authoring) { + const originalAuthoring = jsonObject(contract.vision_authoring) ?? {}; + const authoring = retain({...originalAuthoring}, originalAuthoring); + delete authoring.minimal_example; + contract.vision_authoring = authoring; + } + const writeback = resolveWriteback(payload, precision, sourceHash); + const plan = object(writeback.settlement_plan); + const boundContract = payload.schema_version === COMPLETE_TURN_DECISION_VERSION + ? contract : bindReplanSuccessorContract(contract, plan); + if (typeof boundContract.successor_command === "string" && typeof object(plan.identity).turn_instance_id === "string") { + // Creation returns the original settlement plan directly. A guard + // reentry would repeat admission/context and can select new work. + writeback.next_cli_actions = [boundContract.successor_command]; + } + const steps = Array.isArray(plan.ordered_steps) ? plan.ordered_steps.map(object) : []; + const refresh = steps.find(step => step.kind === "durable_writeback"); + const spend = steps.find(step => step.kind === "quota_spend"); + const receipt = object(payload.heartbeat_receipt), identity = object(plan.identity); + const cli = object(object(payload.interaction_contract).cli_channel); + const settlement = object(cli.replan_settlement_contract), binding = object(settlement.settlement_binding); + const semantic = object(settlement.semantic_obligation), actions = cli.next_cli_actions; + // Use the captured semantic writer, which already carries the owner's + // authoring arguments. The generic plan template omits those arguments. + // Leave the signed plan and separate recovery actions untouched. + const directWriter = payload.schema_version === COMPLETE_TURN_DECISION_VERSION + && payload.should_run === true && payload.effective_action === EffectiveAction.AUTONOMOUS_REPLAN_REQUIRED + && plan.schema_version === SETTLEMENT_PLAN_SCHEMA_VERSION && identity.binding_kind === "autonomous_replan" + && typeof identity.turn_instance_id === "string" && receipt.turn_instance_id === identity.turn_instance_id + && identity.replan_obligation_id === packet.obligation_id + && ["committed", "upgraded", "replayed"].includes(String(receipt.status)) + && receipt.settlement_binding_owed !== true && isDeepStrictEqual(receipt.settlement_identity, identity) + && settlement.schema_version === REPLAN_SETTLEMENT_CONTRACT_SCHEMA && settlement.single_binding_required === true + && binding.kind === "autonomous_replan" && binding.id === packet.obligation_id + && binding.cli_argument === "--replan-obligation-id" && semantic.kind === "autonomous_replan" + && semantic.settlement_bound === true && semantic.id === packet.obligation_id + && semantic.discharge === "direct_settlement" && cli.spend_after_validation === true + && cli.spend_allowed_now === false && cli.selection_required !== true + && typeof boundContract.successor_command !== "string" + && refresh?.owner === "agent" && spend?.owner === "agent" && typeof spend.command_template === "string" + && Array.isArray(actions) && actions.length === 2 && actions[1] === spend.command_template + && typeof actions[0] === "string" && actions[0].length > 0 + && isDeepStrictEqual(writeback.next_cli_actions, [actions[0]]) + ? actions[0] : undefined; + const settlementCommand = directWriter !== undefined + ? directWriter + " --settle-turn --settlement-receipt" + : typeof refresh?.command_template === "string" ? refresh.command_template + " --settle-turn" : undefined; + return retain({...common, ...sourceRead, writeback_contract: retain(boundContract, originalContract), + required_outcome: packet.required_outcome, allowed_terminal: packet.allowed_terminal, + ...(packet.stride_control ? {stride_control: stride} : {}), + writeback, + ...(settlementCommand === undefined ? {} : { + settlement_command: settlementCommand, + settlement_usage: "After validation, fill this refresh command from the actual result. It follows only the verified owed quota step on this same binding. " + + "Do not also execute a quota step after settled readback; retain the original plan for completion, blocked/no-spend closeout and failure recovery.", + })}, packet, ["required_outcome", "allowed_terminal"]); + } + if (request.stage !== "review") throw new EffectRuntimeRequestError("unsupported replan read stage"); + const {core, horizon, acceptanceIndex} = replanGoalContext(payload, reads, undefined, precision); + const cli = object(object(payload.interaction_contract).cli_channel); + // Index every captured outcome, including differing context/horizon revisions. + // Full-content equality alone shares a row; identical IDs do not erase edits. + const coverage = Array.isArray(context.coverage_ledger) ? context.coverage_ledger.map(value => + jsonObject(value) ?? {}) : []; + const originalFollow = jsonObject(context.decision_followthrough) ?? {}; + const follow = {...originalFollow}; + delete follow.guidance; + const followFields = Object.keys(follow); + if (Object.hasOwn(follow, "recorded_progress_count")) { + follow.observation_count = follow.recorded_progress_count; + delete follow.recorded_progress_count; + retain(follow, originalFollow, followFields.filter(field => field !== "observation_count")); + retain(follow, originalFollow, [["recorded_progress_count", "observation_count"]]); + } else retain(follow, originalFollow, followFields); + const explore = jsonObject(context.explore_basis) ?? {}; + const yardstickCount = Array.isArray(explore.work_yardsticks) ? explore.work_yardsticks.length : 0; + const reversal = reads ? scopedReplanYardstickReversal(payload) : undefined; + const decisionValueReview = jsonObject(jsonObject(packet.stride_control)?.decision_value_review); + const review = retain({...common, + core_goal: core, + planning_guidance: packet.planning_guidance ?? [], + // The staged writer only carries authoring rules. Deliver the captured + // decision advice here so it can inform the choice before writeback. + ...(decisionValueReview ? {decision_value_review: decisionValueReview} : {}), + ...(acceptanceIndex ? {acceptance_index: acceptanceIndex} : {}), + triggers: obligation.triggers, + decision_followthrough: Object.keys(follow).length ? follow : null, + planning_horizon: payload.planning_horizon == null ? null : horizon, + action_portfolio: payload.action_portfolio ?? null, + ...(context.explore_basis ? {capabilities: {explore: retain({ + availability: explore.availability, revision: explore.revision, + ...(Array.isArray(explore.measurement_feedback) && explore.measurement_feedback.length + ? {measurement_count: explore.measurement_feedback.length} : {}), + ...(yardstickCount ? {yardstick_count: yardstickCount} : {}), + ...(reversal ? {work_yardstick_reversal: retain(compactFields(reversal.cue, reversal.fields), reversal.cue)} : {}), + read_action: reads?.explore ?? null, + }, explore, ["availability", "revision"])}} : {}), + evidence: (Array.isArray(context.evidence) ? context.evidence : []).map(value => { + const row = jsonObject(value) ?? {}; + const observation = coverage.find(item => item.fingerprint === row.coverage_ref); + const item = retain({...compactFields(row, ["evidence_ref", "generated_at", "delivery_outcome", "coverage_ref", + "occurrences", "first_observed_at", "read_action"]), + ...(observation ? {result_class: observation.result_class} : {})}, row); + return observation ? retain(item, observation, ["result_class"]) : item; + }), + evidence_count: context.evidence_count, + coverage_count: context.coverage_count, + coverage_truncated: context.coverage_truncated, + omitted_evidence: context.omitted_evidence ?? null, + evidence_read_action_template: context.evidence_read_action_template ?? null, + uncovered_frontier: context.uncovered_frontier, + // Facts and their provenance are the review input. Do not preselect a + // diagnostic method, candidate route or judgment from observation counts. + // A suggested Todo can already be present before the guard binds it. + // Follow the entry's command: its host may already have bound the current + // presentation options after this immutable decision was captured. + next: cli.selection_required === true + ? {selection_required: true, selection_command_ref: "$.interaction_contract.cli_channel.selection_command"} + : {writeback: reads?.writeback ?? null}, + }, context, ["evidence_count", "coverage_count", "coverage_truncated", "omitted_evidence", + "evidence_read_action_template", "uncovered_frontier"]); + retain(review, obligation, ["triggers"]); + return retain(review, packet, ["planning_guidance"]); +} + +export function replanActionPacket(payload: JsonObject, reads = replanReadCommands(payload)): JsonObject | null { + const source = object(payload.replan_action_packet); + if (Object.keys(source).length === 0) return null; + const writeback = replanAuthoringContract(payload); + if (reads) return {...compactFields(source, ["schema_version", "decision", "obligation_id", "required_outcome", "allowed_terminal"]), + review: reads.review, writeback: reads.writeback, + guidance: "Read review state and applicable acceptance/evidence; choose the next work, then follow review.next for Todo selection or writeback. Reads grant no authority and require no acknowledgement."}; + const compact = compactFields(source, [ + "schema_version", "decision", "obligation_id", "uncovered_frontier", + "required_outcome", "allowed_terminal", "bounded_frontier", "settlement_only", "successor_todo_id", "stride_control", + ]); + // The typed replan owner supplies bounded instructions; do not truncate their + // authority/stop qualifiers through generic diagnostic compaction. + if (Array.isArray(source.planning_guidance)) compact.planning_guidance = source.planning_guidance; + if (writeback.vision_authoring) compact.writeback_contract = writeback; + return Object.keys(compact).length > 0 ? compact : null; +} + +export function userChannel(interaction: JsonObject, payload: JsonObject): JsonObject { + const source = object(interaction.user_channel); + const channel: JsonObject = { + action_required: Boolean(source.action_required ?? payload.action_required), + open_count: integer(payload.open_count, "payload.open_count"), + notify: scalarString(source.notify, "interaction.user_channel.notify", "DONT_NOTIFY"), + }; + const actions = textList(source.actions, 3, 360); + if (actions.length > 0) channel.actions = actions; + const reason = text(source.reason, 360); + if (reason) channel.reason = reason; + return channel; +} + +export function responsePlan(interaction: JsonObject): JsonObject | null { + const source = object(interaction.response_plan); + if (Object.keys(source).length === 0) return null; + const plan: JsonObject = {}; + for (const field of ["schema_version", "kind", "decision"]) { + const rendered = text(source[field], 80); + if (rendered) plan[field] = rendered; + } + const actionSequence = textList(source.action_sequence, 8, 80); + if (actionSequence.length > 0) plan.action_sequence = actionSequence; + if (typeof source.silent_wait_allowed === "boolean") plan.silent_wait_allowed = source.silent_wait_allowed; + return Object.keys(plan).length > 0 ? plan : null; +} + +export function requiredReads(interaction: JsonObject, payload: JsonObject): JsonObject[] { + const raw = object(interaction.agent_channel).required_reads + ?? interaction.required_reads ?? payload.required_reads; + const result: JsonObject[] = []; + for (const value of Array.isArray(raw) ? raw : []) { + const item = object(value); + // Required reads are executable obligations, not display summaries. Keep + // every admitted command byte-for-byte, including quoted path whitespace. + const command = scalarString(item.command, "required read command"); + if (!command) continue; + const compact: JsonObject = { command }; + // These are existing obligation coordinates, not provider diagnostics. + // Keep identity and ordering intact, just like the executable command. + for (const field of ["kind", "reason", "source", "ordering", "hook_id", "capability_id"]) { + const value = scalarString(item[field], `required read ${field}`); + if (value) compact[field] = value; + } + if (item.source === "turn_start_capability_hook" && item.prompt_budget_bytes !== undefined) { + compact.prompt_budget_bytes = item.prompt_budget_bytes; + } + result.push(compact); + } + return result; +} + +export function replanCliView(payload: JsonObject, identity: ReplanValueIdentity = canonicalHash, + reads = replanReadCommands(payload), precision?: ReplanReadPrecision): JsonObject { + if (!reads) return payload; + const obligation = {...object(payload.autonomous_replan_obligation)}; + delete obligation.replan_context; + const interaction = object(payload.interaction_contract), agent = object(interaction.agent_channel); + const cli = object(interaction.cli_channel); + // Defer only authoring/settlement format, not admission or stop facts. + // This default captured path needs no optional native delta transport. + const goal = replanGoalContext(payload, reads, undefined, precision); + const summary = object(payload.agent_todo_summary); + const originalCore = object(object(object(payload.autonomous_replan_obligation).replan_context).core_goal); + // Reuse the same captured acceptance index for an exact summary copy. + // Otherwise this legacy carrier silently restores the full deferred detail. + // A different revision or an existing summary index remains untouched. + const indexedSummary = goal.core.outcome_requirements_index && + !Object.hasOwn(summary, "outcome_requirements_index") && + identity(summary.goal_acceptance_contract ?? null, ["agent_todo_summary", "goal_acceptance_contract"]) + === identity(originalCore.acceptance_contract ?? null, + ["autonomous_replan_obligation", "replan_context", "core_goal", "acceptance_contract"]) + ? {...summary, goal_acceptance_contract: goal.core.acceptance_contract, + outcome_requirements_index: goal.core.outcome_requirements_index} : summary; + // Review owns the captured planning facts. The entry retains admission, + // current selection and stops; the mandatory reader supplies the complete + // Goal and horizon before the Agent chooses its next work. + const {core_goal: _core, planning_horizon: _horizon, ...entry} = payload; + return {...entry, + ...(indexedSummary !== summary ? {agent_todo_summary: indexedSummary} : {}), + interaction_contract: {...interaction, cli_channel: deferredReplanWriteback(cli), agent_channel: {...agent, + work_context: replanWorkContext(payload, object(agent.work_context), reads, identity)}}, + autonomous_replan_obligation: {...obligation, context_read: reads.review}, + replan_action_packet: replanActionPacket(payload, reads)}; +} + +export function nativeReplanPresentation(request: JsonObject): JsonObject | undefined { + const projection = object(request.native_projection); + const captured = object(projection.captured_decision); + const stateless = captured.path === undefined && projection.replan_reader_argv !== undefined; + const path = stateless ? projection.source_path : captured.path; + if (typeof path !== "string") return undefined; + const source = requireJsonObject(request.context, "captured replan source"); + if (stateless) { + if (projection.sha256 === undefined || request.surface !== "complete_turn" && + (request.surface !== "quota_packet" || Object.hasOwn(source, "schema_version") || + Object.hasOwn(source, "contract_binding"))) return undefined; + // Preserve a bound reversal in the opening, before candidate choice. + if (scopedReplanYardstickReversal(source)) return undefined; + } + const packet = object(source.replan_action_packet); + const review = object(object(source.autonomous_replan_obligation).replan_context); + // Existing staged files are presentation inputs. Do not derive a new source + // hash from them or replace their already pinned reader commands. + if ((!stateless && typeof source.replan_read_path !== "string") || packet.schema_version !== "replan_action_packet_v0" + || typeof packet.obligation_id !== "string" + || packet.obligation_id !== review.obligation_id || packet.review !== undefined + || packet.writeback !== undefined) return undefined; + const precision = replanReadPrecision(request, request.source_number_tokens); + const identity = precision?.identity ?? contextSourceIdentity(request); + const view = replanCliView(source, (value, field) => identity(value, ["context", ...field]), + replanReadCommands(source, path, stateless ? projection.replan_reader_argv : undefined, + undefined, stateless ? projection.sha256 : captured.sha256), precision); + return view === source ? undefined : {staged_context: view, deferred: [], instructions: []}; +} diff --git a/loopx/control_plane/runtime_decode.ts b/loopx/control_plane/runtime_decode.ts index 9a42e3b4a8..2dacd8e3ba 100644 --- a/loopx/control_plane/runtime_decode.ts +++ b/loopx/control_plane/runtime_decode.ts @@ -113,6 +113,13 @@ export function optionalNonEmptyString( return requireNonEmptyString(value, label); } +export function pythonString(value: unknown): string { + if (value === null || value === undefined) return "None"; + if (value === true) return "True"; + if (value === false) return "False"; + return String(value); +} + export function requireStringArray(value: unknown, label: string): string[] { if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) { throw new EffectRuntimeRequestError(`${label} must be an array of strings`); diff --git a/loopx/control_plane/scheduler/state_store.ts b/loopx/control_plane/scheduler/state_store.ts index 81f8ecb6b9..6a5c0009f7 100644 --- a/loopx/control_plane/scheduler/state_store.ts +++ b/loopx/control_plane/scheduler/state_store.ts @@ -13,6 +13,7 @@ import { import { assertNever, jsonObject, + pythonString, requireJsonObject as requiredObject, requireNonEmptyString as requiredString, requireStringLiteral, @@ -107,15 +108,6 @@ function pythonTruthy(value: unknown): boolean { return true; } -function pythonString(value: unknown): string { - if (value === null || value === undefined) return "None"; - if (value === true) return "True"; - if (value === false) return "False"; - if (typeof value === "string") return value; - if (typeof value === "number") return String(value); - return String(value); -} - function stringOrEmpty(value: unknown): string { return pythonTruthy(value) ? pythonString(value) : ""; } diff --git a/tests/control_plane_ts/content_digest_single_owner.test.ts b/tests/control_plane_ts/content_digest_single_owner.test.ts index 1ad78cc4f2..5095efc08c 100644 --- a/tests/control_plane_ts/content_digest_single_owner.test.ts +++ b/tests/control_plane_ts/content_digest_single_owner.test.ts @@ -165,6 +165,7 @@ const CANONICAL_CONSUMERS = [ "control_plane/quota/refresh_external_delivery.ts", "control_plane/quota/settlement_readback.ts", "control_plane/quota/turn_envelope.ts", + "control_plane/quota/turn_envelope_references.ts", "control_plane/runtime/checkpoint_artifacts.ts", "control_plane/runtime/checkpoint_retention.ts", "control_plane/runtime/execution_identity.ts",